@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
@@ -0,0 +1,12 @@
1
+ export function classifyXlsxUiState(namespace) {
2
+ switch (namespace) {
3
+ case "runtime.workbook":
4
+ case "ui.scope.projection":
5
+ return "canonical-document";
6
+ case "runtime.viewport":
7
+ case "runtime.collab.session":
8
+ return "session-shared";
9
+ case "ui.local.preference":
10
+ return "local-preference";
11
+ }
12
+ }
@@ -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
+ }