ZeroCell Excel Matrix Tool (Rust)

A Rust CLI for matrix-layered Excel processing intended for AI agent workflows.

Benchmark Status

• Benchmark harness, methodology, and reproducibility docs:
  • Benchmarking/README.md
  • Benchmarking/METHODOLOGY.md
  • Benchmarking/REPRODUCIBILITY.md

Current capabilities

• read: Extracts parallel matrices from an .xlsx worksheet:
  • values: evaluated cell values in JSON form
  • formulas: formula strings aligned to the same grid (null where no formula exists)
• read-resilient: Performs read with fallback policy; when a sheet is missing it returns deterministic suggestions and available sheet inventory.
• context: Generates an agent-oriented context pack for a worksheet:
  • dimension stats and formula density
  • workbook named ranges
  • merged ranges, hidden rows/columns, table metadata
  • inferred section zones and formula reference lineage summary
  • formula lineage graph with upstream/downstream impact samples
• write: Reconstructs a worksheet from those matrices into a new .xlsx file.
• plan: Validates payload and returns a dry-run cell-level diff summary.
• update: Non-destructive workbook update that preserves all existing sheets and updates/adds one target sheet.
  • for pre-existing target sheets, updates are applied in-place at worksheet-XML level to preserve cell styles/formatting, merged ranges, and data validations.
• inspect-workbook: Returns per-sheet dimensions, value fill, and formula density.
• inspect-workbook-parallel: Parallelized per-sheet inspection for faster workbook profiling.
• inspect-sheet: Sheet-level inspection alias for context pack output.
• profile-sheet: Infers a sheet schema and column profiles from the Polars-backed analytics layer.
• scan-sheet-anomalies: Flags duplicate headers, mixed types, sparse columns, partial formula coverage, and numeric outliers on one sheet.
• scan-workbook-anomalies: Aggregates sheet anomaly scans and cross-sheet header/type conflicts.
• join-sources: Joins two workbook sources by key, where each source can be a sheet or a named range (named:RangeName).
• read-sparse: Sparse read mode that emits only non-null value cells and non-empty formula cells.
  • sparse analytics now run on a Polars-backed cell frame for bounded sheet sizes, with native fallback on larger frames
• benchmark-read: Benchmark harness for read performance with configurable warmup/iterations and thresholds.
• propose-patch: Builds operation-level patch JSON (set_value, set_formula, clear_cell) from direct cell map payload (e.g. {"Sheet1": {"A1": "Value"}}).
• validate-patch: Validates patch operations and returns risk/confidence + diff preview.
• read-safe: Reads sheet matrices with optional PII redaction (--detect-only for scan-only mode).
• apply-patch: Applies patch operations non-destructively and writes updated workbook, with optional policy checks, backup copy, and append-only audit log.
• finance-analyze: Runs financial-model intelligence checks:
  • totals consistency checks
  • ratio sanity checks
  • missing input detection
  • scenario projection (base, conservative, aggressive)
  • recommendation/risk flags
• recalculate-workbook: Spawns LibreOffice headless to natively recalculate all complex formula results in the workbook.
• mcp-stdio: MCP-compatible stdio adapter (tools/list, tools/call) for agent tool integration.
• telemetry-summary: Aggregates operation outcomes/latencies from telemetry logs.
• runtime-observability: Alias for telemetry summary with fallback and failure-code trend fields.
• query-sheet: Targeted query endpoint for sheet/range/category slices.
  • for MCP callers, workbook_path/sheet_name aliases are accepted (path, workbook, sheet, worksheet)
  • if range is omitted, the response is clipped to a safe default window to avoid oversized agent output
• scan-agent-comments: Finds workbook notes/comments tagged with @agent and extracts explicit cell/range mentions for downstream agent execution.
• sync-agent-tasks: Persists scanned @agent tasks into a sidecar state file and preserves prior status transitions across rescans.
• set-agent-task-status: Updates persisted task state to pending, running, done, or error.
• resolve-agent-task-context: Builds a task-specific context bundle with anchor window and explicit reference slices.
• doctor: Validates Python, LibreOffice, recalc helper scripts, temp dir access, telemetry directory setup, and runtime override summary.
• init: Bootstraps downstream project MCP config (opencode.json) and a local ZeroCell skill stub under .zerocell/.
• schema-info: Stable schema compatibility/version guarantees for integrations.
• skill-api-contract: Formal skill API contract + changelog/fallback policy metadata for runtime integration gating.
• Global runtime controls:
  • --telemetry-log <path>: telemetry destination (default .zerocell/telemetry.ndjson)
  • --no-telemetry: disable telemetry write
  • --diagnostic-json: structured operator diagnostics on failure
