@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.
Files changed (42) hide show
  1. package/README.md +136 -0
  2. package/dist/ai/agent-metadata.d.ts +363 -0
  3. package/dist/ai/agent-metadata.js +227 -0
  4. package/dist/ai/index.d.ts +5 -1
  5. package/dist/ai/index.js +6 -0
  6. package/dist/ai/mutation-bridge.d.ts +82 -0
  7. package/dist/ai/mutation-bridge.js +179 -0
  8. package/dist/ai/types.d.ts +448 -3
  9. package/dist/index.d.ts +7 -3
  10. package/dist/index.js +20 -2
  11. package/dist/runtime/index.d.ts +1 -1
  12. package/dist/runtime/types.d.ts +57 -1
  13. package/dist/wasm/ai-session-bridge.d.ts +97 -0
  14. package/dist/wasm/ai-session-bridge.js +154 -0
  15. package/dist/wasm/bridge-contract.d.ts +108 -6
  16. package/dist/wasm/bridge-contract.js +146 -7
  17. package/dist/wasm/index.d.ts +43 -2
  18. package/dist/wasm/index.js +253 -23
  19. package/dist/wasm/memory-budget.d.ts +77 -0
  20. package/dist/wasm/memory-budget.js +532 -0
  21. package/dist/wasm/runtime-guard.d.ts +141 -0
  22. package/dist/wasm/runtime-guard.js +373 -0
  23. package/dist/wasm/web.d.ts +16 -3
  24. package/dist/wasm/web.js +91 -9
  25. package/generated/wasm-web/xlsx_substrate_wasm.d.ts +66 -0
  26. package/generated/wasm-web/xlsx_substrate_wasm.js +2488 -2104
  27. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
  28. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +15 -0
  29. package/package.json +18 -4
  30. package/dist/wasm/chart-test-fixture.d.ts +0 -19
  31. package/dist/wasm/chart-test-fixture.js +0 -42
  32. package/dist/wasm/media-test-fixture.d.ts +0 -44
  33. package/dist/wasm/media-test-fixture.js +0 -160
  34. package/dist/wasm/volatile-test-fixture.d.ts +0 -7
  35. package/dist/wasm/volatile-test-fixture.js +0 -35
  36. package/generated/wasm/package.json +0 -3
  37. package/generated/wasm/sheet-window-binary.mjs +0 -482
  38. package/generated/wasm/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +0 -45
  39. package/generated/wasm/xlsx_substrate_wasm.d.ts +0 -336
  40. package/generated/wasm/xlsx_substrate_wasm.js +0 -2108
  41. package/generated/wasm/xlsx_substrate_wasm_bg.wasm +0 -0
  42. package/generated/wasm/xlsx_substrate_wasm_bg.wasm.d.ts +0 -105
