Skip to content

Complete Excel Agent 0.5 private-beta hardening and vNext foundations - #37

Draft
itscharles175 wants to merge 7 commits into
mainfrom
codex/finish-excel-agent
Draft

itscharles175 wants to merge 7 commits into
mainfrom
codex/finish-excel-agent

Conversation

@itscharles175

@itscharles175 itscharles175 commented Aug 10, 2026 •

Copy link
Copy Markdown
Owner

Outcome

This draft completes the repository-side private-beta hardening program and lands the experimental vNext clean-break foundations at commit c540dce80144b3b1d7ef7f17a9217580c9a9363d.

The supported 0.5 path now has stronger review/apply/recovery controls, bounded worker admission, encrypted storage and migration tooling, sparse local-first spreadsheet hydration, accessible history/recovery UX, and a fail-closed local release plane. vNext adds frozen contracts, portable domain cores, an exact-proof OPC/XLSX slice, transport-neutral SDKs, and a native local persistence host—without claiming a deployed service.

How it looks

Synthetic browser workbook preview

This is a locally rendered browser-workbook preview with synthetic values. It demonstrates the grid, formula bar, explicit AI preview, sync health, and recovery controls. It is not native Excel, private-workbook, production, or release-certification evidence.

Root cause and trust boundary

The prior branch had strong feature breadth but incomplete cross-cutting authority, recovery, lifecycle, evidence, and offline-verification boundaries. This change makes those boundaries explicit and fail closed:

  • Excel remains authoritative for supported live mutation and calculation.
  • Cloud egress requires explicit policy and digest-bound approval; no silent fallback is allowed.
  • Session deletion, cancellation, lifecycle purge, and storage rotation are durable fences.
  • vNext domain cores are experimental and transport-neutral; the native service host is local persistence only.
  • Exact package/operation proof—not a general OOXML claim—controls the experimental XLSX export slice.
  • Repository tests cannot manufacture native-host, private-corpus, production, signing, licensing, or legal evidence.

Scope

  • Legacy 0.5 hardening
  • vNext experimental foundations
  • Generated contracts and API types included
  • No hidden legacy/vNext dependency or dual-write path introduced

What landed

Area Outcome
Taskpane and spreadsheet Accessible onboarding/help/recovery, durable local history, sparse large-workbook viewport reads, fenced sync replay, Office/coauthor invalidation, and visible authority/queue health
Apply and lifecycle Exact rollback/acknowledgement proof, cancellation propagation, graceful drain, durable tombstones, and anti-resurrection fences
Storage and migration SQLCipher evidence/rotation, opt-in encrypted managed objects, PostgreSQL parity, one-way v0.5 neutral intake, and manifest-last materialization
Run control and egress CAS event streams, bounded replay cursors, idempotent commands, one-use digest-bound cloud approval, and explicit no-fallback receipts
vNext contracts and cores Workbook, formula, run, collaboration, and fenced bridge cores with canonical recovery, stable identities, bounded resources, and exact receipts
OPC/XLSX Complete ZIP/part/XML/relationship validation, exact no-edit bytes, constrained existing-cell edits, opaque-part equality, signature/calc-chain fences, and restart idempotency
SDK and local host TypeScript/Python clients for all current Workbook/Run/Collaboration/Formula RPCs plus native-only authenticated local snapshot/CAS persistence
Release and operator plane Self-hosted runners, hermetic Rust tools, verified offline dependency cache, signed promotion/distribution tooling, evidence portal, and pending-only native-host certification harness

