@mnmal-ai/substrate 1.0.0-alpha.2 → 1.0.0-alpha.21

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 (53) hide show
  1. package/README.md +64 -14
  2. package/dist/boot-store-Dz6PGwNY.js +4079 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-BeVye_Oj.d.ts} +2 -87
  4. package/dist/cli-CH7M6ZTQ.js +3383 -0
  5. package/dist/client.browser.js +2485 -0
  6. package/dist/client.d.ts +273 -135
  7. package/dist/client.js +6 -6
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-CoHLKAX0.d.ts} +44 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-D7XRAGC6.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/pg-edges-store-Dnaxesmy.js +443 -0
  19. package/dist/{plugin-QuJN9pG_.js → plugin-BIz4Pr5-.js} +132 -8
  20. package/dist/proposals-bootstrap.js +6 -5
  21. package/dist/proposals.config.schema.json +5 -0
  22. package/dist/proposals.d.ts +17 -5
  23. package/dist/proposals.default-config.json +2 -1
  24. package/dist/proposals.js +2 -3
  25. package/dist/recall-bootstrap.js +5 -4
  26. package/dist/recall.config.schema.json +6 -0
  27. package/dist/recall.d.ts +35 -6
  28. package/dist/recall.js +2 -3
  29. package/dist/{repl-C52wyfMs.js → repl-BUkd9DPZ.js} +65 -33
  30. package/dist/{row-ByLFE2Wx.d.ts → row-aEWVHEsf.d.ts} +92 -12
  31. package/dist/run-Cu9w5Y10.js +2435 -0
  32. package/dist/{plugin-t2g2wX0b.d.ts → schema-DwnXxdjk.d.ts} +1293 -63
  33. package/dist/script-A9dxMRZA.js +143 -0
  34. package/dist/script-runner.js +77 -0
  35. package/dist/sdk.d.ts +227 -38
  36. package/dist/sdk.js +5 -110
  37. package/dist/semver-D_zdq0hi.js +17 -0
  38. package/dist/{src-DWm0iA88.js → src--accZ5Ka.js} +188 -87
  39. package/dist/{src-DMzc3HfW.js → src-BNdhH_Hx.js} +745 -851
  40. package/dist/{src-CG7giuHr.js → src-BQnDrs_E.js} +793 -75
  41. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  42. package/dist/src-BbCUeMsI.js +7723 -0
  43. package/dist/{src-CHp3QyqB.js → src-BmJD4ScT.js} +9215 -3376
  44. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  45. package/dist/substrate-admin.js +17 -782
  46. package/dist/substrate.js +4 -5487
  47. package/dist/testing.d.ts +730 -53
  48. package/dist/testing.js +20 -163
  49. package/dist/{ws-C72iVS5T.d.ts → ws-DJaKruX-.d.ts} +4 -5
  50. package/package.json +26 -26
  51. package/dist/dataset-BQ8egGl5.js +0 -1535
  52. package/dist/schema-g4FQLr0V.d.ts +0 -433
  53. package/dist/src-CXKnqeTW.js +0 -2339
@@ -1,5 +1,4 @@
1
- import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { Unpackr, pack, pack as packFrame, unpack, unpack as unpackFrame } from "msgpackr";
1
+ import { n as pack, r as unpack, t as createUnpackr } from "./msgpackr-Dq18g6Ds.js";
3
2
 
4
3
  //#region ../../packages/substrate-types/src/assert-never.ts
5
4
  /**
@@ -11,6 +10,140 @@ function assertNever(x) {
11
10
  throw new Error(`unhandled variant: ${JSON.stringify(x)}`);
12
11
  }
13
12
 
13
+ //#endregion
14
+ //#region ../../packages/substrate-types/src/expression.ts
15
+ const sig = (name, args, returns, description) => ({
16
+ name,
17
+ args,
18
+ returns,
19
+ description
20
+ });
21
+ const CMP = "both sides the same type; int64 and number compare as number.";
22
+ const EXPR_FUNCTIONS = [
23
+ sig("add", ["number", "number"], "any", "Sum; int64 when both are int64 (or a safe-integer literal), else number. Errors on overflow."),
24
+ sig("sub", ["number", "number"], "any", "Difference; int64 when both are int64, else number. Errors on overflow."),
25
+ sig("mul", ["number", "number"], "any", "Product; int64 when both are int64, else number. Errors on overflow, and on a nonzero product that underflows to zero."),
26
+ sig("div", ["number", "number"], "number", "Quotient as a number; null when the divisor is zero. Errors on overflow, and on a nonzero quotient that underflows to zero."),
27
+ sig("mod", ["int64", "int64"], "int64", "Remainder of int64 arguments (a safe-integer literal counts); null when the divisor is zero."),
28
+ sig("neg", ["number"], "any", "Arithmetic negation; keeps int64."),
29
+ sig("eq", ["any", "any"], "boolean", `Equal; ${CMP}`),
30
+ sig("neq", ["any", "any"], "boolean", `Not equal; ${CMP}`),
31
+ sig("gt", ["any", "any"], "boolean", `Greater than; ${CMP}`),
32
+ sig("gte", ["any", "any"], "boolean", `Greater than or equal; ${CMP}`),
33
+ sig("lt", ["any", "any"], "boolean", `Less than; ${CMP}`),
34
+ sig("lte", ["any", "any"], "boolean", `Less than or equal; ${CMP}`),
35
+ sig("and", "variadic", "boolean", "True when every boolean argument (one or more) is true."),
36
+ sig("or", "variadic", "boolean", "True when any boolean argument (one or more) is true."),
37
+ sig("not", ["boolean"], "boolean", "Boolean negation."),
38
+ sig("isNull", ["any"], "boolean", "True when its one argument is null; any type."),
39
+ sig("in", "variadic", "boolean", "True when the first argument equals any later one (two or more arguments share a type)."),
40
+ sig("length", ["string"], "number", "Length in characters."),
41
+ sig("lower", ["string"], "string", "Lower-cased text; ASCII letters only, every other character is unchanged."),
42
+ sig("upper", ["string"], "string", "Upper-cased text; ASCII letters only, every other character is unchanged."),
43
+ sig("substring", [
44
+ "string",
45
+ "number",
46
+ "number"
47
+ ], "string", "Substring from a 1-based start for a length."),
48
+ sig("concat", "variadic", "string", "Concatenation of one or more string arguments."),
49
+ sig("like", ["string", "likePattern"], "boolean", "SQL LIKE, case-sensitive: % and _ wildcards, backslash escape. The pattern is a lit that does not end in an unescaped backslash."),
50
+ sig("notLike", ["string", "likePattern"], "boolean", "Negated SQL LIKE, case-sensitive."),
51
+ sig("regexpMatch", ["string", "pattern"], "boolean", "True when the portable-subset regex (a lit) matches anywhere."),
52
+ sig("regexpReplace", [
53
+ "string",
54
+ "pattern",
55
+ "string"
56
+ ], "string", "Replace the leftmost-longest regex (a lit) match; the replacement may use \\1 to \\9. The pattern may use capturing groups or |, not both."),
57
+ sig("dateTrunc", ["unit", "date"], "date", "Truncate a date (UTC) to a unit given as a lit."),
58
+ sig("extract", ["unit", "date"], "number", "A date part (UTC) as a number; the unit is a lit."),
59
+ sig("case", "variadic", "any", "Pairs [cond, then] then a final else; branches share a type."),
60
+ sig("coalesce", "variadic", "any", "First non-null of one or more arguments sharing a type.")
61
+ ];
62
+ const EXPR_LIMITS = {
63
+ maxDepth: 16,
64
+ maxNodesPerExpr: 64,
65
+ maxNodesPerFrame: 1024
66
+ };
67
+ /** The aggregate names `_agg`, `having` and grouped reads accept. */
68
+ const EXPR_AGGREGATES = [
69
+ "count",
70
+ "countDistinct",
71
+ "sum",
72
+ "avg",
73
+ "min",
74
+ "max"
75
+ ];
76
+ const DATE_UNITS = [
77
+ "second",
78
+ "minute",
79
+ "hour",
80
+ "day",
81
+ "week",
82
+ "month",
83
+ "year"
84
+ ];
85
+
86
+ //#endregion
87
+ //#region ../../packages/substrate-types/src/int64.ts
88
+ const MIN_INT64 = -(2n ** 63n);
89
+ const MAX_INT64 = 2n ** 63n - 1n;
90
+ const MIN_INT16 = -(2 ** 15);
91
+ const MAX_INT16 = 2 ** 15 - 1;
92
+ const MIN_INT32 = -(2 ** 31);
93
+ const MAX_INT32 = 2 ** 31 - 1;
94
+ const CANONICAL_INT = /^-?(0|[1-9]\d*)$/;
95
+ /**
96
+ * An `int64` operand or write value as a bigint: a bigint, a safe-integer
97
+ * number, or a canonical decimal string, within the int64 range. Anything else
98
+ * (a float, a number past 2^53, `'007'`, `'1e3'`, an out-of-range value) is
99
+ * `undefined`.
100
+ */
101
+ function parseInt64(v) {
102
+ let n;
103
+ if (typeof v === "bigint") n = v;
104
+ else if (typeof v === "number") {
105
+ if (!Number.isSafeInteger(v)) return void 0;
106
+ n = BigInt(v);
107
+ } else if (typeof v === "string" && CANONICAL_INT.test(v)) n = BigInt(v);
108
+ else return void 0;
109
+ return n >= MIN_INT64 && n <= MAX_INT64 ? n : void 0;
110
+ }
111
+ /** Whether `v` is an `int16` value: an integer number within the int16 range. */
112
+ function isInt16(v) {
113
+ return Number.isInteger(v) && v >= MIN_INT16 && v <= MAX_INT16;
114
+ }
115
+ /** Whether `v` is an `int32` value: an integer number within the int32 range. */
116
+ function isInt32(v) {
117
+ return Number.isInteger(v) && v >= MIN_INT32 && v <= MAX_INT32;
118
+ }
119
+ /**
120
+ * `JSON.stringify` that writes a bigint as a decimal string, so an `int64`
121
+ * keeps every digit on the JSON wire. The plain call runs first, so a value
122
+ * with no bigint pays nothing for the replacer.
123
+ */
124
+ function stringifyJson(value) {
125
+ try {
126
+ return JSON.stringify(value);
127
+ } catch (e) {
128
+ if (!(e instanceof TypeError) || !/BigInt/.test(e.message)) throw e;
129
+ return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
130
+ }
131
+ }
132
+ /**
133
+ * Like {@link stringifyJson}, but a bigint is written as an exact JSON number
134
+ * (`9223372036854775807`, not a string), for a jsonb body that `substrate_num`
135
+ * reads back as the number it is.
136
+ */
137
+ function stringifyJsonExact(value) {
138
+ try {
139
+ return JSON.stringify(value);
140
+ } catch (e) {
141
+ if (!(e instanceof TypeError) || !/BigInt/.test(e.message)) throw e;
142
+ const raw = JSON.rawJSON;
143
+ return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? raw(v.toString()) : v);
144
+ }
145
+ }
146
+
14
147
  //#endregion