@@ -0,0 +1,97 @@
1
+ import type { XlsxAiApplyPlanRequest, XlsxAiApplyProposalRequest, XlsxAiApplyReceipt, XlsxAiCalcGraphEdgesRequest, XlsxAiCalcGraphEdgesResult, XlsxAiPlanReceipt, XlsxAiPreviewRequest, XlsxAiPreviewResult, XlsxAiRefusal, XlsxAiScopeBundleReadRequest, XlsxAiScopeNeighborhoodRequest, XlsxAiScopeNeighborhoodResult, XlsxAiScopeReadResult, XlsxAiSessionReferenceRequest, XlsxAiSessionReferenceResult, XlsxAiSessionScopeBundleResult, XlsxAiUnknownOpRefusal, XlsxAiValidateRequest, XlsxAiValidateResult } from "../ai/types.ts";
2
+ /** The one capability gating the AI session lane (Q8). */
3
+ export declare const AI_SESSION_AGENT_CAPABILITY: "ai-session-agent-v1";
4
+ /** The one raw `#[wasm_bindgen]` export every AI verb rides (Q8 fold). */
5
+ export declare const AI_SESSION_RAW_METHOD: "aiSessionCall";
6
+ /**
7
+ * The nine verbs by pool class, as `aiSessionCall`'s `op` values.
8
+ * `sessionCall` runs outside the session commit lock (reads, preview,
9
+ * validate); `sessionCommit` is the two apply ports, which run the fence
10
+ * check, apply, drain and mint in one call. XB7's floors are expressed over
11
+ * the four read verbs of XB5 here; XB8's over the preview, validate and
12
+ * apply verbs. The fifth read verb, `readRuntimeSessionCalcGraphEdges`, is
13
+ * T-O's adjacency export (WP-DOC P4-prep-2): the projector's read, never an
14
+ * agent tool.
15
+ */
16
+ export declare const AI_SESSION_OPS: {
17
+ readonly sessionCall: readonly ["getRuntimeSessionScopeBundle", "resolveRuntimeSessionReference", "readRuntimeSessionScope", "readRuntimeSessionScopeNeighborhood", "readRuntimeSessionCalcGraphEdges", "previewRuntimeSessionAiProposal", "validateRuntimeSessionAiProposal"];
18
+ readonly sessionCommit: readonly ["applyRuntimeSessionAiProposal", "applyRuntimeSessionAiPlan"];
19
+ };
20
+ export type AiSessionCallOp = (typeof AI_SESSION_OPS.sessionCall)[number];
21
+ /**
22
+ * The AI commit ports at op level; `commitSessionOnly` (XB8) types its port
23
+ * with this and maps it to `{ method: "aiSessionCall", args: [port, …] }`.
24
+ */
25
+ export type AiSessionCommitMethod = (typeof AI_SESSION_OPS.sessionCommit)[number];
26
+ export type AiSessionOp = AiSessionCallOp | AiSessionCommitMethod;
27
+ /** The bridge object's typed AI method names are the op names. */
28
+ export type AiSessionMethod = AiSessionOp;
29
+ /** Every AI verb, flat, in the order the two lists declare them. */
30
+ export declare const AI_SESSION_METHODS: readonly AiSessionMethod[];
31
+ /**
32
+ * The raw method names by pool class: the ONE raw export in BOTH classes.
33
+ * The caller's pool `op` ("session-call" vs "session-commit") picks the
34
+ * path, and the pool and the worker check that `args[0]` (the verb) belongs
35
+ * to that class (`isAiSessionOpInClass`), so a commit verb can never ride a
36
+ * session-call job outside the service's session commit lock.
37
+ */
38
+ export declare const AI_SESSION_POOL_METHODS: {
39
+ readonly sessionCall: readonly ["aiSessionCall"];
40
+ readonly sessionCommit: readonly ["aiSessionCall"];
41
+ };
42
+ /** The raw export names the mount gate requires (the two classes, deduplicated). */
43
+ export declare const AI_SESSION_RAW_METHODS: readonly ["aiSessionCall"];
44
+ /** The pool class an `aiSessionCall` job must carry for its verb; `undefined` for an unknown verb. */
45
+ export declare function aiSessionOpClass(op: unknown): "session-call" | "session-commit" | undefined;
46
+ /** The one export's answer for a known op: one of the nine result DTOs (§5.6; T-O). */
47
+ export type XlsxAiSessionCallResult = XlsxAiSessionScopeBundleResult | XlsxAiSessionReferenceResult | XlsxAiScopeReadResult | XlsxAiScopeNeighborhoodResult | XlsxAiCalcGraphEdgesResult | XlsxAiPreviewResult | XlsxAiValidateResult | XlsxAiApplyReceipt | XlsxAiPlanReceipt;
48
+ /**
49
+ * The raw wasm module's AI surface: the one export, `aiSessionCall(handleId,
50
+ * op, request)` — the handle FIRST, the pooled worker's dispatch convention
51
+ * (R-XB5-4). `op` selects the request and result DTO pair (§5.6); an unknown
52
+ * `op` answers the `XlsxAiUnknownOpRefusal` DTO (`verdict: "refused"`, the
53
+ * op, an `input:malformed-body` refusal, no stamp).
54
+ */
55
+ export interface RawXlsxAiSessionModule {
56
+ aiSessionCall(handleId: string, op: string, request: unknown): XlsxAiSessionCallResult | XlsxAiUnknownOpRefusal;
57
+ }
58
+ /**
59
+ * The unknown-op answer is the only AI answer without a stamp: a refused
60
+ * verdict that names the op it could not dispatch (R-XB5-6).
61
+ */
62
+ export declare function isXlsxAiUnknownOpRefusal(answer: unknown): answer is XlsxAiUnknownOpRefusal;
63
+ /**
64
+ * Thrown by the typed methods when the export answers the unknown-op DTO:
65
+ * the nine typed methods only ever send a declared verb, so this answer
66
+ * means the mounted wasm and these bindings disagree on the verb list (a
67
+ * stale bundle), which the service's thrown-class mapping (Q4) surfaces as a
68
+ * typed refusal rather than a mis-shaped result.
69
+ */
70
+ export declare class XlsxAiUnknownOpRefusalError extends Error {
71
+ readonly code: string;
72
+ readonly op: string;
73
+ readonly refusal: XlsxAiRefusal;
74
+ readonly answer: XlsxAiUnknownOpRefusal;
75
+ constructor(answer: XlsxAiUnknownOpRefusal);
76
+ }
77
+ /** The bridge's AI surface: the nine typed methods, dispatching to the one export. */
78
+ export interface XlsxAiSessionBridgeMethods {
79
+ getRuntimeSessionScopeBundle(handleId: string, request: XlsxAiScopeBundleReadRequest): XlsxAiSessionScopeBundleResult;
80
+ resolveRuntimeSessionReference(handleId: string, request: XlsxAiSessionReferenceRequest): XlsxAiSessionReferenceResult;
81
+ readRuntimeSessionScope(handleId: string, request: XlsxAiScopeBundleReadRequest): XlsxAiScopeReadResult;
82
+ readRuntimeSessionScopeNeighborhood(handleId: string, request: XlsxAiScopeNeighborhoodRequest): XlsxAiScopeNeighborhoodResult;
83
+ /** T-O (WP-DOC P4-prep-2): the calc-graph adjacency export — sorted (dependent, precedent) pairs + descriptors; fenced, bounded by `limit`. */
84
+ readRuntimeSessionCalcGraphEdges(handleId: string, request: XlsxAiCalcGraphEdgesRequest): XlsxAiCalcGraphEdgesResult;
85
+ previewRuntimeSessionAiProposal(handleId: string, request: XlsxAiPreviewRequest): XlsxAiPreviewResult;
86
+ validateRuntimeSessionAiProposal(handleId: string, request: XlsxAiValidateRequest): XlsxAiValidateResult;
87
+ applyRuntimeSessionAiProposal(handleId: string, request: XlsxAiApplyProposalRequest): XlsxAiApplyReceipt;
88
+ applyRuntimeSessionAiPlan(handleId: string, request: XlsxAiApplyPlanRequest): XlsxAiPlanReceipt;
89
+ }
90
+ /**
91
+ * Bind the nine typed methods on a validated raw module: each dispatches to
92
+ * `aiSessionCall(handleId, op, request)` with its own verb as `op` — the
93
+ * same call the pooled worker makes (R-XB5-4). The results are plain JSON
94
+ * values (no byte carriers); the one normalization is the unknown-op DTO,
95
+ * surfaced as the typed `XlsxAiUnknownOpRefusalError` (R-XB5-6).
96
+ */
97
+ export declare function attachAiSessionMethods(raw: RawXlsxAiSessionModule): XlsxAiSessionBridgeMethods;
@@ -0,0 +1,154 @@
1
+ // XB5 (design record §5.5, Q8): the AI session lane's bridge surface, declared
2
+ // ONCE. The pool, the worker's twin, the packed consumer and the contract's
3
+ // `requiredRawMethods` all read these constants, so a method cannot reach the
4
+ // bridge without reaching the two allowlists (the X1-D-068 class).
5
+ //
6
+ // Q8's fold criterion fired at XB5 (R-XB5-1): the measured glue delta of
7
+ // eight `#[wasm_bindgen]` exports exceeded 3% of the glue row on both
8
+ // targets, so `crates/sheets-wasm/src/ai_session.rs` declares ONE
9
+ // JSON-dispatched export, `aiSessionCall(handleId, op, req)` — the handle
10
+ // FIRST, as every export the pooled worker dispatches
11
+ // (`raw[method](handleId, ...args)`), so the pool job
12
+ // `{method: "aiSessionCall", args: [op, request]}` and this bridge share ONE
13
+ // dispatch convention (R-XB5-4) — and the nine verbs (the eight of XB5 plus
14
+ // WP-DOC P4-prep-2's read-only adjacency export, T-O; gate note WP-G1) are
15
+ // its `op` values (`AI_SESSION_OPS`, the same list the Rust table
16
+ // `AI_SESSION_OPS` spells). The bridge object keeps the nine TYPED methods:
17
+ // `attachAiSessionMethods` dispatches each to the one raw export with its
18
+ // verb, so callers, `aiSurface` and the DTOs are unchanged by the fold. The
19
+ // service pin `wasm-runtime-pool-allowlist.test.ts` asserts the Rust
20
+ // `js_name` set equals `AI_SESSION_POOL_METHODS`' one raw name and the Rust
21
+ // op table equals `AI_SESSION_OPS`.
22
+ /** The one capability gating the AI session lane (Q8). */
23
+ export const AI_SESSION_AGENT_CAPABILITY = "ai-session-agent-v1";
24
+ /** The one raw `#[wasm_bindgen]` export every AI verb rides (Q8 fold). */
25
+ export const AI_SESSION_RAW_METHOD = "aiSessionCall";
26
+ /**
27
+ * The nine verbs by pool class, as `aiSessionCall`'s `op` values.
28
+ * `sessionCall` runs outside the session commit lock (reads, preview,
29
+ * validate); `sessionCommit` is the two apply ports, which run the fence
30
+ * check, apply, drain and mint in one call. XB7's floors are expressed over
31
+ * the four read verbs of XB5 here; XB8's over the preview, validate and
32
+ * apply verbs. The fifth read verb, `readRuntimeSessionCalcGraphEdges`, is
33
+ * T-O's adjacency export (WP-DOC P4-prep-2): the projector's read, never an
34
+ * agent tool.
35
+ */
36
+ export const AI_SESSION_OPS = {
37
+ sessionCall: [
38
+ "getRuntimeSessionScopeBundle",
39
+ "resolveRuntimeSessionReference",
40
+ "readRuntimeSessionScope",
41
+ "readRuntimeSessionScopeNeighborhood",
42
+ "readRuntimeSessionCalcGraphEdges",
43
+ "previewRuntimeSessionAiProposal",
44
+ "validateRuntimeSessionAiProposal"
45
+ ],
46
+ sessionCommit: ["applyRuntimeSessionAiProposal", "applyRuntimeSessionAiPlan"]
47
+ };
48
+ /** Every AI verb, flat, in the order the two lists declare them. */
49
+ export const AI_SESSION_METHODS = [
50
+ ...AI_SESSION_OPS.sessionCall,
51
+ ...AI_SESSION_OPS.sessionCommit
52
+ ];
53
+ /**
54
+ * The raw method names by pool class: the ONE raw export in BOTH classes.
55
+ * The caller's pool `op` ("session-call" vs "session-commit") picks the
56
+ * path, and the pool and the worker check that `args[0]` (the verb) belongs
57
+ * to that class (`isAiSessionOpInClass`), so a commit verb can never ride a
58
+ * session-call job outside the service's session commit lock.
59
+ */
60
+ export const AI_SESSION_POOL_METHODS = {
61
+ sessionCall: [AI_SESSION_RAW_METHOD],
62
+ sessionCommit: [AI_SESSION_RAW_METHOD]
63
+ };
64
+ /** The raw export names the mount gate requires (the two classes, deduplicated). */
65
+ export const AI_SESSION_RAW_METHODS = [AI_SESSION_RAW_METHOD];
66
+ /** The pool class an `aiSessionCall` job must carry for its verb; `undefined` for an unknown verb. */
67
+ export function aiSessionOpClass(op) {
68
+ if (typeof op !== "string")
69
+ return undefined;
70
+ if (AI_SESSION_OPS.sessionCall.includes(op))
71
+ return "session-call";
72
+ if (AI_SESSION_OPS.sessionCommit.includes(op))
73
+ return "session-commit";
74
+ return undefined;
75
+ }
76
+ /**
77
+ * The unknown-op answer is the only AI answer without a stamp: a refused
78
+ * verdict that names the op it could not dispatch (R-XB5-6).
79
+ */
80
+ export function isXlsxAiUnknownOpRefusal(answer) {
81
+ if (typeof answer !== "object" || answer === null)
82
+ return false;
83
+ const candidate = answer;
84
+ return (candidate.verdict === "refused" &&
85
+ typeof candidate.op === "string" &&
86
+ typeof candidate.refusal === "object" &&
87
+ candidate.refusal !== null &&
88
+ !("sessionEpoch" in candidate));
89
+ }
90
+ /**
91
+ * Thrown by the typed methods when the export answers the unknown-op DTO:
92
+ * the nine typed methods only ever send a declared verb, so this answer
93
+ * means the mounted wasm and these bindings disagree on the verb list (a
94
+ * stale bundle), which the service's thrown-class mapping (Q4) surfaces as a
95
+ * typed refusal rather than a mis-shaped result.
96
+ */
97
+ export class XlsxAiUnknownOpRefusalError extends Error {
98
+ code;
99
+ op;
100
+ refusal;
101
+ answer;
102
+ constructor(answer) {
103
+ super(`${answer.refusal.code}: ${answer.refusal.message}`);
104
+ this.name = "XlsxAiUnknownOpRefusalError";
105
+ this.code = answer.refusal.code;
106
+ this.op = answer.op;
107
+ this.refusal = answer.refusal;
108
+ this.answer = answer;
109
+ }
110
+ }
111
+ /**
112
+ * Bind the nine typed methods on a validated raw module: each dispatches to
113
+ * `aiSessionCall(handleId, op, request)` with its own verb as `op` — the
114
+ * same call the pooled worker makes (R-XB5-4). The results are plain JSON
115
+ * values (no byte carriers); the one normalization is the unknown-op DTO,
116
+ * surfaced as the typed `XlsxAiUnknownOpRefusalError` (R-XB5-6).
117
+ */
118
+ export function attachAiSessionMethods(raw) {
119
+ const call = (op, handleId, request) => {
120
+ const answer = raw.aiSessionCall(handleId, op, request);
121
+ if (isXlsxAiUnknownOpRefusal(answer))
122
+ throw new XlsxAiUnknownOpRefusalError(answer);
123
+ return answer;
124
+ };
125
+ return {
126
+ getRuntimeSessionScopeBundle(handleId, request) {
127
+ return call("getRuntimeSessionScopeBundle", handleId, request);
128
+ },
129
+ resolveRuntimeSessionReference(handleId, request) {
130
+ return call("resolveRuntimeSessionReference", handleId, request);
131
+ },
132
+ readRuntimeSessionScope(handleId, request) {
133
+ return call("readRuntimeSessionScope", handleId, request);
134
+ },
135
+ readRuntimeSessionScopeNeighborhood(handleId, request) {
136
+ return call("readRuntimeSessionScopeNeighborhood", handleId, request);
137
+ },
138
+ readRuntimeSessionCalcGraphEdges(handleId, request) {
139
+ return call("readRuntimeSessionCalcGraphEdges", handleId, request);
140
+ },
141
+ previewRuntimeSessionAiProposal(handleId, request) {
142
+ return call("previewRuntimeSessionAiProposal", handleId, request);
143
+ },
144
+ validateRuntimeSessionAiProposal(handleId, request) {
145
+ return call("validateRuntimeSessionAiProposal", handleId, request);
146
+ },
147
+ applyRuntimeSessionAiProposal(handleId, request) {
148
+ return call("applyRuntimeSessionAiProposal", handleId, request);
149
+ },
150
+ applyRuntimeSessionAiPlan(handleId, request) {
151
+ return call("applyRuntimeSessionAiPlan", handleId, request);
152
+ }
153
+ };
154
+ }
@@ -1,13 +1,17 @@
1
+ import { type RawXlsxAiSessionModule, type XlsxAiSessionBridgeMethods } from "./ai-session-bridge.ts";
1
2
  import type { XlsxAiCompressedContextRequest, XlsxAiCompressedContextResult, XlsxAiCompressedDrilldownRequest, XlsxAiCompressedDrilldownResult, XlsxAiFormulaExplanationResult, XlsxAiReferenceQuery, XlsxAiReferenceResolution, XlsxAiScopeListRequest, XlsxAiScopeListResult, XlsxAiWorkbookInspection } from "../ai/index.ts";