• SDK wrappers:
  • ZeroCellSdk exposes typed Rust wrappers for read/inspect/patch/finance workflows.

Build

cargo build --release

Platform Skill Bundles

The main repo now publishes install-ready platform bundles through platform-bundles.yml.

• Triggers:
  • workflow_dispatch
  • pushes to main
  • tags matching v*
• Output:
  • one zip per platform
  • one per-platform manifest JSON
  • one per-platform SHA256 checksum text file
  • one aggregate manifest JSON
  • one aggregate SHA256SUMS file

Bundle naming:

• ZeroCell-macos-arm64-<version>.zip
• ZeroCell-macos-x64-<version>.zip
• ZeroCell-windows-x64-<version>.zip
• ZeroCell-windows-arm64-<version>.zip

Each zip extracts to a single top-level ZeroCell/ folder containing:

• README.md
• SKILL.md
• mcp.json
• bin/<platform binary>
• required helper files under scripts/ for features such as workbook recalculation

Install flow:

1. Download the matching bundle zip.
2. Extract it.
3. Move the extracted ZeroCell/ folder directly into your skills directory.
4. Use the bundled mcp.json; it already points at ./bin/<platform binary> and passes mcp-stdio.

Usage

Read worksheet matrices:

./target/release/zerocell_excel_matrix read ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix read-resilient ./path/to/input.xlsx MaybeWrongSheet --pretty

Generate worksheet context pack:

./target/release/zerocell_excel_matrix context ./path/to/input.xlsx Sheet1 --pretty

Write worksheet from matrix payload:

./target/release/zerocell_excel_matrix write ./examples/write_payload.json ./output.xlsx

Preview payload changes before writing:

./target/release/zerocell_excel_matrix plan ./path/to/input.xlsx ./payload.json --pretty

Update workbook non-destructively:

./target/release/zerocell_excel_matrix update ./path/to/input.xlsx ./payload.json ./output.xlsx --pretty

Inspect workbook/sheet:

./target/release/zerocell_excel_matrix inspect-workbook ./path/to/input.xlsx --pretty
./target/release/zerocell_excel_matrix inspect-workbook-parallel ./path/to/input.xlsx --pretty
./target/release/zerocell_excel_matrix inspect-sheet ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix profile-sheet ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix scan-sheet-anomalies ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix scan-workbook-anomalies ./path/to/input.xlsx --pretty
./target/release/zerocell_excel_matrix join-sources ./path/to/input.xlsx Inputs ID Lookup ID --join-type inner --pretty
./target/release/zerocell_excel_matrix join-sources ./path/to/input.xlsx named:BudgetItems ID Lookup ID --join-type left --pretty

Financial model intelligence analysis:

./target/release/zerocell_excel_matrix finance-analyze ./path/to/input.xlsx Sheet1 --pretty

Targeted query and schema compatibility:

./target/release/zerocell_excel_matrix query-sheet ./path/to/input.xlsx Sheet1 --range A1:C20 --category inputs --pretty
./target/release/zerocell_excel_matrix scan-agent-comments ./path/to/input.xlsx --pretty
./target/release/zerocell_excel_matrix sync-agent-tasks ./path/to/input.xlsx --pretty
./target/release/zerocell_excel_matrix set-agent-task-status ./path/to/input.xlsx Model!A2 running --note "picked up" --pretty
./target/release/zerocell_excel_matrix resolve-agent-task-context ./path/to/input.xlsx Model!A2 --window-radius 1 --pretty
./target/release/zerocell_excel_matrix doctor --pretty
./target/release/zerocell_excel_matrix init /path/to/project --binary /abs/path/to/zerocell_excel_matrix --pretty
./target/release/zerocell_excel_matrix schema-info --pretty
./target/release/zerocell_excel_matrix skill-api-contract --pretty

For MCP integrations, prefer sending a narrow range. Alias forms such as request.path + request.sheet are accepted, but the stable contract remains workbook_path + sheet_name.

MCP adapter + telemetry trends:

./target/release/zerocell_excel_matrix mcp-stdio --pretty
./target/release/zerocell_excel_matrix telemetry-summary ./.zerocell/telemetry.ndjson --pretty
./target/release/zerocell_excel_matrix runtime-observability ./.zerocell/telemetry.ndjson --pretty

Structured diagnostics:

