Skip to content

Excel-authored oracle generation is an available capability

Status: available on this macOS host. Not a blocker.

For a long time the parity campaign treated "real-Excel-authored fixture" evidence (Oracle C, native .xls/BIFF8, cached pivot records, VBA streams) as requiring a human to hand-author files in Excel, so those lanes were deferred as "Excel-bound, cannot run headlessly." That deferral is a policy default, not a technical limit. This host can drive real Microsoft Excel programmatically to author genuine fixtures plus an independent oracle, on demand.

Whenever a future task is about to report "blocked: needs Excel-authored fixture," it should instead check this doc and, with the user's approval, run or extend the generator below.

What's available

  • Microsoft Excel (real, sandboxed) at /Applications/Microsoft Excel.app.
  • xlwings (dev dependency) drives Excel via AppleScript on macOS.
  • Reference generator: scripts/generate_real_excel_xls_fixtures.py, which authors BIFF8 .xls fixtures and captures an authoring-time oracle JSON.

The one gotcha: sandbox "Grant File Access"

macOS Excel is sandboxed. The first programmatic save into a new folder raises a one-time "Grant File Access" modal. It does not auto-dismiss, so a naive save appears to hang.

Handle it once per target folder:

  1. Trigger a save into the target folder (it will block on the dialog).
  2. In the dialog, click Select…, then in the folder picker choose the target folder (Cmd+Shift+G to type the path), and confirm.
  3. macOS (TCC) persists the grant. Every later save into that folder — via xlwings or AppleScript — succeeds with no prompt.

The reference generator saves directly into tests/parity/fixtures/xls/real_excel/, which has already been granted, so it runs unattended now. A brand-new output folder needs the grant step once.

If automating the click: the dialog is window "Grant File Access" of process Microsoft Excel; drive it with System Events (click button "Select...", then keystroke the path + return).

Guardrail interaction

Running Excel is deferred-by-default under .omp/RULES.md:41 and Plans/aspose-parity-goal-objective.md (§10, Excel-bound lanes) — it needs explicit user approval per session/batch, precisely because it is local, stateful, and GUI-driven rather than reproducible in CI. That approval unlocks an automated batch; it does not require the user to hand-type cells.

Correct pattern:

  1. Reach a point where only Excel-authored evidence remains.
  2. Ask the user to approve an Excel-authored batch (cite this doc).
  3. On approval, run/extend the generator, commit the fixtures + oracle JSON.
  4. CI consumes the committed bytes — Excel is never needed on a runner.

Extending to other oracles

The same mechanism produces the other Excel-bound oracles the acquisition manifest (docs/fidelity/evidence/2026-07-03-oracle-acquisition-manifest.json) lists: cached pivot records, Oracle C calc values, macro/VBA streams. Add FixtureSpecs (or a sibling generator) and reuse the sandbox-grant step. None of these is a true blocker on this host — only an approval gate.