@beyondwork/xlsx-substrate-bindings 0.0.0-stage → 0.2.0

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/LICENSE.md +31 -0
  2. package/README.md +135 -2
  3. package/dist/ai/agent-metadata.d.ts +363 -0
  4. package/dist/ai/agent-metadata.js +227 -0
  5. package/dist/ai/index.d.ts +6 -0
  6. package/dist/ai/index.js +7 -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 +765 -0
  10. package/dist/ai/types.js +23 -0
  11. package/dist/index.d.ts +50 -0
  12. package/dist/index.js +90 -0
  13. package/dist/runtime/index.d.ts +2 -0
  14. package/dist/runtime/index.js +1 -0
  15. package/dist/runtime/types.d.ts +1435 -0
  16. package/dist/runtime/types.js +15 -0
  17. package/dist/shared.d.ts +69 -0
  18. package/dist/shared.js +1 -0
  19. package/dist/ui/index.d.ts +2 -0
  20. package/dist/ui/index.js +1 -0
  21. package/dist/ui/types.d.ts +765 -0
  22. package/dist/ui/types.js +12 -0
  23. package/dist/wasm/ai-session-bridge.d.ts +97 -0
  24. package/dist/wasm/ai-session-bridge.js +154 -0
  25. package/dist/wasm/bridge-contract.d.ts +643 -0
  26. package/dist/wasm/bridge-contract.js +1001 -0
  27. package/dist/wasm/index.d.ts +50 -0
  28. package/dist/wasm/index.js +297 -0
  29. package/dist/wasm/memory-budget.d.ts +77 -0
  30. package/dist/wasm/memory-budget.js +532 -0
  31. package/dist/wasm/runtime-guard.d.ts +141 -0
  32. package/dist/wasm/runtime-guard.js +373 -0
  33. package/dist/wasm/session-router.d.ts +98 -0
  34. package/dist/wasm/session-router.js +184 -0
  35. package/dist/wasm/sheet-window-binary-reference.d.ts +9 -0
  36. package/dist/wasm/sheet-window-binary-reference.js +308 -0
  37. package/dist/wasm/sheet-window-binary.d.ts +279 -0
  38. package/dist/wasm/sheet-window-binary.js +636 -0
  39. package/dist/wasm/web.d.ts +72 -0
  40. package/dist/wasm/web.js +142 -0
  41. package/generated/wasm-web/package.json +3 -0
  42. package/generated/wasm-web/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +42 -0
  43. package/generated/wasm-web/xlsx_substrate_wasm.d.ts +532 -0
  44. package/generated/wasm-web/xlsx_substrate_wasm.js +2493 -0
  45. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
  46. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +120 -0
  47. package/package.json +55 -3
