@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/xlsx-react/agent-llm-interaction-layer-docx-xlsx.md

@@ -1,621 +0,0 @@
-# Agent / LLM Interaction Layer for DOCX and XLSX Editors
-
-## Interpretation of the problem
-
-You’re building a **shared agent/LLM interaction layer** that can sit on top of two editors: a shipped React-based **Word review editor** and a planned React-based **Excel-compatible spreadsheet editor**. The goal is not “chat next to a document,” but a **deterministic, auditable, compatibility-honest** system that can: (a) answer questions, (b) propose edits, and (c) execute edits *only* via typed runtime commands—while preserving OpenXML fidelity and never silently dropping unsupported content.
-
-The key constraint is architectural: **React is a projection layer**. Canonical truth lives in the runtime; all editor mutations must flow through **commands → transactions → commit**, and rendering must consume snapshots from an external store subscription boundary.
-
-The key product constraint is fidelity: treat `.docx` and `.xlsx` as **OPC packages**—with parts, relationships, content types, and markup-compatibility rules—not as a handful of XML files. This implies that “unsupported but preservable” content must survive import → runtime edit → export, and exported artifacts must reopen in modern host apps without repair prompts.
-
-So the interaction layer must provide a shared mental model across DOCX (linear text + anchors + review artifacts) and XLSX (grid + formulas + ranges + sheet/workbook objects), **without collapsing both into the least-common-denominator**. It must also explicitly surface capability boundaries using the existing taxonomy (**supported-roundtrip / preserve-only / unsupported-fatal**) and the preserve/lock/warn/block/fail response model.
-
-## Research plan
-
-The research focus is “implementation-ready,” so the plan prioritizes **existing runtime contracts** and **primary packaging semantics** before UI or prompting tactics.
-
-First, I grounded the shared agent design in the shipped Word editor’s frozen v1 contract: the runtime boundary, snapshot boundary, command execution model, warnings/errors/compatibility envelopes, and the UX/architecture constraints that govern how truth flows through the system.
-
-Second, I reviewed packaging and markup-compatibility fundamentals that matter directly for “preserve-only must not be dropped” and “host reopening is the final standard”: OPC relationships, conformance constraints on parts/relationships, plus Markup Compatibility and Extensibility (MCE) constructs like `mc:Ignorable` and `mc:AlternateContent` that affect how unknown namespaces and alternates must be handled.
-
-Third, I targeted strong implementation references for spreadsheet abstractions and review-like constructs (ranges, tables, named items, comments, pivot tables), using official **Office JavaScript API** documentation as a proxy for what “feels native” and what abstractions users expect when they say “this range,” “this table,” or “the comment on D12.”
-
-Finally, I derived a shared tool/command contract for agent ↔ runtime integration that (a) never allows direct mutation, (b) supports simulation/proposal/approval, (c) stays honest under preserve-only and blocked states, and (d) is testable with a fixture matrix and release gates consistent with the existing DOCX repo’s compliance stance (SDK validation is necessary but not sufficient; host behavior is authoritative).
-
-## Findings
-
-The findings below separate (a) what your platform already commits to for DOCX and (b) what packaging/Excel-like object models imply for a shared agent layer.
-
-Your shipped DOCX editor runtime already defines the right shape for an agent layer
-
-The Word editor’s frozen contract is already architected like a “tool-execution runtime,” which is exactly what an agent layer needs.
-
-* **Single mutation authority:** one mounted editor session owns one runtime instance, and `DocumentRuntime` is the only mutation authority.
-* **External-store snapshots:** React renders from `RuntimeRenderSnapshot` via an external-store boundary; snapshots are projections and not persistence artifacts.
-* **Deterministic mutation pipeline:** “every mutating entry point routes through command → transaction → mapping → remap → commit → notify,” and subscriptions fire only after atomic commits.
-* **Typed command surface:** edits are expressed through a discriminated union `EditorCommand`, executed into an `EditorTransaction` with mapping and effects.
-* **Stable address model (anchors):** selections are integer positions mapped through edits; detached anchors remain inspectable instead of disappearing.
-* **Explicit trust surfaces:** warnings and errors are structured envelopes; compatibility is a separate report with the fixed feature taxonomy `supported-roundtrip / preserve-only / unsupported-fatal`, plus an explicit `blockExport` gate.
-* **Preserve/lock/warn/block/fail is a product stance, not a slogan:** unsupported but preservable content must be preserved; preserve-only regions are locked; warnings/blocks are explicit; malformed packages can fail-closed into diagnostics.
-
-This matters because an agent layer can treat the runtime as the executable substrate: “propose typed commands, simulate them, then commit them,” without ever touching DOM or OOXML directly.
-
-OPC and MCE are not optional if “preserve-only survives” is real
-
-Your internal compliance doc explicitly frames `.docx` as an OPC package and requires export to preserve ZIP integrity, required parts/relationships, content types, semantics, and preservable unsupported content. This aligns with foundational OPC norms: packages are sets of parts linked by relationships, intended to make links discoverable independent of content markup.
-
-Two packaging points are directly relevant to the agent layer’s “don’t silently break fidelity” contract:
-
-1) **Relationships are first-class, not incidental.** OPC relationships exist precisely to allow discovery and linking “without looking at the part contents,” and to attach relationships without modifying signed/encrypted parts.
-2) **Conformance constraints exist at the package layer.** OPC conformance rules include requirements on part names, relationship parts, relationship IDs, and targets. Violating these is how you end up with repairs or unreadable files.
-
-On markup compatibility: MCE defines how producers mark namespaces as ignorable and how consumers should behave in the presence of unknown namespaces. The `@Ignorable` attribute explicitly governs when unknown namespaces can be ignored without error. The `mc:AlternateContent` model is an explicit mechanism for forward compatibility—consumers choose the first matching `Choice` based on required namespaces, otherwise fallback.
-
-Why this matters for the agent layer: the agent must not propose edits that imply rewriting content across preserve-only boundaries, because those boundaries often exist specifically due to unknown namespaces/parts where safe semantics are not guaranteed. Your DOCX compliance stance makes this explicit: if you can’t support import → runtime edit → export → reopen without loss, the correct classification is preserve-only or unsupported-fatal, not “supported but flaky.”
-
-Spreadsheet interactions need native spreadsheet abstractions, not “text edits in cells”
-
-Microsoft’s official Excel JavaScript API docs are a strong reference for mental-model alignment: there is no “Cell” object; the core abstraction is `Range`, which can represent a single cell or a contiguous grid. This matters for agent design: “selection-aware” in spreadsheets is almost always “range-aware,” including things like “used range,” “table range,” “spill ranges,” etc.
-
-Key spreadsheet-level abstractions that show up repeatedly in official APIs and should be first-class in the agent model:
-
-* **Range**: values vs text vs formulas are different surfaces (`values`, `text`, `formulas`), and users talk about them distinctly.
-* **Tables**: tables have stable identity and provide distinct ranges (header, body, totals) and operations like convert-to-range.
-* **Named items (names / named ranges / named formulas)**: names are first-class objects at workbook/sheet scope and can point at a range or value; users refer to names naturally (“update the range called ExpensesHeader”).
-* **Comments as threads tied to a cell**: Excel comments are threaded discussions tied to an individual cell and tracked at workbook level.
-* **PivotTables exist as objects with refresh semantics**: even if preserve-only in v1, the agent model should “see” them as objects rather than opaque XML.
-
-So the shared agent model must include spreadsheet-native object handles (workbook/sheet/range/table/name/comment-thread), and it must treat formulas as a distinct semantic surface—not just strings in cells—because of cross-cell dependencies and calculation behavior.
-
-## Recommended design / decisions
-
-This section is the concrete spec. It answers the ten required questions explicitly and calls out tradeoffs and failure modes.
-
-Shared mental model for agent interaction across both editors
-
-The shared mental model should be:
-
-**“The runtime is the only editor. The agent is a deterministic command author and explainer, operating on stable editor abstractions, producing explicit outcomes.”**
-
-More concretely:
-
-1) The user speaks in natural language (“rewrite this paragraph,” “make this table consistent,” “explain this formula”).
-2) The agent layer translates that into one of three intents: **Explain**, **Propose**, or **Execute**.
-3) Any mutation intent becomes **typed commands** submitted to a runtime **transaction boundary**, never direct state mutation.
-4) The system always returns an explicit action state: **explanation-only**, **simulated**, **proposed**, **applied**, plus **export-risk classification** derived from runtime compatibility/warnings.
-5) Preserve-only and unsupported-fatal content are never rewritten silently; attempts to cross those boundaries produce explicit **lock/warn/block/fail** behavior.
-
-This mirrors the Word editor contract’s central principles (runtime authority, snapshot rendering, command-backed edits) while leaving room for spreadsheet-native objects.
-
-Editor abstractions the agent should target
-
-The agent should target a small set of **shared primitives** plus editor-specific specializations.
-
-Shared primitives (apply to both DOCX and XLSX):
-
-* **DocumentHandle**: `{ editorKind, documentId, sessionId, revisionToken }` (revisionToken is already a first-class runtime concept).
-* **SelectionHandle**: a discriminated union so “selection-aware” stays explicit:
-  * DOCX: `{ kind: "docx-range", anchor: number, head: number, activeRange: EditorAnchorProjection }`
-  * XLSX: `{ kind: "xlsx-range", sheetId, a1: "Sheet!A1:D10", areas?: [...] }` (support disjoint selections as `areas`, analogous to Excel’s RangeAreas).
-* **CompatibilitySurface**: `{ report: CompatibilityReport, warnings: EditorWarning[], fatalError?: EditorError }` using the existing taxonomy and export gate.
-
-Editor-specific abstractions (must be first-class, not “strings with tags”):
-
-For DOCX:
-
-* **StoryRange** / **AnchorProjection** (already defined).
-* **CommentThread** (Word comment threads) and **TrackedChangeEntry** (review actions accept/reject).
-* **OpaqueFragmentHandle** for preserve-only inline/block placeholders (already represented in surface segments/blocks as `opaque_inline` / `opaque_block`).
-
-For XLSX:
-
-* **Workbook**, **Worksheet**, **Range**, **Table**, **NamedItem**, **CommentThread**, **PivotTable** as addressable objects.
-* **FormulaRegion**: a derived abstraction grouping a range of formula cells that share structure (same R1C1 pattern, shared dependencies, spill parent, etc.). The Excel Range docs explicitly distinguish multiple formula representations (`formulas`, `formulasR1C1`, `hasSpill`).
-* **CellDataSurface**: values/text/formulas are distinct. The “set/get values vs formulas” documentation makes that explicit (values show computed values even when formulas exist; formulas show formula strings).
-
-Action classes and their execution constraints
-
-Instead of a vague “allowed/not allowed,” define action classes as **policy-driven** based on: (a) mutation vs read-only, (b) scope size, (c) crossing preserve-only boundaries, (d) export risk, and (e) whether the runtime can deterministically validate.
-
-The interaction layer should implement four execution classes:
-
-**Synchronous (auto-execute, no approval)**
-Read-only transforms and queries that do not mutate runtime state.
-* Examples: explain selection, summarize doc/sheet, list named ranges, enumerate comments, explain formula logic, locate dependencies, generate a checklist.
-* Failure mode: context insufficiency → request more structured context rather than guessing.
-
-**Proposal-only (must simulate; user must accept to apply)**
-Deterministic, bounded edits where simulation can produce a clear diff and compatibility impact.
-* DOCX: rewrite selected text, insert comment, propose tracked change acceptance/rejection suggestions (but don’t auto-accept), style normalization within supported features.
-* XLSX: set cell values/formulas in a bounded range, fill-down formulas, normalize number formats, create/update named items, add cell comments.
-* Failure mode: if simulation produces preserve-only boundary crossings or export-risk warnings, the proposal remains but is labeled export-risky or blocked depending on policy.
-
-**Approval-required (proposal + explicit “risk acknowledgement” even if supported)**
-Edits that are supported in principle but have known high-impact or non-local consequences.
-* Examples:
-  * DOCX: accept-all / reject-all changes, large-scale transformations, anything touching many anchors.
-  * XLSX: bulk refactors across sheets, mass formula rewrites, changes that modify table structure, pivot refresh/changes (even if later supported), operations that materially change calculation outcomes.
-* Failure mode: user must explicitly approve after seeing a diff summary + “what changed” + “what might break.”
-
-**Blocked in preserve-only or fatal states**
-Any action requiring semantic rewriting inside preserve-only regions or any session with unsupported-fatal states that prevent trustworthy preservation.
-* DOCX: opaque fragments are locked; attempts to rewrite inside must block or require a destructive “convert/downgrade” flow with explicit warning.
-* XLSX: treat preserve-only package parts (unknown extensions, pivot caches, macros, external connections, charts you can’t roundtrip, etc.) as locked boundaries; edits that require rewriting them are blocked. This is the direct spreadsheet analogue of the DOCX stance.
-* Unsupported-fatal: fail closed into read-only diagnostics (still allow explanation, but no mutation and usually no export).
-
-Common tool/command contract between the LLM layer and the editor runtime
-
-The contract must be explicit, typed, and deterministic. You already have strong precedent: `EditorCommand` is a discriminated union, executed into transactions, then committed.
-
-Build a *shared* agent contract in three layers:
-
-**Layer A: Agent intents (LLM-level)**
-High-level actions the model returns (or calls) that always map to deterministic runtime commands.
-
-**Layer B: Tool calls (agent orchestrator-level)**
-Fetching context slices, running simulations, applying transactions, creating audit artifacts.
-
-**Layer C: Runtime commands (editor-level)**
-The real mutation boundary: DOCX `EditorCommand` and XLSX `SpreadsheetCommand` (to be designed similarly).
-
-A minimal shared TypeScript-like contract (conceptual, repo-ready) looks like:
-
-```ts
-// Shared: always included in every agent -> runtime request
-type AgentEnvelope = {
-agentSessionId: string;
-editorKind: "docx" | "xlsx";
-documentId: string;
-baseRevisionToken: string;   // optimistic concurrency check
-mode: "explain" | "propose" | "execute";
-user: { userId: string; displayName: string };
-trace: { requestId: string; timestamp: string };
-};
-
-// Shared selection union
-type AgentSelection =
-  | { kind: "docx"; anchor: number; head: number }
-  | { kind: "xlsx"; sheetId: string; a1: string; areas?: Array<{ sheetId: string; a1: string }> };
-
-// Shared response state model (explicit trust surface)
-type AgentActionState =
-  | "explanation_only"
-  | "simulated"
-  | "proposed_not_applied"
-  | "applied"
-  | "blocked"
-  | "failed";
-
-// Shared compatibility posture (imports existing taxonomy)
-type AgentExportPosture =
-  | { level: "safe"; blockExport: false }
-  | { level: "risky"; blockExport: false; reasons: string[] }   // warnings, preserve-only touched
-  | { level: "blocked"; blockExport: true; reasons: string[] }; // unsupported-fatal or fatal errors
-
-// Shared "tool result" envelope
-type AgentToolResult<T> = {
-state: AgentActionState;
-exportPosture: AgentExportPosture;
-compatibility: CompatibilityReport; // existing shape
-warnings: EditorWarning[];
-error?: EditorError;
-payload?: T;
-};
-```
-
-The key decision is that the LLM does **not** emit arbitrary patches; it emits either:
-
-* a request for more context slices, or
-* a set of **typed commands** (or a higher-level “action” that deterministically compiles to commands inside the runtime).
-
-This matches your repo’s non-negotiable: “All edits must flow through commands and transactions.”
-
-How editors should expose structured context without leaking raw OOXML into prompts
-
-The agent should never receive “the OOXML package.” Instead, create a **context slicing API** that serves *semantic projections* with strict size limits and explicit redaction.
-
-Design principle: **Context is pull-based, scoped, and typed.** The model gets an initial “index card” summary, then can request specific slices.
-
-Baseline context (always available):
-
-* **Runtime snapshot summary:** doc/workbook id, revision token, ready/dirty/readOnly, selection.
-* **Compatibility/report summary:** `blockExport`, preserve-only count, unsupported-fatal count, top warnings/errors.
-* **Selection neighborhood:**
-  * DOCX: selected plain text + a small surrounding window; plus surface segments and any `opaque_*` tokens inside the selection.
-  * XLSX: a rectangular grid sample with values/text/formulas for the selection (`values`, `text`, `formulas` are distinct surfaces).
-
-Optional context slices (agent can request explicitly):
-
-* **DOCX slices:** comments in selection, tracked changes in selection, document stats, headings outline, hyperlink list.
-* **XLSX slices:** named items, table definition metadata, table header/body ranges, comment threads for cells, pivot table metadata (even if preserve-only), dependency summary for a formula region.
-* **OOXML boundary descriptions (not raw XML):** a “preservation map” that describes which parts/regions are opaque and why (featureKey + message + affected anchor or range), matching the existing compatibility entry pattern.
-
-Critical security and product honesty point: for any slice that the agent did not fetch, the UI must not imply the agent “reviewed everything.” The trust surface should show “what the agent looked at” as a first-class artifact (see below).
-
-Handling “change this” when the target crosses supported and preserve-only boundaries
-
-This is the fidelity trap where products get dishonest. Implement an explicit boundary algorithm:
-
-1) **Resolve target surface**: map “this” to a concrete selection handle (DOCX anchor range or XLSX range).
-2) **Intersect with compatibility/preservation map**: identify whether the target intersects any preserve-only or unsupported-fatal feature entries or locked opaque fragments/cells.
-3) **Compute required semantic operations**: does the requested change require rewriting preserve-only content or only supported surfaces around it? This must be conservative: if uncertain, treat as preserve-only.
-4) **Return explicit response model** (never silent):
-   * **preserve**: keep content untouched but proceed around it
-   * **lock**: prevent direct edits inside
-   * **warn**: require user acknowledgement for destructive boundary crossing
-   * **block**: refuse operation if it would require unsupported semantic rewrite
-   * **fail**: session-level failure for malformed/unpreservable states
-
-In agent UX terms, if the user says “change this” over a mixed region, the default behavior should be:
-
-* produce an explanation of what is editable vs locked,
-* propose a safe alternative that edits supported content only, and
-* if the user explicitly asks for destructive conversion, gate it behind a “warn + explicit approval + export-risky labeling” flow.
-
-What good UX looks like across both editors
-
-Your Word editor UX guide and frontend architecture already codify strong patterns: the editor surface is central; review rails are distinct; health surfaces explain preserve-only and fatal states; “trust” is not hidden.
-
-Build the agent UX as a **four-pane mental structure** that works in both editors:
-
-1) **Conversation pane** (left rail or right rail section): user prompt + agent response + “what I used” citations (context slices).
-2) **Explanation pane** (inline in conversation): reasoning and interpretation of the selection/range and constraints.
-3) **Proposed changes pane** (diff view): deterministic, command-backed change list + preview.
-4) **Trust/health pane** (always visible when needed): compatibility report deltas, preserve-only touched, export-risk posture. This maps to your existing “Health” tab concept.
-
-Specific UX patterns by feature:
-
-* **Inline suggestions (DOCX):** show suggestion chips anchored to ranges (existing anchor model), with accept/reject actions that call runtime commands.
-* **Inline suggestions (XLSX):** highlight affected cells/ranges; show a “diff table” with old/new values/formulas; allow accept/reject per change group. This aligns with range-centric Excel semantics.
-* **Rewrite proposals (DOCX):** show “before/after” text blocks plus a command list; never apply automatically by default.
-* **Formula explanations (XLSX):** show formula text, referenced ranges, and computed interpretation using `formulas` vs `values` distinction; present as explanation-only unless user explicitly asks to edit.
-* **Workbook summaries:** show sheet list, used-range summaries, table list, named item list, pivot table list (even if preserve-only), comment counts; keep it structured and navigable.
-* **Comments generated by the agent:** treat comments as first-class threads (DOCX and XLSX). Word already has explicit add/open/resolve flows. Excel comments are threads tied to a cell.
-
-Trust surface and explicit state labeling
-
-The trust surface must make it impossible for the user to confuse:
-
-* explanation-only,
-* simulated,
-* proposed-but-not-applied,
-* applied-to-canonical-state,
-* export-risky.
-
-The agent layer should present a standard “action badge” for every agent response, derived from `AgentActionState` + `AgentExportPosture`.
-
-Mapping to your existing system:
-
-* Export risk and blocks should be derived from the runtime’s compatibility report (including `blockExport` and `unsupported-fatal` entries).
-* Warning-backed risk should be derived from runtime warnings and preserve-only touches, not from model “confidence.”
-* For OOXML forward-compat concerns, surface MCE-related semantics as “preserve-only reason” rather than dumping XML. MCE explicitly defines ignorable namespaces and alternate content selection mechanics.
-
-Telemetry, audit trail, and replay model
-
-You already have a host-level datastore adapter that can log events (`logEvent?`) and persist snapshots/exports.
-
-The agent layer needs an **append-only audit log** with replay capability. The minimum viable audit record per agent action:
-
-* agentSessionId, requestId, timestamp
-* editorKind, documentId, baseRevisionToken
-* requested mode (explain/propose/execute)
-* context slices used (IDs + hashes + size)
-* model output (structured tool calls, not raw chain-of-thought)
-* simulation result (diff summary + compatibility delta + warnings)
-* user decision (accepted/rejected/edited)
-* applied commands (exact typed commands, in order)
-* resulting revisionToken + export posture
-
-Replay model:
-
-* Since canonical truth is stored as a `PersistedEditorSnapshot` and restored from canonical state without rerunning OOXML import, replay should be “load snapshot → apply recorded commands → verify revisionToken deltas.”
-* For DOCX, the runtime already produces deterministic commit boundaries and revision tokens.
-* For XLSX, the workbook runtime must adopt the same pattern (revisionToken increments per commit).
-
-Minimum viable shared architecture across both editors
-
-Make the agent layer a **shared platform module** with editor adapters. Do not bury agent behavior inside React components.
-
-A minimal architecture:
-
-* `agent-core/` (shared):
-  * schemas: `AgentEnvelope`, `AgentSelection`, `AgentActionState`, `AgentExportPosture`
-  * tool contract: context slice requests, proposal packaging, simulation/apply pipeline
-  * policy engine: action class resolution + preserve/lock/warn/block/fail rules
-  * audit/telemetry: event record builder, hashing, replay harness
-
-* `agent-docx-adapter/` (DOCX-specific):
-  * context extraction from `RuntimeRenderSnapshot.surface`, comments, trackedChanges
-  * command mapping to existing `EditorCommand` union
-  * sandbox simulation via snapshot-clone runtime instantiation (see deliverables)
-
-* `agent-xlsx-adapter/` (XLSX-specific):
-  * context extraction: selected range values/text/formulas; tables; named items; comments; pivot metadata
-  * command mapping to `SpreadsheetCommand` union (new, DOCX-inspired)
-  * sandbox simulation: workbook runtime clone from persisted snapshot (design requirement)
-
-* `agent-ui/` (shared React components):
-  * conversation pane + context citation chips
-  * proposal diff viewer (pluggable doc/range renderer)
-  * trust badge + compatibility delta panel (reuses “Health” concept)
-
-This matches your repo guidance: keep content model, review model, preservation, UI state, import/export boundaries separate, and don’t use the Open XML SDK in the shipped runtime.
-
-## Risks and open questions
-
-The honest risks here aren’t “LLMs make mistakes” (they do), but the product integrity traps where a system *appears* to work while quietly corrupting fidelity or trust.
-
-Determinism vs. model creativity
-
-If the LLM can emit arbitrary patches (text diffs, cell diffs) without a typed command contract, the system becomes untestable and non-deterministic. The contract must force the model into a small space of structured actions, even if that feels “less magical.”
-
-Simulation fidelity and performance
-
-Simulation by “clone runtime from snapshot, apply commands” is clean and keeps the live runtime pure, but it may be expensive for large documents/workbooks. Your Word editor currently runs in the main thread with no Web Workers. If XLSX follows that constraint, simulation must be bounded and possibly incremental.
-
-Spreadsheet scope creep
-
-Excel-compatible isn’t just cells: tables, named items, pivot tables, comments, charts, external connections, macros, conditional formatting, data validation, etc. Many of these will be preserve-only early. The agent design must be brutally honest: if an operation can’t be proven safe for import → edit → export → reopen, it stays preserve-only or unsupported-fatal.
-
-Crossing preserve-only boundaries
-
-The hardest UX is not blocking; it’s explaining clearly *why* something is locked and what alternatives exist without implying the system can “just handle it.” This must be standardized: a preserve-only boundary always yields explicit lock/warn/block behavior.
-
-Validation vs. real host behavior
-
-Open XML SDK validation is necessary but not sufficient; your repo says Word behavior is final, and SDK validation is not an authorization to “repair heuristics.” Even at the package level, conformant relationships/parts matter, but host apps still have quirks.
-
-Open questions to resolve before locking the spec into v1
-
-* Should the agent layer be allowed to “execute” by default in any mode, or should v1 be proposal-first with an opt-in “direct execution” switch per host? This affects trust posture and audit requirements.
-* How do you want to represent XLSX “detached anchors” analogues (e.g., a comment tied to a cell that gets deleted, or a named range whose target moves)? The Word model has explicit detached anchors; XLSX needs an equivalent if you want honest review trails.
-* What is the minimum spreadsheet command set that can be certified against “reopen in Excel without repair prompts” early? This dictates what the agent can safely do.
-* How will you surface MCE/unknown namespace issues in XLSX packages without showing XML? The compatibility report pattern can carry “featureKey + message + affected range,” but the importer must generate those consistently.
-
-## Concrete deliverable in the requested format
-
-This section is a repo-ready deliverable: interaction model, command/tool interfaces, UX patterns, safety/trust rules, approval flows, implementation phases, open questions, and test/release gates.
-
-Interaction model
-
-Define a strict interaction loop with explicit runtime boundaries:
-
-1) **Context hydration** (read-only): agent layer requests baseline context + selection slice.
-2) **Classification**: agent decides whether the user asked for explain/propose/execute (default: propose for mutations).
-3) **Plan output**: agent emits a structured `AgentPlan` and either requests more slices or emits commands.
-4) **Simulation transaction**: run commands in sandbox runtime clone; generate diff + compatibility delta.
-5) **Present**: show explanation + proposed changes + trust badge + risk posture.
-6) **User decision**: accept/reject/edit the plan.
-7) **Commit**: apply commands via live runtime dispatch in a single host-visible transaction group; emit audit log entry.
-
-Command/tool interface examples
-
-Define a minimal tool surface that the LLM can call (or that the orchestrator can call on its behalf). Keep it small.
-
-**Tool: `context.get`**
-Fetch structured context slices; must be explicit in scope.
-
-```ts
-type ContextGetRequest =
-  & AgentEnvelope
-  & {
-selection?: AgentSelection;
-slices: Array<
-        | { kind: "docx.selection_text"; maxChars: number; includeSurrounding?: number }
-        | { kind: "docx.comments_in_selection" }
-        | { kind: "docx.tracked_changes_in_selection" }
-        | { kind: "xlsx.range_grid"; sheetId: string; a1: string; include: ("values"|"text"|"formulas")[]; maxCells: number }
-        | { kind: "xlsx.tables_overlapping_range"; sheetId: string; a1: string }
-        | { kind: "xlsx.named_items"; scope: "workbook"|"sheet"; sheetId?: string; maxItems: number }
-        | { kind: "xlsx.comments_in_range"; sheetId: string; a1: string }
-        | { kind: "compatibility.summary" }
-      >;
-    };
-
-type ContextGetResponse = AgentToolResult<{
-slices: Record<string, unknown>;     // keyed by slice request ids
-redactions: Array<{ sliceId: string; reason: string }>;
-}>;
-```
-
-Why this structure: it enforces “don’t leak the full package,” and it gives you a UI-native “what the agent saw” artifact for trust.
-
-**Tool: `changes.simulate`**
-Run a command batch against a sandbox runtime.
-
-```ts
-type SimulateRequest =
-  & AgentEnvelope
-  & {
-selection?: AgentSelection;
-commands: Array<DocxEditorCommand | XlsxEditorCommand>;
-expectedEffects?: Array<"text_change"|"formula_change"|"format_change"|"comment_change">;
-limits: { maxChangedAtoms: number; maxRuntimeMs: number };
-    };
-
-type SimulateResponse = AgentToolResult<{
-diff: {
-kind: "docx" | "xlsx";
-summary: string;
-atomsChanged: number;
-docx?: { before: string; after: string; affectedAnchors: Array<{ from: number; to: number }> };
-xlsx?: { cells: Array<{ a1: string; before: { value?: any; formula?: string }; after: { value?: any; formula?: string } }> };
-  };
-commandDigest: string; // hash of normalized commands
-compatibilityDelta: {
-blockExportChanged: boolean;
-newWarnings: EditorWarning[];
-newFeatureEntries: CompatibilityFeatureEntry[];
-  };
-}>;
-```
-
-This bakes in two “honesty” properties: (a) simulation is distinct from apply, and (b) export posture is always computed from compatibility/warnings, not inferred.
-
-**Tool: `changes.apply`**
-Apply the exact simulated command batch to the live runtime, guarded by `baseRevisionToken`.
-
-```ts
-type ApplyRequest =
-  & AgentEnvelope
-  & {
-commands: Array<DocxEditorCommand | XlsxEditorCommand>;
-commandDigest: string;  // must match simulation
-approval: { approvedByUserId: string; approvedAt: string; rationale?: string };
-    };
-
-type ApplyResponse = AgentToolResult<{
-committedRevisionToken: string;
-committedAt: string;
-undoBoundaryId?: string;
-}>;
-```
-
-This enforces “what you apply must match what you showed.” It also supports optimistic concurrency: if the revision token changed, block and require re-simulation.
-
-DOCX command subset (existing)
-
-For DOCX, reuse `EditorCommand` and a constrained subset for agent use in v1; your runtime already supports dispatching these commands and producing deterministic commit boundaries.
-
-Examples the agent can output:
-
-```ts
-// Replace selected text with new text (via the runtime's text command sequence)
-{ type: "text.insert", text: "…" }
-{ type: "text.delete-backward" }
-
-// Add a comment anchored to current selection
-{ type: "comment.add", comment: { … } }
-
-// Open/resolve/reopen comment threads
-{ type: "comment.open", commentId: "…" }
-{ type: "comment.resolve", commentId: "…" }
-```
-
-Note: the agent layer should prefer high-level “replace selection” compound actions that compile to a deterministic sequence of primitive commands, rather than letting the model freestyle multi-step editing. This is a product honesty measure: fewer degrees of freedom means fewer unexpected diffs.
-
-XLSX command subset (new; must mirror DOCX rigor)
-
-Design `XlsxEditorCommand` as a discriminated union parallel to `EditorCommand`, with explicit range semantics.
-
-Minimum v1 command surface (agent-safe):
-
-```ts
-type XlsxEditorCommand =
-  | { type: "selection.set"; selection: { sheetId: string; a1: string; areas?: Array<{sheetId:string;a1:string}> } }
-  | { type: "range.setValues"; sheetId: string; a1: string; values: any[][] }
-  | { type: "range.setFormulas"; sheetId: string; a1: string; formulas: string[][] }
-  | { type: "range.clear"; sheetId: string; a1: string; mode: "values"|"formats"|"all" }
-  | { type: "comment.add"; sheetId: string; cellA1: string; body: string }
-  | { type: "comment.reply"; commentId: string; body: string }
-  | { type: "namedItem.add"; scope: "workbook"|"sheet"; name: string; referenceA1: string; sheetId?: string }
-  | { type: "table.convertToRange"; tableId: string }; // if/when supported
-```
-
-This mirrors Excel’s own object model emphasis on ranges and avoids inventing a “cell mutation API” that doesn’t match user expectations.
-
-Safety/trust rules (non-negotiable)
-
-These rules are the spec-level guardrails that make the system honest:
-
-* The agent must never mutate state directly; it must propose or invoke typed runtime commands.
-* Any mutation must be simulatable; if you can’t simulate it deterministically, it cannot be auto-applied in v1.
-* Preserve-only regions are locked; agent edits inside them are blocked unless the user explicitly enters a destructive conversion flow (warn + risk acknowledgement).
-* Unsupported-fatal states fail closed: explanation-only allowed; mutation and export blocked.
-* Export posture must be derived from compatibility report + warnings + errors. Never infer from model confidence.
-* Open XML SDK is for CI/service validation, not shipped runtime transformations.
-
-Approval flows
-
-Implement two layers of approval:
-
-* **Proposal approval**: user accepts a proposed change set (single-step accept or per-change accept).
-* **Risk acknowledgement approval**: required when the simulation indicates any of:
-  * preserve-only content touched,
-  * new warnings of `export_roundtrip_risk` class,
-  * any newly introduced compatibility feature entries that are not supported-roundtrip, or
-  * operation crosses a policy threshold (too many atoms, too many sheets).
-
-The apply step must re-check `baseRevisionToken` and command digest to prevent stale approvals and “apply something different than what was shown.”
-
-Implementation phases
-
-Phase boundaries are defined by what can be certified safely.
-
-**Phase Alpha: shared agent scaffolding (DOCX only, explain-only)**
-Ship `agent-core` + DOCX adapter for context slices and explanations; no mutation. Use this to validate context slicing, trust UI, and audit logging.
-
-**Phase Beta: DOCX proposal mode (bounded text + comments)**
-Enable proposal + simulation + approval for: rewrite selected text, add comment, small formatting normalizations that are already supported-roundtrip. Gate apply behind simulation.
-
-**Phase Gamma: XLSX runtime + schema of commands + proposal mode for ranges**
-As soon as XLSX runtime exists, implement range context slices and a minimal `XlsxEditorCommand` set: set values/formulas, add comments, add named items. This matches Microsoft’s range-centric model and gives agent “real” spreadsheet capabilities early.
-
-**Phase Delta: cross-editor parity + shared trust UI + replay harness**
-Unify UI components, finalize audit schema, build replay runner that replays agent-applied commands from snapshots for both editors.
-
-Test matrix, fixture plan, and release gates
-
-Reuse the DOCX repo’s stance: fixtures + package integrity checks + Open XML SDK validation + preserve-only survival checks + host certification; SDK validation is necessary but not sufficient.
-
-For the agent layer, add two new fixture dimensions:
-
-* **A-dimension (agent action scripts):** deterministic sequences of tool calls and expected normalized command outputs.
-* **R-dimension (roundtrip evidence):** import → simulate → apply → export → reopen checks, including “no repair prompts” in real host environments.
-
-DOCX fixtures already have a defined corpus and gate. The agent layer should add scripted interactions per fixture (e.g., “summarize,” “rewrite paragraph 2,” “add comment,” “accept a change”), ensuring that in preserve-only fixtures, the agent correctly locks/blocks instead of attempting edits.
-
-For XLSX, define an analogous minimal v1 fixture corpus (example keys, not requirements):
-
-* X01: values + basic formatting (supported-roundtrip target)
-* X02: basic formulas + relative references (supported-roundtrip target)
-* X03: named ranges + named formulas (supported-roundtrip target)
-* X04: comments as threads (supported-roundtrip target)
-* X05: tables (likely preserve-only initially; still must survive)
-* X06: pivot tables (preserve-only early; must survive; edits blocked)
-* X07: unknown extensions / extLst / MCE content (preserve-only survival)
-* X08: malformed package states (unsupported-fatal; fail closed)
-
-Release gate for agent-enabled edits (both editors):
-
-* “Simulated diff matches applied diff” (command digest enforcement).
-* “No silent drops” (preserve-only survival check).
-* “Open XML SDK validation passes” as a necessary check (CI/service only).
-* “Host reopen without repair prompts” as the final gate.
-
-Open questions (deliverable reminders)
-
-* Do you want agent-generated spreadsheet “comments” to map to Excel threaded comments exclusively, or do you also support legacy notes? Microsoft’s docs focus on threaded comments as the comment object model.
-* Should the agent be allowed to propose pivot table mutations at all in v1, or must pivots be preserve-only with explanation-only? The official API treats pivots as objects with refresh semantics, but roundtrip fidelity is non-trivial.
-* For formulas, will the runtime provide an internal evaluator, or will it treat formulas as strings and rely on Excel recalculation on open? The Range docs distinguish formulas vs values; correctness expectations differ.
-
-## Sources
-
-Repository primary sources (runtime, contracts, UX, compliance):
-
-* Runtime/host contract lock (WordReviewEditor): snapshot boundaries, command dispatch, compatibility report, events.
-* Document runtime implementation: command dispatch → transaction → commit, revision tokens, event emission.
-* Command model (`EditorCommand`, `EditorTransaction`, mapping/effects): typed mutation surface.
-* Public API types (`RuntimeRenderSnapshot`, warnings/errors, compatibility taxonomy, surface projections): shared data contracts.
-* Frontend architecture + UX guide: snapshot-driven UI, health/trust surfaces, review workflow patterns.
-* Repo guidance for agents and compliance stance: commands-only edits, preservation requirements, Open XML SDK policy.
-
-Primary/strong external references (packaging, MCE, spreadsheet abstractions):
-
-* OPC overview and mandatory structures described in a preservation-oriented reference (mandatory `[Content_Types].xml`, `_rels/`, etc.).
-* Markup Compatibility and Extensibility (MCE) overview and constructs (ignorable namespaces, process-content, must-understand).
-* ECMA/OOXML spec mirrors for OPC relationships and conformance constraints (relationships; package conformance requirements; MCE `Ignorable` + `AlternateContent` rules).
-
-Open XML SDK documentation (validation and packaging surfaces; CI/service only per your policy):
-
-* `OpenXmlValidator` documentation (validation surface; doesn’t replace host behavior).
-* Spreadsheet packaging type: `SpreadsheetDocument` as an `OpenXmlPackage`.
-* Markup compatibility processing settings in the SDK (`MarkupCompatibilityProcessSettings`, OpenSettings).
-
-Excel object model references (official Microsoft docs; informs spreadsheet-native abstractions):
-
-* Range-centric model (no Cell object; values/text/formulas distinction; getting ranges).
-* Excel comments as threaded discussions tied to a cell.
-* Excel tables as objects with ranges and identity.
-* Named items (defined names) and collections at workbook/sheet scope.
-* Pivot tables as first-class objects (useful even if preserve-only initially).