2
- import type { XlsxFormulaCommitRequest, XlsxFormulaCommitResult, XlsxFormulaRecalculateRequest, XlsxFormulaRecalculateResult, XlsxLayoutMetricResizeRequest, XlsxLayoutMetricResizeResult, XlsxLayoutMetricVisibilityRequest, XlsxLayoutMetricVisibilityResult, XlsxFrozenPaneRequest, XlsxFrozenPaneResult, XlsxMergeCellsRequest, XlsxMergeCellsResult, XlsxOutlineGroupVisibilityResult, XlsxOutlineLevelRequest, XlsxOutlineLevelResult, XlsxSheetStructureMutationRequest, XlsxSheetStructureMutationResult, XlsxSheetTabMutationRequest, XlsxSheetTabMutationResult, XlsxShiftCellsCommitRequest, XlsxShiftCellsCommitResult, XlsxRangeFilterApplyRequest, XlsxRangeFilterClearRequest, XlsxRangeFilterResult, XlsxRangeSortRequest, XlsxRangeSortResult, XlsxTableAppendRowRequest, XlsxTableAppendRowResult, XlsxKernelActionRequest, XlsxKernelActionValidation, XlsxKernelCreateRequest, XlsxKernelMutationResult, XlsxKernelPanelReadback, XlsxRangeClearCommitRequest, XlsxRangeClearCommitResult, XlsxRangeFormatCommitRequest, XlsxRangeDataValidationCommitRequest, XlsxRangeDataValidationCommitResult, XlsxReviewCommentCommitRequest, XlsxReviewCommentCommitResult, XlsxFindRequest, XlsxFindResult, XlsxGoToRequest, XlsxGoToResult, XlsxDataRegionRequest, XlsxDataRegionResult, XlsxRangeHyperlinkCommitRequest, XlsxRangeHyperlinkCommitResult, XlsxRangeFormatCommitResult, XlsxRangeFillCommitRequest, XlsxRangeFillCommitResult, XlsxRangePasteCommitRequest, XlsxRangePasteCommitResult, XlsxRangeTransferCommitRequest, XlsxRangeTransferCommitResult, XlsxRuntimeSessionDelimitedExportRequest, XlsxRuntimeSessionDelimitedExportResult, XlsxRuntimeSessionExportRequest, XlsxRuntimeSessionExportResult, XlsxSelectionSetClearCommitRequest, XlsxSelectionSetFormatCommitRequest, XlsxSelectionSetPasteCommitRequest, XlsxSessionRecalculateRequest, XlsxWorkflowContextInput } from "../runtime/index.ts";
3
+ import type { XlsxFormulaCommitRequest, XlsxFormulaCommitResult, XlsxFormulaRecalculateRequest, XlsxFormulaRecalculateResult, XlsxLayoutMetricResizeRequest, XlsxLayoutMetricResizeResult, XlsxLayoutMetricVisibilityRequest, XlsxLayoutMetricVisibilityResult, XlsxFrozenPaneRequest, XlsxFrozenPaneResult, XlsxMergeCellsRequest, XlsxMergeCellsResult, XlsxOutlineGroupVisibilityResult, XlsxOutlineLevelRequest, XlsxOutlineLevelResult, XlsxSheetStructureMutationRequest, XlsxSheetStructureMutationResult, XlsxSheetTabMutationRequest, XlsxSheetTabMutationResult, XlsxDefinedNameMutationRequest, XlsxDefinedNameMutationResult, XlsxShiftCellsCommitRequest, XlsxShiftCellsCommitResult, XlsxRangeFilterApplyRequest, XlsxRangeFilterClearRequest, XlsxRangeFilterResult, XlsxRangeSortRequest, XlsxRangeSortResult, XlsxTableAppendRowRequest, XlsxTableAppendRowResult, XlsxKernelActionRequest, XlsxKernelActionValidation, XlsxKernelCreateRequest, XlsxKernelMutationResult, XlsxKernelPanelReadback, XlsxRangeClearCommitRequest, XlsxRangeClearCommitResult, XlsxRangeFormatCommitRequest, XlsxRangeDataValidationCommitRequest, XlsxRangeDataValidationCommitResult, XlsxReviewCommentCommitRequest, XlsxReviewCommentCommitResult, XlsxFindRequest, XlsxFindResult, XlsxGoToRequest, XlsxGoToResult, XlsxDataRegionRequest, XlsxDataRegionResult, XlsxRangeHyperlinkCommitRequest, XlsxRangeHyperlinkCommitResult, XlsxRangeFormatCommitResult, XlsxRangeFillCommitRequest, XlsxRangeFillCommitResult, XlsxRangePasteCommitRequest, XlsxRangePasteCommitResult, XlsxRangeTransferCommitRequest, XlsxRangeTransferCommitResult, XlsxRuntimeSessionDelimitedExportRequest, XlsxRuntimeSessionDelimitedExportResult, XlsxRuntimeSessionExportRequest, XlsxRuntimeSessionExportResult, XlsxSelectionSetClearCommitRequest, XlsxSelectionSetFormatCommitRequest, XlsxSelectionSetPasteCommitRequest, XlsxSessionRecalculateRequest, XlsxWorkflowContextInput } from "../runtime/index.ts";
3
4
  import type { XlsxScopeHandle } from "../shared.ts";