./target/release/zerocell_excel_matrix read ./path/to/input.xlsx MissingSheet --diagnostic-json --pretty

Sparse decomposition and benchmarking:

./target/release/zerocell_excel_matrix read-sparse ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix benchmark-read ./path/to/input.xlsx --iterations 25 --warmup 3 --parallel --fail-avg-ms 120 --fail-p95-ms 200 --pretty

PII-safe export mode:

./target/release/zerocell_excel_matrix read-safe ./path/to/input.xlsx Sheet1 --pretty
./target/release/zerocell_excel_matrix read-safe ./path/to/input.xlsx Sheet1 --detect-only --pretty

Generate and apply patch workflow:

./target/release/zerocell_excel_matrix propose-patch ./path/to/input.xlsx Sheet1 ./cell_map.json --pretty > patch.json
./target/release/zerocell_excel_matrix validate-patch ./path/to/input.xlsx ./patch.json --pretty
./target/release/zerocell_excel_matrix apply-patch ./path/to/input.xlsx ./patch.json ./output.xlsx --pretty
./target/release/zerocell_excel_matrix validate-patch ./path/to/input.xlsx ./patch.json --policy ./policy.json --pretty
./target/release/zerocell_excel_matrix apply-patch ./path/to/input.xlsx ./patch.json ./output.xlsx --policy ./policy.json --backup-dir ./backups --audit-log ./logs/patch-audit.log --pretty

Recalculate formulas natively (LibreOffice required):

./target/release/zerocell_excel_matrix recalculate-workbook ./path/to/input.xlsx --pretty

Notes:

• recalculate-workbook resolves scripts/recalc.py from the current working directory, executable-relative bundle paths, or ZEROCELL_RECALC_SCRIPT.
• Python interpreter override: ZEROCELL_PYTHON_BIN.
• Windows recalculation no longer depends on AF_UNIX; the helper skips the Unix socket shim there and uses native subprocess timeouts.

Incremental optimization note:

• update now short-circuits with status: \"no_changes\" and copies the source workbook as-is when no cell-level diff is detected.

Analytics stack note:

• Excel workbook I/O remains on calamine + rust_xlsxwriter because ZeroCell needs formula fidelity, sheet preservation, and patch-safe writes.
• Columnar analytics for sparse extraction, schema inference, and column profiling now use polars where that is a net improvement, with a native fallback for oversized cell frames.
• Anomaly scans reuse the same profiling layer so agents can gate edits on structural issues before patching.
• Join primitives now let agents align sheet-backed tables and named ranges without flattening the workbook externally first.

Workbook-native agent note:

• Users can tag notes/comments with @agent and mention cells/ranges directly in the comment text.
• ZeroCell currently scans classic XLSX notes/comments and emits structured task payloads via scan-agent-comments, including deterministic task_id and default task_status = "pending".
• sync-agent-tasks writes a sidecar task-state file under .zerocell/agent-tasks/ by default and preserves operator status across rescans.
• resolve-agent-task-context overlays any persisted task status and returns the anchor window plus explicit reference slices, including cross-sheet refs.
• Design details and future lifecycle work are documented in docs/AGENT_COMMENT_WORKFLOW.md.

Setup streamlining note:

• init safely merges a zerocell MCP entry into an existing opencode.json or creates one if missing.
• init also writes a local project helper file at .zerocell/SKILL.md.
• doctor now reports runtime platform, working directory, and active override environment variables in addition to individual checks.

JSON payload (write)

{
  "sheet": "Model",
  "matrices": {
    "values": [[1, 2], [null, null]],
    "formulas": [[null, null], ["=A1+B1", "=A1-B1"]]
  }
}

Validation and security checks used in this iteration

• cargo test
• cargo check
• cargo audit
• cargo clippy --all-targets --all-features -- -D warnings
• cargo deny check
• cargo test --test golden_corpus --all-features

Integration docs

• See docs/SCHEMA_AND_INTEGRATIONS.md for:
  • stable payload/patch/diagnostic/telemetry schemas
  • MCP tool contract examples
  • Rust SDK usage examples
• See docs/SKILL_API_CONTRACT.md, docs/CHANGELOG_POLICY.md, and docs/RELEASES_AND_ROLLBACK.md for production contract governance and release lifecycle operations.
• See docs/CONTRACT_MIGRATION.md and ops/dashboard/README.md for downstream migration and operator observability starter assets.
• See distribution/README.md, security/policies/SBOM_POLICY.md, and integration/chaos/README.md for single-binary bundle, SBOM gate, and chaos resilience operations.