@beyondwork/xlsx-substrate-bindings 0.1.0 → 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.
- package/README.md +136 -0
- package/dist/ai/agent-metadata.d.ts +363 -0
- package/dist/ai/agent-metadata.js +227 -0
- package/dist/ai/index.d.ts +5 -1
- package/dist/ai/index.js +6 -0
- package/dist/ai/mutation-bridge.d.ts +82 -0
- package/dist/ai/mutation-bridge.js +179 -0
- package/dist/ai/types.d.ts +448 -3
- package/dist/index.d.ts +7 -3
- package/dist/index.js +20 -2
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/types.d.ts +57 -1
- package/dist/wasm/ai-session-bridge.d.ts +97 -0
- package/dist/wasm/ai-session-bridge.js +154 -0
- package/dist/wasm/bridge-contract.d.ts +108 -6
- package/dist/wasm/bridge-contract.js +146 -7
- package/dist/wasm/index.d.ts +43 -2
- package/dist/wasm/index.js +253 -23
- package/dist/wasm/memory-budget.d.ts +77 -0
- package/dist/wasm/memory-budget.js +532 -0
- package/dist/wasm/runtime-guard.d.ts +141 -0
- package/dist/wasm/runtime-guard.js +373 -0
- package/dist/wasm/web.d.ts +16 -3
- package/dist/wasm/web.js +91 -9
- package/generated/wasm-web/xlsx_substrate_wasm.d.ts +66 -0
- package/generated/wasm-web/xlsx_substrate_wasm.js +2488 -2104
- package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
- package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +15 -0
- package/package.json +18 -4
- package/dist/wasm/chart-test-fixture.d.ts +0 -19
- package/dist/wasm/chart-test-fixture.js +0 -42
- package/dist/wasm/media-test-fixture.d.ts +0 -44
- package/dist/wasm/media-test-fixture.js +0 -160
- package/dist/wasm/volatile-test-fixture.d.ts +0 -7
- package/dist/wasm/volatile-test-fixture.js +0 -35
- package/generated/wasm/package.json +0 -3
- package/generated/wasm/sheet-window-binary.mjs +0 -482
- package/generated/wasm/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +0 -45
- package/generated/wasm/xlsx_substrate_wasm.d.ts +0 -336
- package/generated/wasm/xlsx_substrate_wasm.js +0 -2108
- package/generated/wasm/xlsx_substrate_wasm_bg.wasm +0 -0
- package/generated/wasm/xlsx_substrate_wasm_bg.wasm.d.ts +0 -105
package/README.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
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
|
+
|
|
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[];
|