5
+ import { type XlsxWasmMemoryReadback, type XlsxWasmRuntime } from "./runtime-guard.ts";
4
6
  import { type XlsxSheetWindowBinaryEnvelope } from "./sheet-window-binary.ts";
5
7
  import type { XlsxUiAccessibilitySummary, XlsxUiOverlayLanesReadback, XlsxUiOverlayLanesRequest, XlsxUiSelectionCursor, XlsxUiSelectionReadback, XlsxUiSelectionSetReadback, XlsxUiSheetWindowReadback, XlsxUiSessionBinding, XlsxUiStateClass, XlsxUiStateNamespace, XlsxUiViewportHint, XlsxUiViewportReadback } from "../ui/index.ts";
8
+ export { createXlsxWasmRuntime, deserializeXlsxWasmBridgeError, isXlsxWasmBridgeError, serializeXlsxWasmBridgeError, XlsxWasmBridgeError, type SerializedXlsxWasmBridgeError, type XlsxWasmAdmissionOptions, type XlsxWasmBridgeErrorCode, type XlsxWasmBridgeErrorDetails, type XlsxWasmInstanceSource, type XlsxWasmMemoryReadback, type XlsxWasmReinstantiate, type XlsxWasmRuntime, type XlsxWasmRuntimeOptions } from "./runtime-guard.ts";
9
+ export { estimateXlsxPackageMemory, readWasmMemoryLimits, XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES, type XlsxPackageMemoryEstimate, type XlsxWasmMemoryLimits } from "./memory-budget.ts";
6
10
  export interface XlsxWasmBridgeStatus {
7
11
  readonly packageName: "@beyondwork/xlsx-substrate-bindings";
8
12
  readonly role: "wasm-ai-ui-runtime-binding";
9
- readonly bridgeVersion: "xlsx-wasm-bridge-v40";
10
- readonly capabilities: readonly ("workflow-context-v1" | "workflow-context-v2" | "workflow-overlay-lanes-v1" | "sheet-window-paint-geometry-v1" | "sheet-window-coordinate-posture-v1" | "formula-diagnostics-v2" | "formula-address-commit-v1" | "formula-recalculate-commit-v1" | "formula-recalculate-volatile-inputs-v1" | "formula-translation-interaction-v1" | "kernel-ui-v1" | "runtime-session-handles-v1" | "runtime-session-mutations-v1" | "staged-open-v1" | "sheet-window-cache-v1" | "readback-envelope-v1" | "preserve-only-entities-v1" | "selection-set-v1" | "multi-area-mutation-v1" | "range-fill-commit-v1" | "range-paste-commit-v1" | "range-clear-commit-v1" | "range-format-commit-v1" | "range-transfer-v1" | "layout-metric-resize-v1" | "layout-metric-visibility-v1" | "outline-group-visibility-v1" | "sheet-structure-v1" | "sheet-tabs-v1" | "table-mutation-v1" | "filter-sort-v1" | "sort-commit-v1" | "operation-pattern-hints-v1" | "ai-compressed-bundles-v1" | "ui-capability-records-v1" | "drawing-media-v1" | "drawing-chart-v1" | "sheet-window-binary-v1" | "frozen-pane-v1" | "sheet-window-extent-v1" | "selection-cursor-v1" | "merge-cells-v1" | "shift-cells-v1" | "selection-set-capabilities-v1" | "find-v1" | "go-to-v1" | "data-region-v1")[];
13
+ readonly bridgeVersion: "xlsx-wasm-bridge-v46";
14
+ readonly capabilities: readonly ("workflow-context-v1" | "workflow-context-v2" | "workflow-overlay-lanes-v1" | "sheet-window-paint-geometry-v1" | "sheet-window-coordinate-posture-v1" | "formula-diagnostics-v2" | "formula-address-commit-v1" | "formula-recalculate-commit-v1" | "formula-recalculate-volatile-inputs-v1" | "formula-translation-interaction-v1" | "kernel-ui-v1" | "runtime-session-handles-v1" | "runtime-session-mutations-v1" | "staged-open-v1" | "sheet-window-cache-v1" | "readback-envelope-v1" | "preserve-only-entities-v1" | "selection-set-v1" | "multi-area-mutation-v1" | "range-fill-commit-v1" | "range-paste-commit-v1" | "range-clear-commit-v1" | "range-format-commit-v1" | "range-transfer-v1" | "layout-metric-resize-v1" | "layout-metric-visibility-v1" | "outline-group-visibility-v1" | "sheet-structure-v1" | "sheet-tabs-v1" | "table-mutation-v1" | "filter-sort-v1" | "sort-commit-v1" | "operation-pattern-hints-v1" | "ai-compressed-bundles-v1" | "ui-capability-records-v1" | "drawing-media-v1" | "drawing-chart-v1" | "sheet-window-binary-v1" | "frozen-pane-v1" | "sheet-window-extent-v1" | "selection-cursor-v1" | "merge-cells-v1" | "shift-cells-v1" | "selection-set-capabilities-v1" | "find-v1" | "go-to-v1" | "data-region-v1" | "ai-session-agent-v1" | "defined-names-v1")[];
11
15
  readonly wasmBinding: "mounted";
12
16
  readonly nativeBinding: "not-mounted";
13
17
  readonly readOnly: false;
@@ -47,8 +51,20 @@ export interface XlsxSelectionSetRequest {
47
51
  readonly activeScopeId?: string;
48
52
  readonly anchorScopeId?: string;
49
53
  }
50
- export interface XlsxWasmBridge {
54
+ export interface XlsxWasmBridge extends XlsxAiSessionBridgeMethods {
51
55
  readonly status: XlsxWasmBridgeStatus;
56
+ /**
57
+ * R4: the live instance's linear memory in bytes (`memory.buffer.byteLength`,
58
+ * read on the JS side; no wasm call). Undefined when the loader could not
59
+ * see the instance's memory.
60
+ */
61
+ wasmMemoryBytes(): number | undefined;
62
+ /**
63
+ * R4: set the high-water mark (with `bytes`) and read the memory posture.
64
+ * Linear memory never shrinks, so `aboveHighWater` stays true until the
65
+ * instance is replaced: the host's cue to recycle its worker.
66
+ */
67
+ highWater(bytes?: number): XlsxWasmMemoryReadback;
52
68
  openWorkbookRuntimeSession(bytes: Uint8Array, request?: XlsxRuntimeSessionOpenRequest): XlsxRuntimeSessionHandle;
53
69
  disposeWorkbookRuntimeSession(handleId: string): XlsxRuntimeSessionDisposeResult;
54
70
  inspectWorkbookRuntimeSession(handleId: string): XlsxAiWorkbookInspection;
@@ -190,6 +206,40 @@ export interface XlsxWasmBridge {
190
206
  mutateSheetTabsInSession?(handleId: string, request: XlsxSheetTabMutationRequest): XlsxSheetTabMutationResult;
191
207
  commitTableAppendRowInSession?(handleId: string, request: XlsxTableAppendRowRequest): XlsxTableAppendRowResult;
192
208
  commitShiftCellsInSession?(handleId: string, request: XlsxShiftCellsCommitRequest): XlsxShiftCellsCommitResult;
209
+ /**
210
+ * UX-P-102 phase P2a (bridge v42): the six families that had only a bytes
211
+ * export now commit on the resident session too — selection-set paste /
212
+ * clear / format, hyperlink, data validation and review comment. Same
213
+ * request DTOs as their bytes exports; same results minus `exportedBytes`
214
+ * plus the `session` receipt.
215
+ */
216
+ commitSelectionSetPasteInSession?(handleId: string, request: XlsxSelectionSetPasteCommitRequest): XlsxRangePasteCommitResult;
217
+ commitSelectionSetClearInSession?(handleId: string, request: XlsxSelectionSetClearCommitRequest): XlsxRangeClearCommitResult;
218
+ commitSelectionSetFormatInSession?(handleId: string, request: XlsxSelectionSetFormatCommitRequest): XlsxRangeFormatCommitResult;
219
+ commitRangeHyperlinkInSession?(handleId: string, request: XlsxRangeHyperlinkCommitRequest): XlsxRangeHyperlinkCommitResult;
220
+ commitRangeDataValidationInSession?(handleId: string, request: XlsxRangeDataValidationCommitRequest): XlsxRangeDataValidationCommitResult;
221
+ commitReviewCommentInSession?(handleId: string, request: XlsxReviewCommentCommitRequest): XlsxReviewCommentCommitResult;
222
+ /**
223
+ * UX-P-102 phase P2b (bridge v43): the last six bytes-only families commit
224
+ * on the resident session too — filter apply / clear, sort, row / column
225
+ * outline-group visibility and outline level. Same request DTOs as their
226
+ * bytes exports; same results minus `exportedBytes` plus the `session`
227
+ * receipt.
228
+ */
229
+ commitApplyFilterInSession?(handleId: string, request: XlsxRangeFilterApplyRequest): XlsxRangeFilterResult;
230
+ commitClearFilterInSession?(handleId: string, request: XlsxRangeFilterClearRequest): XlsxRangeFilterResult;
231
+ commitApplySortInSession?(handleId: string, request: XlsxRangeSortRequest): XlsxRangeSortResult;
232
+ setRowOutlineGroupHiddenInSession?(handleId: string, request: XlsxLayoutMetricVisibilityRequest): XlsxOutlineGroupVisibilityResult;
233
+ setColumnOutlineGroupHiddenInSession?(handleId: string, request: XlsxLayoutMetricVisibilityRequest): XlsxOutlineGroupVisibilityResult;
234
+ setSheetOutlineLevelInSession?(handleId: string, request: XlsxOutlineLevelRequest): XlsxOutlineLevelResult;
235
+ /**
236
+ * X5-U-023 (bridge v44): Name Manager authoring on the resident session —
237
+ * create, edit or delete one workbook- or sheet-scoped defined name. Same
238
+ * request DTO as `defineName`; same result minus `exportedBytes` plus the
239
+ * `session` receipt. The commit drops the keep-alive graph, so the drain
240
+ * recalculates every reader in full.
241
+ */
242
+ defineNameInSession?(handleId: string, request: XlsxDefinedNameMutationRequest): XlsxDefinedNameMutationResult;
193
243
  commitRangeFill(bytes: Uint8Array, request: XlsxRangeFillCommitRequest): XlsxRangeFillCommitResult;
194
244
  commitRangePaste(bytes: Uint8Array, request: XlsxRangePasteCommitRequest): XlsxRangePasteCommitResult;
195
245
  commitRangeTransfer(bytes: Uint8Array, request: XlsxRangeTransferCommitRequest): XlsxRangeTransferCommitResult;
@@ -227,6 +277,8 @@ export interface XlsxWasmBridge {
227
277
  commitClearFilter(bytes: Uint8Array, request: XlsxRangeFilterClearRequest): XlsxRangeFilterResult;
228
278
  commitApplySort(bytes: Uint8Array, request: XlsxRangeSortRequest): XlsxRangeSortResult;
229
279
  mutateSheetTabs(bytes: Uint8Array, request: XlsxSheetTabMutationRequest): XlsxSheetTabMutationResult;
280
+ /** X5-U-023 (bridge v44): create, edit or delete one defined name, then export (defined-names-v1). */
281
+ defineName(bytes: Uint8Array, request: XlsxDefinedNameMutationRequest): XlsxDefinedNameMutationResult;
230
282
  /** X5-U-006 insert/delete cells with shift (shift-cells-v1). */
231
283
  commitShiftCells(bytes: Uint8Array, request: XlsxShiftCellsCommitRequest): XlsxShiftCellsCommitResult;
232
284
  }
@@ -258,6 +310,19 @@ export interface XlsxRuntimeSessionMutationBridge extends XlsxWasmBridge {
258
310
  mutateSheetTabsInSession(handleId: string, request: XlsxSheetTabMutationRequest): XlsxSheetTabMutationResult;
259
311
  commitTableAppendRowInSession(handleId: string, request: XlsxTableAppendRowRequest): XlsxTableAppendRowResult;
260
312
  commitShiftCellsInSession(handleId: string, request: XlsxShiftCellsCommitRequest): XlsxShiftCellsCommitResult;
313
+ commitSelectionSetPasteInSession(handleId: string, request: XlsxSelectionSetPasteCommitRequest): XlsxRangePasteCommitResult;
314
+ commitSelectionSetClearInSession(handleId: string, request: XlsxSelectionSetClearCommitRequest): XlsxRangeClearCommitResult;
315
+ commitSelectionSetFormatInSession(handleId: string, request: XlsxSelectionSetFormatCommitRequest): XlsxRangeFormatCommitResult;
316
+ commitRangeHyperlinkInSession(handleId: string, request: XlsxRangeHyperlinkCommitRequest): XlsxRangeHyperlinkCommitResult;
317
+ commitRangeDataValidationInSession(handleId: string, request: XlsxRangeDataValidationCommitRequest): XlsxRangeDataValidationCommitResult;
318
+ commitReviewCommentInSession(handleId: string, request: XlsxReviewCommentCommitRequest): XlsxReviewCommentCommitResult;
319
+ commitApplyFilterInSession(handleId: string, request: XlsxRangeFilterApplyRequest): XlsxRangeFilterResult;
320
+ commitClearFilterInSession(handleId: string, request: XlsxRangeFilterClearRequest): XlsxRangeFilterResult;
321
+ commitApplySortInSession(handleId: string, request: XlsxRangeSortRequest): XlsxRangeSortResult;
322
+ setRowOutlineGroupHiddenInSession(handleId: string, request: XlsxLayoutMetricVisibilityRequest): XlsxOutlineGroupVisibilityResult;
323
+ setColumnOutlineGroupHiddenInSession(handleId: string, request: XlsxLayoutMetricVisibilityRequest): XlsxOutlineGroupVisibilityResult;
324
+ setSheetOutlineLevelInSession(handleId: string, request: XlsxOutlineLevelRequest): XlsxOutlineLevelResult;
325
+ defineNameInSession(handleId: string, request: XlsxDefinedNameMutationRequest): XlsxDefinedNameMutationResult;
261
326
  }
262
327
  /**
263
328
  * T1 feature detection: true when the mounted wasm build advertises
@@ -273,7 +338,7 @@ export interface XlsxRuntimeSessionMutationBridge extends XlsxWasmBridge {
273
338
  */
274
339
  export declare function missingXlsxWasmCapabilities(bridge: XlsxWasmBridge, required: readonly string[]): string[];
275
340
  export declare function supportsRuntimeSessionMutations(bridge: XlsxWasmBridge): bridge is XlsxRuntimeSessionMutationBridge;
276
- export interface RawXlsxWasmModule {
341
+ export interface RawXlsxWasmModule extends RawXlsxAiSessionModule {
277
342
  getWasmStatus(): XlsxWasmBridgeStatus;
278
343
  openWorkbookRuntimeSession(bytes: Uint8Array, request?: XlsxRuntimeSessionOpenRequest): XlsxRuntimeSessionHandle;
279
344
  disposeWorkbookRuntimeSession(handleId: string): XlsxRuntimeSessionDisposeResult;
@@ -365,6 +430,19 @@ export interface RawXlsxWasmModule {
365
430
  mutateSheetTabsInSession?(handleId: string, request: XlsxSheetTabMutationRequest): RawXlsxSheetTabMutationResult;
366
431
  commitTableAppendRowInSession?(handleId: string, request: XlsxTableAppendRowRequest): RawXlsxTableAppendRowResult;
367
432
  commitShiftCellsInSession?(handleId: string, request: XlsxShiftCellsCommitRequest): RawXlsxShiftCellsCommitResult;
433
+ commitSelectionSetPasteInSession?(handleId: string, request: XlsxSelectionSetPasteCommitRequest): RawXlsxRangePasteCommitResult;
434
+ commitSelectionSetClearInSession?(handleId: string, request: XlsxSelectionSetClearCommitRequest): RawXlsxRangeClearCommitResult;
435
+ commitSelectionSetFormatInSession?(handleId: string, request: XlsxSelectionSetFormatCommitRequest): RawXlsxRangeFormatCommitResult;
436
+ commitRangeHyperlinkInSession?(handleId: string, request: XlsxRangeHyperlinkCommitRequest): RawXlsxRangeHyperlinkCommitResult;
437
+ commitRangeDataValidationInSession?(handleId: string, request: XlsxRangeDataValidationCommitRequest): RawXlsxRangeDataValidationCommitResult;
438
+ commitReviewCommentInSession?(handleId: string, request: XlsxReviewCommentCommitRequest): RawXlsxReviewCommentCommitResult;
439
+ commitApplyFilterInSession?(handleId: string, request: XlsxRangeFilterApplyRequest): RawXlsxRangeFilterResult;
440
+ commitClearFilterInSession?(handleId: string, request: XlsxRangeFilterClearRequest): RawXlsxRangeFilterResult;
441
+ commitApplySortInSession?(handleId: string, request: XlsxRangeSortRequest): RawXlsxRangeSortResult;
442
+ setRowOutlineGroupHiddenInSession?(handleId: string, request: XlsxLayoutMetricVisibilityRequest): RawXlsxOutlineGroupVisibilityResult;
443
+ setColumnOutlineGroupHiddenInSession?(handleId: string, request: XlsxLayoutMetricVisibilityRequest): RawXlsxOutlineGroupVisibilityResult;
444
+ setSheetOutlineLevelInSession?(handleId: string, request: XlsxOutlineLevelRequest): RawXlsxOutlineLevelResult;
445
+ defineNameInSession?(handleId: string, request: XlsxDefinedNameMutationRequest): RawXlsxDefinedNameMutationResult;
368
446
  commitRangeFill(bytes: Uint8Array, request: XlsxRangeFillCommitRequest): RawXlsxRangeFillCommitResult;
369
447
  commitRangePaste(bytes: Uint8Array, request: XlsxRangePasteCommitRequest): RawXlsxRangePasteCommitResult;
370
448
  commitRangeTransfer(bytes: Uint8Array, request: XlsxRangeTransferCommitRequest): RawXlsxRangeTransferCommitResult;
@@ -391,6 +469,7 @@ export interface RawXlsxWasmModule {
391
469
  commitClearFilter(bytes: Uint8Array, request: XlsxRangeFilterClearRequest): RawXlsxRangeFilterResult;
392
470
  commitApplySort(bytes: Uint8Array, request: XlsxRangeSortRequest): RawXlsxRangeSortResult;
393
471
  mutateSheetTabs(bytes: Uint8Array, request: XlsxSheetTabMutationRequest): RawXlsxSheetTabMutationResult;
472
+ defineName(bytes: Uint8Array, request: XlsxDefinedNameMutationRequest): RawXlsxDefinedNameMutationResult;
394
473
  commitShiftCells(bytes: Uint8Array, request: XlsxShiftCellsCommitRequest): RawXlsxShiftCellsCommitResult;
395
474
  }
396
475
  type RawXlsxFormulaCommitResult = Omit<XlsxFormulaCommitResult, "exportedBytes"> & {
@@ -456,6 +535,9 @@ type RawXlsxRangeSortResult = Omit<XlsxRangeSortResult, "exportedBytes"> & {
456
535
  type RawXlsxSheetTabMutationResult = Omit<XlsxSheetTabMutationResult, "exportedBytes"> & {
457
536
  readonly exportedBytes?: Uint8Array | readonly number[];
458
537
  };
538
+ type RawXlsxDefinedNameMutationResult = Omit<XlsxDefinedNameMutationResult, "exportedBytes"> & {
539
+ readonly exportedBytes?: Uint8Array | readonly number[];
540
+ };
459
541
  type RawXlsxShiftCellsCommitResult = Omit<XlsxShiftCellsCommitResult, "exportedBytes"> & {
460
542
  readonly exportedBytes?: Uint8Array | readonly number[];
461
543
  };
@@ -515,6 +597,19 @@ export interface XlsxPreserveOnlyEntitiesReadback {
515
597
  readonly entityCount: number;
516
598
  readonly entities: readonly XlsxPreserveOnlyEntityReadback[];
517
599
  }
600
+ /**
601
+ * R5: the bridge version this package mounts. A host reports it with
602
+ * `generatedWasmModuleSha256()`; the package version policy (README, the
603
+ * package.json `conductor` field) moves the MINOR version whenever the
604
+ * published value of this constant changes.
605
+ */
606
+ export declare const BRIDGE_VERSION: XlsxWasmBridgeStatus["bridgeVersion"];
607
+ /**
608
+ * R5: the capabilities every mounted bridge advertises (the mount gate's
609
+ * list). Hosts gate on the capabilities they call; see
610
+ * `missingXlsxWasmCapabilities`.
611
+ */
612
+ export declare const BRIDGE_CAPABILITIES: readonly string[];
518
613
  /**
519
614
  * Result of validating a raw wasm module object against the bridge
520
615
  * contract. `reason` is the soft not-mounted loader reason;
@@ -538,4 +633,11 @@ export type XlsxRawWasmModuleValidation = {
538
633
  * never mount divergent contracts.
539
634
  */
540
635
  export declare function validateRawXlsxWasmModule(raw: RawXlsxWasmModule): XlsxRawWasmModuleValidation;
541
- export declare function createXlsxWasmBridge(raw: RawXlsxWasmModule, status?: XlsxWasmBridgeStatus): XlsxWasmBridge;
636
+ /**
637
+ * Wrap a raw wasm module object in the typed bridge. Every call goes through
638
+ * `runtime` (R4): pre-admission against the memory budget before open and
639
+ * recalculate, and trap containment at the call boundary. Without a runtime
640
+ * the bridge builds one over `source` that can contain a trap but has no
641
+ * Module to re-instantiate from (the loaders always pass one that can).
642
+ */
643
+ export declare function createXlsxWasmBridge(source: RawXlsxWasmModule, status?: XlsxWasmBridgeStatus, runtime?: XlsxWasmRuntime): XlsxWasmBridge;