Risk and compatibility

  • Workbook fidelity: Supported Office.js behavior remains authoritative. The new Rust codec exports only an exact package and mutation it can re-open and prove; unsupported/signature-sensitive cases are fenced.
  • Apply / rollback / recovery: State transitions are CAS/idempotency bound; terminal, deletion, and host-acknowledgement fences reject ambiguous continuation.
  • Identity / ownership / privacy: Tenant, owner, workbook, session, actor, and stable-axis identities are rebound at storage and replay boundaries. Reports and metrics use bounded/redacted fields.
  • Storage / migration / retention: Migrations are additive. v0.5 intake is one-way inert data; there is no reverse conversion, hidden compatibility runtime, or dual write.
  • Egress / licensing / dependencies: No provider fallback is implied. HyperFormula is omitted from the standard build. New Rust registry dependencies are exact-pinned, reviewed, and represented in the SBOM/notices.
  • Performance / large workbooks: Sparse viewport hydration, bounded queues, iterative graph traversal, and fixed workload tests prevent the new paths from becoming unbounded defaults.
  • Rollback / forward fix: c540dce can be reverted to branch SHA d3b4fda; additive schemas and opt-in experimental stores remain dormant unless explicitly constructed. A scoped forward fix is preferred once data has been created under a new additive schema.

Evidence

All commands ran locally or in local Docker/self-hosted-compatible environments; no GitHub-hosted runner was used.

  • Red-first and adversarial regressions across each implementation lane
  • Full backend: 1,034 passed / 9 environment-gated PostgreSQL skips / 0 failed
  • Plugin: 207 Vitest + 50 Office mocks + 16 Playwright; typecheck, ESLint, production build/budget, and critical audit passed
  • Workbook worker: 66 passed; smoke/audit passed; parser corpus 31 matched / 0 mismatched
  • Fast policy plane: 95 release contracts + 133 operator/release tests (1 host skip) + 11 encryption tests
  • vNext Rust: formatting, strict all-target Clippy, 186 workspace tests, and explicit 8-package WASM checks passed for all 9 workspace members
  • Hermetic offline replay: cached tools image was removed locally, restored only from the verified tar, and completed with --network none, Cargo offline, read-only source/vendor mounts
  • vNext generated/baseline checks, 7 TypeScript programs, 122 Python tests, SDK loopbacks (network=false), and npm audit passed
  • No-cache backend/edge images, packaged worker smoke, production manifest/assets, source-map exclusion, and bundle budget passed
  • Docs: 30 documents / 99 links / 21 syntax snippets / 10 OpenAPI operations / 3 runnable examples
  • SBOM, lock/package integrity, OpenAPI freshness, pinned Actionlint, Ruff, mypy, staged whitespace, and staged secret-signature scans passed
  • GitNexus compare-to-main reviewed: CRITICAL — 625 files / 8,763 symbols / 300 flows. This is the expected whole-program fanout and remains an explicit review risk.

Genuine external blockers

The strict release prerequisite command intentionally remains red with six blocker groups:

  1. exact-SHA signed release-evidence index and out-of-band Ed25519 trust key;
  2. completed 54-row Windows Excel smoke metadata/results;
  3. privacy-reviewed Windows Excel artifact pack;
  4. private golden-workbook fixture corpus;
  5. promoted generated-fixture inventory audit evidence;
  6. production-like anonymized replay baseline.

Target-topology PostgreSQL/OIDC/mTLS, real Windows/Mac/Web host execution, independent reviewer/witness approvals, signing/key custody, licensing/legal approval, and production deployment evidence are not fabricated by this PR.

Release posture

  • This PR does not claim GA, signing, native-host certification, private-corpus coverage, production evidence, Marketplace publication, or deployment.
  • No GitHub-hosted runner minutes are required: all 4 workflows / 10 jobs use explicit self-hosted labels, and all 26 external action refs are pinned to full 40-character SHAs.
  • No tag or GitHub Release is created; keep this PR draft until the external evidence owners complete the exact-SHA gates.

itscharles175 and others added 7 commits May 12, 2026 08:17
Trust correctness foundations
- workbook-worker: silent OOXML regen fallback now requires explicit consent;
  .xlsm fallback gated behind allowMacroRegeneratedFallback; fallbackTriggered
  surfaced on fidelity/trust report.
- backend: plan state machine enforces draft -> approved -> applied paths and
  V3 lifecycle transitions; illegal transitions return 409 instead of silently
  back-dating plans.