15
148
  //#region ../../packages/substrate-types/src/qualified-key.ts
16
149
  function parseQualifiedKey(key) {
@@ -31,6 +164,33 @@ function formatQualifiedKey(namespace, name) {
31
164
 
32
165
  //#endregion
33
166
  //#region ../../packages/substrate-pack/src/_plan-cache.ts
167
+ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
168
+ /** The slot for one selection entry, or undefined for a plain field. */
169
+ function walkSlot(name, sel, fieldMap) {
170
+ if (!isObj(sel)) return void 0;
171
+ if (name === "_agg") return {
172
+ kind: "agg",
173
+ names: Object.keys(sel)
174
+ };
175
+ const walk = sel._walk;
176
+ if (!isObj(walk)) return void 0;
177
+ let type;
178
+ if (typeof walk.in === "string") type = /^[^/]+\/([^./]+)\./.exec(walk.in)?.[1];
179
+ else if (typeof walk.out === "string") {
180
+ const def = Object.hasOwn(fieldMap, walk.out) ? fieldMap[walk.out] : void 0;
181
+ if (def?.kind === "crossRef") type = def.type;
182
+ }
183
+ if (type === void 0) return void 0;
184
+ const fields = isObj(sel.fields) ? sel.fields : {};
185
+ return {
186
+ kind: "nested",
187
+ type,
188
+ fields: {
189
+ id: true,
190
+ ...fields
191
+ }
192
+ };
193
+ }
34
194
  /**
35
195
  * Lookup-or-build the per-(fields, fieldMap) plan. O(1) on hit; O(F) on miss
36
196
  * for F selected fields.
@@ -45,14 +205,29 @@ function getRowPlan$2(cache, fields, fieldMap) {
45
205
  if (cached !== void 0) return cached;
46
206
  const entries = Object.entries(fields);
47
207
  const plan = new Array(entries.length);
208
+ let nested = false;
48
209
  for (let i = 0; i < entries.length; i++) {
49
210
  const pair = entries[i];
50
- plan[i] = [
211
+ const def = Object.hasOwn(fieldMap, pair[0]) ? fieldMap[pair[0]] : void 0;
212
+ const slot = def === void 0 ? walkSlot(pair[0], pair[1], fieldMap) : void 0;
213
+ if (slot?.kind === "nested") nested = true;
214
+ plan[i] = slot === void 0 ? [
215
+ pair[0],
216
+ pair[1],
217
+ def
218
+ ] : [
51
219
  pair[0],
52
220
  pair[1],
53
- Object.hasOwn(fieldMap, pair[0]) ? fieldMap[pair[0]] : void 0
221
+ def,
222
+ slot
54
223
  ];
55
224
  }
225
+ if (nested) plan.push([
226
+ "_truncated",
227
+ true,
228
+ void 0,
229
+ { kind: "truncated" }
230
+ ]);
56
231
  perFieldMap.set(fieldMap, plan);
57
232
  return plan;
58
233
  }
@@ -104,272 +279,335 @@ function resolveFieldMap$2(schema, typeName, path, makeError) {
104
279
  }
105
280
 
106
281
  //#endregion
107
- //#region ../../packages/substrate-pack/src/decoder.ts
282
+ //#region ../../packages/substrate-pack/src/encoder.ts
108
283
  /**
109
- * Positional decoder. Spec: §7.0, §7.2.
284
+ * Positional encoder. Spec: §7.0, §7.5.
110
285
  *
111
- * Mirror of `encoder.ts`. Rebuilds named objects from positional tuples using
112
- * the same `FieldInput` the client originally sent plus the schema cached at
113
- * init. Single-vs-list dispatch is driven by `PackEnvelope.shapes[key]`
114
- * (§7.2) — no inference from the tuple shape.
286
+ * Strips field names from the wire. For a selected FieldInput, emits a tuple
287
+ * of values in iteration order; the decoder reconstructs the named object
288
+ * using the same FieldInput plus the schema cached at client init. The win is
289
+ * parse time (§7.5) — msgpackr handles named objects fine, but positional
290
+ * arrays skip the key lookup per cell, which compounds across thousand-row
291
+ * responses.
115
292
  *
116
- * Schema drift (§7.1) is detected here when the caller passes
117
- * `expectedSchemaVersion`: the decoder throws `SchemaDriftError` before
118
- * decoding any data value, so drift fails loudly instead of corrupting row
119
- * shapes. Refetch-and-retry is the caller's job. Without
120
- * `expectedSchemaVersion` no check is made.
293
+ * Contract: `encodePositional` is shape-blind. Callers decide single-vs-list
294
+ * via `PackEnvelope.shapes[key]` (§7.2) and pass either a row or an array
295
+ * of rows; the encoder emits the corresponding tuple or array-of-tuples. It does
296
+ * NOT infer list-vs-single from the value shape.
297
+ *
298
+ * Mutation responses use `encodePositionalFromFieldDef` — mutations don't
299
+ * carry a client-sent `FieldInput`, so the FieldDef declared at registration
300
+ * (MutationSchema.returns) drives the encoding directly.
121
301
  */
122
302
  /**
123
- * @internal — error thrown by the positional decoder on malformed input.
124
- * Exported, but treat as package-private; signature may change without a
125
- * major bump.
303
+ * @internal — error thrown by the positional encoder on malformed input.
304
+ * Exported, but treat as package-private.
126
305
  */
127
- var PackDecodeError = class extends Error {
128
- name = "PackDecodeError";
306
+ var PackEncodeError = class extends Error {
307
+ name = "PackEncodeError";
129
308
  path;
130
309
  constructor(message, path) {
131
310
  super(`${message} at ${path.length === 0 ? "<root>" : path.join(".")}`);
132
311
  this.path = path.slice();
133
312
  }
134
313
  };
135
- /**
136
- * §7.1 loud-failure. Thrown by `decodeEnvelope` when the caller supplied an
137
- * `expectedSchemaVersion` that disagrees with the envelope's declared version.
138
- * Carries both sides of the mismatch so the caller can decide whether to
139
- * refetch the federated schema and retry or surface the error.
140
- */
141
- var SchemaDriftError = class extends Error {
142
- envelopeSchemaVersion;
143
- expectedSchemaVersion;
144
- name = "SchemaDriftError";
145
- constructor(envelopeSchemaVersion, expectedSchemaVersion) {
146
- super(`schema drift: envelope schemaVersion '${envelopeSchemaVersion}' does not match expected '${expectedSchemaVersion}'`);
147
- this.envelopeSchemaVersion = envelopeSchemaVersion;
148
- this.expectedSchemaVersion = expectedSchemaVersion;
149
- }
150
- };
151
- function decodePositional(encoded, fields, schema, typeName, ctx) {
152
- if (encoded === null || encoded === void 0) return null;
153
- return decodeValueByArity(encoded, fields, resolveFieldMap$1(schema, typeName, [typeName]), schema, [typeName], ctx);
314
+ function encodePositional(value, fields, schema, typeName, ctx) {
315
+ if (value === null || value === void 0) return null;
316
+ const plan = getRowPlan$1(fields, resolveFieldMap$1(schema, typeName, [typeName]));
317
+ if (Array.isArray(value)) return value.map((row) => encodeRowWithPlan(row, plan, schema, [typeName], ctx));
318
+ return encodeRowWithPlan(value, plan, schema, [typeName], ctx);
154
319
  }
155
320
  /**
156
- * Decode a mutation response against its declared `FieldDef`. Symmetric to
157
- * `encodePositionalFromFieldDef`.
321
+ * Encode a mutation response against its declared `FieldDef` (no client-sent
322
+ * FieldInput). Symmetric to `encodePositional` but driven entirely by the
323
+ * schema descriptor.
158
324
  *
159
- * @internal — used by `decodeEnvelope` for mutation returns. Treat as
325
+ * - `scalar` → value passes through (nullable tolerated)
326
+ * - `struct` → positional tuple over `def.fields` iteration order
327
+ * - `list` → value is an array; each element encoded against `def.of`
328
+ * - `crossRef` → value is expected to be an id scalar (eq-on-id; we don't
329
+ * recurse into the target type — mutation returns don't embed sub-rows)
330
+ *
331
+ * @internal — used by `encodeEnvelope` for mutation returns. Treat as
160
332
  * package-private.
161
333
  */
162
- function decodePositionalFromFieldDef(encoded, def, schema, ctx, path = []) {
163
- if (encoded === null || encoded === void 0) return null;
164
- return decodeFieldDef(encoded, def, schema, path, ctx);
334
+ function encodePositionalFromFieldDef(value, def, schema, ctx, path = []) {
335
+ if (value === null || value === void 0) return null;
336
+ return encodeFieldDef(value, def, schema, path, ctx);
165
337
  }
166
- function decodeEnvelope(bytes, ctx) {
167
- const raw = unpack(Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
168
- if (ctx.expectedSchemaVersion !== void 0 && raw.schemaVersion !== ctx.expectedSchemaVersion) throw new SchemaDriftError(raw.schemaVersion, ctx.expectedSchemaVersion);
169
- const rewritten = {};
170
- for (const [key, value] of Object.entries(raw.data)) {
171
- const returns = ctx.returnsByKey?.[key];
172
- if (returns !== void 0) {
173
- const currentNs = ctx.currentNsByKey[key];
174
- const schema = currentNs !== void 0 ? ctx.schemas[currentNs] : void 0;
175
- if (currentNs === void 0 || schema === void 0) {
176
- rewritten[key] = value;
177
- continue;
178
- }
179
- rewritten[key] = decodeByShapeFromDef(value, returns, schema, raw.shapes[key], {
180
- schemas: ctx.schemas,
181
- currentNs
182
- });
183
- continue;
184
- }
185
- const fields = ctx.fieldsByKey[key];
186
- const typeName = ctx.typeByKey[key];
338
+ function encodeEnvelope(envelope, ctx) {
339
+ const data = {};
340
+ for (const key of Object.keys(envelope.data)) data[key] = positionValue(envelope, ctx, key);
341
+ return Buffer.from(pack(withData(envelope, data)));
342
+ }
343
+ /**
344
+ * The wire form of `envelope.data[key]`, or of `value` in its place: rows as
345
+ * positional tuples, or the value as-is when nothing positions it. A `list`
346
+ * value's rows encode one by one, so a slice of its rows gives that slice of
347
+ * the whole value's wire form.
348
+ */
349
+ function positionValue(envelope, ctx, key, value = envelope.data[key]) {
350
+ if (isAggShape(envelope.shapes[key])) return value;
351
+ const returns = ctx.returnsByKey?.[key];
352
+ if (returns !== void 0) {
187
353
  const currentNs = ctx.currentNsByKey[key];
188
- if (fields === void 0 || typeName === void 0 || currentNs === void 0) {
189
- rewritten[key] = value;
190
- continue;
191
- }
192
- const schema = ctx.schemas[currentNs];
193
- if (schema === void 0) {
194
- rewritten[key] = value;
195
- continue;
196
- }
197
- const rawShape = raw.shapes[key];
198
- rewritten[key] = decodeByShape(value, fields, schema, typeName, Array.isArray(rawShape) ? void 0 : rawShape, {
354
+ const schema = currentNs !== void 0 ? ctx.schemas[currentNs] : void 0;
355
+ if (currentNs === void 0 || schema === void 0) return value;
356
+ return encodePositionalForShape(value, returns, schema, envelope.shapes[key], {
199
357
  schemas: ctx.schemas,
200
358
  currentNs
201
359
  });
202
360
  }
361
+ const fields = ctx.fieldsByKey[key];
362
+ const typeName = ctx.typeByKey[key];
363
+ const currentNs = ctx.currentNsByKey[key];
364
+ if (fields === void 0 || typeName === void 0 || currentNs === void 0) return value;
365
+ const schema = ctx.schemas[currentNs];
366
+ if (schema === void 0) return value;
367
+ return encodePositional(value, fields, schema, typeName, {
368
+ schemas: ctx.schemas,
369
+ currentNs
370
+ });
371
+ }
372
+ /** `envelope` with `data` replaced by its wire form; `pack` of it is the response body. */
373
+ function withData(envelope, data) {
203
374
  const out = {
204
- schemaVersion: raw.schemaVersion,
205
- data: rewritten,
206
- shapes: raw.shapes
375
+ schemaVersion: envelope.schemaVersion,
376
+ data,
377
+ shapes: envelope.shapes
207
378
  };
208
- if (raw._meta !== void 0) out._meta = raw._meta;
209
- if (raw._pagination !== void 0) out._pagination = raw._pagination;
210
- if (raw._completeness !== void 0) out._completeness = raw._completeness;
211
- if (raw._diagnostics !== void 0) out._diagnostics = raw._diagnostics;
212
- if (raw.errors !== void 0) out.errors = raw.errors;
379
+ if (envelope._meta !== void 0) out._meta = envelope._meta;
380
+ if (envelope._pagination !== void 0) out._pagination = envelope._pagination;
381
+ if (envelope._completeness !== void 0) out._completeness = envelope._completeness;
382
+ if (envelope._diagnostics !== void 0) out._diagnostics = envelope._diagnostics;
383
+ if (envelope.errors !== void 0) out.errors = envelope.errors;
213
384
  return out;
214
385
  }
215
- function decodeByShape(value, fields, schema, typeName, shape, ctx) {
216
- if (value === null || value === void 0) return null;
217
- const plan = getRowPlan$1(fields, resolveFieldMap$1(schema, typeName, [typeName]));
218
- if (shape === "list") {
219
- if (!Array.isArray(value)) throw new PackDecodeError("expected array for list shape", [typeName]);
220
- return value.map((elem) => decodeRowWithPlan(elem, plan, schema, [typeName], ctx));
386
+ /**
387
+ * `pack(wire)` in pieces, a long row list `rowsPerPart` rows per piece, for a
388
+ * `wire` envelope from `withData`. msgpackr's default `pack` writes every
389
+ * object as a map16 (`de`) and records no shared state between values, so
390
+ * the pieces concatenate to the same bytes.
391
+ */
392
+ function* packEnvelopeParts(wire, rowsPerPart) {
393
+ const packed = (v) => Buffer.from(pack(v));
394
+ const keys = Object.keys(wire);
395
+ yield mapHeader(keys.length);
396
+ for (const key of keys) {
397
+ yield packed(key);
398
+ if (key !== "data") {
399
+ yield packed(wire[key]);
400
+ continue;
401
+ }
402
+ const entries = Object.entries(wire.data);
403
+ yield mapHeader(entries.length);
404
+ for (const [k, v] of entries) {
405
+ yield packed(k);
406
+ if (!Array.isArray(v) || v.length <= rowsPerPart) {
407
+ yield packed(v);
408
+ continue;
409
+ }
410
+ yield arrayHeader(v.length);
411
+ for (let i = 0; i < v.length; i += rowsPerPart) {
412
+ const rows = v.slice(i, i + rowsPerPart);
413
+ yield packed(rows).subarray(arrayHeader(rows.length).length);
414
+ }
415
+ }
221
416
  }
222
- return decodeRowWithPlan(value, plan, schema, [typeName], ctx);
223
417
  }
224
- function decodeByShapeFromDef(value, def, schema, shape, ctx) {
225
- if (value === null || value === void 0) return null;
226
- if (Array.isArray(shape)) {
227
- if (!Array.isArray(value)) throw new PackDecodeError("expected array for batched shape", []);
228
- return value.map((elem, idx) => decodeByShapeFromDef(elem, def, schema, shape[idx], ctx));
229
- }
230
- if (shape === "list") {
231
- if (!Array.isArray(value)) throw new PackDecodeError("expected array for list shape", []);
232
- return value.map((elem, idx) => decodePositionalFromFieldDef(elem, def, schema, ctx, [`[${idx}]`]));
233
- }
234
- return decodePositionalFromFieldDef(value, def, schema, ctx);
418
+ function mapHeader(n) {
419
+ if (n > 65535) throw new PackEncodeError(`map of ${n} keys`, []);
420
+ return Uint8Array.of(222, n >> 8, n & 255);
235
421
  }
236
- function resolveFieldMap$1(schema, typeName, path) {
237
- return resolveFieldMap$2(schema, typeName, path, (message, p) => new PackDecodeError(message, p));
422
+ function arrayHeader(n) {
423
+ if (n < 16) return Uint8Array.of(144 | n);
424
+ if (n <= 65535) return Uint8Array.of(220, n >> 8, n & 255);
425
+ return Uint8Array.of(221, n >>> 24, n >> 16 & 255, n >> 8 & 255, n & 255);
426
+ }
427
+ /** A shape whose value is a `{ count }` or `{ groups }` map, not rows. */
428
+ function isAggShape(shape) {
429
+ return shape === "count" || shape === "groups";
238
430
  }
239
431
  /**
240
- * Decide whether `value` is a single tuple or a list of tuples based on its
241
- * shape plus the FieldInput — used only by the top-level `decodePositional`
242
- * helper (the envelope decoder uses `shapes[key]` directly). Heuristic:
243
- * - null → null
244
- * - Array where the first element is itself an array → list of rows
245
- * - Array otherwise → single row (tuple)
432
+ * Encode a single envelope value against its declared `returns` FieldDef,
433
+ * honouring the envelope's single-vs-list shape for that key. `single` encodes
434
+ * one row; `list` encodes an array of rows element-by-element.
246
435
  *
247
- * This heuristic is the ambiguity §7.2 calls out, so callers SHOULD go through
248
- * `decodeEnvelope` to use explicit shape metadata.
436
+ * Batched mutate (§5.13): when the shape is `Array<'single' | 'list'>`, the
437
+ * value is itself `Array<unknown>` (one per-frame slot); each slot encodes
438
+ * against the same FieldDef using its own per-frame shape.
249
439
  */
250
- function decodeValueByArity(value, fields, fieldMap, schema, path, ctx) {
440
+ function encodePositionalForShape(value, def, schema, shape, ctx) {
251
441
  if (value === null || value === void 0) return null;
252
- if (!Array.isArray(value)) throw new PackDecodeError("expected array (tuple) for positional row", path);
253
- const plan = getRowPlan$1(fields, fieldMap);
254
- if (value.length > 0 && Array.isArray(value[0])) return value.map((elem) => decodeRowWithPlan(elem, plan, schema, path, ctx));
255
- return decodeRowWithPlan(value, plan, schema, path, ctx);
442
+ if (Array.isArray(shape)) {
443
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for batched shape", []);
444
+ return value.map((elem, idx) => {
445
+ const perFrameShape = shape[idx];
446
+ return encodePositionalForShape(elem, frameDef(def, idx), schema, perFrameShape, ctx);
447
+ });
448
+ }
449
+ const one = frameDef(def, 0);
450
+ if (shape === "list" && one.kind !== "list") {
451
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for list shape", []);
452
+ return value.map((elem, idx) => encodePositionalFromFieldDef(elem, one, schema, ctx, [`[${idx}]`]));
453
+ }
454
+ return encodePositionalFromFieldDef(value, one, schema, ctx);
256
455
  }
257
- const DECODE_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
456
+ /** Frame `idx`'s return shape: its own entry for a batched key, else the key's one shape. */
457
+ function frameDef(def, idx) {
458
+ if (!Array.isArray(def)) return def;
459
+ const one = def[idx];
460
+ if (one === void 0) throw new PackEncodeError(`no return shape for frame ${idx}`, []);
461
+ return one;
462
+ }
463
+ function resolveFieldMap$1(schema, typeName, path) {
464
+ return resolveFieldMap$2(schema, typeName, path, (message, p) => new PackEncodeError(message, p));
465
+ }
466
+ const ENCODE_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
258
467
  function getRowPlan$1(fields, fieldMap) {
259
- return getRowPlan$2(DECODE_PLAN_CACHE, fields, fieldMap);
468
+ return getRowPlan$2(ENCODE_PLAN_CACHE, fields, fieldMap);
260
469
  }
261
- function decodeRowWithPlan(tuple, plan, schema, path, ctx) {
262
- if (tuple === null || tuple === void 0) return null;
263
- if (!Array.isArray(tuple)) throw new PackDecodeError("expected array (tuple) for row", path);
264
- const out = {};
470
+ function encodeRowWithPlan(row, plan, schema, path, ctx) {
471
+ if (row === null || row === void 0) return null;
472
+ if (typeof row !== "object" || Array.isArray(row)) throw new PackEncodeError(`expected object row, got ${Array.isArray(row) ? "array" : typeof row}`, path);
473
+ const rowObj = row;
265
474
  const len = plan.length;
475
+ const tuple = new Array(len);
266
476
  for (let i = 0; i < len; i++) {
267
477
  const entry = plan[i];
268
478
  const field = entry[0];
269
479
  const selection = entry[1];
270
480
  const def = entry[2];
271
- const cell = tuple[i] ?? null;
481
+ const value = Object.hasOwn(rowObj, field) ? rowObj[field] : void 0;
272
482
  path.push(field);
273
- out[field] = decodeField(cell, selection, def, schema, path, ctx);
483
+ const slot = entry[3];
484
+ tuple[i] = slot === void 0 ? encodeField(value, selection, def, schema, path, ctx) : encodeWalkSlot(value, slot, schema, path, ctx);
274
485
  path.pop();
275
486
  }
276
- return out;
487
+ return tuple;
277
488
  }
278
- function decodeField(cell, selection, def, schema, path, ctx) {
279
- if (cell === null || cell === void 0) return null;
280
- if (def === void 0) return cell;
281
- if (selection === true) return decodeLeaf(cell, def, path);
489
+ function encodeWalkSlot(value, slot, schema, path, ctx) {
490
+ if (value === null || value === void 0) return null;
491
+ switch (slot.kind) {
492
+ case "truncated": return value;
493
+ case "agg": {
494
+ if (typeof value !== "object" || Array.isArray(value)) throw new PackEncodeError("expected object for _agg", path);
495
+ const aggs = value;
496
+ return slot.names.map((n) => coerceScalar(Object.hasOwn(aggs, n) ? aggs[n] : null));
497
+ }
498
+ case "nested": {
499
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for nested selection", path);
500
+ const plan = getRowPlan$1(slot.fields, resolveFieldMap$1(schema, slot.type, path));
501
+ return value.map((row, idx) => {
502
+ path.push(`[${idx}]`);
503
+ const out = encodeRowWithPlan(row, plan, schema, path, ctx);
504
+ path.pop();
505
+ return out;
506
+ });
507
+ }
508
+ default: return assertNever(slot);
509
+ }
510
+ }
511
+ function encodeField(value, selection, def, schema, path, ctx) {
512
+ if (value === null || value === void 0) return null;
513
+ if (def === void 0) return selection === true ? coerceScalar(value) : value;
514
+ if (selection === true) return encodeLeaf(value, def, path);
282
515
  switch (def.kind) {
283
- case "scalar": throw new PackDecodeError(`field is a scalar (${def.type}); cannot select sub-fields`, path);
284
- case "struct": return decodeStruct(cell, selection, def, schema, path, ctx);
285
- case "list": return decodeList(cell, selection, def, schema, path, ctx);
286
- case "crossRef": return decodeCrossRef(cell, selection, def, schema, path, ctx);
516
+ case "scalar": throw new PackEncodeError(`field is a scalar (${def.type}); cannot select sub-fields`, path);
517
+ case "struct": return encodeStruct(value, selection, def, schema, path, ctx);
518
+ case "list": return encodeList(value, selection, def, schema, path, ctx);
519
+ case "crossRef": return encodeCrossRef(value, selection, def, schema, path, ctx);
287
520
  default: return assertNever(def);
288
521
  }
289
522
  }
290
- function decodeLeaf(cell, def, path) {
523
+ function encodeLeaf(value, def, path) {
291
524
  switch (def.kind) {
292
- case "scalar": return cell;
525
+ case "scalar": return coerceScalar(value);
293
526
  case "list":
294
- if (!Array.isArray(cell)) throw new PackDecodeError("expected array for list leaf", path);
295
- return cell;
527
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
528
+ return value.map((v) => coerceScalar(v));
296
529
  case "struct":
297
- case "crossRef": return cell;
530
+ case "crossRef": return value;
298
531
  default: return assertNever(def);
299
532
  }
300
533
  }
301
- function decodeStruct(cell, selection, def, schema, path, ctx) {
302
- return decodeRowWithPlan(cell, getRowPlan$1(selection, def.fields), schema, path, ctx);
534
+ function encodeStruct(value, selection, def, schema, path, ctx) {
535
+ return encodeRowWithPlan(value, getRowPlan$1(selection, def.fields), schema, path, ctx);
303
536
  }
304
- function decodeList(cell, selection, def, schema, path, ctx) {
305
- if (!Array.isArray(cell)) throw new PackDecodeError("expected array for list field", path);
537
+ function encodeList(value, selection, def, schema, path, ctx) {
538
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
306
539
  const inner = def.of;
307
540
  const innerPlan = inner.kind === "struct" ? getRowPlan$1(selection, inner.fields) : void 0;
308
541
  const out = [];
309
- for (let idx = 0; idx < cell.length; idx++) {
310
- const elem = cell[idx];
542
+ for (let idx = 0; idx < value.length; idx++) {
543
+ const elem = value[idx];
311
544
  if (elem === null || elem === void 0) {
312
545
  out.push(null);
313
546
  continue;
314
547
  }
315
548
  path.push(`[${idx}]`);
316
- out.push(decodeListElement(elem, selection, inner, schema, path, ctx, innerPlan));
549
+ out.push(encodeListElement(elem, selection, inner, schema, path, ctx, innerPlan));
317
550
  path.pop();
318
551
  }
319
552
  return out;
320
553
  }
321
- function decodeListElement(elem, selection, inner, schema, elemPath, ctx, structPlan) {
554
+ function encodeListElement(elem, selection, inner, schema, elemPath, ctx, structPlan) {
322
555
  switch (inner.kind) {
323
- case "scalar": throw new PackDecodeError(`list element is scalar (${inner.type}); cannot select sub-fields`, elemPath);
324
- case "struct": return decodeRowWithPlan(elem, structPlan ?? getRowPlan$1(selection, inner.fields), schema, elemPath, ctx);
325
- case "list": return decodeList(elem, selection, inner, schema, elemPath, ctx);
326
- case "crossRef": return decodeCrossRef(elem, selection, inner, schema, elemPath, ctx);
556
+ case "scalar": throw new PackEncodeError(`list element is scalar (${inner.type}); cannot select sub-fields`, elemPath);
557
+ case "struct": return encodeRowWithPlan(elem, structPlan ?? getRowPlan$1(selection, inner.fields), schema, elemPath, ctx);
558
+ case "list": return encodeList(elem, selection, inner, schema, elemPath, ctx);
559
+ case "crossRef": return encodeCrossRef(elem, selection, inner, schema, elemPath, ctx);
327
560
  default: return assertNever(inner);
328
561
  }
329
562
  }
330
- function decodeCrossRef(cell, selection, def, schema, path, ctx) {
331
- if (def.ns === ctx.currentNs) return decodeRowWithPlan(cell, getRowPlan$1(selection, resolveFieldMap$1(schema, def.type, path)), schema, path, ctx);
563
+ function encodeCrossRef(value, selection, def, schema, path, ctx) {
564
+ if (def.ns === ctx.currentNs) return encodeRowWithPlan(value, getRowPlan$1(selection, resolveFieldMap$1(schema, def.type, path)), schema, path, ctx);
332
565
  const schemas = ctx.schemas;
333
- if (schemas === void 0) throw new PackDecodeError(`cross-namespace crossRef '${def.ns}/${def.type}' requires ctx.schemas`, path);
566
+ if (schemas === void 0) throw new PackEncodeError(`cross-namespace crossRef '${def.ns}/${def.type}' requires ctx.schemas`, path);
334
567
  const targetSchema = schemas[def.ns];
335
- if (targetSchema === void 0) throw new PackDecodeError(`cross-namespace crossRef target namespace '${def.ns}' not in ctx.schemas`, path);
336
- return decodeRowWithPlan(cell, getRowPlan$1(selection, resolveFieldMap$1(targetSchema, def.type, path)), targetSchema, path, {
568
+ if (targetSchema === void 0) throw new PackEncodeError(`cross-namespace crossRef target namespace '${def.ns}' not in ctx.schemas`, path);
569
+ return encodeRowWithPlan(value, getRowPlan$1(selection, resolveFieldMap$1(targetSchema, def.type, path)), targetSchema, path, {
337
570
  ...ctx,
338
571
  currentNs: def.ns
339
572
  });
340
573
  }
341
- function decodeFieldDef(value, def, schema, path, ctx) {
574
+ function encodeFieldDef(value, def, schema, path, ctx) {
342
575
  if (value === null || value === void 0) return null;
343
576
  switch (def.kind) {
344
- case "scalar": return value;
345
- case "struct": return decodeStructFromDef(value, def, schema, path, ctx);
346
- case "list": return decodeListFromDef(value, def, schema, path, ctx);
347
- case "crossRef": return value;
577
+ case "scalar": return coerceScalar(value);
578
+ case "struct": return encodeStructFromDef(value, def, schema, path, ctx);
579
+ case "list": return encodeListFromDef(value, def, schema, path, ctx);
580
+ case "crossRef": return coerceScalar(value);
348
581
  default: return assertNever(def);
349
582
  }
350
583
  }
351
- const DECODE_FIELDDEF_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
584
+ const ENCODE_FIELDDEF_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
352
585
  function getFieldDefPlan$1(fields) {
353
- return getFieldDefPlan$2(DECODE_FIELDDEF_PLAN_CACHE, fields);
586
+ return getFieldDefPlan$2(ENCODE_FIELDDEF_PLAN_CACHE, fields);
354
587
  }
355
- function decodeStructFromDef(value, def, schema, path, ctx) {
356
- if (!Array.isArray(value)) throw new PackDecodeError("expected array (tuple) for struct", path);
357
- const out = {};
588
+ function encodeStructFromDef(value, def, schema, path, ctx) {
589
+ if (typeof value !== "object" || Array.isArray(value)) throw new PackEncodeError(`expected object for struct, got ${Array.isArray(value) ? "array" : typeof value}`, path);
590
+ const rowObj = value;
358
591
  const plan = getFieldDefPlan$1(def.fields);
359
592
  const len = plan.length;
593
+ const tuple = new Array(len);
360
594
  for (let i = 0; i < len; i++) {
361
595
  const entry = plan[i];
362
596
  const fieldName = entry[0];
363
597
  const sub = entry[1];
364
- const cell = value[i] ?? null;
598
+ const cell = Object.hasOwn(rowObj, fieldName) ? rowObj[fieldName] : void 0;
599
+ if (cell === void 0) {
600
+ tuple[i] = null;
601
+ continue;
602
+ }
365
603
  path.push(fieldName);
366
- out[fieldName] = decodeFieldDef(cell, sub, schema, path, ctx);
604
+ tuple[i] = encodeFieldDef(cell, sub, schema, path, ctx);
367
605
  path.pop();
368
606
  }
369
- return out;
607
+ return tuple;
370
608
  }
371
- function decodeListFromDef(value, def, schema, path, ctx) {
372
- if (!Array.isArray(value)) throw new PackDecodeError("expected array for list field", path);
609
+ function encodeListFromDef(value, def, schema, path, ctx) {
610
+ if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
373
611
  const out = [];
374
612
  for (let idx = 0; idx < value.length; idx++) {
375
613
  const elem = value[idx];
@@ -378,72 +616,88 @@ function decodeListFromDef(value, def, schema, path, ctx) {
378
616
  continue;
379
617
  }
380
618
  path.push(`[${idx}]`);
381
- out.push(decodeFieldDef(elem, def.of, schema, path, ctx));
619
+ out.push(encodeFieldDef(elem, def.of, schema, path, ctx));
382
620
  path.pop();
383
621
  }
384
622
  return out;
385
623
  }
624
+ /**
625
+ * Identity today — msgpackr round-trips Dates natively. Kept as the single
626
+ * choke point for any future scalar normalisation.
627
+ */
628
+ function coerceScalar(value) {
629
+ return value;
630
+ }
386
631
 
387
632
  //#endregion
388
- //#region ../../packages/substrate-pack/src/encoder.ts
633
+ //#region ../../packages/substrate-pack/src/decoder.ts
389
634
  /**
390
- * Positional encoder. Spec: §7.0, §7.5.
391
- *
392
- * Strips field names from the wire. For a selected FieldInput, emits a tuple
393
- * of values in iteration order; the decoder reconstructs the named object
394
- * using the same FieldInput plus the schema cached at client init. The win is
395
- * parse time (§7.5) — msgpackr handles named objects fine, but positional
396
- * arrays skip the key lookup per cell, which compounds across thousand-row
397
- * responses.
635
+ * Positional decoder. Spec: §7.0, §7.2.
398
636
  *
399
- * Contract: `encodePositional` is shape-blind. Callers decide single-vs-list
400
- * via `PackEnvelope.shapes[key]` (§7.2) and pass either a row or an array
401
- * of rows; the encoder emits the corresponding tuple or array-of-tuples. It does
402
- * NOT infer list-vs-single from the value shape.
637
+ * Mirror of `encoder.ts`. Rebuilds named objects from positional tuples using
638
+ * the same `FieldInput` the client originally sent plus the schema cached at
639
+ * init. Single-vs-list dispatch is driven by `PackEnvelope.shapes[key]`
640
+ * (§7.2) — no inference from the tuple shape.
403
641
  *
404
- * Mutation responses use `encodePositionalFromFieldDef` — mutations don't
405
- * carry a client-sent `FieldInput`, so the FieldDef declared at registration
406
- * (MutationSchema.returns) drives the encoding directly.
642
+ * Schema drift (§7.1) is detected here when the caller passes
643
+ * `expectedSchemaVersion`: the decoder throws `SchemaDriftError` before
644
+ * decoding any data value, so drift fails loudly instead of corrupting row
645
+ * shapes. Refetch-and-retry is the caller's job. Without
646
+ * `expectedSchemaVersion` no check is made.
407
647
  */
408
648
  /**
409
- * @internal — error thrown by the positional encoder on malformed input.
410
- * Exported, but treat as package-private.
649
+ * @internal — error thrown by the positional decoder on malformed input.
650
+ * Exported, but treat as package-private; signature may change without a
651
+ * major bump.
411
652
  */
412
- var PackEncodeError = class extends Error {
413
- name = "PackEncodeError";
653
+ var PackDecodeError = class extends Error {
654
+ name = "PackDecodeError";
414
655
  path;
415
656
  constructor(message, path) {
416
657
  super(`${message} at ${path.length === 0 ? "<root>" : path.join(".")}`);
417
658
  this.path = path.slice();
418
659
  }
419
660
  };
420
- function encodePositional(value, fields, schema, typeName, ctx) {
421
- if (value === null || value === void 0) return null;
422
- const plan = getRowPlan(fields, resolveFieldMap(schema, typeName, [typeName]));
423
- if (Array.isArray(value)) return value.map((row) => encodeRowWithPlan(row, plan, schema, [typeName], ctx));
424
- return encodeRowWithPlan(value, plan, schema, [typeName], ctx);
661
+ /**
662
+ * §7.1 loud-failure. Thrown by `decodeEnvelope` when the caller supplied an
663
+ * `expectedSchemaVersion` that disagrees with the envelope's declared version.
664
+ * Carries both sides of the mismatch so the caller can decide whether to
665
+ * refetch the federated schema and retry or surface the error.
666
+ */
667
+ var SchemaDriftError = class extends Error {
668
+ envelopeSchemaVersion;
669
+ expectedSchemaVersion;
670
+ name = "SchemaDriftError";
671
+ constructor(envelopeSchemaVersion, expectedSchemaVersion) {
672
+ super(`schema drift: envelope schemaVersion '${envelopeSchemaVersion}' does not match expected '${expectedSchemaVersion}'`);
673
+ this.envelopeSchemaVersion = envelopeSchemaVersion;
674
+ this.expectedSchemaVersion = expectedSchemaVersion;
675
+ }
676
+ };
677
+ function decodePositional(encoded, fields, schema, typeName, ctx) {
678
+ if (encoded === null || encoded === void 0) return null;
679
+ return decodeValueByArity(encoded, fields, resolveFieldMap(schema, typeName, [typeName]), schema, [typeName], ctx);
425
680
  }
426
681
  /**
427
- * Encode a mutation response against its declared `FieldDef` (no client-sent
428
- * FieldInput). Symmetric to `encodePositional` but driven entirely by the
429
- * schema descriptor.
430
- *
431
- * - `scalar` → value passes through (nullable tolerated)
432
- * - `struct` → positional tuple over `def.fields` iteration order
433
- * - `list` → value is an array; each element encoded against `def.of`
434
- * - `crossRef` → value is expected to be an id scalar (eq-on-id; we don't
435
- * recurse into the target type — mutation returns don't embed sub-rows)
682
+ * Decode a mutation response against its declared `FieldDef`. Symmetric to
683
+ * `encodePositionalFromFieldDef`.
436
684
  *
437
- * @internal — used by `encodeEnvelope` for mutation returns. Treat as
685
+ * @internal — used by `decodeEnvelope` for mutation returns. Treat as
438
686
  * package-private.
439
687
  */
440
- function encodePositionalFromFieldDef(value, def, schema, ctx, path = []) {
441
- if (value === null || value === void 0) return null;
442
- return encodeFieldDef(value, def, schema, path, ctx);
688
+ function decodePositionalFromFieldDef(encoded, def, schema, ctx, path = []) {
689
+ if (encoded === null || encoded === void 0) return null;
690
+ return decodeFieldDef(encoded, def, schema, path, ctx);
443
691
  }
444
- function encodeEnvelope(envelope, ctx) {
692
+ function decodeEnvelope(bytes, ctx) {
693
+ const raw = unpack(bytes);
694
+ if (ctx.expectedSchemaVersion !== void 0 && raw.schemaVersion !== ctx.expectedSchemaVersion) throw new SchemaDriftError(raw.schemaVersion, ctx.expectedSchemaVersion);
445
695
  const rewritten = {};
446
- for (const [key, value] of Object.entries(envelope.data)) {
696
+ for (const [key, value] of Object.entries(raw.data)) {
697
+ if (isAggShape(raw.shapes[key])) {
698
+ rewritten[key] = value;
699
+ continue;
700
+ }
447
701
  const returns = ctx.returnsByKey?.[key];
448
702
  if (returns !== void 0) {
449
703
  const currentNs = ctx.currentNsByKey[key];
@@ -452,7 +706,7 @@ function encodeEnvelope(envelope, ctx) {
452
706
  rewritten[key] = value;
453
707
  continue;
454
708
  }
455
- rewritten[key] = encodePositionalForShape(value, returns, schema, envelope.shapes[key], {
709
+ rewritten[key] = decodeByShapeFromDef(value, returns, schema, raw.shapes[key], {
456
710
  schemas: ctx.schemas,
457
711
  currentNs
458
712
  });
@@ -470,172 +724,205 @@ function encodeEnvelope(envelope, ctx) {
470
724
  rewritten[key] = value;
471
725
  continue;
472
726
  }
473
- rewritten[key] = encodePositional(value, fields, schema, typeName, {
727
+ const rawShape = raw.shapes[key];
728
+ rewritten[key] = decodeByShape(value, fields, schema, typeName, Array.isArray(rawShape) || isAggShape(rawShape) ? void 0 : rawShape, {
474
729
  schemas: ctx.schemas,
475
730
  currentNs
476
731
  });
477
732
  }
478
733
  const out = {
479
- schemaVersion: envelope.schemaVersion,
734
+ schemaVersion: raw.schemaVersion,
480
735
  data: rewritten,
481
- shapes: envelope.shapes
736
+ shapes: raw.shapes
482
737
  };
483
- if (envelope._meta !== void 0) out._meta = envelope._meta;
484
- if (envelope._pagination !== void 0) out._pagination = envelope._pagination;
485
- if (envelope._completeness !== void 0) out._completeness = envelope._completeness;
486
- if (envelope._diagnostics !== void 0) out._diagnostics = envelope._diagnostics;
487
- if (envelope.errors !== void 0) out.errors = envelope.errors;
488
- return Buffer.from(pack(out));
738
+ if (raw._meta !== void 0) out._meta = raw._meta;
739
+ if (raw._pagination !== void 0) out._pagination = raw._pagination;
740
+ if (raw._completeness !== void 0) out._completeness = raw._completeness;
741
+ if (raw._diagnostics !== void 0) out._diagnostics = raw._diagnostics;
742
+ if (raw.errors !== void 0) out.errors = raw.errors;
743
+ return out;
489
744
  }
490
- /**
491
- * Encode a single envelope value against its declared `returns` FieldDef,
492
- * honouring the envelope's single-vs-list shape for that key. `single` encodes
493
- * one row; `list` encodes an array of rows element-by-element.
494
- *
495
- * Batched mutate (§5.13): when the shape is `Array<'single' | 'list'>`, the
496
- * value is itself `Array<unknown>` (one per-frame slot); each slot encodes
497
- * against the same FieldDef using its own per-frame shape.
498
- */
499
- function encodePositionalForShape(value, def, schema, shape, ctx) {
745
+ function decodeByShape(value, fields, schema, typeName, shape, ctx) {
746
+ if (value === null || value === void 0) return null;
747
+ const plan = getRowPlan(fields, resolveFieldMap(schema, typeName, [typeName]));
748
+ if (shape === "list") {
749
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array for list shape", [typeName]);
750
+ return value.map((elem) => decodeRowWithPlan(elem, plan, schema, [typeName], ctx));
751
+ }
752
+ return decodeRowWithPlan(value, plan, schema, [typeName], ctx);
753
+ }
754
+ function decodeByShapeFromDef(value, def, schema, shape, ctx) {
500
755
  if (value === null || value === void 0) return null;
501
756
  if (Array.isArray(shape)) {
502
- if (!Array.isArray(value)) throw new PackEncodeError("expected array for batched shape", []);
503
- return value.map((elem, idx) => {
504
- const perFrameShape = shape[idx];
505
- return encodePositionalForShape(elem, def, schema, perFrameShape, ctx);
506
- });
757
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array for batched shape", []);
758
+ return value.map((elem, idx) => decodeByShapeFromDef(elem, frameDef(def, idx), schema, shape[idx], ctx));
507
759
  }
508
- if (shape === "list") {
509
- if (!Array.isArray(value)) throw new PackEncodeError("expected array for list shape", []);
510
- return value.map((elem, idx) => encodePositionalFromFieldDef(elem, def, schema, ctx, [`[${idx}]`]));
760
+ const one = frameDef(def, 0);
761
+ if (shape === "list" && one.kind !== "list") {
762
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array for list shape", []);
763
+ return value.map((elem, idx) => decodePositionalFromFieldDef(elem, one, schema, ctx, [`[${idx}]`]));
511
764
  }
512
- return encodePositionalFromFieldDef(value, def, schema, ctx);
765
+ return decodePositionalFromFieldDef(value, one, schema, ctx);
513
766
  }
514
767
  function resolveFieldMap(schema, typeName, path) {
515
- return resolveFieldMap$2(schema, typeName, path, (message, p) => new PackEncodeError(message, p));
768
+ return resolveFieldMap$2(schema, typeName, path, (message, p) => new PackDecodeError(message, p));
516
769
  }
517
- const ENCODE_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
770
+ /**
771
+ * Decide whether `value` is a single tuple or a list of tuples based on its
772
+ * shape plus the FieldInput — used only by the top-level `decodePositional`
773
+ * helper (the envelope decoder uses `shapes[key]` directly). Heuristic:
774
+ * - null → null
775
+ * - Array where the first element is itself an array → list of rows
776
+ * - Array otherwise → single row (tuple)
777
+ *
778
+ * This heuristic is the ambiguity §7.2 calls out, so callers SHOULD go through
779
+ * `decodeEnvelope` to use explicit shape metadata.
780
+ */
781
+ function decodeValueByArity(value, fields, fieldMap, schema, path, ctx) {
782
+ if (value === null || value === void 0) return null;
783
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array (tuple) for positional row", path);
784
+ const plan = getRowPlan(fields, fieldMap);
785
+ if (value.length > 0 && Array.isArray(value[0])) return value.map((elem) => decodeRowWithPlan(elem, plan, schema, path, ctx));
786
+ return decodeRowWithPlan(value, plan, schema, path, ctx);
787
+ }
788
+ const DECODE_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
518
789
  function getRowPlan(fields, fieldMap) {
519
- return getRowPlan$2(ENCODE_PLAN_CACHE, fields, fieldMap);
790
+ return getRowPlan$2(DECODE_PLAN_CACHE, fields, fieldMap);
520
791
  }
521
- function encodeRowWithPlan(row, plan, schema, path, ctx) {
522
- if (row === null || row === void 0) return null;
523
- if (typeof row !== "object" || Array.isArray(row)) throw new PackEncodeError(`expected object row, got ${Array.isArray(row) ? "array" : typeof row}`, path);
524
- const rowObj = row;
792
+ function decodeRowWithPlan(tuple, plan, schema, path, ctx) {
793
+ if (tuple === null || tuple === void 0) return null;
794
+ if (!Array.isArray(tuple)) throw new PackDecodeError("expected array (tuple) for row", path);
795
+ const out = {};
525
796
  const len = plan.length;
526
- const tuple = new Array(len);
527
797
  for (let i = 0; i < len; i++) {
528
798
  const entry = plan[i];
529
799
  const field = entry[0];
530
800
  const selection = entry[1];
531
801
  const def = entry[2];
532
- const value = Object.hasOwn(rowObj, field) ? rowObj[field] : void 0;
802
+ const cell = tuple[i] ?? null;
803
+ const slot = entry[3];
804
+ if (slot?.kind === "truncated" && cell === null) continue;
533
805
  path.push(field);
534
- tuple[i] = encodeField(value, selection, def, schema, path, ctx);
806
+ out[field] = slot === void 0 ? decodeField(cell, selection, def, schema, path, ctx) : decodeWalkSlot(cell, slot, schema, path, ctx);
535
807
  path.pop();
536
808
  }
537
- return tuple;
809
+ return out;
538
810
  }
539
- function encodeField(value, selection, def, schema, path, ctx) {
540
- if (value === null || value === void 0) return null;
541
- if (def === void 0) return selection === true ? coerceScalar(value) : value;
542
- if (selection === true) return encodeLeaf(value, def, path);
811
+ function decodeWalkSlot(cell, slot, schema, path, ctx) {
812
+ if (cell === null || cell === void 0) return null;
813
+ switch (slot.kind) {
814
+ case "truncated": return cell;
815
+ case "agg":
816
+ if (!Array.isArray(cell)) throw new PackDecodeError("expected array for _agg", path);
817
+ return Object.fromEntries(slot.names.map((n, i) => [n, cell[i] ?? null]));
818
+ case "nested": {
819
+ if (!Array.isArray(cell)) throw new PackDecodeError("expected array for nested selection", path);
820
+ const plan = getRowPlan(slot.fields, resolveFieldMap(schema, slot.type, path));
821
+ return cell.map((tuple, idx) => {
822
+ path.push(`[${idx}]`);
823
+ const out = decodeRowWithPlan(tuple, plan, schema, path, ctx);
824
+ path.pop();
825
+ return out;
826
+ });
827
+ }
828
+ default: return assertNever(slot);
829
+ }
830
+ }
831
+ function decodeField(cell, selection, def, schema, path, ctx) {
832
+ if (cell === null || cell === void 0) return null;
833
+ if (def === void 0) return cell;
834
+ if (selection === true) return decodeLeaf(cell, def, path);
543
835
  switch (def.kind) {
544
- case "scalar": throw new PackEncodeError(`field is a scalar (${def.type}); cannot select sub-fields`, path);
545
- case "struct": return encodeStruct(value, selection, def, schema, path, ctx);
546
- case "list": return encodeList(value, selection, def, schema, path, ctx);
547
- case "crossRef": return encodeCrossRef(value, selection, def, schema, path, ctx);
836
+ case "scalar": throw new PackDecodeError(`field is a scalar (${def.type}); cannot select sub-fields`, path);
837
+ case "struct": return decodeStruct(cell, selection, def, schema, path, ctx);
838
+ case "list": return decodeList(cell, selection, def, schema, path, ctx);
839
+ case "crossRef": return decodeCrossRef(cell, selection, def, schema, path, ctx);
548
840
  default: return assertNever(def);
549
841
  }
550
842
  }
551
- function encodeLeaf(value, def, path) {
843
+ function decodeLeaf(cell, def, path) {
552
844
  switch (def.kind) {
553
- case "scalar": return coerceScalar(value);
845
+ case "scalar": return cell;
554
846
  case "list":
555
- if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
556
- return value.map((v) => coerceScalar(v));
847
+ if (!Array.isArray(cell)) throw new PackDecodeError("expected array for list leaf", path);
848
+ return cell;
557
849
  case "struct":
558
- case "crossRef": return value;
850
+ case "crossRef": return cell;
559
851
  default: return assertNever(def);
560
852
  }
561
853
  }
562
- function encodeStruct(value, selection, def, schema, path, ctx) {
563
- return encodeRowWithPlan(value, getRowPlan(selection, def.fields), schema, path, ctx);
854
+ function decodeStruct(cell, selection, def, schema, path, ctx) {
855
+ return decodeRowWithPlan(cell, getRowPlan(selection, def.fields), schema, path, ctx);
564
856
  }
565
- function encodeList(value, selection, def, schema, path, ctx) {
566
- if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
857
+ function decodeList(cell, selection, def, schema, path, ctx) {
858
+ if (!Array.isArray(cell)) throw new PackDecodeError("expected array for list field", path);
567
859
  const inner = def.of;
568
860
  const innerPlan = inner.kind === "struct" ? getRowPlan(selection, inner.fields) : void 0;
569
861
  const out = [];
570
- for (let idx = 0; idx < value.length; idx++) {
571
- const elem = value[idx];
862
+ for (let idx = 0; idx < cell.length; idx++) {
863
+ const elem = cell[idx];
572
864
  if (elem === null || elem === void 0) {
573
865
  out.push(null);
574
866
  continue;
575
867
  }
576
868
  path.push(`[${idx}]`);
577
- out.push(encodeListElement(elem, selection, inner, schema, path, ctx, innerPlan));
869
+ out.push(decodeListElement(elem, selection, inner, schema, path, ctx, innerPlan));
578
870
  path.pop();
579
871
  }
580
872
  return out;
581
873
  }
582
- function encodeListElement(elem, selection, inner, schema, elemPath, ctx, structPlan) {
874
+ function decodeListElement(elem, selection, inner, schema, elemPath, ctx, structPlan) {
583
875
  switch (inner.kind) {
584
- case "scalar": throw new PackEncodeError(`list element is scalar (${inner.type}); cannot select sub-fields`, elemPath);
585
- case "struct": return encodeRowWithPlan(elem, structPlan ?? getRowPlan(selection, inner.fields), schema, elemPath, ctx);
586
- case "list": return encodeList(elem, selection, inner, schema, elemPath, ctx);
587
- case "crossRef": return encodeCrossRef(elem, selection, inner, schema, elemPath, ctx);
876
+ case "scalar": throw new PackDecodeError(`list element is scalar (${inner.type}); cannot select sub-fields`, elemPath);
877
+ case "struct": return decodeRowWithPlan(elem, structPlan ?? getRowPlan(selection, inner.fields), schema, elemPath, ctx);
878
+ case "list": return decodeList(elem, selection, inner, schema, elemPath, ctx);
879
+ case "crossRef": return decodeCrossRef(elem, selection, inner, schema, elemPath, ctx);
588
880
  default: return assertNever(inner);
589
881
  }
590
882
  }
591
- function encodeCrossRef(value, selection, def, schema, path, ctx) {
592
- if (def.ns === ctx.currentNs) return encodeRowWithPlan(value, getRowPlan(selection, resolveFieldMap(schema, def.type, path)), schema, path, ctx);
883
+ function decodeCrossRef(cell, selection, def, schema, path, ctx) {
884
+ if (def.ns === ctx.currentNs) return decodeRowWithPlan(cell, getRowPlan(selection, resolveFieldMap(schema, def.type, path)), schema, path, ctx);
593
885
  const schemas = ctx.schemas;
594
- if (schemas === void 0) throw new PackEncodeError(`cross-namespace crossRef '${def.ns}/${def.type}' requires ctx.schemas`, path);
886
+ if (schemas === void 0) throw new PackDecodeError(`cross-namespace crossRef '${def.ns}/${def.type}' requires ctx.schemas`, path);
595
887
  const targetSchema = schemas[def.ns];
596
- if (targetSchema === void 0) throw new PackEncodeError(`cross-namespace crossRef target namespace '${def.ns}' not in ctx.schemas`, path);
597
- return encodeRowWithPlan(value, getRowPlan(selection, resolveFieldMap(targetSchema, def.type, path)), targetSchema, path, {
888
+ if (targetSchema === void 0) throw new PackDecodeError(`cross-namespace crossRef target namespace '${def.ns}' not in ctx.schemas`, path);
889
+ return decodeRowWithPlan(cell, getRowPlan(selection, resolveFieldMap(targetSchema, def.type, path)), targetSchema, path, {
598
890
  ...ctx,
599
891
  currentNs: def.ns
600
892
  });
601
893
  }
602
- function encodeFieldDef(value, def, schema, path, ctx) {
894
+ function decodeFieldDef(value, def, schema, path, ctx) {
603
895
  if (value === null || value === void 0) return null;
604
896
  switch (def.kind) {
605
- case "scalar": return coerceScalar(value);
606
- case "struct": return encodeStructFromDef(value, def, schema, path, ctx);
607
- case "list": return encodeListFromDef(value, def, schema, path, ctx);
608
- case "crossRef": return coerceScalar(value);
897
+ case "scalar": return value;
898
+ case "struct": return decodeStructFromDef(value, def, schema, path, ctx);
899
+ case "list": return decodeListFromDef(value, def, schema, path, ctx);
900
+ case "crossRef": return value;
609
901
  default: return assertNever(def);
610
902
  }
611
903
  }
612
- const ENCODE_FIELDDEF_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
904
+ const DECODE_FIELDDEF_PLAN_CACHE = /* @__PURE__ */ new WeakMap();
613
905
  function getFieldDefPlan(fields) {
614
- return getFieldDefPlan$2(ENCODE_FIELDDEF_PLAN_CACHE, fields);
906
+ return getFieldDefPlan$2(DECODE_FIELDDEF_PLAN_CACHE, fields);
615
907
  }
616
- function encodeStructFromDef(value, def, schema, path, ctx) {
617
- if (typeof value !== "object" || Array.isArray(value)) throw new PackEncodeError(`expected object for struct, got ${Array.isArray(value) ? "array" : typeof value}`, path);
618
- const rowObj = value;
908
+ function decodeStructFromDef(value, def, schema, path, ctx) {
909
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array (tuple) for struct", path);
910
+ const out = {};
619
911
  const plan = getFieldDefPlan(def.fields);
620
912
  const len = plan.length;
621
- const tuple = new Array(len);
622
913
  for (let i = 0; i < len; i++) {
623
914
  const entry = plan[i];
624
915
  const fieldName = entry[0];
625
916
  const sub = entry[1];
626
- const cell = Object.hasOwn(rowObj, fieldName) ? rowObj[fieldName] : void 0;
627
- if (cell === void 0) {
628
- tuple[i] = null;
629
- continue;
630
- }
917
+ const cell = value[i] ?? null;
631
918
  path.push(fieldName);
632
- tuple[i] = encodeFieldDef(cell, sub, schema, path, ctx);
919
+ out[fieldName] = decodeFieldDef(cell, sub, schema, path, ctx);
633
920
  path.pop();
634
921
  }
635
- return tuple;
922
+ return out;
636
923
  }
637
- function encodeListFromDef(value, def, schema, path, ctx) {
638
- if (!Array.isArray(value)) throw new PackEncodeError("expected array for list field", path);
924
+ function decodeListFromDef(value, def, schema, path, ctx) {
925
+ if (!Array.isArray(value)) throw new PackDecodeError("expected array for list field", path);
639
926
  const out = [];
640
927
  for (let idx = 0; idx < value.length; idx++) {
641
928
  const elem = value[idx];
@@ -644,17 +931,47 @@ function encodeListFromDef(value, def, schema, path, ctx) {
644
931
  continue;
645
932
  }
646
933
  path.push(`[${idx}]`);
647
- out.push(encodeFieldDef(elem, def.of, schema, path, ctx));
934
+ out.push(decodeFieldDef(elem, def.of, schema, path, ctx));
648
935
  path.pop();
649
936
  }
650
937
  return out;
651
938
  }
939
+
940
+ //#endregion
941
+ //#region ../../packages/substrate-pack/src/mutation-returns.ts
942
+ /** What a row-writing mutation answers when the frame names no `fields`. */
943
+ const MUTATION_ACK_FIELDS = {
944
+ id: true,
945
+ shortId: true
946
+ };
947
+ /** The `returns` a mutation's result is positioned by, given the frame's `fields` (`true` selects everything). */
948
+ function mutationReturns(mutation, fields) {
949
+ if (fields === true) return mutation.returns;
950
+ const selection = fields ?? (mutation.writesRows === true ? MUTATION_ACK_FIELDS : void 0);
951
+ return selection === void 0 ? mutation.returns : narrow(mutation.returns, selection);
952
+ }
652
953
  /**
653
- * Identity today — msgpackr round-trips Dates natively. Kept as the single
654
- * choke point for any future scalar normalisation.
954
+ * `def` narrowed to the selection, in declared order: a list narrows its
955
+ * element, and a nested selection narrows a nested struct, as the JSON
956
+ * projection recurses. A selected field the struct does not declare is
957
+ * dropped, as the JSON projection drops a field the row does not carry.
655
958
  */
656
- function coerceScalar(value) {
657
- return value;
959
+ function narrow(def, selection) {
960
+ if (def.kind === "list") return {
961
+ ...def,
962
+ of: narrow(def.of, selection)
963
+ };
964
+ if (def.kind !== "struct") return def;
965
+ const fields = {};
966
+ for (const [name, field] of Object.entries(def.fields)) {
967
+ const sub = selection[name];
968
+ if (sub === void 0) continue;
969
+ fields[name] = typeof sub === "object" && sub !== null ? narrow(field, sub) : field;
970
+ }
971
+ return {
972
+ ...def,
973
+ fields
974
+ };
658
975
  }
659
976
 
660
977
  //#endregion
@@ -685,7 +1002,7 @@ function encodeStreamChunk(input) {
685
1002
  * `_meta` round-trip unchanged.
686
1003
  */
687
1004
  function decodeStreamChunk(bytes, input) {
688
- const raw = unpack(Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
1005
+ const raw = unpack(bytes);
689
1006
  const decoded = decodePositional(raw.data, input.fields, input.schema, input.typeName, {
690
1007
  currentNs: input.currentNs,
691
1008
  ...input.schemas !== void 0 ? { schemas: input.schemas } : {}
@@ -705,25 +1022,24 @@ function decodeStreamChunk(bytes, input) {
705
1022
  //#endregion
706
1023
  //#region ../../packages/substrate-pack/src/wire.ts
707
1024
  /**
708
- * WS-frame wire codec. Spec §8.5.
1025
+ * Frame wire codec. Spec §8.5.
709
1026
  *
710
- * Centralizes JSON-vs-pack envelope handling for WebSocket transports plus the
1027
+ * Centralizes JSON-vs-pack envelope handling for frame streams plus the
711
1028
  * precomputed decode plan that turns positional `data` tuples back into named
712
1029
  * objects. The plan is built once per subscription, so per-frame work is
713
1030
  * O(plan entries). Shared by substrate-client and the perf harness so both
714
1031
  * measure the same codepath.
715
1032
  */
716
1033
  /**
717
- * Encode an outbound WS frame. Pack mode returns msgpack bytes; JSON mode
718
- * returns stringified text. The `mode` argument is the wire-format discriminant
719
- * — call sites can route the result to the right `WebSocket.send` overload via
720
- * a typed `typeof wire === 'string'` branch.
1034
+ * Encode an outbound frame. Pack mode returns msgpack bytes; JSON mode
1035
+ * returns stringified text. The `mode` argument is the wire-format discriminant;
1036
+ * callers branch on `typeof wire === 'string'`.
721
1037
  */
722
1038
  function encodeWsFrame(value, mode) {
723
- return mode === "pack" ? pack(value) : JSON.stringify(value);
1039
+ return mode === "pack" ? pack(value) : stringifyJson(value);
724
1040
  }
725
1041
  /**
726
- * Decode an inbound WS message envelope (the outer `{ id, kind, data?, ... }`
1042
+ * Decode an inbound frame envelope (the outer `{ id, kind, data?, ... }`
727
1043
  * shape — positional `data` reconstruction is a separate concern handled by
728
1044
  * `applyDecodePlanInPlace`).
729
1045
  *
@@ -737,9 +1053,15 @@ function encodeWsFrame(value, mode) {
737
1053
  * `raw as string` casts at every call site.
738
1054
  */
739
1055
  function decodeWsEnvelope(raw, mode) {
740
- if (mode === "pack") return inbound.unpack(toBytes(raw));
1056
+ if (mode === "pack") {
1057
+ inbound ??= createUnpackr({
1058
+ structuredClone: false,
1059
+ mapsAsObjects: true
1060
+ });
1061
+ return inbound.unpack(toBytes(raw));
1062
+ }
741
1063
  if (typeof raw === "string") return JSON.parse(raw);
742
- return JSON.parse(Buffer.from(toBytes(raw)).toString("utf8"));
1064
+ return JSON.parse(new TextDecoder().decode(toBytes(raw)));
743
1065
  }
744
1066
  /**
745
1067
  * Inbound frames come from untrusted peers: structured-clone references (and
@@ -747,10 +1069,7 @@ function decodeWsEnvelope(raw, mode) {
747
1069
  * plain-object maps. msgpackr's other built-in extensions are process-global
748
1070
  * and still decode, so a server checks a request with `isPlainRequestData`.
749
1071
  */
750
- const inbound = new Unpackr({
751
- structuredClone: false,
752
- mapsAsObjects: true
753
- });
1072
+ let inbound;
754
1073
  const MAX_REQUEST_DEPTH = 64;
755
1074
  /**
756
1075
  * Whether a decoded request holds only JSON-shaped data (plus `Date`, which
@@ -771,7 +1090,7 @@ function isPlainRequestData(value, depth = 0) {
771
1090
  function toBytes(raw) {
772
1091
  if (raw instanceof Uint8Array) return raw;
773
1092
  if (raw instanceof ArrayBuffer) return new Uint8Array(raw);
774
- return Buffer.from(raw);
1093
+ return new Uint8Array(raw);
775
1094
  }
776
1095
  /**
777
1096
  * Build the decode plan from a frame spec map + federated schemas. Called
@@ -827,13 +1146,144 @@ function applyDecodePlanInPlace(envelope, plan) {
827
1146
  }
828
1147
 
829
1148
  //#endregion
830
- //#region ../../packages/substrate-pack/src/index.ts
1149
+ //#region ../../packages/substrate-pack/src/stream-frames.ts
1150
+ /**
1151
+ * Length-prefixed stream frames: the body of an HTTP/2 subscription or stream.
1152
+ *
1153
+ * Each frame is a big-endian u32 payload length, then the payload: UTF-8 JSON
1154
+ * or msgpack, exactly what `encodeWsFrame` produces, so
1155
+ * the positional pack decode plan applies unchanged. A zero-length frame is a
1156
+ * heartbeat and carries nothing.
1157
+ */
1158
+ const FRAMES_JSON_MIME = "application/vnd.substrate.frames+json";
1159
+ const FRAMES_PACK_MIME = "application/vnd.substrate.frames+pack";
1160
+ /** Largest payload a decoder accepts unless told otherwise. */
1161
+ const DEFAULT_MAX_FRAME_BYTES = 16777216;
1162
+ /** A frame of length 0: keeps an idle stream alive, and decoders skip it. */
1163
+ const HEARTBEAT_FRAME = /* @__PURE__ */ new Uint8Array(4);
1164
+ var FrameStreamError = class extends Error {
1165
+ code;
1166
+ constructor(code, message) {
1167
+ super(message);
1168
+ this.name = "FrameStreamError";
1169
+ this.code = code;
1170
+ }
1171
+ };
1172
+ /** A little over three of the server's 20 s heartbeats. */
1173
+ const DEFAULT_STREAM_IDLE_MS = 65e3;
1174
+ /**
1175
+ * `body`, failing with `stream_idle` when a read waits `ms` for bytes,
1176
+ * heartbeats included. It times only reads the consumer is waiting on, so a
1177
+ * slow consumer never trips it; a connection that died without closing does.
1178
+ * The underlying reader is cancelled on timeout, which settles its pending read.
1179
+ */
1180
+ function withIdleTimeout(body, ms) {
1181
+ const reader = body.getReader();
1182
+ return new ReadableStream({
1183
+ async pull(controller) {
1184
+ let timer;
1185
+ const idle = new Promise((_, reject) => {
1186
+ timer = setTimeout(() => reject(new FrameStreamError("stream_idle", `the stream sent nothing for ${ms} ms`)), ms);
1187
+ });
1188
+ try {
1189
+ const r = await Promise.race([reader.read(), idle]);
1190
+ if (r.done) controller.close();
1191
+ else controller.enqueue(r.value);
1192
+ } catch (err) {
1193
+ reader.cancel().catch(() => {});
1194
+ controller.error(err);
1195
+ } finally {
1196
+ clearTimeout(timer);
1197
+ }
1198
+ },
1199
+ cancel(reason) {
1200
+ return reader.cancel(reason);
1201
+ }
1202
+ }, { highWaterMark: 0 });
1203
+ }
1204
+ /** The frames encoding an `Accept` header asks for, or undefined when it asks for none. */
1205
+ function framesEncodingFromAccept(accept) {
1206
+ if (accept === void 0) return void 0;
1207
+ for (const clause of accept.split(",")) {
1208
+ const [type = "", ...params] = clause.split(";");
1209
+ if (params.some((p) => /^\s*q\s*=\s*0(\.0*)?\s*$/i.test(p))) continue;
1210
+ const mime = type.trim().toLowerCase();
1211
+ if (mime === "application/vnd.substrate.frames+pack") return "pack";
1212
+ if (mime === "application/vnd.substrate.frames+json") return "json";
1213
+ }
1214
+ }
1215
+ const utf8 = new TextEncoder();
1216
+ /**
1217
+ * One frame: u32 BE length, then `value` as JSON or msgpack.
1218
+ *
1219
+ * @throws FrameStreamError `frame_too_large` when the payload is over `maxFrameBytes`,
1220
+ * which a decoder with the same limit would refuse
1221
+ */
1222
+ function encodeStreamFrame(value, mode, maxFrameBytes = DEFAULT_MAX_FRAME_BYTES) {
1223
+ const raw = encodeWsFrame(value, mode);
1224
+ const payload = typeof raw === "string" ? utf8.encode(raw) : raw;
1225
+ if (payload.length > maxFrameBytes) throw new FrameStreamError("frame_too_large", `frame of ${payload.length} bytes exceeds the ${maxFrameBytes}-byte limit`);
1226
+ const out = new Uint8Array(4 + payload.length);
1227
+ new DataView(out.buffer).setUint32(0, payload.length, false);
1228
+ out.set(payload, 4);
1229
+ return out;
1230
+ }
831
1231
  /**
832
- * WebSocket subprotocol advertised in `Sec-WebSocket-Protocol` at handshake
833
- * time. Connections negotiating this subprotocol receive msgpack frames with
834
- * positionally-encoded `data`; anything else falls back to JSON.
1232
+ * The payloads of a frame stream, in order, heartbeats skipped. A length above
1233
+ * `maxFrameBytes` throws `frame_too_large` before any of that payload is read
1234
+ * or allocated; a body that ends inside a frame throws `truncated_frame`.
835
1235
  */
836
- const WS_SUBPROTOCOL_SUBSTRATE_PACK = "substrate-pack";
1236
+ async function* decodeStreamFrames(body, opts = {}) {
1237
+ const max = opts.maxFrameBytes ?? 16777216;
1238
+ if (!Number.isInteger(max) || max < 0) throw new RangeError(`maxFrameBytes must be a non-negative integer, got ${max}`);
1239
+ let buf = /* @__PURE__ */ new Uint8Array(4096);
1240
+ let start = 0;
1241
+ let end = 0;
1242
+ const append = (chunk) => {
1243
+ if (end + chunk.length > buf.length) {
1244
+ const live = end - start;
1245
+ if (live + chunk.length > buf.length) {
1246
+ const grown = new Uint8Array(Math.max(buf.length * 2, live + chunk.length));
1247
+ grown.set(buf.subarray(start, end), 0);
1248
+ buf = grown;
1249
+ } else buf.copyWithin(0, start, end);
1250
+ start = 0;
1251
+ end = live;
1252
+ }
1253
+ buf.set(chunk, end);
1254
+ end += chunk.length;
1255
+ };
1256
+ const source = typeof body[Symbol.asyncIterator] === "function" ? body : readableToIterable(body);
1257
+ for await (const chunk of source) {
1258
+ append(chunk);
1259
+ while (end - start >= 4) {
1260
+ const len = new DataView(buf.buffer, buf.byteOffset + start, 4).getUint32(0, false);
1261
+ if (len > max) throw new FrameStreamError("frame_too_large", `frame of ${len} bytes exceeds the ${max}-byte limit`);
1262
+ if (end - start < 4 + len) break;
1263
+ if (len > 0) yield buf.slice(start + 4, start + 4 + len);
1264
+ start += 4 + len;
1265
+ }
1266
+ }
1267
+ if (end - start > 0) throw new FrameStreamError("truncated_frame", `stream ended inside a frame (${end - start} bytes left over)`);
1268
+ }
1269
+ /** A ReadableStream without async iteration (Safari), cancelled when the consumer stops early. */
1270
+ async function* readableToIterable(stream) {
1271
+ const reader = stream.getReader();
1272
+ let finished = false;
1273
+ try {
1274
+ for (;;) {
1275
+ const { done, value } = await reader.read();
1276
+ if (done) {
1277
+ finished = true;
1278
+ return;
1279
+ }
1280
+ yield value;
1281
+ }
1282
+ } finally {
1283
+ if (!finished) await reader.cancel().catch(() => {});
1284
+ reader.releaseLock();
1285
+ }
1286
+ }
837
1287
 
838
1288
  //#endregion
839
- export { assertNever as S, decodeEnvelope as _, buildDecodePlan as a, formatQualifiedKey as b, isPlainRequestData as c, PackEncodeError as d, encodeEnvelope as f, SchemaDriftError as g, PackDecodeError as h, applyDecodePlanInPlace as i, decodeStreamChunk as l, encodePositionalFromFieldDef as m, packFrame as n, decodeWsEnvelope as o, encodePositional as p, unpackFrame as r, encodeWsFrame as s, WS_SUBPROTOCOL_SUBSTRATE_PACK as t, encodeStreamChunk as u, decodePositional as v, parseQualifiedKey as x, decodePositionalFromFieldDef as y };
1289
+ export { positionValue as A, EXPR_AGGREGATES as B, decodePositional as C, encodePositional as D, encodeEnvelope as E, isInt32 as F, EXPR_LIMITS as H, parseInt64 as I, stringifyJson as L, formatQualifiedKey as M, parseQualifiedKey as N, encodePositionalFromFieldDef as O, isInt16 as P, stringifyJsonExact as R, decodeEnvelope as S, PackEncodeError as T, assertNever as U, EXPR_FUNCTIONS as V, encodeStreamChunk as _, FrameStreamError as a, PackDecodeError as b, encodeStreamFrame as c, applyDecodePlanInPlace as d, buildDecodePlan as f, decodeStreamChunk as g, isPlainRequestData as h, FRAMES_PACK_MIME as i, withData as j, packEnvelopeParts as k, framesEncodingFromAccept as l, encodeWsFrame as m, DEFAULT_STREAM_IDLE_MS as n, HEARTBEAT_FRAME as o, decodeWsEnvelope as p, FRAMES_JSON_MIME as r, decodeStreamFrames as s, DEFAULT_MAX_FRAME_BYTES as t, withIdleTimeout as u, MUTATION_ACK_FIELDS as v, decodePositionalFromFieldDef as w, SchemaDriftError as x, mutationReturns as y, DATE_UNITS as z };