@beyondwork/xlsx-substrate-bindings 0.1.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +189 -0
  2. package/assets/blank-workbook.xlsx +0 -0
  3. package/dist/ai/agent-metadata.d.ts +387 -0
  4. package/dist/ai/agent-metadata.js +227 -0
  5. package/dist/ai/index.d.ts +5 -1
  6. package/dist/ai/index.js +6 -0
  7. package/dist/ai/mutation-bridge.d.ts +82 -0
  8. package/dist/ai/mutation-bridge.js +179 -0
  9. package/dist/ai/types.d.ts +468 -3
  10. package/dist/blank-workbook/index.d.ts +24 -0
  11. package/dist/blank-workbook/index.js +77 -0
  12. package/dist/index.d.ts +8 -3
  13. package/dist/index.js +20 -2
  14. package/dist/runtime/index.d.ts +1 -1
  15. package/dist/runtime/types.d.ts +108 -18
  16. package/dist/wasm/ai-session-bridge.d.ts +97 -0
  17. package/dist/wasm/ai-session-bridge.js +154 -0
  18. package/dist/wasm/bridge-contract.d.ts +108 -6
  19. package/dist/wasm/bridge-contract.js +146 -7
  20. package/dist/wasm/index.d.ts +43 -2
  21. package/dist/wasm/index.js +253 -23
  22. package/dist/wasm/memory-budget.d.ts +77 -0
  23. package/dist/wasm/memory-budget.js +532 -0
  24. package/dist/wasm/runtime-guard.d.ts +141 -0
  25. package/dist/wasm/runtime-guard.js +373 -0
  26. package/dist/wasm/session-router.d.ts +1 -1
  27. package/dist/wasm/session-router.js +4 -1
  28. package/dist/wasm/web.d.ts +18 -3
  29. package/dist/wasm/web.js +99 -9
  30. package/generated/wasm-web/xlsx_substrate_wasm.d.ts +66 -0
  31. package/generated/wasm-web/xlsx_substrate_wasm.js +2488 -2104
  32. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
  33. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +15 -0
  34. package/package.json +24 -4
  35. package/dist/wasm/chart-test-fixture.d.ts +0 -19
  36. package/dist/wasm/chart-test-fixture.js +0 -42
  37. package/dist/wasm/media-test-fixture.d.ts +0 -44
  38. package/dist/wasm/media-test-fixture.js +0 -160
  39. package/dist/wasm/volatile-test-fixture.d.ts +0 -7
  40. package/dist/wasm/volatile-test-fixture.js +0 -35
  41. package/generated/wasm/package.json +0 -3
  42. package/generated/wasm/sheet-window-binary.mjs +0 -482
  43. package/generated/wasm/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +0 -45
  44. package/generated/wasm/xlsx_substrate_wasm.d.ts +0 -336
  45. package/generated/wasm/xlsx_substrate_wasm.js +0 -2108
  46. package/generated/wasm/xlsx_substrate_wasm_bg.wasm +0 -0
  47. package/generated/wasm/xlsx_substrate_wasm_bg.wasm.d.ts +0 -105
package/README.md ADDED
@@ -0,0 +1,189 @@
1
+ # @beyondwork/xlsx-substrate-bindings
2
+
3
+ Conductor, the Ensemble spreadsheet runtime: native XLSX sessions compiled to
4
+ WebAssembly, for Node and browsers. The package carries one `.wasm` binary
5
+ and the TypeScript bridge over it.
6
+
7
+ ## Entry points
8
+
9
+ | Import | What it gives you |
10
+ | --- | --- |
11
+ | `@beyondwork/xlsx-substrate-bindings` | Plain-value AI and UI types, the Conductor agent metadata, `BRIDGE_VERSION` and `BRIDGE_CAPABILITIES`. No wasm. |
12
+ | `@beyondwork/xlsx-substrate-bindings/wasm` | The Node loader and the full bridge contract. |
13
+ | `@beyondwork/xlsx-substrate-bindings/wasm/web` | The browser loader. No `node:` imports. |
14
+ | `@beyondwork/xlsx-substrate-bindings/wasm/web/glue` | The wasm-bindgen glue (ES module) the browser loader takes. |
15
+ | `@beyondwork/xlsx-substrate-bindings/wasm/web/binary` | The one `.wasm` binary, for hosts that serve or preload it. |
16
+ | `@beyondwork/xlsx-substrate-bindings/blank-workbook` | `createBlankWorkbookBytes()`: a new one-sheet workbook to open and edit. No imports at all, so it bundles for a browser. |
17
+ | `@beyondwork/xlsx-substrate-bindings/assets/blank-workbook.xlsx` | The same blank workbook as a file. |
18
+
19
+ ## Node
20
+
21
+ ```js
22
+ import { loadXlsxWasmBridge } from "@beyondwork/xlsx-substrate-bindings/wasm";
23
+
24
+ const loaded = loadXlsxWasmBridge();
25
+ if (!loaded.bridge) throw new Error(loaded.reason);
26
+ const session = loaded.bridge.openWorkbookRuntimeSession(bytes, { loadMode: "full" });
27
+ ```
28
+
29
+ `loadXlsxWasmBridge()` (and the older `loadGeneratedXlsxWasmBridge()`) returns
30
+ a bridge on the process's shared default instance: every such bridge sees the
31
+ same sessions.
32
+
33
+ To run several instances, compile the binary once and instantiate from the
34
+ Module. A Module can be posted to `worker_threads`; each worker instantiates
35
+ its own instance without compiling again.
36
+
37
+ ```js
38
+ import { Worker } from "node:worker_threads";
39
+ import { compileXlsxWasmModule } from "@beyondwork/xlsx-substrate-bindings/wasm";
40
+
41
+ const module = await compileXlsxWasmModule();
42
+ new Worker(new URL("./worker.mjs", import.meta.url), { workerData: { module } });
43
+
44
+ // worker.mjs
45
+ import { workerData } from "node:worker_threads";
46
+ import { loadXlsxWasmBridge } from "@beyondwork/xlsx-substrate-bindings/wasm";
47
+ const { bridge } = loadXlsxWasmBridge({ module: workerData.module });
48
+ ```
49
+
50
+ `generatedWasmModuleSha256()` is the SHA-256 of the binary. Report it with
51
+ `BRIDGE_VERSION` to identify a deployed runtime. `xlsxWasmModuleSha256(module)`
52
+ returns the hash this process recorded when it compiled `module`; a Module
53
+ received from another thread answers `undefined`.
54
+
55
+ The package loads under plain `node` (Node 22.12 or later), with no loader
56
+ flags and an empty `NODE_OPTIONS`.
57
+
58
+ ## Browsers
59
+
60
+ The host imports the glue module and supplies the wasm source itself; the
61
+ package never fetches anything on its own.
62
+
63
+ ```js
64
+ import * as glue from "@beyondwork/xlsx-substrate-bindings/wasm/web/glue";
65
+ import { loadXlsxWasmBridgeWeb } from "@beyondwork/xlsx-substrate-bindings/wasm/web";
66
+
67
+ const loaded = await loadXlsxWasmBridgeWeb({ glueModule: glue, wasmSource: wasmUrlOrBytes });
68
+ ```
69
+
70
+ Serve the `.wasm` from a cacheable route with the `application/wasm` MIME
71
+ type, or preload it and pass the bytes.
72
+
73
+ ## Memory contract
74
+
75
+ - **Maximum.** The binary is linked with a 2 GiB linear-memory maximum
76
+ (`XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES`, and `linearMemoryMaximumBytes`
77
+ in the package.json `conductor` field).
78
+ - **Readbacks.** `bridge.wasmMemoryBytes()` is the live instance's
79
+ `memory.buffer.byteLength`, read in JavaScript without a wasm call.
80
+ `bridge.highWater(bytes)` sets a mark and returns the memory posture.
81
+ Linear memory never shrinks, so once `aboveHighWater` is true it stays true
82
+ until the instance is replaced. xlsx-api recycles a worker at 1 GiB.
83
+ - **Pre-admission.** Before an open or a recalculation, the bridge estimates
84
+ the memory the call needs from the package's declared part sizes and sheet
85
+ dimensions. The bridge keeps the open estimate of every live session; a
86
+ call is admitted when its estimate fits beside them under the maximum, and
87
+ under a host cap passed as `memoryBudgetBytes` when there is one. It never
88
+ uses `maximum - memory.buffer.byteLength`: linear memory does not shrink,
89
+ so after a large workbook is disposed its memory is free for reuse even
90
+ though the byte length stays. An over-budget call throws an
91
+ `XlsxWasmBridgeError` with `code: "out-of-memory-budget"` and wasm is not
92
+ called. The estimate weights are coarse and are not upper bounds: on a
93
+ 105,000-cell test workbook the estimate was 26.7 MB and linear memory grew
94
+ 244 MB. Admission stops packages that are far over budget; a workbook it
95
+ admits can still run out of memory, and trap containment (below) handles
96
+ that.
97
+ `loadXlsxWasmBridge({ memoryBudgetBytes, admission })` and
98
+ `loadGeneratedXlsxWasmBridge({ memoryBudgetBytes, admission })` set these
99
+ for the returned bridge only; on the shared default instance every bridge
100
+ keeps its own setting. `admission: "off"` skips the check (trap
101
+ containment stays on). Reading a package for the estimate is bounded: at
102
+ most 16 KiB of output and 64 KiB of input per worksheet part, and each
103
+ local header is read once.
104
+ - **Trap containment.** An allocation past the maximum aborts and traps in
105
+ wasm. The bridge catches `WebAssembly.RuntimeError` at every call, discards
106
+ the instance, instantiates a fresh one from the cached Module, and throws an
107
+ `XlsxWasmBridgeError` with `code: "wasm-instance-lost"`. Its
108
+ `lostSessions` names the sessions that are gone and `recovered` says
109
+ whether the fresh instance is live. The next call runs on the fresh
110
+ instance. A raw trap never reaches the host. `trapped` is true on the
111
+ error from the call that trapped. A call with a lost handle throws the
112
+ same typed error with `trapped: false`. Sessions opened after a recovery
113
+ get handle ids with an `@<n>` suffix, so a lost id can never address a new
114
+ session.
115
+
116
+ Use `isXlsxWasmBridgeError(error, code)` to recognise both errors. A
117
+ structured clone (`postMessage`) drops an error's name and own properties,
118
+ so to send one to another thread post `serializeXlsxWasmBridgeError(error)`;
119
+ the receiving side recognises that plain object with `isXlsxWasmBridgeError`
120
+ and can rebuild the error with `deserializeXlsxWasmBridgeError`.
121
+
122
+ ## Release notes
123
+
124
+ ### 0.3.1 (bridge `xlsx-wasm-bridge-v49`)
125
+
126
+ A PATCH release on the same bridge.
127
+
128
+ - **Browser hosting.** `@beyondwork/xlsx-substrate-bindings/wasm/web` is safe
129
+ in a browser bundle (no Node built-in is reachable from it, guarded by a
130
+ bundle test) and exports the capability helpers, `BRIDGE_*` and the
131
+ mutation router.
132
+ - The root entry exports the session-commit result types
133
+ (`XlsxFormulaRecalculateResult`, `XlsxRuntimeSessionExportResult`,
134
+ `XlsxRuntimeSessionMutationReceipt`, `XlsxSessionVolatileInputs`).
135
+ - `@beyondwork/xlsx-react-component` 0.1.0 depends on this release.
136
+
137
+ ### 0.3.0 (bridge `xlsx-wasm-bridge-v49`)
138
+
139
+ A MINOR release: the bridge moved from v46 (0.2.0) to v49. Hosts on 0.2.0
140
+ should upgrade; 0.3.0 carries correctness fixes.
141
+
142
+ - **Format edits on Excel-saved workbooks export.** A format edit (bold,
143
+ number format, fill, border) on a workbook Excel saved used to make the
144
+ export refuse, because Excel's styles part carries an extension list and
145
+ differential formats. The export now carries the source styles root and its
146
+ extension list byte for byte and keeps every differential-format binding.
147
+ Unknown styles extensions and `mc:AlternateContent` still refuse typed. A
148
+ worksheet whose own extension list holds x14 conditional formatting (data
149
+ bars) still refuses cell edits (`PreserveOnlyExportRisk`).
150
+ - **A blank workbook.** `createBlankWorkbookBytes()` from
151
+ `@beyondwork/xlsx-substrate-bindings/blank-workbook` returns a fresh copy of
152
+ a one-sheet workbook Conductor wrote itself. The entry imports nothing, so it
153
+ is safe in a browser bundle.
154
+ - **Stateless commits recalculate honestly.** A stateless (bytes-in,
155
+ bytes-out) commit recalculates the formulas its edit dirties, including
156
+ volatile functions when the host passes the volatile inputs (v48). Before
157
+ 0.3.0 such a commit could return stale formula values.
158
+ - **Smaller and faster runtime.** One evaluator serves every cell store: the
159
+ wasm binary went from about 11.9 MB to about 8.0 MB, and cold load is faster.
160
+ - **Name reads and go-to.** A sheet-qualified read of a name the sheet defines
161
+ evaluates to that sheet's name; a two-area name (a Print_Titles with
162
+ columns and rows) selects both areas in go-to (v49).
163
+
164
+ Limits that stay in 0.3.0: single-user sessions; the runtime runs on the
165
+ calling thread; very large workbooks (about a million cells) take seconds per
166
+ commit; three calculation shapes may differ from Excel until an Excel capture
167
+ settles them: SUMX2MY2, SUMX2PY2 and SUMXMY2 with a non-number element in a
168
+ pair (Conductor folds it as 0), the implicit intersection of a plain TAKE,
169
+ DROP, CHOOSECOLS or CHOOSEROWS over a range (Conductor takes the top-left),
170
+ and SUBTOTAL 1-11 on a sheet whose table is filtered, for rows hidden by hand
171
+ outside that table (Conductor skips them).
172
+
173
+ ## Version policy
174
+
175
+ This is the S34 runtime policy ruling. The 2 GiB memory maximum above comes
176
+ from the same ruling.
177
+
178
+ - Versions stay `0.x` while the runtime is pre-1.0.
179
+ - A release is **MINOR** when its bridge version (`BRIDGE_VERSION`, also in
180
+ the package.json `conductor.bridgeVersion`) differs from the last published
181
+ release's.
182
+ - A release is **PATCH** for fixes on the same bridge version.
183
+ - **MAJOR** is reserved for removing a required method or capability.
184
+ - A bridge version change on the integration branch does not by itself need
185
+ a release.
186
+
187
+ Hosts should gate on the capabilities they call (`missingXlsxWasmCapabilities`
188
+ against `BRIDGE_CAPABILITIES` or the mounted `bridge.status.capabilities`)
189
+ rather than pin a bridge version.
Binary file
@@ -0,0 +1,387 @@
1
+ import type { XlsxScopeHandle } from "../shared.ts";
2
+ import type { XlsxRuntimeAuditDeltaSummary, XlsxRuntimeCellReadback, XlsxRuntimeUndoBoundary, XlsxRuntimeWarning, XlsxSessionVolatileInputs, XlsxWorkflowContextInput } from "../runtime/types.ts";
3
+ import type { XlsxAiAfterState, XlsxAiPreviewResult, XlsxAiRefusal, XlsxAiScopeNeighborhoodResult, XlsxAiScopeReadResult, XlsxAiSessionProposal, XlsxAiSessionReferenceResult, XlsxAiSessionScopeBundleResult, XlsxAiValidateResult, XlsxSessionFence } from "./types.ts";
4
+ /**
5
+ * The optimistic-concurrency fence of the Conductor AI lane, as the catalogue
6
+ * publishes it (structurally the root `EnsembleToolFence`):
7
+ * - `field` is the input member carrying the caller's assertion about the
8
+ * session state it reasoned against;
9
+ * - `echoFrom` is the result member it is echoed from (every stamped answer's
10
+ * `sessionFence`);
11
+ * - omitting it on an `agent`-origin call is the refusal `refusalCode`
12
+ * (§6 `input:fence-required`), never a warning;
13
+ * - `warningCode` is `input:fence-missing`, a RESERVED roster row of category
14
+ * `warning`: never emitted today, because no origin reaches a fenced
15
+ * Conductor verb without the fence being required. `EnsembleToolFence`
16
+ * requires the member, so the reserved code keeps the record total.
17
+ */
18
+ export declare const CONDUCTOR_AI_FENCE: {
19
+ readonly field: "expectedSessionFence";
20
+ readonly echoFrom: "sessionFence";
21
+ readonly requiredForOrigins: readonly ["agent"];
22
+ readonly refusalCode: "input:fence-required";
23
+ readonly warningCode: "input:fence-missing";
24
+ };
25
+ /** The fence record's shape; `CONDUCTOR_AI_FENCE` is its one value. */
26
+ export interface XlsxAiAgentToolFence {
27
+ readonly field: string;
28
+ readonly echoFrom: string;
29
+ readonly requiredForOrigins: readonly string[];
30
+ readonly refusalCode: string;
31
+ readonly warningCode: string;
32
+ }
33
+ export type XlsxAiAgentToolEffect = "read" | "mutate";
34
+ /** The HTTP binding of one verb: the method and the path under `/api/sessions/{sessionId}`. */
35
+ export interface XlsxAiAgentToolHttp {
36
+ readonly method: "POST";
37
+ readonly path: `/ai/${string}`;
38
+ }
39
+ /**
40
+ * Which published schema the tool binds: `Input` names the type as declared;
41
+ * `ApplyInput` is the apply-shaped variant the generator publishes beside it,
42
+ * with the fence field moved into `required` (the apply and plan tools, Q9).
43
+ */
44
+ export interface XlsxAiAgentToolInput {
45
+ /** An exported type name under `bindings/typescript/src/**` (the generator's Conductor roots). */
46
+ readonly type: string;
47
+ readonly schema: "Input" | "ApplyInput";
48
+ }
49
+ export type XlsxAiAgentRefusalCategory = XlsxAiRefusal["category"];
50
+ export interface XlsxAiAgentToolRecord {
51
+ /** Stable dotted name, `xlsx.ai.<verb>`; the catalogue's `name`. */
52
+ readonly name: `xlsx.ai.${string}`;
53
+ /** The deterministic snake-case of `name`, `xlsx_ai_<verb>`; the MCP tool name. */
54
+ readonly wireName: `xlsx_ai_${string}`;
55
+ readonly http: XlsxAiAgentToolHttp;
56
+ readonly input: XlsxAiAgentToolInput;
57
+ /** The result type name: an exported type of THIS module (the stamped answer the route writes), published as a real schema. */
58
+ readonly output: string;
59
+ readonly effect: XlsxAiAgentToolEffect;
60
+ readonly readOrMutate: XlsxAiAgentToolEffect;
61
+ /**
62
+ * The event-log line the call is recorded under, when it is recorded:
63
+ * `ai.request` for every memoized mutating verb, `ai.discard` for the
64
+ * discard. The reads, `preview` and `validate` write no per-call line (a
65
+ * stale refusal writes `ai.stale-refusal` on every verb), so they declare
66
+ * none.
67
+ */
68
+ readonly auditCategory?: string;
69
+ /** Every Conductor verb reaches one workbook session. */
70
+ readonly scope: "workbook";
71
+ /** One sentence: what the verb does and what it does not do. */
72
+ readonly summary: string;
73
+ /** Present on every verb whose body carries `expectedSessionFence`; always `CONDUCTOR_AI_FENCE`. */
74
+ readonly fence?: XlsxAiAgentToolFence;
75
+ readonly refusalCategories: readonly XlsxAiAgentRefusalCategory[];
76
+ }
77
+ /** `/ai/read`: one handle's cells, paged in memory; the cursor embeds the fence the runtime minted in the same call. */
78
+ export interface XlsxAiScopeReadToolInput {
79
+ readonly handle: XlsxScopeHandle;
80
+ readonly expectedSessionFence: XlsxSessionFence;
81
+ /** At most 2000 cells per page. */
82
+ readonly limit?: number;
83
+ /** `page.nextCursor` of the previous answer; a pre-commit cursor is stale after a commit. */
84
+ readonly cursor?: string;
85
+ readonly workflowContext?: XlsxWorkflowContextInput;
86
+ }
87
+ /** `/ai/preview`: guards (or the simulated arm) over one proposal; the fence rides `proposal.expectedSessionFence`. */
88
+ export interface XlsxAiPreviewToolInput {
89
+ readonly proposal: XlsxAiSessionProposal;
90
+ readonly fidelity?: "guards-only" | "simulated";
91
+ readonly workflowContext?: XlsxWorkflowContextInput;
92
+ }
93
+ /** `/ai/validate`: `ai_check` only over one proposal; the fence rides `proposal.expectedSessionFence`. */
94
+ export interface XlsxAiValidateToolInput {
95
+ readonly proposal: XlsxAiSessionProposal;
96
+ readonly workflowContext?: XlsxWorkflowContextInput;
97
+ }
98
+ /** One plan step: a proposal without its own fence (a plan is fenced once, by the request). */
99
+ export type XlsxAiPlanToolStep = Omit<XlsxAiSessionProposal, "expectedSessionFence">;
100
+ /** The plan body of `/ai/plan` and of a `/ai/propose {plan}` subject: at most 50 pairwise disjoint steps. */
101
+ export interface XlsxAiPlanToolBody {
102
+ readonly steps: readonly XlsxAiPlanToolStep[];
103
+ /** The only atomicity a plan has (Q3). */
104
+ readonly atomic?: "all-or-nothing";
105
+ /** When present it must equal the request's `expectedSessionFence`. */
106
+ readonly expectedSessionFence?: XlsxSessionFence;
107
+ }
108
+ /** The `{undo}` subject of `/ai/propose`: the request to undo and the boundary its outcome returned. */
109
+ export interface XlsxAiUndoSubjectToolInput {
110
+ readonly targetRequestId: string;
111
+ readonly undoBoundaryId: string;
112
+ }
113
+ /** The journal cut a graph pin names: the checkpoint's `journal_cut_seq` and the chain head it was cut at (64 lowercase hex). */
114
+ export interface XlsxAiGraphPinJournalCutToolInput {
115
+ readonly journal_cut_seq: number;
116
+ readonly chain_head: string;
117
+ }
118
+ /**
119
+ * The consumer's graph pin on `/ai/propose` (WP-DOC T-I; published by DW-C2): the tenant-wide graph epoch the agent
120
+ * read at and the journal cut it was projected from, with the engine read token when the read carried one
121
+ * (`glt1.<service>.<incarnation>.<epoch>`). Advisory evidence carried on the staged subject beside the check's
122
+ * facts; no fence reads it and it is outside the request memo's digest. At most 256 canonical bytes. The service
123
+ * admits it only while it runs the graph projector (`CONDUCTOR_GRAPH_PROJECTION=on`): with the projector off (the
124
+ * default) a `/ai/propose` body carrying it is refused BEFORE the request memo with the roster row
125
+ * `transport:graph-projection:off` (404; Composer parity; DW-C2 R-DWC2-3 — the row stands in
126
+ * `crates/sheets-scope/tests/fixtures/ai-refusal-roster.json`), nothing is staged, and a retry without the pin
127
+ * proposes afresh.
128
+ */
129
+ export interface XlsxAiGraphPinToolInput {
130
+ readonly graphEpoch: number;
131
+ readonly journalCut: XlsxAiGraphPinJournalCutToolInput;
132
+ readonly readToken?: string;
133
+ }
134
+ /** `/ai/propose {proposal}`: stage one replacement proposal. */
135
+ export interface XlsxAiProposeProposalToolInput {
136
+ readonly requestId: string;
137
+ readonly expectedSessionFence: XlsxSessionFence;
138
+ readonly proposal: XlsxAiSessionProposal;
139
+ /**
140
+ * XBC-2 (Q2 item 7; R-XBC2-1 item 2): `simulated` runs the subject's check through the clone arm under the size gate
141
+ * (once, at the staged fence) and pins the clone's predicted post-apply CONTENT (`predictedAfterState`: state SHA +
142
+ * changed-cells digest) on the staged subject; `/ai/apply` then attests its post-commit content and compares both
143
+ * facts (`previewArmCheck`, `previewFidelity: "simulated"`). Above the gate the check runs guards-only and the
144
+ * outcome carries the `preview:simulated-unavailable` warning. Default `guards-only` (no prediction, no comparison).
145
+ */
146
+ readonly fidelity?: "guards-only" | "simulated";
147
+ readonly workflowContext?: XlsxWorkflowContextInput;
148
+ readonly graph?: XlsxAiGraphPinToolInput;
149
+ }
150
+ /** `/ai/propose {plan}`: stage one plan. */
151
+ export interface XlsxAiProposePlanToolInput {
152
+ readonly requestId: string;
153
+ readonly expectedSessionFence: XlsxSessionFence;
154
+ readonly plan: XlsxAiPlanToolBody;
155
+ readonly workflowContext?: XlsxWorkflowContextInput;
156
+ readonly graph?: XlsxAiGraphPinToolInput;
157
+ }
158
+ /** `/ai/propose {undo}`: stage one undo. */
159
+ export interface XlsxAiProposeUndoToolInput {
160
+ readonly requestId: string;
161
+ readonly expectedSessionFence: XlsxSessionFence;
162
+ readonly undo: XlsxAiUndoSubjectToolInput;
163
+ readonly workflowContext?: XlsxWorkflowContextInput;
164
+ readonly graph?: XlsxAiGraphPinToolInput;
165
+ }
166
+ /** `/ai/propose`: exactly one subject per request (Q7 "Governed mutations are staged subjects"). */
167
+ export type XlsxAiProposeToolInput = XlsxAiProposeProposalToolInput | XlsxAiProposePlanToolInput | XlsxAiProposeUndoToolInput;
168
+ /** `/ai/apply`: execute a staged proposal or plan subject by its ref; dispatched on the STAGED fence. */
169
+ export interface XlsxAiApplyToolInput {
170
+ readonly requestId: string;
171
+ readonly proposalRef: string;
172
+ /** Checked for grammar only; the apply is fenced on the staged fence (Q7 check 3). Required on the published `.ApplyInput`. */
173
+ readonly expectedSessionFence?: XlsxSessionFence;
174
+ /** Await the commit's own durability (<= 10 s) before answering. */
175
+ readonly requireDurable?: boolean;
176
+ /** Governed mode: the confirmed decision bound to the subject. */
177
+ readonly decisionRef?: string;
178
+ readonly workflowContext?: XlsxWorkflowContextInput;
179
+ }
180
+ /** `/ai/plan`: preview (the default) or apply one plan inline; governed deployments refuse the inline apply. */
181
+ export interface XlsxAiPlanToolInput {
182
+ readonly requestId: string;
183
+ readonly mode?: "preview" | "apply";
184
+ readonly expectedSessionFence: XlsxSessionFence;
185
+ readonly plan: XlsxAiPlanToolBody;
186
+ readonly requireDurable?: boolean;
187
+ readonly workflowContext?: XlsxWorkflowContextInput;
188
+ }
189
+ /** `/ai/undo`: reverse the newest settled apply or plan by its request and boundary (Q5). */
190
+ export interface XlsxAiUndoToolInput {
191
+ /** The undo's own memo key; never `targetRequestId`. */
192
+ readonly requestId: string;
193
+ /** The `requestId` of the apply or plan to undo. */
194
+ readonly targetRequestId: string;
195
+ /** The `undoBoundary.id` the undone request's outcome returned. */
196
+ readonly undoBoundaryId: string;
197
+ /** Governed mode: the staged `undo` subject (required there). */
198
+ readonly proposalRef?: string;
199
+ /** Governed mode: its confirmed decision (required there). */
200
+ readonly decisionRef?: string;
201
+ }
202
+ /** `/ai/discard`: release one staged subject the caller owns. */
203
+ export interface XlsxAiDiscardToolInput {
204
+ readonly proposalRef: string;
205
+ }
206
+ /** Why a fence was refused stale (Q1 item 7): the service's `AiStaleCause`. */
207
+ export type XlsxAiStaleCause = "content-changed" | "reopened-same-content" | "unknown";
208
+ /**
209
+ * A stamped answer's refusal after the service's stale tag: `runtime:stale-target` carries why. The tool results
210
+ * below re-spell `verdict` as the literal union their DTO's `Extract<XlsxVerdict, …>` denotes (type-equal), so the
211
+ * published output schemas carry no unconstrained member.
212
+ */
213
+ export interface XlsxAiStaleTaggedRefusal extends XlsxAiRefusal {
214
+ readonly staleCause?: XlsxAiStaleCause;
215
+ }
216
+ /** `/ai/bundle`'s answer: the runtime's bundle result, the refusal tagged and `staleCause` beside it when stale. */
217
+ export interface XlsxAiBundleToolResult extends XlsxAiSessionScopeBundleResult {
218
+ readonly verdict: "available" | "refused";
219
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
220
+ readonly staleCause?: XlsxAiStaleCause;
221
+ }
222
+ /** `/ai/resolve`'s answer. */
223
+ export interface XlsxAiResolveToolResult extends XlsxAiSessionReferenceResult {
224
+ readonly verdict: "available" | "refused";
225
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
226
+ readonly staleCause?: XlsxAiStaleCause;
227
+ }
228
+ /** `/ai/read`'s paging: the service slices the runtime's full cell set in memory (R-XB7-1 item 8). */
229
+ export interface XlsxAiScopeReadPage {
230
+ readonly offset: number;
231
+ readonly limit: number;
232
+ readonly total: number;
233
+ /** Present when more cells follow; embeds the fence minted by THIS call. */
234
+ readonly nextCursor?: string;
235
+ }
236
+ /** `/ai/read`'s answer: the runtime's read result, paged — `page` is on every answer, a refused one included. */
237
+ export interface XlsxAiScopeReadToolResult extends XlsxAiScopeReadResult {
238
+ readonly verdict: "available" | "refused";
239
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
240
+ readonly staleCause?: XlsxAiStaleCause;
241
+ readonly page: XlsxAiScopeReadPage;
242
+ }
243
+ /** `/ai/neighborhood`'s answer. */
244
+ export interface XlsxAiNeighborhoodToolResult extends XlsxAiScopeNeighborhoodResult {
245
+ readonly verdict: "available" | "refused";
246
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
247
+ readonly staleCause?: XlsxAiStaleCause;
248
+ }
249
+ /** The preview DTO's `validation`, its refusal stale-tagged (`XlsxAiPreviewResult["validation"]` spelled out: the generator publishes a real schema for it). */
250
+ export interface XlsxAiPreviewToolValidation {
251
+ readonly verdict?: "applied" | "applied-with-warnings";
252
+ readonly warnings: readonly XlsxRuntimeWarning[];
253
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
254
+ }
255
+ /** `/ai/preview`'s answer: the preview DTO carries its refusal under `validation.refusal`, and that is where the stale tag lands. */
256
+ export interface XlsxAiPreviewToolResult extends XlsxAiPreviewResult {
257
+ readonly verdict: "validated" | "refused";
258
+ readonly validation: XlsxAiPreviewToolValidation;
259
+ readonly staleCause?: XlsxAiStaleCause;
260
+ }
261
+ /** `/ai/validate`'s answer. */
262
+ export interface XlsxAiValidateToolResult extends XlsxAiValidateResult {
263
+ readonly verdict: "validated" | "refused";
264
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
265
+ readonly staleCause?: XlsxAiStaleCause;
266
+ }
267
+ /** The R7 attestation of an executed apply or plan (record §5.7). */
268
+ export interface XlsxAiAttestation {
269
+ readonly before: string;
270
+ readonly after: string;
271
+ readonly epoch: string;
272
+ readonly dispatchRevision: number;
273
+ readonly receiptRevision: number;
274
+ }
275
+ /** An executed undo's attestation, read from the restored record (Q5). */
276
+ export interface XlsxAiUndoAttestation {
277
+ readonly preRestoreSha256: string;
278
+ readonly restoredSha256: string;
279
+ readonly cursorBefore: number;
280
+ readonly cursorAfter: number;
281
+ readonly entryIndex: number;
282
+ }
283
+ export interface XlsxAiImpactMeasured {
284
+ readonly status: "measured";
285
+ }
286
+ export interface XlsxAiImpactUnmeasured {
287
+ readonly status: "unmeasured";
288
+ readonly reason: string;
289
+ }
290
+ export type XlsxAiImpactStatus = XlsxAiImpactMeasured | XlsxAiImpactUnmeasured;
291
+ /** Why the resident session was dropped inside this request (R-XB8a-4 item 8). */
292
+ export type XlsxAiInvalidationCause = "session-disposed" | "drain-failed" | "drain-unsettled" | "unattested-apply" | "runtime-job-error" | "worker-unavailable" | "wasm-trap";
293
+ export interface XlsxAiOutcomeInvalidation {
294
+ readonly kind: "resident-session";
295
+ readonly sessionDropped: true;
296
+ readonly cause: XlsxAiInvalidationCause;
297
+ }
298
+ /** A warning on an outcome: the runtime's own, or a roster warning such as `apply:drain-refused`. */
299
+ export type XlsxAiOutcomeWarning = XlsxRuntimeWarning | XlsxAiRefusal;
300
+ /**
301
+ * The one answer of `/ai/propose`, `/ai/apply`, `/ai/plan` and `/ai/undo`
302
+ * (record §5.7 `AiMutationOutcome`; XB8 "Preview, propose, validate, apply,
303
+ * and `AiMutationOutcome`"). A verb refusal rides a 200 with `verdict:
304
+ * "refused"` and `executed: false`; `executed` is attestation, never intent.
305
+ */
306
+ export interface XlsxAiMutationOutcome {
307
+ readonly schemaVersion: "xlsx-conductor-ai-outcome-v1";
308
+ readonly phase: "preview" | "validate" | "propose" | "apply" | "plan" | "undo" | "discard";
309
+ readonly verdict: "validated" | "applied" | "applied-with-warnings" | "refused";
310
+ readonly executed: boolean;
311
+ readonly attestation?: XlsxAiAttestation;
312
+ /** An executed undo's attestation (Q5); never on an apply. */
313
+ readonly undoAttestation?: XlsxAiUndoAttestation;
314
+ /** `settled.sessionFence` after an apply (absent after a drain failure); the current stamp on a refusal. */
315
+ readonly sessionFence?: XlsxSessionFence;
316
+ /** Scoped to THIS request's deferred task (Q4 J2). */
317
+ readonly durability: "pending" | "durable" | "failed" | "not-applicable";
318
+ readonly readbackStatus: "verified" | "not-applicable" | "mismatch";
319
+ readonly formulaGraphDelta: XlsxRuntimeAuditDeltaSummary;
320
+ readonly impactStatus: XlsxAiImpactStatus;
321
+ /** Present exactly when this request's containment dropped the resident session. */
322
+ readonly invalidation?: XlsxAiOutcomeInvalidation;
323
+ readonly undoBoundary?: XlsxRuntimeUndoBoundary;
324
+ /** The session identity after the call; empty when no call ran. */
325
+ readonly canonicalHash: string;
326
+ /** The receipt's advisory revision; -1 when no call ran. */
327
+ readonly revision: number;
328
+ readonly actor: {
329
+ readonly actorId: string;
330
+ readonly displayName: string;
331
+ };
332
+ /** `anonymous` / `unauthenticated`: the service produced the outcome with no principal bound (its observe-mode fallback); `system` is its tool-api lane. */
333
+ readonly lane: "agent" | "human" | "system" | "anonymous";
334
+ readonly trust: "host-bound" | "session-bound" | "system" | "unauthenticated";
335
+ readonly proposalRef?: string;
336
+ readonly decisionRef?: string;
337
+ readonly requestId: string;
338
+ readonly replayed?: boolean;
339
+ /** On a `/ai/propose` outcome: the decision subject (Revision 5). */
340
+ readonly proposalDigest?: string;
341
+ readonly subjectKind?: "proposal" | "plan" | "undo";
342
+ readonly expiresAt?: string;
343
+ readonly targetRequestId?: string;
344
+ readonly refusals: readonly XlsxAiRefusal[];
345
+ readonly changedCells: readonly XlsxRuntimeCellReadback[];
346
+ readonly warnings: readonly XlsxAiOutcomeWarning[];
347
+ readonly volatileInputs?: XlsxSessionVolatileInputs;
348
+ readonly staleCause?: XlsxAiStaleCause;
349
+ /** Plan receipts only (Rust's one producer). */
350
+ readonly planDigest?: string;
351
+ /**
352
+ * XBC-2: on a `/ai/propose {proposal}` outcome the fidelity its check ran with (`simulated`: the clone arm ran under
353
+ * the gate and its predicted post-apply content is pinned on the staged subject); on a `/ai/apply` outcome
354
+ * `simulated` exactly when a comparison happened (`previewArmCheck` present; a mismatch is the
355
+ * `internal:preview-arm-divergence` warning on the executed outcome). Absent otherwise.
356
+ */
357
+ readonly previewFidelity?: "guards-only" | "simulated";
358
+ /**
359
+ * XBC-2 R1 (R-XBC2-1 item 2): the apply-time comparison of the clone arm's predicted post-apply content (state SHA +
360
+ * changed-cells digest, pinned at propose from Rust's answer) with the real receipt's `afterState`; present exactly
361
+ * when it happened. `actual` is absent when the runtime answered none (a mismatch).
362
+ */
363
+ readonly previewArmCheck?: {
364
+ readonly predicted: XlsxAiAfterState;
365
+ readonly actual?: XlsxAiAfterState;
366
+ readonly agreed: boolean;
367
+ };
368
+ }
369
+ /** `/ai/discard`'s 200 answer (Q7): `decision` only when a live decision was marked `refused/withdrawn`. */
370
+ export interface XlsxAiDiscardAnswer {
371
+ readonly proposalRef: string;
372
+ readonly subjectKind: "proposal" | "plan" | "undo";
373
+ readonly discarded: true;
374
+ readonly decision?: {
375
+ readonly decisionRef: string;
376
+ readonly state: "refused";
377
+ };
378
+ }
379
+ /** `/ai/discard`'s answer: the discard, or its refusal as an outcome (`proposal:unknown`, `governance:missing-authority`). */
380
+ export type XlsxAiDiscardToolResult = XlsxAiDiscardAnswer | XlsxAiMutationOutcome;
381
+ /**
382
+ * One record per wrapped `/ai` verb, in the service's route order (the four
383
+ * XB7 reads, then XB8's five, then XB9's two). The bijection test pins this
384
+ * list against the route files; a verb added without a record, or a record
385
+ * without a verb, fails there.
386
+ */
387
+ export declare const XLSX_AI_AGENT_TOOLS: readonly XlsxAiAgentToolRecord[];