package/LICENSE.md ADDED
@@ -0,0 +1,31 @@
1
+ # Beyond Work Use License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is granted, free of charge, to:
6
+
7
+ - Beyond Work
8
+ - any employee, contractor, or agent acting on behalf of Beyond Work
9
+ - any user of Beyond Work
10
+
11
+ to use, copy, modify, create with, and distribute this software solely:
12
+
13
+ - for Beyond Work's internal business purposes, or
14
+ - as part of workblocks that run on Beyond Work
15
+
16
+ No license is granted to any other person or entity. Except for the limited
17
+ permission above, you may not use, copy, modify, merge, publish, distribute,
18
+ sublicense, sell, host, or otherwise exploit this software in any environment,
19
+ platform, or product outside Beyond Work or outside workblocks running on Beyond
20
+ Work.
21
+
22
+ This software is provided "as is", without warranty of any kind, express or
23
+ implied, including but not limited to the warranties of merchantability,
24
+ fitness for a particular purpose, and noninfringement. In no event shall the
25
+ authors or copyright holders be liable for any claim, damages, or other
26
+ liability, whether in an action of contract, tort, or otherwise, arising from,
27
+ out of, or in connection with the software or the use of the software.
28
+
29
+ For the avoidance of doubt, if you are not Beyond Work, not acting on behalf of
30
+ Beyond Work, and not a user of Beyond Work using this software for workblocks
31
+ running on Beyond Work, you have no permission to use this software.
package/README.md CHANGED
@@ -1,3 +1,136 @@
1
- # Temporary Holding Version
1
+ # @beyondwork/xlsx-substrate-bindings
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+
17
+ ## Node
18
+
19
+ ```js
20
+ import { loadXlsxWasmBridge } from "@beyondwork/xlsx-substrate-bindings/wasm";
21
+
22
+ const loaded = loadXlsxWasmBridge();
23
+ if (!loaded.bridge) throw new Error(loaded.reason);
24
+ const session = loaded.bridge.openWorkbookRuntimeSession(bytes, { loadMode: "full" });
25
+ ```
26
+
27
+ `loadXlsxWasmBridge()` (and the older `loadGeneratedXlsxWasmBridge()`) returns
28
+ a bridge on the process's shared default instance: every such bridge sees the
29
+ same sessions.
30
+
31
+ To run several instances, compile the binary once and instantiate from the
32
+ Module. A Module can be posted to `worker_threads`; each worker instantiates
33
+ its own instance without compiling again.
34
+
35
+ ```js
36
+ import { Worker } from "node:worker_threads";
37
+ import { compileXlsxWasmModule } from "@beyondwork/xlsx-substrate-bindings/wasm";
38
+
39
+ const module = await compileXlsxWasmModule();
40
+ new Worker(new URL("./worker.mjs", import.meta.url), { workerData: { module } });
41
+
42
+ // worker.mjs
43
+ import { workerData } from "node:worker_threads";
44
+ import { loadXlsxWasmBridge } from "@beyondwork/xlsx-substrate-bindings/wasm";
45
+ const { bridge } = loadXlsxWasmBridge({ module: workerData.module });
46
+ ```
47
+
48
+ `generatedWasmModuleSha256()` is the SHA-256 of the binary. Report it with
49
+ `BRIDGE_VERSION` to identify a deployed runtime. `xlsxWasmModuleSha256(module)`
50
+ returns the hash this process recorded when it compiled `module`; a Module
51
+ received from another thread answers `undefined`.
52
+
53
+ The package loads under plain `node` (Node 22.12 or later), with no loader
54
+ flags and an empty `NODE_OPTIONS`.
55
+
56
+ ## Browsers
57
+
58
+ The host imports the glue module and supplies the wasm source itself; the
59
+ package never fetches anything on its own.
60
+
61
+ ```js
62
+ import * as glue from "@beyondwork/xlsx-substrate-bindings/wasm/web/glue";
63
+ import { loadXlsxWasmBridgeWeb } from "@beyondwork/xlsx-substrate-bindings/wasm/web";
64
+
65
+ const loaded = await loadXlsxWasmBridgeWeb({ glueModule: glue, wasmSource: wasmUrlOrBytes });
66
+ ```
67
+
68
+ Serve the `.wasm` from a cacheable route with the `application/wasm` MIME
69
+ type, or preload it and pass the bytes.
70
+
71
+ ## Memory contract
72
+
73
+ - **Maximum.** The binary is linked with a 2 GiB linear-memory maximum
74
+ (`XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES`, and `linearMemoryMaximumBytes`
75
+ in the package.json `conductor` field).
76
+ - **Readbacks.** `bridge.wasmMemoryBytes()` is the live instance's
77
+ `memory.buffer.byteLength`, read in JavaScript without a wasm call.
78
+ `bridge.highWater(bytes)` sets a mark and returns the memory posture.
79
+ Linear memory never shrinks, so once `aboveHighWater` is true it stays true
80
+ until the instance is replaced. xlsx-api recycles a worker at 1 GiB.
81
+ - **Pre-admission.** Before an open or a recalculation, the bridge estimates
82
+ the memory the call needs from the package's declared part sizes and sheet
83
+ dimensions. The bridge keeps the open estimate of every live session; a
84
+ call is admitted when its estimate fits beside them under the maximum, and
85
+ under a host cap passed as `memoryBudgetBytes` when there is one. It never
86
+ uses `maximum - memory.buffer.byteLength`: linear memory does not shrink,
87
+ so after a large workbook is disposed its memory is free for reuse even
88
+ though the byte length stays. An over-budget call throws an
89
+ `XlsxWasmBridgeError` with `code: "out-of-memory-budget"` and wasm is not
90
+ called. The estimate weights are coarse and are not upper bounds: on a
91
+ 105,000-cell test workbook the estimate was 26.7 MB and linear memory grew
92
+ 244 MB. Admission stops packages that are far over budget; a workbook it
93
+ admits can still run out of memory, and trap containment (below) handles
94
+ that.
95
+ `loadXlsxWasmBridge({ memoryBudgetBytes, admission })` and
96
+ `loadGeneratedXlsxWasmBridge({ memoryBudgetBytes, admission })` set these
97
+ for the returned bridge only; on the shared default instance every bridge
98
+ keeps its own setting. `admission: "off"` skips the check (trap
99
+ containment stays on). Reading a package for the estimate is bounded: at
100
+ most 16 KiB of output and 64 KiB of input per worksheet part, and each
101
+ local header is read once.
102
+ - **Trap containment.** An allocation past the maximum aborts and traps in
103
+ wasm. The bridge catches `WebAssembly.RuntimeError` at every call, discards
104
+ the instance, instantiates a fresh one from the cached Module, and throws an
105
+ `XlsxWasmBridgeError` with `code: "wasm-instance-lost"`. Its
106
+ `lostSessions` names the sessions that are gone and `recovered` says
107
+ whether the fresh instance is live. The next call runs on the fresh
108
+ instance. A raw trap never reaches the host. `trapped` is true on the
109
+ error from the call that trapped. A call with a lost handle throws the
110
+ same typed error with `trapped: false`. Sessions opened after a recovery
111
+ get handle ids with an `@<n>` suffix, so a lost id can never address a new
112
+ session.
113
+
114
+ Use `isXlsxWasmBridgeError(error, code)` to recognise both errors. A
115
+ structured clone (`postMessage`) drops an error's name and own properties,
116
+ so to send one to another thread post `serializeXlsxWasmBridgeError(error)`;
117
+ the receiving side recognises that plain object with `isXlsxWasmBridgeError`
118
+ and can rebuild the error with `deserializeXlsxWasmBridgeError`.
119
+
120
+ ## Version policy
121
+
122
+ This is the S34 runtime policy ruling. The 2 GiB memory maximum above comes
123
+ from the same ruling.
124
+
125
+ - Versions stay `0.x` while the runtime is pre-1.0.
126
+ - A release is **MINOR** when its bridge version (`BRIDGE_VERSION`, also in
127
+ the package.json `conductor.bridgeVersion`) differs from the last published
128
+ release's.
129
+ - A release is **PATCH** for fixes on the same bridge version.
130
+ - **MAJOR** is reserved for removing a required method or capability.
131
+ - A bridge version change on the integration branch does not by itself need
132
+ a release.
133
+
134
+ Hosts should gate on the capabilities they call (`missingXlsxWasmCapabilities`
135
+ against `BRIDGE_CAPABILITIES` or the mounted `bridge.status.capabilities`)
136
+ rather than pin a bridge version.
@@ -0,0 +1,363 @@
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
+ /** `/ai/propose {proposal}`: stage one replacement proposal. */
114
+ export interface XlsxAiProposeProposalToolInput {
115
+ readonly requestId: string;
116
+ readonly expectedSessionFence: XlsxSessionFence;
117
+ readonly proposal: XlsxAiSessionProposal;
118
+ /**
119
+ * XBC-2 (Q2 item 7; R-XBC2-1 item 2): `simulated` runs the subject's check through the clone arm under the size gate
120
+ * (once, at the staged fence) and pins the clone's predicted post-apply CONTENT (`predictedAfterState`: state SHA +
121
+ * changed-cells digest) on the staged subject; `/ai/apply` then attests its post-commit content and compares both
122
+ * facts (`previewArmCheck`, `previewFidelity: "simulated"`). Above the gate the check runs guards-only and the
123
+ * outcome carries the `preview:simulated-unavailable` warning. Default `guards-only` (no prediction, no comparison).
124
+ */
125
+ readonly fidelity?: "guards-only" | "simulated";
126
+ readonly workflowContext?: XlsxWorkflowContextInput;
127
+ }
128
+ /** `/ai/propose {plan}`: stage one plan. */
129
+ export interface XlsxAiProposePlanToolInput {
130
+ readonly requestId: string;
131
+ readonly expectedSessionFence: XlsxSessionFence;
132
+ readonly plan: XlsxAiPlanToolBody;
133
+ readonly workflowContext?: XlsxWorkflowContextInput;
134
+ }
135
+ /** `/ai/propose {undo}`: stage one undo. */
136
+ export interface XlsxAiProposeUndoToolInput {
137
+ readonly requestId: string;
138
+ readonly expectedSessionFence: XlsxSessionFence;
139
+ readonly undo: XlsxAiUndoSubjectToolInput;
140
+ readonly workflowContext?: XlsxWorkflowContextInput;
141
+ }
142
+ /** `/ai/propose`: exactly one subject per request (Q7 "Governed mutations are staged subjects"). */
143
+ export type XlsxAiProposeToolInput = XlsxAiProposeProposalToolInput | XlsxAiProposePlanToolInput | XlsxAiProposeUndoToolInput;
144
+ /** `/ai/apply`: execute a staged proposal or plan subject by its ref; dispatched on the STAGED fence. */
145
+ export interface XlsxAiApplyToolInput {
146
+ readonly requestId: string;
147
+ readonly proposalRef: string;
148
+ /** Checked for grammar only; the apply is fenced on the staged fence (Q7 check 3). Required on the published `.ApplyInput`. */
149
+ readonly expectedSessionFence?: XlsxSessionFence;
150
+ /** Await the commit's own durability (<= 10 s) before answering. */
151
+ readonly requireDurable?: boolean;
152
+ /** Governed mode: the confirmed decision bound to the subject. */
153
+ readonly decisionRef?: string;
154
+ readonly workflowContext?: XlsxWorkflowContextInput;
155
+ }
156
+ /** `/ai/plan`: preview (the default) or apply one plan inline; governed deployments refuse the inline apply. */
157
+ export interface XlsxAiPlanToolInput {
158
+ readonly requestId: string;
159
+ readonly mode?: "preview" | "apply";
160
+ readonly expectedSessionFence: XlsxSessionFence;
161
+ readonly plan: XlsxAiPlanToolBody;
162
+ readonly requireDurable?: boolean;
163
+ readonly workflowContext?: XlsxWorkflowContextInput;
164
+ }
165
+ /** `/ai/undo`: reverse the newest settled apply or plan by its request and boundary (Q5). */
166
+ export interface XlsxAiUndoToolInput {
167
+ /** The undo's own memo key; never `targetRequestId`. */
168
+ readonly requestId: string;
169
+ /** The `requestId` of the apply or plan to undo. */
170
+ readonly targetRequestId: string;
171
+ /** The `undoBoundary.id` the undone request's outcome returned. */
172
+ readonly undoBoundaryId: string;
173
+ /** Governed mode: the staged `undo` subject (required there). */
174
+ readonly proposalRef?: string;
175
+ /** Governed mode: its confirmed decision (required there). */
176
+ readonly decisionRef?: string;
177
+ }
178
+ /** `/ai/discard`: release one staged subject the caller owns. */
179
+ export interface XlsxAiDiscardToolInput {
180
+ readonly proposalRef: string;
181
+ }
182
+ /** Why a fence was refused stale (Q1 item 7): the service's `AiStaleCause`. */
183
+ export type XlsxAiStaleCause = "content-changed" | "reopened-same-content" | "unknown";
184
+ /**
185
+ * A stamped answer's refusal after the service's stale tag: `runtime:stale-target` carries why. The tool results
186
+ * below re-spell `verdict` as the literal union their DTO's `Extract<XlsxVerdict, …>` denotes (type-equal), so the
187
+ * published output schemas carry no unconstrained member.
188
+ */
189
+ export interface XlsxAiStaleTaggedRefusal extends XlsxAiRefusal {
190
+ readonly staleCause?: XlsxAiStaleCause;
191
+ }
192
+ /** `/ai/bundle`'s answer: the runtime's bundle result, the refusal tagged and `staleCause` beside it when stale. */
193
+ export interface XlsxAiBundleToolResult extends XlsxAiSessionScopeBundleResult {
194
+ readonly verdict: "available" | "refused";
195
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
196
+ readonly staleCause?: XlsxAiStaleCause;
197
+ }
198
+ /** `/ai/resolve`'s answer. */
199
+ export interface XlsxAiResolveToolResult extends XlsxAiSessionReferenceResult {
200
+ readonly verdict: "available" | "refused";
201
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
202
+ readonly staleCause?: XlsxAiStaleCause;
203
+ }
204
+ /** `/ai/read`'s paging: the service slices the runtime's full cell set in memory (R-XB7-1 item 8). */
205
+ export interface XlsxAiScopeReadPage {
206
+ readonly offset: number;
207
+ readonly limit: number;
208
+ readonly total: number;
209
+ /** Present when more cells follow; embeds the fence minted by THIS call. */
210
+ readonly nextCursor?: string;
211
+ }
212
+ /** `/ai/read`'s answer: the runtime's read result, paged — `page` is on every answer, a refused one included. */
213
+ export interface XlsxAiScopeReadToolResult extends XlsxAiScopeReadResult {
214
+ readonly verdict: "available" | "refused";
215
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
216
+ readonly staleCause?: XlsxAiStaleCause;
217
+ readonly page: XlsxAiScopeReadPage;
218
+ }
219
+ /** `/ai/neighborhood`'s answer. */
220
+ export interface XlsxAiNeighborhoodToolResult extends XlsxAiScopeNeighborhoodResult {
221
+ readonly verdict: "available" | "refused";
222
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
223
+ readonly staleCause?: XlsxAiStaleCause;
224
+ }
225
+ /** The preview DTO's `validation`, its refusal stale-tagged (`XlsxAiPreviewResult["validation"]` spelled out: the generator publishes a real schema for it). */
226
+ export interface XlsxAiPreviewToolValidation {
227
+ readonly verdict?: "applied" | "applied-with-warnings";
228
+ readonly warnings: readonly XlsxRuntimeWarning[];
229
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
230
+ }
231
+ /** `/ai/preview`'s answer: the preview DTO carries its refusal under `validation.refusal`, and that is where the stale tag lands. */
232
+ export interface XlsxAiPreviewToolResult extends XlsxAiPreviewResult {
233
+ readonly verdict: "validated" | "refused";
234
+ readonly validation: XlsxAiPreviewToolValidation;
235
+ readonly staleCause?: XlsxAiStaleCause;
236
+ }
237
+ /** `/ai/validate`'s answer. */
238
+ export interface XlsxAiValidateToolResult extends XlsxAiValidateResult {
239
+ readonly verdict: "validated" | "refused";
240
+ readonly refusal?: XlsxAiStaleTaggedRefusal;
241
+ readonly staleCause?: XlsxAiStaleCause;
242
+ }
243
+ /** The R7 attestation of an executed apply or plan (record §5.7). */
244
+ export interface XlsxAiAttestation {
245
+ readonly before: string;
246
+ readonly after: string;
247
+ readonly epoch: string;
248
+ readonly dispatchRevision: number;
249
+ readonly receiptRevision: number;
250
+ }
251
+ /** An executed undo's attestation, read from the restored record (Q5). */
252
+ export interface XlsxAiUndoAttestation {
253
+ readonly preRestoreSha256: string;
254
+ readonly restoredSha256: string;
255
+ readonly cursorBefore: number;
256
+ readonly cursorAfter: number;
257
+ readonly entryIndex: number;
258
+ }
259
+ export interface XlsxAiImpactMeasured {
260
+ readonly status: "measured";
261
+ }
262
+ export interface XlsxAiImpactUnmeasured {
263
+ readonly status: "unmeasured";
264
+ readonly reason: string;
265
+ }
266
+ export type XlsxAiImpactStatus = XlsxAiImpactMeasured | XlsxAiImpactUnmeasured;
267
+ /** Why the resident session was dropped inside this request (R-XB8a-4 item 8). */
268
+ export type XlsxAiInvalidationCause = "session-disposed" | "drain-failed" | "drain-unsettled" | "unattested-apply" | "runtime-job-error" | "worker-unavailable" | "wasm-trap";
269
+ export interface XlsxAiOutcomeInvalidation {
270
+ readonly kind: "resident-session";
271
+ readonly sessionDropped: true;
272
+ readonly cause: XlsxAiInvalidationCause;
273
+ }
274
+ /** A warning on an outcome: the runtime's own, or a roster warning such as `apply:drain-refused`. */
275
+ export type XlsxAiOutcomeWarning = XlsxRuntimeWarning | XlsxAiRefusal;
276
+ /**
277
+ * The one answer of `/ai/propose`, `/ai/apply`, `/ai/plan` and `/ai/undo`
278
+ * (record §5.7 `AiMutationOutcome`; XB8 "Preview, propose, validate, apply,
279
+ * and `AiMutationOutcome`"). A verb refusal rides a 200 with `verdict:
280
+ * "refused"` and `executed: false`; `executed` is attestation, never intent.
281
+ */
282
+ export interface XlsxAiMutationOutcome {
283
+ readonly schemaVersion: "xlsx-conductor-ai-outcome-v1";
284
+ readonly phase: "preview" | "validate" | "propose" | "apply" | "plan" | "undo" | "discard";
285
+ readonly verdict: "validated" | "applied" | "applied-with-warnings" | "refused";
286
+ readonly executed: boolean;
287
+ readonly attestation?: XlsxAiAttestation;
288
+ /** An executed undo's attestation (Q5); never on an apply. */
289
+ readonly undoAttestation?: XlsxAiUndoAttestation;
290
+ /** `settled.sessionFence` after an apply (absent after a drain failure); the current stamp on a refusal. */
291
+ readonly sessionFence?: XlsxSessionFence;
292
+ /** Scoped to THIS request's deferred task (Q4 J2). */
293
+ readonly durability: "pending" | "durable" | "failed" | "not-applicable";
294
+ readonly readbackStatus: "verified" | "not-applicable" | "mismatch";
295
+ readonly formulaGraphDelta: XlsxRuntimeAuditDeltaSummary;
296
+ readonly impactStatus: XlsxAiImpactStatus;
297
+ /** Present exactly when this request's containment dropped the resident session. */
298
+ readonly invalidation?: XlsxAiOutcomeInvalidation;
299
+ readonly undoBoundary?: XlsxRuntimeUndoBoundary;
300
+ /** The session identity after the call; empty when no call ran. */
301
+ readonly canonicalHash: string;
302
+ /** The receipt's advisory revision; -1 when no call ran. */
303
+ readonly revision: number;
304
+ readonly actor: {
305
+ readonly actorId: string;
306
+ readonly displayName: string;
307
+ };
308
+ /** `anonymous` / `unauthenticated`: the service produced the outcome with no principal bound (its observe-mode fallback); `system` is its tool-api lane. */
309
+ readonly lane: "agent" | "human" | "system" | "anonymous";
310
+ readonly trust: "host-bound" | "session-bound" | "system" | "unauthenticated";
311
+ readonly proposalRef?: string;
312
+ readonly decisionRef?: string;
313
+ readonly requestId: string;
314
+ readonly replayed?: boolean;
315
+ /** On a `/ai/propose` outcome: the decision subject (Revision 5). */
316
+ readonly proposalDigest?: string;
317
+ readonly subjectKind?: "proposal" | "plan" | "undo";
318
+ readonly expiresAt?: string;
319
+ readonly targetRequestId?: string;
320
+ readonly refusals: readonly XlsxAiRefusal[];
321
+ readonly changedCells: readonly XlsxRuntimeCellReadback[];
322
+ readonly warnings: readonly XlsxAiOutcomeWarning[];
323
+ readonly volatileInputs?: XlsxSessionVolatileInputs;
324
+ readonly staleCause?: XlsxAiStaleCause;
325
+ /** Plan receipts only (Rust's one producer). */
326
+ readonly planDigest?: string;
327
+ /**
328
+ * XBC-2: on a `/ai/propose {proposal}` outcome the fidelity its check ran with (`simulated`: the clone arm ran under
329
+ * the gate and its predicted post-apply content is pinned on the staged subject); on a `/ai/apply` outcome
330
+ * `simulated` exactly when a comparison happened (`previewArmCheck` present; a mismatch is the
331
+ * `internal:preview-arm-divergence` warning on the executed outcome). Absent otherwise.
332
+ */
333
+ readonly previewFidelity?: "guards-only" | "simulated";
334
+ /**
335
+ * XBC-2 R1 (R-XBC2-1 item 2): the apply-time comparison of the clone arm's predicted post-apply content (state SHA +
336
+ * changed-cells digest, pinned at propose from Rust's answer) with the real receipt's `afterState`; present exactly
337
+ * when it happened. `actual` is absent when the runtime answered none (a mismatch).
338
+ */
339
+ readonly previewArmCheck?: {
340
+ readonly predicted: XlsxAiAfterState;
341
+ readonly actual?: XlsxAiAfterState;
342
+ readonly agreed: boolean;
343
+ };
344
+ }
345
+ /** `/ai/discard`'s 200 answer (Q7): `decision` only when a live decision was marked `refused/withdrawn`. */
346
+ export interface XlsxAiDiscardAnswer {
347
+ readonly proposalRef: string;
348
+ readonly subjectKind: "proposal" | "plan" | "undo";
349
+ readonly discarded: true;
350
+ readonly decision?: {
351
+ readonly decisionRef: string;
352
+ readonly state: "refused";
353
+ };
354
+ }
355
+ /** `/ai/discard`'s answer: the discard, or its refusal as an outcome (`proposal:unknown`, `governance:missing-authority`). */
356
+ export type XlsxAiDiscardToolResult = XlsxAiDiscardAnswer | XlsxAiMutationOutcome;
357
+ /**
358
+ * One record per wrapped `/ai` verb, in the service's route order (the four
359
+ * XB7 reads, then XB8's five, then XB9's two). The bijection test pins this
360
+ * list against the route files; a verb added without a record, or a record
361
+ * without a verb, fails there.
362
+ */
363
+ export declare const XLSX_AI_AGENT_TOOLS: readonly XlsxAiAgentToolRecord[];