- backend: require_apply_eligibility is now server-authoritative via
  BRAIN_APPLY_ELIGIBILITY_MANDATORY env; clients can only ratchet up.
- backend: workbook_snapshots gain state_hash column (migration 0014) so
  rollback can detect tampering via state_verified.
- backend: apply-token consumption + dedupe — open attempts coalesce on retry,
  completed tokens reject reuse with apply_token_consumed.
- backend: plan approval refuses non-atomic batches (multiple ops on same
  sheet+range) before snapshot/audit.

Security and injection
- backend: new cell_value_safety.sanitize_literal + is_potential_formula;
  write_cell validator warns on formula-trigger values; source_evidence
  sanitizes extracted labels.
- backend: ZIP-bomb hardening for .xlsx/.xlsm uploads — entry-count, total
  uncompressed size, compression ratio, path-traversal and absolute-path
  rejection.
- backend: WS API key accepted via Authorization header or
  sec-websocket-protocol; query-string fallback logs a deprecation warning.
- backend: CORS allow_methods + allow_headers explicitly pinned.
- backend: STATIC_KEY_ADMIN_ENABLED default flipped to false.
- backend: macro detection prefers ooxml.vba_project_present over extension
  sniffing (spoof-resistant).

OOXML fidelity
- worker: contentTypeIntegrity flags vbaProject.bin + non-macro workbook
  override and missing application/vnd.ms-office.vbaProject default/override.
- worker: trustReport now exposes ooxml.fallbackTriggered.

Sync engine reliability
- plugin: stableQueueHash upgraded to 64-bit FNV-1a (16 hex, ~4B collision
  boundary).
- plugin: SYNC_MAX_ATTEMPTS + jittered exponential backoff helper;
  classifySyncFailure distinguishes terminal vs transient.
- plugin: sync-replay keeps transient failures pending for retry inside the
  attempts budget; only terminal or budget-exhausted failures mark failed.

Patch + storage durability
- plugin: appendSyncJournal dedupes by (idempotencyKey, kind, status,
  revision); WorkbookStorageQuotaError surfaces remaining bytes from
  navigator.storage.estimate.

Calculation parity
- plugin: calc-worker registers workbook-scope named ranges via
  addNamedExpression, counts and warns on volatile functions, reports
  namedRangesRegistered + volatileFormulaCount + warnings.

AI pipeline correctness and cost
- backend: REACT_STEP_TOKEN_BUDGET and REACT_TOTAL_TOKEN_BUDGET env-tunable
  budgets; ReActTrace records token totals and aborts with REFLECT when total
  budget is exceeded.

Backend hardening
- backend: WorkbookIngestion/Export/Diff synchronous calls now wrapped in
  asyncio.wait_for(asyncio.to_thread(...), timeout) with HTTP 504 on timeout.
- backend: rate limiter prunes stale buckets every 60s.

Frontend polish
- plugin: per-endpoint timeouts (5s/health, 60s/spreadsheet,
  120s/plan-simulation-experiments); built-in exponential-with-jitter retry
  for idempotent GETs on 408/429/502/503/504/network/timeout; honors
  Retry-After.

Tests + release evidence
- pyproject.toml adds unit/integration/contract/security pytest markers.
- New scripts/check_version_sync.py enforces VERSION across manifest.xml,
  package.json, backend/config.py.
- New backend tests: test_plan_state_machine (12), test_snapshot_integrity
  (4 incl. tamper detection).
- New worker test: OOXML preserve fallback for macro workbooks requires
  explicit consent.

Verification: 216/216 backend tests, 32/32 worker tests, 37/37 plugin
vitest, 11/11 plugin office-mock pass; typecheck + lint clean; OpenAPI
types in sync; VERSION sync clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
[skip ci]

Verified locally; do not consume or depend on GitHub-hosted Actions minutes.
@itscharles175 itscharles175 changed the title Harden Excel Agent 0.5.0 and bootstrap the vNext clean break Complete Excel Agent 0.5 private-beta hardening and vNext foundations Aug 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant