@mnmal-ai/substrate 1.0.0-alpha.10 → 1.0.0-alpha.11

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 (37) hide show
  1. package/dist/{boot-store-BVqfFxh1.js → boot-store-C5vNZJ3i.js} +13 -8
  2. package/dist/{bridge-Cp4PaIYO.d.ts → bridge-COu0Tg_h.d.ts} +1 -1
  3. package/dist/{cli-hSCBywhE.js → cli-BrwW4tjO.js} +41 -23
  4. package/dist/client.d.ts +3 -4
  5. package/dist/client.js +3 -3
  6. package/dist/{errors-7mycvNGq.d.ts → errors-BOllGhVx.d.ts} +15 -2
  7. package/dist/{index-DgSfwx7M.d.ts → index-Cp74OcmS.d.ts} +1 -1
  8. package/dist/pack.d.ts +2 -2
  9. package/dist/pack.js +1 -1
  10. package/dist/{pg-edges-store-Lxsl5ZnK.js → pg-edges-store-BLsbcXkk.js} +1 -1
  11. package/dist/{plugin-CtwOINCM.js → plugin-DIYm2cZE.js} +2 -2
  12. package/dist/proposals-bootstrap.js +2 -2
  13. package/dist/proposals.d.ts +2 -3
  14. package/dist/proposals.js +1 -1
  15. package/dist/recall-bootstrap.js +2 -2
  16. package/dist/recall.d.ts +1 -2
  17. package/dist/recall.js +2 -2
  18. package/dist/{repl-DqfHelK7.js → repl-B8gy0YM7.js} +22 -22
  19. package/dist/{row-BKKCXIG6.d.ts → row-DwaDU4b-.d.ts} +57 -10
  20. package/dist/{run-B5dTbZ3g.js → run-B18qtGKc.js} +23 -8
  21. package/dist/{dataset-CejF-Fr_.d.ts → schema-CijHRfuk.d.ts} +2225 -1604
  22. package/dist/sdk.d.ts +21 -11
  23. package/dist/sdk.js +4 -4
  24. package/dist/{src-7CUSMK66.js → src-Br6aDUti.js} +7 -3
  25. package/dist/{src-CqT-QWZ_.js → src-D041j6GS.js} +3 -3
  26. package/dist/{src-5SJ5GEIM.js → src-DK7VEQT6.js} +2572 -742
  27. package/dist/{src-hZb8wfvg.js → src-Dbvuel6w.js} +383 -284
  28. package/dist/{src-Da0t6si5.js → src-DpPdw2oL.js} +1 -1
  29. package/dist/{src-Bi849yhn.js → src-DptNGNYQ.js} +3 -3
  30. package/dist/{src-CyvV7dCK.js → src-gz4I1F29.js} +1027 -263
  31. package/dist/substrate-admin.js +1 -1
  32. package/dist/substrate.js +1 -1
  33. package/dist/testing.d.ts +28 -4
  34. package/dist/testing.js +4 -4
  35. package/dist/{ws-ByZyHk7m.d.ts → ws-DC8OhMaV.d.ts} +2 -3
  36. package/package.json +20 -19
  37. package/dist/schema-DoSc-4ig.d.ts +0 -470
@@ -1,6 +1,6 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-Da0t6si5.js";
3
- import { C as parseQualifiedKey, S as formatQualifiedKey, c as isPlainRequestData, f as encodeEnvelope, o as decodeWsEnvelope, p as encodePositional, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, w as assertNever, x as naturalOrderOf } from "./src-hZb8wfvg.js";
2
+ import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-DpPdw2oL.js";
3
+ import { C as parseQualifiedKey, S as formatQualifiedKey, _ as encodeEnvelope, c as isPlainRequestData, o as decodeWsEnvelope, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, v as encodePositional, w as assertNever, x as naturalOrderOf } from "./src-Dbvuel6w.js";
4
4
  import { n as acceptsPack, t as PACK_MIME } from "./content-type-C7T28xNb.js";
5
5
  import { readFileSync } from "node:fs";
6
6
  import { createCipheriv, createDecipheriv, createHash, createHmac, createPrivateKey, createPublicKey, createVerify, hkdfSync, randomBytes, randomUUID, sign, timingSafeEqual, verify } from "node:crypto";
@@ -88,6 +88,19 @@ const ROW_METADATA_FIELDS = [
88
88
 
89
89
  //#endregion
90
90
  //#region ../../packages/substrate-types/src/errors.ts
91
+ /** Refusal codes for the typed-edge-walk grammar. */
92
+ const WALKS_NEED_PARTITIONED = "walks_need_partitioned";
93
+ const WALKS_IN_SUBSCRIPTION = "walks_in_subscription";
94
+ const WALKS_IN_MUTATION = "walks_in_mutation";
95
+ const ROW_POLICY_BLOCKS_WALK = "row_policy_blocks_walk";
96
+ const WALK_BUDGET_EXCEEDED = "walk_budget_exceeded";
97
+ const WALKS_UNSUPPORTED_STORE = "walks_unsupported_store";
98
+ /**
99
+ * A walk construct refused where it cannot be answered: inside a struct, over
100
+ * a list or struct-nested crossRef, under a reused field name, on a virtual
101
+ * type, or on a read path that does not evaluate walks.
102
+ */
103
+ const WALK_UNSUPPORTED_REF = "walk_unsupported_ref";
91
104
  /**
92
105
  * Throwable by a resolver to surface a structured per-frame error with a
93
106
  * caller-chosen `code` instead of the generic `resolver_error`. The engine's
@@ -475,17 +488,29 @@ function putResolved(b, name, pred) {
475
488
  if (isAuthor(name)) putAuthor(b, name, pred);
476
489
  else b.put(name, pred);
477
490
  }
491
+ /** A `_walk` / `_agg` node with its `where` rewritten against the far type. */
492
+ function normaliseWalkNode(node, hop) {
493
+ if (hop === void 0 || !isRecord(node) || node.where === void 0) return node;
494
+ const far = hop(node);
495
+ if (far === void 0) return node;
496
+ return {
497
+ ...node,
498
+ where: normaliseMetadataWhere(node.where, far.fields, far.hop)
499
+ };
500
+ }
478
501
  /**
479
502
  * Rewrites every metadata spelling in a `where` clause onto the canonical
480
- * columns, through AND / OR / NOT. A name the type declares as a field of its
481
- * own is left alone, and so is anything that is not a metadata spelling, for
482
- * the validator to judge.
503
+ * columns, through AND / OR / NOT and, given `hop`, into each `_walk` / `_agg`
504
+ * against its far type. A name the type declares as a field of its own is
505
+ * left alone, and so is anything that is not a metadata spelling, for the
506
+ * validator to judge.
483
507
  */
484
- function normaliseMetadataWhere(where, fieldDefs) {
508
+ function normaliseMetadataWhere(where, fieldDefs, hop) {
485
509
  if (!isRecord(where)) return where;
486
510
  const b = new Builder();
487
- for (const [key, value] of Object.entries(where)) if ((key === "AND" || key === "OR") && Array.isArray(value)) b.out[key] = value.map((w) => normaliseMetadataWhere(w, fieldDefs));
488
- else if (key === "NOT") b.out[key] = normaliseMetadataWhere(value, fieldDefs);
511
+ for (const [key, value] of Object.entries(where)) if ((key === "AND" || key === "OR") && Array.isArray(value)) b.out[key] = value.map((w) => normaliseMetadataWhere(w, fieldDefs, hop));
512
+ else if (key === "NOT") b.out[key] = normaliseMetadataWhere(value, fieldDefs, hop);
513
+ else if (key === "_walk" || key === "_agg") b.put(key, normaliseWalkNode(value, hop));
489
514
  else if (Object.hasOwn(fieldDefs, key)) b.put(key, value);
490
515
  else if (key === "_metadata" && isRecord(value)) for (const [inner, pred] of Object.entries(value)) {
491
516
  const name = resolveName(inner);
@@ -1112,9 +1137,25 @@ function projectValue(value, selection) {
1112
1137
  const obj = value;
1113
1138
  if (obj.__orphan === true) return value;
1114
1139
  const out = {};
1115
- for (const [field, sub] of Object.entries(selection)) if (field in obj) out[field] = projectValue(obj[field], sub);
1140
+ let walked = false;
1141
+ for (const [field, sub] of Object.entries(selection)) {
1142
+ if (!(field in obj)) continue;
1143
+ const nested = nestedFields(sub);
1144
+ if (nested !== void 0) walked = true;
1145
+ out[field] = field === "_agg" ? obj[field] : projectValue(obj[field], nested === void 0 ? sub : {
1146
+ id: true,
1147
+ ...nested
1148
+ });
1149
+ }
1150
+ if (walked && obj._truncated !== void 0) out._truncated = obj._truncated;
1116
1151
  return out;
1117
1152
  }
1153
+ /** A nested `{ _walk }` selection's own `fields`, or undefined for any other selection. */
1154
+ function nestedFields(sel) {
1155
+ if (typeof sel !== "object" || !Object.hasOwn(sel, "_walk")) return void 0;
1156
+ const fields = sel.fields;
1157
+ return typeof fields === "object" && fields !== null ? fields : {};
1158
+ }
1118
1159
  /**
1119
1160
  * Return a new envelope whose `data` map has each entry trimmed to its
1120
1161
  * frame entry's `fields` projection. `errors`, `shapes`, `_pagination`, and
@@ -1129,7 +1170,8 @@ function projectEnvelope(envelope, frame) {
1129
1170
  continue;
1130
1171
  }
1131
1172
  const fields = entry.fields;
1132
- if (fields === void 0) {
1173
+ const shape = envelope.shapes[key];
1174
+ if (fields === void 0 || shape === "count" || shape === "groups") {
1133
1175
  data[key] = value;
1134
1176
  continue;
1135
1177
  }
@@ -1653,11 +1695,13 @@ function shapeKey(s) {
1653
1695
  if (s.disjunctive === true || literals.length > 0) key.push(s.disjunctive === true, literals);
1654
1696
  return JSON.stringify(key);
1655
1697
  }
1656
- const COMBINATORS = /* @__PURE__ */ new Set([
1698
+ const COMBINATORS$1 = /* @__PURE__ */ new Set([
1657
1699
  "AND",
1658
1700
  "OR",
1659
1701
  "NOT"
1660
1702
  ]);
1703
+ /** Walk grammar inside a `where`: walks are recorded as far-type shapes of their own, never as fields. */
1704
+ const WALK_KEYS$1 = /* @__PURE__ */ new Set(["_walk", "_agg"]);
1661
1705
  const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
1662
1706
  /**
1663
1707
  * The shape of a read: every field `where` names, at any depth (through
@@ -1669,9 +1713,10 @@ function readShapeOf(namespace, type, fields, where, orderBy) {
1669
1713
  const literals = {};
1670
1714
  let disjunctive = false;
1671
1715
  const walk = (w, defs, prefix, conjunct) => {
1672
- if (!isObject(w)) return;
1716
+ if (!isObject(w) || Object.hasOwn(w, "_agg")) return;
1673
1717
  for (const [k, v] of Object.entries(w)) {
1674
- if (COMBINATORS.has(k)) {
1718
+ if (WALK_KEYS$1.has(k)) continue;
1719
+ if (COMBINATORS$1.has(k)) {
1675
1720
  const under = conjunct && k === "AND";
1676
1721
  if (!under) disjunctive = true;
1677
1722
  for (const sub of Array.isArray(v) ? v : [v]) walk(sub, defs, prefix, under);
@@ -1704,6 +1749,28 @@ function readShapeOf(namespace, type, fields, where, orderBy) {
1704
1749
  ...Object.keys(literals).length > 0 ? { literals } : {}
1705
1750
  };
1706
1751
  }
1752
+ /**
1753
+ * One far-type shape per inbound walk: the far rows are read by the hop's
1754
+ * crossRef (an equality per seed row), then the walk's own filters, in the
1755
+ * walk's order. An outbound hop reads one row by primary key, which no index
1756
+ * could speed, so it has none.
1757
+ */
1758
+ function walkShapesOf(namespace, sites, fieldsOf) {
1759
+ const out = [];
1760
+ for (const s of sites) {
1761
+ if (s.crossRef === void 0) continue;
1762
+ const wheres = s.wheres.map((w) => w.where);
1763
+ const where = wheres.length === 1 ? wheres[0] : { AND: wheres };
1764
+ const order = (s.order?.by ?? []).map(([f, d]) => ({ [f]: d }));
1765
+ const shape = readShapeOf(namespace, s.far, fieldsOf(s.far) ?? {}, where, order);
1766
+ shape.filters.unshift({
1767
+ field: s.crossRef,
1768
+ op: "eq"
1769
+ });
1770
+ out.push(shape);
1771
+ }
1772
+ return out;
1773
+ }
1707
1774
  /** Distinct shapes held between drains; past it the least recently seen is dropped. */
1708
1775
  const MAX_SHAPES = 1024;
1709
1776
  var ShapeRecorder = class {
@@ -1743,6 +1810,260 @@ var ShapeRecorder = class {
1743
1810
  }
1744
1811
  };
1745
1812
 
1813
+ //#endregion
1814
+ //#region ../../packages/substrate-core/src/advisor/walk-service.ts
1815
+ const isObj$4 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
1816
+ const dirOf = (d) => d === "desc" ? "desc" : "asc";
1817
+ function orderOf(orderBy) {
1818
+ const out = [];
1819
+ for (const clause of Array.isArray(orderBy) ? orderBy : []) {
1820
+ if (!isObj$4(clause)) continue;
1821
+ for (const [f, d] of Object.entries(clause)) out.push([f, dirOf(d)]);
1822
+ }
1823
+ return out;
1824
+ }
1825
+ /** Every walk site of a frame entry `{ params, fields }` seeded at `seed`, at any depth. */
1826
+ function walkSites(entry, seed, resolve) {
1827
+ const out = [];
1828
+ const site = (node, from, path) => {
1829
+ const s = {
1830
+ path,
1831
+ far: resolve(node, from, path),
1832
+ wheres: []
1833
+ };
1834
+ if (typeof node.in === "string") s.crossRef = node.in.slice(node.in.indexOf(".") + 1);
1835
+ out.push(s);
1836
+ return s;
1837
+ };
1838
+ const addWhere = (s, where, path) => {
1839
+ if (where === void 0) return;
1840
+ s.wheres.push({
1841
+ where,
1842
+ path
1843
+ });
1844
+ inWhere(where, s.far, path);
1845
+ };
1846
+ const inWhere = (v, type, path) => {
1847
+ if (Array.isArray(v)) {
1848
+ v.forEach((c, i) => {
1849
+ inWhere(c, type, [...path, String(i)]);
1850
+ });
1851
+ return;
1852
+ }
1853
+ if (!isObj$4(v)) return;
1854
+ for (const [k, child] of Object.entries(v)) {
1855
+ const at = [...path, k];
1856
+ if (k === "_walk" && isObj$4(child)) {
1857
+ const s = site(child, type, at);
1858
+ const pick = isObj$4(child.pick) ? Object.entries(child.pick)[0] : void 0;
1859
+ if (pick !== void 0) {
1860
+ const [fn, field] = pick;
1861
+ s.order = {
1862
+ by: [[String(field), fn === "min" ? "asc" : "desc"]],
1863
+ path: [...at, "pick"],
1864
+ kind: "order"
1865
+ };
1866
+ }
1867
+ addWhere(s, child.where, [...at, "where"]);
1868
+ } else if (k === "_agg" && isObj$4(child)) agg(child, type, at);
1869
+ else inWhere(child, type, at);
1870
+ }
1871
+ };
1872
+ const agg = (node, from, path) => {
1873
+ const s = site(node, from, path);
1874
+ if (isObj$4(node.latest)) s.order = {
1875
+ by: [[String(node.latest.by), "desc"]],
1876
+ path: [...path, "latest"],
1877
+ kind: "agg"
1878
+ };
1879
+ else if (typeof node.min === "string" || typeof node.max === "string") {
1880
+ const fn = typeof node.min === "string" ? "min" : "max";
1881
+ s.order = {
1882
+ by: [[String(node[fn]), fn === "min" ? "asc" : "desc"]],
1883
+ path: [...path, fn],
1884
+ kind: "agg"
1885
+ };
1886
+ } else s.agg = [...path, [
1887
+ "count",
1888
+ "avg",
1889
+ "sum"
1890
+ ].find((k) => k in node) ?? "count"];
1891
+ addWhere(s, node.where, [...path, "where"]);
1892
+ };
1893
+ const inFields = (fields, type, path) => {
1894
+ if (!isObj$4(fields)) return;
1895
+ for (const [name, sel] of Object.entries(fields)) {
1896
+ const at = [...path, name];
1897
+ if (name === "_agg" && isObj$4(sel)) {
1898
+ for (const [n, a] of Object.entries(sel)) if (isObj$4(a)) agg(a, type, [...at, n]);
1899
+ } else if (isObj$4(sel) && isObj$4(sel._walk)) {
1900
+ const wp = [...at, "_walk"];
1901
+ const s = site(sel._walk, type, wp);
1902
+ const by = orderOf(sel.orderBy);
1903
+ if (by.length > 0) s.order = {
1904
+ by,
1905
+ path: [...at, "orderBy"],
1906
+ kind: "order",
1907
+ exact: true
1908
+ };
1909
+ addWhere(s, sel._walk.where, [...wp, "where"]);
1910
+ addWhere(s, sel.where, [...at, "where"]);
1911
+ inFields(sel.fields, s.far, [...at, "fields"]);
1912
+ }
1913
+ }
1914
+ };
1915
+ inWhere((isObj$4(entry.params) ? entry.params : {}).where, seed, ["where"]);
1916
+ inFields(entry.fields, seed, ["fields"]);
1917
+ return out;
1918
+ }
1919
+ const COMBINATORS = /* @__PURE__ */ new Set([
1920
+ "AND",
1921
+ "OR",
1922
+ "NOT"
1923
+ ]);
1924
+ const SKIP = /* @__PURE__ */ new Set([
1925
+ "_walk",
1926
+ "_agg",
1927
+ "$ref"
1928
+ ]);
1929
+ /** The predicates of one type's `where`, not descending into walks. */
1930
+ function predicates(where, fields, path) {
1931
+ const out = [];
1932
+ const visit = (w, defs, prefix, at, conjunct = true) => {
1933
+ if (Array.isArray(w)) {
1934
+ w.forEach((c, i) => {
1935
+ visit(c, defs, prefix, [...at, String(i)], conjunct);
1936
+ });
1937
+ return;
1938
+ }
1939
+ if (!isObj$4(w) || Object.hasOwn(w, "_agg")) return;
1940
+ for (const [k, v] of Object.entries(w)) {
1941
+ if (SKIP.has(k)) continue;
1942
+ if (COMBINATORS.has(k)) {
1943
+ visit(v, defs, prefix, [...at, k], conjunct && k === "AND");
1944
+ continue;
1945
+ }
1946
+ const def = defs !== void 0 && Object.hasOwn(defs, k) ? defs[k] : void 0;
1947
+ if (def?.kind === "struct") visit(v, def.fields, `${prefix}${k}.`, [...at, k], conjunct);
1948
+ else if (isObj$4(v)) {
1949
+ const ref = Object.values(v).some((o) => isObj$4(o) && "$ref" in o);
1950
+ const bounds = conjunct && Object.keys(v).some((op) => op !== "neq");
1951
+ out.push({
1952
+ field: `${prefix}${k}`,
1953
+ path: [...at, k],
1954
+ ref,
1955
+ bounds
1956
+ });
1957
+ }
1958
+ }
1959
+ };
1960
+ visit(where, fields, "", path);
1961
+ return out;
1962
+ }
1963
+ /** What an `indexes` entry may key on: a declared scalar or crossRef, or a metadata column. */
1964
+ const declarable$1 = (field, fields) => {
1965
+ if (field === "createdAt" || field === "updatedAt") return true;
1966
+ const def = fields !== void 0 && Object.hasOwn(fields, field) ? fields[field] : void 0;
1967
+ return def?.kind === "crossRef" || def?.kind === "scalar" && def.type !== "json";
1968
+ };
1969
+ /**
1970
+ * Whether some full index's keys begin with `lead` and then `next`, by field
1971
+ * name, and when `next` gives a direction, in it: an index key is ascending
1972
+ * or descending, nulls last either way, so one scanned forward is the order
1973
+ * `<dir> NULLS LAST` that reads compile to, and one scanned backward is not.
1974
+ */
1975
+ const leads = (indexes, lead, next) => indexes.some((i) => i.only === void 0 && [...lead, ...next].every((k, n) => typeof k === "string" ? i.keys[n]?.[0] === k : i.keys[n]?.[0] === k[0] && i.keys[n]?.[1] === k[1]));
1976
+ /** The fields that follow `lead` as the next key of a full index, i.e. what a walk through `lead` is served on. */
1977
+ const nextKeys = (indexes, lead) => [...new Set(indexes.flatMap((i) => i.only === void 0 && i.keys[0]?.[0] === lead && i.keys[1] !== void 0 ? [i.keys[1][0]] : []))];
1978
+ /**
1979
+ * Each clause of a walk-grammar frame, served or not (spec §2):
1980
+ * - a hop is served, inbound by the eager `(crossRef, natural order)` index
1981
+ * (absent for a crossRef declared `indexed: false`) and outbound by the
1982
+ * primary key;
1983
+ * - a far filter, pick or latest/min/max is served when a full index on the
1984
+ * far type leads with the hop's crossRef and that field next, and a nested
1985
+ * list's order when its keys follow in its directions too (after an
1986
+ * outbound hop the far row is one primary-key read, so all of it is served);
1987
+ * - a `$ref` predicate is a residual on rows already narrowed: always served;
1988
+ * - a seed filter, or a bucket's field, is served by an index leading with it;
1989
+ * - a derived ordering is served only when a served seed filter bounds the
1990
+ * result (AND-ed, not under OR or NOT, and not only `neq`); no index ever
1991
+ * serves it, so it recommends none;
1992
+ * - anything else is unserved, recommending the index that would serve it
1993
+ * when its fields can be declared.
1994
+ */
1995
+ function classifyWalkService(input, indexesOf) {
1996
+ const { entry, seed, fieldsOf } = input;
1997
+ const out = [];
1998
+ const params = isObj$4(entry.params) ? entry.params : {};
1999
+ const clause = (path, kind, served, type, keys) => {
2000
+ const c = {
2001
+ path,
2002
+ kind,
2003
+ served
2004
+ };
2005
+ const names = keys.map((k) => typeof k === "string" ? k : k.field);
2006
+ if (!served && names.every((f) => declarable$1(f, fieldsOf(type)))) c.recommend = { fields: keys };
2007
+ out.push(c);
2008
+ };
2009
+ const seedIndexes = indexesOf(seed);
2010
+ let bounded = false;
2011
+ for (const p of predicates(params.where, fieldsOf(seed), ["where"])) {
2012
+ if (p.ref) {
2013
+ out.push({
2014
+ path: p.path,
2015
+ kind: "ref",
2016
+ served: true
2017
+ });
2018
+ continue;
2019
+ }
2020
+ const served = leads(seedIndexes, [p.field], []);
2021
+ bounded ||= served && p.bounds;
2022
+ clause(p.path, "filter", served, seed, [p.field]);
2023
+ }
2024
+ for (const s of walkSites(entry, seed, input.resolve)) {
2025
+ const farIndexes = indexesOf(s.far);
2026
+ const cr = s.crossRef;
2027
+ const hop = cr === void 0 || leads(farIndexes, [cr], []);
2028
+ clause(s.path, "hop", hop, s.far, cr === void 0 ? [] : [cr]);
2029
+ for (const w of s.wheres) for (const p of predicates(w.where, fieldsOf(s.far), w.path)) if (p.ref) out.push({
2030
+ path: p.path,
2031
+ kind: "ref",
2032
+ served: true
2033
+ });
2034
+ else {
2035
+ const served = cr === void 0 || leads(farIndexes, [cr], [p.field]);
2036
+ clause(p.path, "filter", served, s.far, cr === void 0 ? [] : [cr, p.field]);
2037
+ }
2038
+ if (s.order !== void 0) {
2039
+ const { by, path, kind, exact } = s.order;
2040
+ const served = cr === void 0 || leads(farIndexes, [cr], by.map(([f, d]) => exact ? [f, d] : f));
2041
+ const keys = cr === void 0 ? [] : [cr, ...by.map(([field, dir]) => ({
2042
+ field,
2043
+ dir
2044
+ }))];
2045
+ clause(path, kind, served, s.far, keys);
2046
+ }
2047
+ if (s.agg !== void 0) out.push({
2048
+ path: s.agg,
2049
+ kind: "agg",
2050
+ served: true
2051
+ });
2052
+ }
2053
+ if (isObj$4(params.bucket) && typeof params.bucket.field === "string") {
2054
+ const field = params.bucket.field;
2055
+ clause(["bucket"], "bucket", leads(seedIndexes, [field], []), seed, [field]);
2056
+ }
2057
+ orderOf(params.orderBy).forEach(([f], i) => {
2058
+ if (f.startsWith("$")) out.push({
2059
+ path: ["orderBy", String(i)],
2060
+ kind: "derive",
2061
+ served: bounded
2062
+ });
2063
+ });
2064
+ return out;
2065
+ }
2066
+
1746
2067
  //#endregion
1747
2068
  //#region ../../packages/substrate-core/src/engine/cursor-seal.ts
1748
2069
  /**
@@ -2353,6 +2674,284 @@ function buildMeta(hits) {
2353
2674
  };
2354
2675
  }
2355
2676
 
2677
+ //#endregion
2678
+ //#region ../../packages/substrate-filter/src/walk.ts
2679
+ /**
2680
+ * Typed edge walk evaluation (spec 2026-10-24-typed-edge-walks §1, §4, §5).
2681
+ *
2682
+ * The reference semantics the pg compiler must match: a walk follows the
2683
+ * crossRef value in the row BODY, never `edges`; tombstoned far rows are never
2684
+ * walked (the dataset's `neighbours` / `get` leave them out); `any` walks with
2685
+ * `as` in one AND group are jointly quantified; a `$ref` to a null value is
2686
+ * never true. The tree is assumed validated (substrate-core walk-validator).
2687
+ */
2688
+ /** Default per-read cap on walk work (far rows examined plus binding assignments tried). */
2689
+ const WALK_EVALUATION_BUDGET = 1e6;
2690
+ const isObj$3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
2691
+ const isRefOperand = (v) => isObj$3(v) && typeof v.$ref === "string";
2692
+ /**
2693
+ * One AND group, flattened: its `any` walks with `as` (the object's own
2694
+ * `_walk`, then, through AND, its conjuncts') and every other conjunct as a
2695
+ * one-key clause, except a `{ _agg, <cmp> }` object, which stays whole. OR
2696
+ * and NOT stay whole, so their walks start their own group.
2697
+ */
2698
+ function groupConjuncts(where, out = {
2699
+ binds: [],
2700
+ items: []
2701
+ }) {
2702
+ if (!isObj$3(where)) return out;
2703
+ if (Object.hasOwn(where, "_agg")) {
2704
+ out.items.push(where);
2705
+ return out;
2706
+ }
2707
+ const w = where._walk;
2708
+ if (isObj$3(w) && typeof w.as === "string") out.binds.push(w);
2709
+ else if (Object.hasOwn(where, "_walk")) out.items.push({ _walk: w });
2710
+ if (Array.isArray(where.AND)) for (const sub of where.AND) groupConjuncts(sub, out);
2711
+ for (const [k, v] of Object.entries(where)) if (k !== "_walk" && k !== "AND") out.items.push({ [k]: v });
2712
+ return out;
2713
+ }
2714
+ /** The `any` walks with `as` in this AND group (see {@link groupConjuncts}). */
2715
+ function bindingWalks(where) {
2716
+ return groupConjuncts(where).binds;
2717
+ }
2718
+ /** Binding names a `$ref` anywhere below `where` reads. */
2719
+ function refNames(where, out = /* @__PURE__ */ new Set()) {
2720
+ if (Array.isArray(where)) for (const w of where) refNames(w, out);
2721
+ else if (isObj$3(where)) {
2722
+ if (typeof where.$ref === "string") out.add(where.$ref.split(".", 1)[0] ?? "");
2723
+ for (const v of Object.values(where)) refNames(v, out);
2724
+ }
2725
+ return out;
2726
+ }
2727
+ function charge(walk, n) {
2728
+ walk.budget.left -= n;
2729
+ if (walk.budget.left < 0) throw new ResolverFrameError(WALK_BUDGET_EXCEEDED, "the walk examined more rows or binding combinations than one read allows; narrow the walks or bind fewer of them");
2730
+ }
2731
+ /** The far type and the live rows one hop from `row`, each charged to the read's budget. */
2732
+ function hop(row, node, walk) {
2733
+ const far = hopRows(row, node, walk);
2734
+ charge(walk, far.rows.length);
2735
+ return far;
2736
+ }
2737
+ function hopRows(row, node, walk) {
2738
+ if (node.in !== void 0) {
2739
+ const m = /^[^/]+\/([^./]+)\.(.+)$/.exec(node.in);
2740
+ if (m === null) throw new Error(`internal: walk 'in' '${node.in}' is not '<ns>/<Type>.<field>'`);
2741
+ const [, type, field] = m;
2742
+ return {
2743
+ type,
2744
+ rows: typeof row.id === "string" ? walk.neighbours(type, field, row.id) : []
2745
+ };
2746
+ }
2747
+ const field = node.out ?? "";
2748
+ const def = walk.fieldDefOf(walk.type)(field);
2749
+ if (def?.kind !== "crossRef") throw new Error(`internal: walk 'out' '${field}' is not a crossRef on '${walk.type}'`);
2750
+ const id = Object.hasOwn(row, field) ? row[field] : void 0;
2751
+ const far = typeof id === "string" ? walk.get(def.type, id) : void 0;
2752
+ return {
2753
+ type: def.type,
2754
+ rows: far === void 0 ? [] : [far]
2755
+ };
2756
+ }
2757
+ /**
2758
+ * The one neighbour a pick names: by the field descending (latest, max) or
2759
+ * ascending (min), nulls last either way, ties by id ascending.
2760
+ */
2761
+ function pickOne(rows, pick, fieldDefOf) {
2762
+ const [dir, field] = Object.entries(pick)[0];
2763
+ const asDate = isDateField(field, fieldDefOf);
2764
+ const key = (r) => asSortValue(field, getFieldValue(r, field), fieldDefOf);
2765
+ const before = (a, b) => {
2766
+ const va = key(a);
2767
+ const vb = key(b);
2768
+ if (va == null !== (vb == null)) return vb == null;
2769
+ const c = va == null ? 0 : compareFilterValues(va, vb, asDate);
2770
+ if (c !== 0) return dir === "min" ? c < 0 : c > 0;
2771
+ return compareFilterValues(a.id, b.id) < 0;
2772
+ };
2773
+ let best;
2774
+ for (const r of rows) if (best === void 0 || before(r, best)) best = r;
2775
+ return best;
2776
+ }
2777
+ /** A walk without `as` (any, none, all or pick), evaluated under the current bindings. */
2778
+ function evaluateWalk(row, node, walk) {
2779
+ const { type, rows } = hop(row, node, walk);
2780
+ const fieldDefOf = walk.fieldDefOf(type);
2781
+ const far = {
2782
+ ...walk,
2783
+ type
2784
+ };
2785
+ const where = node.where;
2786
+ const test = (n) => where === void 0 || evaluateWhere(n, where, fieldDefOf, far);
2787
+ if (node.pick !== void 0) {
2788
+ const one = pickOne(rows, node.pick, fieldDefOf);
2789
+ return one !== void 0 && test(one);
2790
+ }
2791
+ switch (node.quantifier ?? "any") {
2792
+ case "none": return !rows.some(test);
2793
+ case "all": return rows.every(test);
2794
+ default: return rows.some(test);
2795
+ }
2796
+ }
2797
+ /**
2798
+ * Joint quantification of an AND group's binding walks: true when some
2799
+ * assignment of one neighbour to each `as` makes every member true.
2800
+ * Assignments are enumerated left to right; each walk's own `where` is tested
2801
+ * as soon as every group binding it references is assigned.
2802
+ */
2803
+ function evaluateGroup(row, where, fieldDefOf, walk, group) {
2804
+ const names = group.map((n) => n.as ?? "");
2805
+ const hops = group.map((n) => hop(row, n, walk));
2806
+ const checkAt = group.map((n, i) => Math.max(i, ...[...refNames(n.where)].map((name) => names.indexOf(name))));
2807
+ const bindings = new Map(walk.bindings);
2808
+ const ctx = {
2809
+ ...walk,
2810
+ bindings
2811
+ };
2812
+ const bound = new Set(group);
2813
+ const step = (i) => {
2814
+ if (i === group.length) return evaluateMembers(row, where, fieldDefOf, ctx, bound);
2815
+ const name = names[i] ?? "";
2816
+ for (const n of hops[i]?.rows ?? []) {
2817
+ charge(walk, 1);
2818
+ bindings.set(name, n);
2819
+ if (group.every((g, j) => {
2820
+ if (checkAt[j] !== i || g.where === void 0) return true;
2821
+ const h = hops[j];
2822
+ const far = bindings.get(names[j] ?? "");
2823
+ return evaluateWhere(far, g.where, walk.fieldDefOf(h.type), {
2824
+ ...ctx,
2825
+ type: h.type
2826
+ });
2827
+ }) && step(i + 1)) return true;
2828
+ }
2829
+ bindings.delete(name);
2830
+ return false;
2831
+ };
2832
+ return step(0);
2833
+ }
2834
+ /**
2835
+ * A `$ref` operand's value: `$.f` reads the seed, `<as>.f` a binding. A
2836
+ * number becomes `value * times + plus`; a date shifts by `plus`
2837
+ * milliseconds. A null, a value its kind cannot read, or arithmetic that
2838
+ * overflows or underflows to 0, is `null`, which no comparison matches.
2839
+ */
2840
+ function resolveRef(ref, asDate, walk) {
2841
+ const dot = ref.$ref.indexOf(".");
2842
+ const name = ref.$ref.slice(0, dot);
2843
+ const field = ref.$ref.slice(dot + 1);
2844
+ let v;
2845
+ if (name === "_agg") {
2846
+ if (walk.aggValue === void 0) throw new Error(`internal: $ref '${ref.$ref}' names no _agg in this frame`);
2847
+ v = walk.aggValue(field);
2848
+ } else {
2849
+ const row = name === "$" ? walk.seed : walk.bindings.get(name);
2850
+ if (row === void 0) throw new Error(`internal: $ref '${ref.$ref}' names no binding in scope`);
2851
+ v = getFieldValue(row, field);
2852
+ }
2853
+ if (v == null) return null;
2854
+ if (asDate) {
2855
+ const micros = storedMicros(v);
2856
+ if (micros === void 0) return null;
2857
+ return ref.plus ? isoFromMicros(micros + BigInt(Math.round(ref.plus * 1e3))) : v;
2858
+ }
2859
+ if (typeof v !== "number") return null;
2860
+ const times = ref.times ?? 1;
2861
+ const product = v * times;
2862
+ if (product === 0 && v !== 0 && times !== 0) return null;
2863
+ const out = product + (ref.plus ?? 0);
2864
+ return Number.isFinite(out) ? out : null;
2865
+ }
2866
+ /** An instant in microseconds as an ISO string with six fraction digits. */
2867
+ function isoFromMicros(micros) {
2868
+ const sub = (micros % 1000n + 1000n) % 1000n;
2869
+ const ms = Number((micros - sub) / 1000n);
2870
+ return new Date(ms).toISOString().replace("Z", `${sub.toString().padStart(3, "0")}Z`);
2871
+ }
2872
+ /**
2873
+ * An aggregate over `rows`: avg/sum read only numbers (nulls and non-numeric
2874
+ * values drop out); min/max read numbers, or instants on a date field and
2875
+ * return the winning row's stored value (ties id ascending); each is null over
2876
+ * none. count counts rows; latest is the stored `value` of the row latest by
2877
+ * `by` (nulls last, ties id ascending), or null. Arithmetic is float64, and
2878
+ * a sum past float64's range is null.
2879
+ */
2880
+ function applyAgg(rows, fn, fieldDefOf) {
2881
+ if (Object.hasOwn(fn, "count")) return rows.length;
2882
+ if ("latest" in fn && Object.hasOwn(fn, "latest")) {
2883
+ const one = pickOne(rows, { latest: fn.latest.by }, fieldDefOf);
2884
+ return one === void 0 ? null : getFieldValue(one, fn.latest.value) ?? null;
2885
+ }
2886
+ const op = [
2887
+ "avg",
2888
+ "sum",
2889
+ "min",
2890
+ "max"
2891
+ ].find((k) => Object.hasOwn(fn, k));
2892
+ if (op === void 0) throw new Error("internal: aggregate names no function");
2893
+ const field = fn[op];
2894
+ if ((op === "min" || op === "max") && isDateField(field, fieldDefOf)) {
2895
+ const one = pickOne(rows, op === "min" ? { min: field } : { max: field }, fieldDefOf);
2896
+ const v = one === void 0 ? void 0 : getFieldValue(one, field);
2897
+ return v == null || storedMicros(v) === void 0 ? null : v;
2898
+ }
2899
+ let n = 0;
2900
+ let acc = 0;
2901
+ for (const r of rows) {
2902
+ const v = getFieldValue(r, field);
2903
+ if (typeof v !== "number") continue;
2904
+ acc = n === 0 ? v : op === "min" ? Math.min(acc, v) : op === "max" ? Math.max(acc, v) : acc + v;
2905
+ n++;
2906
+ }
2907
+ if (n === 0) return null;
2908
+ if (!Number.isFinite(acc) && (op === "sum" || op === "avg")) {
2909
+ let scaled = 0;
2910
+ for (const r of rows) {
2911
+ const v = getFieldValue(r, field);
2912
+ if (typeof v === "number") scaled += v * 2 ** -64;
2913
+ }
2914
+ const out = (op === "avg" ? scaled / n : scaled) * 2 ** 64;
2915
+ return Number.isFinite(out) ? out : null;
2916
+ }
2917
+ return op === "avg" ? acc / n : acc;
2918
+ }
2919
+ /** The field an aggregate's value is read from, or undefined for count. */
2920
+ function valueField(fn) {
2921
+ if ("latest" in fn && Object.hasOwn(fn, "latest")) return fn.latest.value;
2922
+ const op = [
2923
+ "avg",
2924
+ "sum",
2925
+ "min",
2926
+ "max"
2927
+ ].find((k) => Object.hasOwn(fn, k));
2928
+ return op === void 0 ? void 0 : fn[op];
2929
+ }
2930
+ /**
2931
+ * A walk aggregate for `row`: the hop's live rows that pass the walk's
2932
+ * `where`, aggregated; `asDate` says whether the value is a date (compared
2933
+ * as an instant).
2934
+ */
2935
+ function computeAggTyped(row, spec, walk) {
2936
+ const { type, rows } = hop(row, spec, walk);
2937
+ const fieldDefOf = walk.fieldDefOf(type);
2938
+ const far = {
2939
+ ...walk,
2940
+ type
2941
+ };
2942
+ const where = spec.where;
2943
+ const kept = where === void 0 ? rows : rows.filter((n) => evaluateWhere(n, where, fieldDefOf, far));
2944
+ const field = valueField(spec);
2945
+ return {
2946
+ value: applyAgg(kept, spec, fieldDefOf),
2947
+ asDate: field !== void 0 && isDateField(field, fieldDefOf)
2948
+ };
2949
+ }
2950
+ /** {@link computeAggTyped}'s value. */
2951
+ function computeAgg(row, spec, walk) {
2952
+ return computeAggTyped(row, spec, walk).value;
2953
+ }
2954
+
2356
2955
  //#endregion
2357
2956
  //#region ../../packages/substrate-filter/src/predicate.ts
2358
2957
  /**
@@ -2397,9 +2996,8 @@ const METADATA_COLUMN_PROJECTIONS = {
2397
2996
  * (`row[name]`), preserving the existing filter semantics.
2398
2997
  */
2399
2998
  function getFieldValue(row, name) {
2400
- const projector = METADATA_COLUMN_PROJECTIONS[name];
2401
- if (projector !== void 0) return projector(row);
2402
- return row[name];
2999
+ if (Object.hasOwn(METADATA_COLUMN_PROJECTIONS, name)) return METADATA_COLUMN_PROJECTIONS[name](row);
3000
+ return Object.hasOwn(row, name) ? row[name] : void 0;
2403
3001
  }
2404
3002
  /**
2405
3003
  * Whether `field` holds a date: the `createdAt`/`updatedAt` columns always do,
@@ -2442,6 +3040,7 @@ const KNOWN_OPS = /* @__PURE__ */ new Set([
2442
3040
  */
2443
3041
  function assertWhereHonourable(where) {
2444
3042
  if (where === null || typeof where !== "object" || Array.isArray(where)) return;
3043
+ if (Object.hasOwn(where, "_agg")) return;
2445
3044
  for (const [key, child] of Object.entries(where)) {
2446
3045
  if (key === "AND" || key === "OR") {
2447
3046
  if (Array.isArray(child)) for (const sub of child) assertWhereHonourable(sub);
@@ -2451,6 +3050,12 @@ function assertWhereHonourable(where) {
2451
3050
  assertWhereHonourable(child);
2452
3051
  continue;
2453
3052
  }
3053
+ if (key === "_walk") {
3054
+ const far = child?.where;
3055
+ if (far !== void 0) assertWhereHonourable(far);
3056
+ continue;
3057
+ }
3058
+ if (key === "_agg") continue;
2454
3059
  if (getExtensionOperator(key) !== void 0) continue;
2455
3060
  assertFieldPredicateHonourable(key, child);
2456
3061
  }
@@ -2487,31 +3092,73 @@ function assertFieldPredicateHonourable(field, predicate) {
2487
3092
  * `fieldDefOf` names the row type's declared fields, so `date` fields compare
2488
3093
  * as instants (as pg's timestamptz does). Without it, only `createdAt` and
2489
3094
  * `updatedAt` do; nested struct fields always compare as written.
3095
+ *
3096
+ * `walk` lets `_walk` nodes and `$ref` operands reach other rows; without it
3097
+ * either one throws. The `any` walks with `as` in one AND group are jointly
3098
+ * quantified (see `evaluateGroup`).
3099
+ */
3100
+ function evaluateWhere(row, where, fieldDefOf, walk) {
3101
+ if (walk !== void 0) {
3102
+ const group = bindingWalks(where);
3103
+ if (group.length > 0) return evaluateGroup(row, where, fieldDefOf, walk, group);
3104
+ }
3105
+ return evaluateMembers(row, where, fieldDefOf, walk, NO_WALKS);
3106
+ }
3107
+ const NO_WALKS = /* @__PURE__ */ new Set();
3108
+ /**
3109
+ * {@link evaluateWhere} for one AND group under its current assignment: the
3110
+ * `bound` walks hold already, so they are skipped. Conjuncts stay in the
3111
+ * group; OR and NOT branches start their own.
2490
3112
  */
2491
- function evaluateWhere(row, where, fieldDefOf) {
3113
+ function evaluateMembers(row, where, fieldDefOf, walk, bound) {
2492
3114
  if (where === null || typeof where !== "object" || Array.isArray(where)) return true;
3115
+ if (Object.hasOwn(where, "_agg")) {
3116
+ if (walk === void 0) throw new UnsupportedFilterError("_agg", "<none>", "walk aggregates need a walk context");
3117
+ return evaluateAggPredicate(row, where, walk);
3118
+ }
2493
3119
  for (const [k, child] of Object.entries(where)) if (k === "AND") {
2494
3120
  if (Array.isArray(child)) {
2495
- for (const sub of child) if (!evaluateWhere(row, sub, fieldDefOf)) return false;
3121
+ for (const sub of child) if (!evaluateMembers(row, sub, fieldDefOf, walk, bound)) return false;
2496
3122
  }
2497
3123
  } else if (k === "OR") {
2498
3124
  if (Array.isArray(child)) {
2499
3125
  let any = false;
2500
- for (const sub of child) if (evaluateWhere(row, sub, fieldDefOf)) {
3126
+ for (const sub of child) if (evaluateWhere(row, sub, fieldDefOf, walk)) {
2501
3127
  any = true;
2502
3128
  break;
2503
3129
  }
2504
3130
  if (!any) return false;
2505
3131
  }
2506
3132
  } else if (k === "NOT") {
2507
- if (evaluateWhere(row, child, fieldDefOf)) return false;
3133
+ if (evaluateWhere(row, child, fieldDefOf, walk)) return false;
3134
+ } else if (k === "_walk") {
3135
+ if (walk === void 0) throw new UnsupportedFilterError(k, "<none>", "walks need a walk context");
3136
+ const node = child;
3137
+ if (!bound.has(node) && !evaluateWalk(row, node, walk)) return false;
2508
3138
  } else {
2509
3139
  const asDate = isDateField(k, fieldDefOf);
2510
- if (!evaluateFieldPredicate(k, getFieldValue(row, k), child, asDate)) return false;
3140
+ const ref = walk === void 0 ? void 0 : (r) => resolveRef(r, asDate, walk);
3141
+ if (!evaluateFieldPredicate(k, getFieldValue(row, k), child, asDate, ref)) return false;
3142
+ }
3143
+ return true;
3144
+ }
3145
+ /**
3146
+ * `{ _agg, <cmp>: v }` on this row, compared by the aggregate's kind (dates as
3147
+ * instants). A null aggregate, or a `$ref` operand that resolves to null,
3148
+ * matches nothing, as SQL NULL.
3149
+ */
3150
+ function evaluateAggPredicate(row, where, walk) {
3151
+ const { value, asDate } = computeAggTyped(row, where._agg, walk);
3152
+ if (value == null) return false;
3153
+ for (const [op, raw] of Object.entries(where)) {
3154
+ if (op === "_agg") continue;
3155
+ const operand = isRefOperand(raw) ? resolveRef(raw, asDate, walk) : raw;
3156
+ if (operand == null) return false;
3157
+ if (!applyOp("_agg", op, value, operand, asDate)) return false;
2511
3158
  }
2512
3159
  return true;
2513
3160
  }
2514
- function evaluateFieldPredicate(field, value, predicate, asDate = false) {
3161
+ function evaluateFieldPredicate(field, value, predicate, asDate = false, ref) {
2515
3162
  if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) throw new UnsupportedFilterError(field, "<none>", `expected a predicate object such as { eq: ... }, got ${Array.isArray(predicate) ? "an array" : typeof predicate}`);
2516
3163
  if (isJsonPathPredicate(predicate)) return evaluateJsonPathPredicate(field, value, predicate);
2517
3164
  const p = predicate;
@@ -2522,7 +3169,12 @@ function evaluateFieldPredicate(field, value, predicate, asDate = false) {
2522
3169
  return evaluateWhere(value, p);
2523
3170
  }
2524
3171
  for (const op of keys) {
2525
- const operand = p[op];
3172
+ let operand = p[op];
3173
+ if (isRefOperand(operand)) {
3174
+ if (ref === void 0) throw new UnsupportedFilterError(field, op, "$ref needs a walk context");
3175
+ operand = ref(operand);
3176
+ if (operand == null) return false;
3177
+ }
2526
3178
  if (!applyOp(field, op, value, operand, asDate)) return false;
2527
3179
  }
2528
3180
  return true;
@@ -2970,777 +3622,1467 @@ var Registry = class extends RegistryBase {
2970
3622
  };
2971
3623
 
2972
3624
  //#endregion
2973
- //#region ../../packages/substrate-core/src/engine/internals.ts
2974
- /**
2975
- * Engine internals — pure helpers, types, and constants used by the
2976
- * engine and its subsystems. Nothing in here touches engine state.
2977
- */
2978
- /** Duck-type guard: is this a ReadResult rather than a bare Row[]? */
2979
- function isReadResult(v) {
2980
- return v !== null && typeof v === "object" && !Array.isArray(v) && "rows" in v && Array.isArray(v.rows) && "hasMore" in v;
3625
+ //#region ../../packages/substrate-core/src/walk-gate.ts
3626
+ /** Structural detector for the typed-edge-walk query grammar. Subscriptions and streams use it to refuse walks (query-only). */
3627
+ const WALK_PARAM_KEYS = [
3628
+ "aggregate",
3629
+ "bucket",
3630
+ "derive"
3631
+ ];
3632
+ const isObj$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
3633
+ function inWhere(v, path) {
3634
+ if (Array.isArray(v)) {
3635
+ for (let i = 0; i < v.length; i++) {
3636
+ const hit = inWhere(v[i], [...path, String(i)]);
3637
+ if (hit) return hit;
3638
+ }
3639
+ return null;
3640
+ }
3641
+ if (!isObj$2(v)) return null;
3642
+ for (const [k, child] of Object.entries(v)) {
3643
+ if (k === "_walk" || k === "_agg" || k === "$ref") return [...path, k];
3644
+ const hit = inWhere(child, [...path, k]);
3645
+ if (hit) return hit;
3646
+ }
3647
+ return null;
2981
3648
  }
2982
- /**
2983
- * Duck-type guard for async iterables (§5.5). Plain arrays expose
2984
- * `Symbol.iterator` but NOT `Symbol.asyncIterator`, so this cleanly separates
2985
- * stream-shaped returns from the `Row[]` list shape without touching the
2986
- * existing one-shot discriminators.
2987
- */
2988
- function isAsyncIterable(v) {
2989
- return v !== null && typeof v === "object" && Symbol.asyncIterator in v;
3649
+ /** Path (inside the frame) of the first walk-grammar construct in a frame entry `{ params, fields }`, or null. */
3650
+ function walkGrammarPath(entry) {
3651
+ const params = isObj$2(entry.params) ? entry.params : {};
3652
+ const where = inWhere(params.where, ["where"]);
3653
+ if (where) return where;
3654
+ if (params.count === true) return ["count"];
3655
+ for (const k of WALK_PARAM_KEYS) if (k in params) return [k];
3656
+ return inFields(entry.fields, ["fields"]);
3657
+ }
3658
+ /** `_agg` or a `{ _walk }` selection anywhere in a field selection, sub-selections included. */
3659
+ function inFields(fields, path) {
3660
+ if (!isObj$2(fields)) return null;
3661
+ for (const [name, sel] of Object.entries(fields)) {
3662
+ if (name === "_agg") return [...path, name];
3663
+ if (!isObj$2(sel)) continue;
3664
+ if ("_walk" in sel) return [
3665
+ ...path,
3666
+ name,
3667
+ "_walk"
3668
+ ];
3669
+ const hit = inFields(sel, [...path, name]);
3670
+ if (hit) return hit;
3671
+ }
3672
+ return null;
3673
+ }
3674
+ /** True when a frame entry `{ params, fields }` uses any walk-grammar construct. */
3675
+ function usesWalkGrammar(entry) {
3676
+ return walkGrammarPath(entry) !== null;
2990
3677
  }
3678
+
3679
+ //#endregion
3680
+ //#region ../../packages/substrate-core/src/filter/validator.ts
2991
3681
  /**
2992
- * Deliver a frame the engine does not await. A rejection is counted on
2993
- * `metric` and handed to `onReject`, so a failing transport never becomes an
2994
- * unhandled rejection. A synchronous throw still reaches the caller.
3682
+ * Filter validator. Spec: §5.2.
3683
+ *
3684
+ * Pure function, no I/O. Walks a WhereClause / OrderByClause tree against a
3685
+ * type's TypeSchema and a dataset's FilterCapabilities. Throws
3686
+ * FilterValidationError on the first problem it finds; the engine catches it
3687
+ * and surfaces a structured envelope error per-frame-entry.
3688
+ *
3689
+ * Error codes (see below) are stable — callers can switch on them.
3690
+ *
3691
+ * It does not evaluate, rewrite, or inject row-level policy predicates into
3692
+ * the clause.
2995
3693
  */
2996
- function deliverFrame(onFrame, frame, metric, onReject) {
2997
- Promise.resolve(onFrame(frame)).catch((err) => {
2998
- metric("engine_frame_delivery_rejected", {
2999
- id: frame.id,
3000
- kind: frame.kind,
3001
- error: err instanceof Error ? err.message : String(err)
3002
- });
3003
- onReject?.();
3004
- });
3005
- }
3694
+ var FilterValidationError = class extends Error {
3695
+ name = "FilterValidationError";
3696
+ code;
3697
+ path;
3698
+ constructor(code, message, path) {
3699
+ super(message);
3700
+ this.code = code;
3701
+ this.path = path;
3702
+ }
3703
+ };
3704
+ const NUMBER_OPS = new Set(NUMBER_OPS$1);
3705
+ const STRING_OPS = new Set(STRING_OPS$1);
3706
+ const BOOLEAN_OPS = new Set(BOOLEAN_OPS$1);
3707
+ const CROSSREF_OPS = new Set(CROSSREF_OPS$1);
3708
+ const LIST_OPS = new Set(LIST_OPS$1);
3709
+ const JSON_PATH_OPS = new Set(JSON_PATH_OPS$1);
3006
3710
  /**
3007
- * Client-facing text for a thrown error. A `ResolverFrameError` is written for
3008
- * callers; anything else (a driver error naming a relation or a connection
3009
- * string) goes to the metric only.
3711
+ * Always-allowed virtual filter fields: the row id and row-metadata columns,
3712
+ * which datasets map onto row infrastructure rather than the body. Filterable
3713
+ * on any type whether or not its schema declares them.
3010
3714
  */
3011
- function clientErrorMessage(err, metric, key) {
3012
- if (isResolverFrameError(err)) return err.message;
3013
- metric("engine_internal_error", {
3014
- key,
3015
- error: err instanceof Error ? err.message : String(err)
3016
- });
3017
- return "internal error";
3715
+ const METADATA_VIRTUAL_FIELDS = METADATA_FILTER_FIELDS;
3716
+ /** A declared field, else a metadata field. Own keys only: `constructor` is a caller's field name, not `Object.prototype`'s. */
3717
+ function lookupField(fields, name) {
3718
+ if (Object.hasOwn(fields, name)) return fields[name];
3719
+ return Object.hasOwn(METADATA_VIRTUAL_FIELDS, name) ? METADATA_VIRTUAL_FIELDS[name] : void 0;
3018
3720
  }
3019
3721
  /**
3020
- * No-op `BridgeRegistry` — used when no bridges are wired. Every namespace
3021
- * routes locally and is reachable.
3722
+ * The suffix for an unknown field that looks like row metadata. The spellings
3723
+ * the read path teaches are normalised before validation, so one reaching
3724
+ * here is a variant none of them covers.
3022
3725
  */
3023
- const NO_BRIDGES$1 = {
3024
- has: () => false,
3025
- get: () => void 0,
3026
- isUnreachable: () => false,
3027
- entries: () => []
3028
- };
3029
- /**
3030
- * Default idempotency dedup window (24h) per spec §5.13.
3031
- */
3032
- const DEFAULT_IDEMPOTENCY_TTL_MS = 864e5;
3033
- /**
3034
- * Per-frame authorisation gate (§5.12): checks that `identity`'s grant covers
3035
- * `ns` AND allows `operation` there (`mutate` needs `mutate`; everything else
3036
- * needs `read`). Returns which dimension failed.
3037
- *
3038
- * An absent identity, or one with no grant (a bare `{ id }`), passes: those
3039
- * are direct-call tests and system actors. So an authenticator must give every
3040
- * remote caller a `grants` object (`{}` for none), or that caller reaches
3041
- * every namespace on transports that rely on this gate.
3042
- */
3043
- function checkIdentityGrant(identity, ns, operation) {
3044
- if (identity === null || identity === void 0) return { ok: true };
3045
- const resolved = grantOf(identity);
3046
- if (resolved === null) return { ok: true };
3047
- if (!coversNamespace(resolved, ns)) return {
3048
- ok: false,
3049
- reason: "namespace"
3050
- };
3051
- const required = operation === "mutate" ? "mutate" : "read";
3052
- return grantedIn(resolved, ns).includes(required) ? { ok: true } : {
3053
- ok: false,
3054
- reason: "capability",
3055
- required
3056
- };
3057
- }
3058
- function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx, txEntries) {
3059
- const args = { edges };
3060
- if (dataset !== void 0) args.dataset = dataset;
3061
- if (entry.params !== void 0) args.params = entry.params;
3062
- if (entry.fields !== void 0) args.fields = entry.fields;
3063
- if (onWrite !== void 0) args.onWrite = onWrite;
3064
- if (signal !== void 0) args.signal = signal;
3065
- if (resolveDataset !== void 0) args.resolveDataset = resolveDataset;
3066
- if (afterTx !== void 0) args.afterTx = afterTx;
3067
- if (txEntries !== void 0) args.txEntries = txEntries;
3068
- return args;
3069
- }
3070
- /**
3071
- * `params` with the type's natural order as `orderBy` when it names none: the
3072
- * default read order of a query, a subscription's snapshot and a stream. A
3073
- * single-row `id` read has no order, and get-shaped resolvers refuse one. An
3074
- * extension operator (semantic, …) in `where` keeps its relevance order.
3075
- * Returns `params` itself when nothing is added.
3076
- */
3077
- function withNaturalOrder(params, entry, dataset) {
3078
- if (entry.kind !== "type" || dataset?.capabilities.orderBy !== true || params?.id !== void 0 || listExtensionOperators().some((op) => whereContainsOperator(params?.where, op))) return params;
3079
- const orderBy = params?.orderBy;
3080
- if (Array.isArray(orderBy) && orderBy.length > 0) return params;
3081
- return {
3082
- ...params,
3083
- orderBy: [{ ...naturalOrderOf(entry) }]
3084
- };
3726
+ function metadataHint(fieldName) {
3727
+ if (!/^(_metadata|createdBy|updatedBy)(\.|$)/.test(fieldName)) return "";
3728
+ return " — row metadata is filterable as createdAt, updatedAt, createdBy / updatedBy (an identity id, or { kind, id }), or createdById, createdByKind, updatedById, updatedByKind, and seq on a visible-order type";
3085
3729
  }
3086
- /**
3087
- * The frame with its `where` / `orderBy` metadata spellings rewritten onto the
3088
- * canonical columns (`createdBy` -> `createdById`, …). Returns the same frame
3089
- * when it carries neither.
3090
- */
3091
- function withCanonicalMetadataFilters(entry, fields) {
3092
- const params = entry.params;
3093
- if (params === void 0 || params.where === void 0 && params.orderBy === void 0) return entry;
3094
- return {
3095
- ...entry,
3096
- params: {
3097
- ...params,
3098
- ...params.where !== void 0 ? { where: normaliseMetadataWhere(params.where, fields) } : {},
3099
- ...params.orderBy !== void 0 ? { orderBy: normaliseMetadataOrderBy(params.orderBy, fields) } : {}
3730
+ const LOGICAL_KEYS = /* @__PURE__ */ new Set([
3731
+ "AND",
3732
+ "OR",
3733
+ "NOT"
3734
+ ]);
3735
+ function fieldKindOf(def) {
3736
+ switch (def.kind) {
3737
+ case "scalar": switch (def.type) {
3738
+ case "number": return "scalar.number";
3739
+ case "string": return "scalar.string";
3740
+ case "boolean": return "scalar.boolean";
3741
+ case "date": return "scalar.date";
3742
+ case "json": return "scalar.json";
3743
+ default: return assertNever(def);
3100
3744
  }
3101
- };
3102
- }
3103
- function addError(envelope, path, message, code, details) {
3104
- const list = envelope.errors ?? [];
3105
- const err = {
3106
- message,
3107
- path
3108
- };
3109
- if (code !== void 0) err.code = code;
3110
- if (details !== void 0) err.details = details;
3111
- list.push(err);
3112
- envelope.errors = list;
3745
+ case "crossRef": return "crossRef";
3746
+ case "struct": return "struct";
3747
+ case "list": return "list";
3748
+ default: return assertNever(def);
3749
+ }
3113
3750
  }
3114
- function addTopLevelError(envelope, message, code) {
3115
- const list = envelope.errors ?? [];
3116
- list.push({
3117
- message,
3118
- code
3119
- });
3120
- envelope.errors = list;
3751
+ function opsAllowedFor(kind) {
3752
+ switch (kind) {
3753
+ case "scalar.number":
3754
+ case "scalar.date": return NUMBER_OPS;
3755
+ case "scalar.string": return STRING_OPS;
3756
+ case "scalar.boolean": return BOOLEAN_OPS;
3757
+ case "crossRef": return CROSSREF_OPS;
3758
+ case "list": return LIST_OPS;
3759
+ case "scalar.json": return JSON_PATH_OPS;
3760
+ default: return /* @__PURE__ */ new Set();
3761
+ }
3121
3762
  }
3122
3763
  /**
3123
- * Stable per-caller component folded into the idempotency dedup key. A cache
3124
- * hit short-circuits dispatch before gates and policy run, so two callers may
3125
- * share a cached envelope ONLY when their authorization surface is identical.
3126
- *
3127
- * Captures the authz-relevant identity fields, sorted for order-independence;
3128
- * a `null` identity collapses to one bucket. Volatile JWT claims (exp/iat/jti)
3129
- * are deliberately excluded so retries across token refresh still hit.
3764
+ * The kinds a dataset declares capabilities for. `struct` is deliberately
3765
+ * absent: it is a ValidatorKind but not a FieldKind — a struct is walked INTO
3766
+ * rather than filtered on, so there is no dataset capability to intersect.
3130
3767
  */
3131
- function callerDedupComponent(identity) {
3132
- if (identity === null || identity === void 0) return "\0anon";
3133
- const sortedOrEmpty = (xs) => Array.isArray(xs) ? [...xs].sort() : [];
3134
- const sortedGrant = (g) => {
3135
- if (g === null || g === void 0 || typeof g !== "object") return [];
3136
- return Object.entries(g).map(([ns, caps]) => [ns, Array.isArray(caps) ? [...caps].sort() : []]).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
3137
- };
3138
- return JSON.stringify({
3139
- id: identity.id,
3140
- roles: sortedOrEmpty(identity.roles),
3141
- scopes: sortedOrEmpty(identity.scopes),
3142
- grantOnly: true,
3143
- grants: sortedGrant(identity.grants)
3144
- });
3145
- }
3768
+ const FIELD_KINDS = [
3769
+ "scalar.number",
3770
+ "scalar.string",
3771
+ "scalar.boolean",
3772
+ "scalar.date",
3773
+ "scalar.json",
3774
+ "crossRef",
3775
+ "list"
3776
+ ];
3146
3777
  /**
3147
- * Frame-scoped idempotency key. §5.13 design call: dedup is per-frame (one
3148
- * frame = one tx = one dedup record), not per-key. The sorted-keys prefix
3149
- * ensures two frames with different operation sets but the same user-supplied
3150
- * key don't collide. `caller` (see {@link callerDedupComponent}) scopes the key
3151
- * to the requester so a cache hit never crosses authorization boundaries.
3778
+ * The operators `validateLeaf` will accept on each field kind for one
3779
+ * dataset: the validator's builtin set intersected with the dataset's
3780
+ * `capabilities.operators`. Both gates matter; a third-party dataset may
3781
+ * declare less than the builtins.
3782
+ *
3783
+ * Extension operators are excluded: they are valid on every kind and are
3784
+ * listed separately by `Engine.listFilterOperators()`.
3152
3785
  */
3153
- function makeDedupKey(keys, idempotencyKey, caller) {
3154
- const sorted = [...keys].sort();
3155
- return JSON.stringify({
3156
- keys: sorted,
3157
- idempotencyKey,
3158
- caller
3159
- });
3786
+ function effectiveFilterOperators(capabilities) {
3787
+ const out = {};
3788
+ for (const kind of FIELD_KINDS) {
3789
+ const builtin = opsAllowedFor(kind);
3790
+ out[kind] = (capabilities.operators[kind] ?? []).filter((op) => builtin.has(op)).sort();
3791
+ }
3792
+ return out;
3160
3793
  }
3161
- /**
3162
- * Per-frame dedup key for batched-array mutate (§5.13). The slot index is
3163
- * included so two frames at different indices in the same array don't
3164
- * collide even when their idempotencyKey values happen to match (as they
3165
- * might under a naïve "retry the same batch" pattern). The op-key prefix
3166
- * keeps arrays under different op-keys in different cache buckets, and `caller`
3167
- * scopes the key to the requester.
3168
- */
3169
- function makeArrayDedupKey(key, index, idempotencyKey, caller) {
3170
- return JSON.stringify({
3171
- batched: true,
3172
- key,
3173
- index,
3174
- idempotencyKey,
3175
- caller
3176
- });
3794
+ function isPrimitive(v) {
3795
+ return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date;
3177
3796
  }
3178
3797
  /**
3179
- * In-flight join key for a mutate made only of array op-keys whose every slot
3180
- * carries an idempotencyKey: the op-keys, each slot's key, and the caller.
3181
- * Undefined when any op is not covered by a key, since two requests could then
3182
- * share this key and differ in what they write.
3798
+ * Check the value shape for a given operator against the field's declared
3799
+ * kind. Returns on success, throws on failure. Leniency rules — matching how
3800
+ * substrates naturally coerce — kept tight on purpose (e.g. a `string` value
3801
+ * on a numeric field is a caller bug, not a silent coerce).
3802
+ *
3803
+ * `nullable` — when true, `null` elements inside `in`/`nin` arrays are
3804
+ * accepted (IS NULL membership semantics). Non-nullable fields still reject
3805
+ * null array elements.
3183
3806
  */
3184
- function batchedInFlightKey(frame, caller) {
3185
- const slots = [];
3186
- for (const [key, entry] of Object.entries(frame)) {
3187
- if (!Array.isArray(entry) || entry.length === 0) return void 0;
3188
- const ids = [];
3189
- for (const f of entry) {
3190
- if (f.idempotencyKey === void 0) return void 0;
3191
- ids.push(f.idempotencyKey);
3807
+ function validateValueShape(fieldKind, op, value, path, nullable = false) {
3808
+ if (op === "in" || op === "nin") {
3809
+ if (!Array.isArray(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' requires an array value`, path);
3810
+ for (const elt of value) {
3811
+ if (nullable && elt === null) continue;
3812
+ validatePrimitiveKind(fieldKind, elt, path, op);
3192
3813
  }
3193
- slots.push([key, ids]);
3814
+ return;
3194
3815
  }
3195
- if (slots.length === 0) return void 0;
3196
- slots.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
3197
- return JSON.stringify({
3198
- batched: slots,
3199
- caller
3200
- });
3201
- }
3202
- /**
3203
- * Narrow a `QualifiedFrame` bucket to a `BridgeFrame`. Bridges don't support
3204
- * batched-array forwarding (§5.13); the mutate path filters array op-keys out
3205
- * of bridge buckets before this runs, so any remaining entry is structurally
3206
- * a single `FrameEntry`; the array skip only narrows the type.
3207
- */
3208
- function toBridgeFrame(bucket) {
3209
- const out = {};
3210
- for (const [key, entry] of Object.entries(bucket)) {
3211
- if (Array.isArray(entry)) continue;
3212
- out[key] = entry;
3816
+ if (op === "between") {
3817
+ if (!Array.isArray(value) || value.length !== 2) throw new FilterValidationError("invalid_between", "operator 'between' requires a [low, high] tuple", path);
3818
+ validatePrimitiveKind(fieldKind, value[0], path, op);
3819
+ validatePrimitiveKind(fieldKind, value[1], path, op);
3820
+ return;
3213
3821
  }
3214
- return out;
3822
+ if ((op === "eq" || op === "neq") && value === null) return;
3823
+ validatePrimitiveKind(fieldKind, value, path, op);
3215
3824
  }
3216
- /**
3217
- * Scope each forwarded `idempotencyKey` to the local caller. The peer sees
3218
- * every forwarded write under the bridge's one credential, so a key passed
3219
- * verbatim lets two callers who pick the same key share one cached reply
3220
- * there. The same caller retrying still forwards the same key.
3221
- */
3222
- function scopeBridgeIdempotency(bucket, caller) {
3223
- const out = {};
3224
- for (const [key, entry] of Object.entries(bucket)) out[key] = !Array.isArray(entry) && typeof entry.idempotencyKey === "string" ? {
3225
- ...entry,
3226
- idempotencyKey: createHash("sha256").update(JSON.stringify([caller, entry.idempotencyKey])).digest("hex")
3227
- } : entry;
3228
- return out;
3825
+ function validatePrimitiveKind(fieldKind, value, path, op) {
3826
+ if (!isPrimitive(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected a primitive value, got ${typeof value}`, path);
3827
+ switch (fieldKind) {
3828
+ case "scalar.number":
3829
+ if (typeof value !== "number") throw new FilterValidationError("type_mismatch", `operator '${op}' expected number, got ${typeof value}`, path);
3830
+ return;
3831
+ case "scalar.string":
3832
+ if (typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected string, got ${typeof value}`, path);
3833
+ return;
3834
+ case "scalar.boolean":
3835
+ if (typeof value !== "boolean") throw new FilterValidationError("type_mismatch", `operator '${op}' expected boolean, got ${typeof value}`, path);
3836
+ return;
3837
+ case "scalar.date": {
3838
+ if (!(value instanceof Date) && typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected Date or ISO string, got ${typeof value}`, path);
3839
+ const field = path.slice(path[0] === "where" ? 1 : 0, -1).join(".");
3840
+ if (value instanceof Date && Number.isNaN(value.getTime()) || typeof value === "string" && isImpossibleIsoTimestamp(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' on '${field}': ${String(value)} is not a real date`, path);
3841
+ return;
3842
+ }
3843
+ case "crossRef":
3844
+ if (typeof value !== "string" && typeof value !== "number") throw new FilterValidationError("type_mismatch", `crossRef '${op}' expected id (string or number), got ${typeof value}`, path);
3845
+ return;
3846
+ }
3847
+ }
3848
+ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, ctx) {
3849
+ if (fieldDef.kind === "struct") {
3850
+ if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' is a struct — expected a nested where clause object`, path);
3851
+ validateWhereAgainstFields(leaf, fieldDef.fields, path, capabilities, {
3852
+ ...ctx,
3853
+ insideStruct: true
3854
+ });
3855
+ return;
3856
+ }
3857
+ if (fieldDef.kind === "list") {
3858
+ const listDef = fieldDef;
3859
+ const elementKind = fieldKindOf(listDef.of);
3860
+ if (elementKind === "struct" || elementKind === "list" || elementKind === "scalar.json") throw new FilterValidationError("unknown_operator", `field '${fieldName}' is a list of ${elementKind} — only lists of scalars / refs support 'has'`, path);
3861
+ if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3862
+ const datasetCapOps = new Set(capabilities.operators.list ?? []);
3863
+ const elemNullable = listDef.of.kind === "scalar" && listDef.of.nullable === true;
3864
+ for (const [op, value] of Object.entries(leaf)) {
3865
+ if (!LIST_OPS.has(op)) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=list)`, [...path, op]);
3866
+ if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'list'`, [...path, op]);
3867
+ if (value === null) {
3868
+ if (!elemNullable) throw new FilterValidationError("type_mismatch", `operator 'has' on non-nullable list element of '${fieldName}' cannot be null`, [...path, op]);
3869
+ continue;
3870
+ }
3871
+ validateValueShape(elementKind, op, value, [...path, op], elemNullable);
3872
+ }
3873
+ return;
3874
+ }
3875
+ const kind = fieldKindOf(fieldDef);
3876
+ if (kind === "scalar.json") {
3877
+ if (ctx.insideStruct === true && isJsonPathPredicate(leaf)) throw new FilterValidationError("unknown_operator", `json path filters apply to top-level json fields only — '${fieldName}' is inside a struct (kind=scalar.json)`, [...path, "path"]);
3878
+ validateJsonPathLeaf(fieldName, leaf, path, capabilities);
3879
+ return;
3880
+ }
3881
+ if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3882
+ const allowedOps = opsAllowedFor(kind);
3883
+ const datasetCapOps = new Set(capabilities.operators[kind] ?? []);
3884
+ for (const [op, value] of Object.entries(leaf)) {
3885
+ if (!allowedOps.has(op)) {
3886
+ const extOp = getExtensionOperator(op);
3887
+ if (extOp === void 0) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=${kind})`, [...path, op]);
3888
+ const vResult = extOp.validate(value);
3889
+ if (!vResult.ok) throw new FilterValidationError("type_mismatch", `operator '${op}' validation failed: ${vResult.reason}`, [...path, op]);
3890
+ continue;
3891
+ }
3892
+ if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind '${kind}'`, [...path, op]);
3893
+ if (value !== null && typeof value === "object" && "$ref" in value) {
3894
+ if (ctx.insideStruct === true) throw new FilterValidationError("walk_unsupported_ref", `$ref is not valid inside a struct ('${fieldName}')`, [...path, op]);
3895
+ validateRef(kind, op, value, [...path, op], ctx.walk, lookupField, fieldKindOf);
3896
+ continue;
3897
+ }
3898
+ const nullable = fieldDef.kind === "scalar" && fieldDef.nullable === true;
3899
+ validateValueShape(kind, op, value, [...path, op], nullable);
3900
+ }
3229
3901
  }
3902
+ const JSON_PATH_HINT = "address inside it with { path: [...], <op>: ... }";
3230
3903
  /**
3231
- * Snapshot obligation gate. Mirrors `applyRowFilters` from the SDK but on a
3232
- * single row — we can't wrap every live push in an allocation when the vast
3233
- * majority of rows pass the filter.
3904
+ * A json field is filterable only through a path predicate. `eq`/`in`/`has`
3905
+ * compile to containment, which the GIN derived for
3906
+ * `field.json({ indexed: true })` serves; anything else scans the
3907
+ * (namespace, type) partition. Either way it is accepted.
3234
3908
  */
3235
- function obligationsPermitRow(obligations, ctx, row) {
3236
- for (const ob of obligations) try {
3237
- if (!ob.predicate(ctx, row)) return false;
3238
- } catch {
3239
- return false;
3909
+ function validateJsonPathLeaf(fieldName, leaf, path, capabilities) {
3910
+ const obj = leaf !== null && typeof leaf === "object" && !Array.isArray(leaf) ? leaf : null;
3911
+ if (obj !== null && "path" in obj && !isJsonPathPredicate(obj)) throw new FilterValidationError("type_mismatch", `field '${fieldName}': path must be an array of keys (kind=scalar.json)`, [...path, "path"]);
3912
+ if (!isJsonPathPredicate(leaf)) {
3913
+ const op = obj !== null ? Object.keys(obj)[0] : void 0;
3914
+ if (op !== void 0) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=scalar.json — opaque body; ${JSON_PATH_HINT})`, [...path, op]);
3915
+ throw new FilterValidationError("type_mismatch", `field '${fieldName}' is json (opaque body) — predicate object cannot apply; ${JSON_PATH_HINT}`, path);
3916
+ }
3917
+ const pathProblem = jsonPathProblem(leaf.path);
3918
+ if (pathProblem !== null) throw new FilterValidationError("type_mismatch", `field '${fieldName}': ${pathProblem} (kind=scalar.json)`, [...path, "path"]);
3919
+ const ops = Object.keys(leaf).filter((k) => k !== "path");
3920
+ if (ops.length === 0) throw new FilterValidationError("type_mismatch", `field '${fieldName}': a json path needs at least one operator beside it (kind=scalar.json)`, [...path, "path"]);
3921
+ const datasetCapOps = new Set(capabilities.operators["scalar.json"] ?? []);
3922
+ for (const op of ops) {
3923
+ const operand = leaf[op];
3924
+ if (!JSON_PATH_OPS.has(op)) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid on a json path of field '${fieldName}' (kind=scalar.json)`, [...path, op]);
3925
+ if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'scalar.json'`, [...path, op]);
3926
+ const problem = jsonPathOperandProblem(op, operand);
3927
+ if (problem !== null) throw new FilterValidationError(op === "between" ? "invalid_between" : "type_mismatch", `operator '${op}' on a json path of field '${fieldName}' ${problem}`, [...path, op]);
3240
3928
  }
3241
- return true;
3242
3929
  }
3243
- function normaliseToRows(result) {
3244
- if (result === null) return [];
3245
- if (Array.isArray(result)) return result;
3246
- if (typeof result === "object" && "rows" in result && Array.isArray(result.rows)) return result.rows;
3247
- return [result];
3930
+ function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
3931
+ if (where === null || typeof where !== "object" || Array.isArray(where)) throw new FilterValidationError("type_mismatch", "where must be an object", path);
3932
+ if (!ctx.walk.groupBound) ctx = {
3933
+ ...ctx,
3934
+ walk: bindGroup(where, path, ctx.walk)
3935
+ };
3936
+ const keys = Object.keys(where);
3937
+ const hasLogical = keys.some((k) => LOGICAL_KEYS.has(k));
3938
+ const hasField = keys.some((k) => !LOGICAL_KEYS.has(k));
3939
+ if (hasLogical && hasField) throw new FilterValidationError("invalid_logical", `mixing logical combinators (AND/OR/NOT) with field keys at the same level is not allowed`, path);
3940
+ if (hasLogical) {
3941
+ for (const k of keys) {
3942
+ const child = where[k];
3943
+ if (k === "AND" || k === "OR") {
3944
+ if (!Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'${k}' expects an array of WhereClause`, [...path, k]);
3945
+ child.forEach((sub, i) => {
3946
+ validateWhereAgainstFields(sub, fields, [
3947
+ ...path,
3948
+ k,
3949
+ String(i)
3950
+ ], capabilities, k === "AND" ? ctx : orNot(ctx));
3951
+ });
3952
+ } else if (k === "NOT") {
3953
+ if (child === null || typeof child !== "object" || Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'NOT' expects a single WhereClause`, [...path, k]);
3954
+ validateWhereAgainstFields(child, fields, [...path, k], capabilities, orNot(ctx));
3955
+ }
3956
+ }
3957
+ return;
3958
+ }
3959
+ const record = where;
3960
+ const hasAgg = Object.hasOwn(record, "_agg");
3961
+ for (const fieldName of keys) {
3962
+ if (fieldName === "_walk" || fieldName === "_agg") {
3963
+ if (ctx.insideStruct === true) throw new FilterValidationError("walk_unsupported_ref", `${fieldName} is not valid inside a struct`, [...path, fieldName]);
3964
+ const h = frameHelpers(capabilities);
3965
+ if (fieldName === "_walk") validateWalk(record._walk, [...path, "_walk"], ctx.walk, lookupField, fieldKindOf, h.validateWhere);
3966
+ else validateAggPredicate(record, path, ctx.walk, h);
3967
+ continue;
3968
+ }
3969
+ if (hasAgg && AGG_COMPARATORS.has(fieldName)) continue;
3970
+ const def = lookupField(fields, fieldName);
3971
+ if (!def) {
3972
+ const extOp = getExtensionOperator(fieldName);
3973
+ if (extOp !== void 0) {
3974
+ const vResult = extOp.validate(where[fieldName]);
3975
+ if (!vResult.ok) throw new FilterValidationError("type_mismatch", `operator '${fieldName}' validation failed: ${vResult.reason}`, [...path, fieldName]);
3976
+ continue;
3977
+ }
3978
+ throw new FilterValidationError("unknown_field", `unknown field '${fieldName}'${metadataHint(fieldName)}`, [...path, fieldName]);
3979
+ }
3980
+ validateLeaf(fieldName, def, where[fieldName], [...path, fieldName], capabilities, ctx);
3981
+ if (def === METADATA_VIRTUAL_FIELDS.seq) assertSeqIntegers(where[fieldName], [...path, fieldName]);
3982
+ }
3983
+ }
3984
+ const AGG_COMPARATORS = /* @__PURE__ */ new Set([
3985
+ "eq",
3986
+ "neq",
3987
+ "gt",
3988
+ "gte",
3989
+ "lt",
3990
+ "lte"
3991
+ ]);
3992
+ /** Inside OR / NOT: a fresh group, and no binding is referenceable. */
3993
+ function orNot(ctx) {
3994
+ return {
3995
+ ...ctx,
3996
+ walk: {
3997
+ ...ctx.walk,
3998
+ underOrNot: true,
3999
+ groupBound: false
4000
+ }
4001
+ };
4002
+ }
4003
+ function frameHelpers(capabilities) {
4004
+ return {
4005
+ lookup: lookupField,
4006
+ kindOf: fieldKindOf,
4007
+ validateWhere: (w, p, scope) => validateWhereAgainstFields(w, scope.fields, p, capabilities, { walk: scope }),
4008
+ validateOrderBy: (o, f, p) => validateOrderBy(o, f, capabilities, p)
4009
+ };
4010
+ }
4011
+ /**
4012
+ * A where-side `{ _agg, <cmp>: operand }`: the aggregate, then each
4013
+ * comparison against the aggregate's value kind.
4014
+ */
4015
+ function validateAggPredicate(record, path, scope, h) {
4016
+ const kind = validateWalkAgg(record._agg, [...path, "_agg"], scope, h);
4017
+ for (const k of Object.keys(record)) if (k !== "_agg" && !AGG_COMPARATORS.has(k)) throw new FilterValidationError("agg_invalid", `'${k}' cannot sit beside _agg; only eq, neq, gt, gte, lt and lte can. Put it in its own clause under AND`, [...path, k]);
4018
+ const ops = Object.keys(record).filter((k) => AGG_COMPARATORS.has(k));
4019
+ if (ops.length === 0) throw new FilterValidationError("agg_invalid", "_agg in a where needs a comparison beside it: eq, neq, gt, gte, lt or lte", [...path, "_agg"]);
4020
+ for (const op of ops) {
4021
+ const value = record[op];
4022
+ if (value !== null && typeof value === "object" && "$ref" in value) validateRef(kind, op, value, [...path, op], scope, lookupField, fieldKindOf);
4023
+ else validateValueShape(kind, op, value, [...path, op]);
4024
+ }
4025
+ }
4026
+ /** `seq` is a bigint column: every numeric operand must be a safe integer. */
4027
+ function assertSeqIntegers(leaf, path) {
4028
+ for (const [op, operand] of Object.entries(leaf)) for (const v of Array.isArray(operand) ? operand : [operand]) if (typeof v === "number" && !Number.isSafeInteger(v)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an integer for 'seq', got ${v}`, [...path, op]);
4029
+ }
4030
+ function validateOrderBy(orderBy, fields, capabilities, path = ["orderBy"], derived = /* @__PURE__ */ new Set()) {
4031
+ if (!capabilities.orderBy) throw new FilterValidationError("capability_unsupported", "dataset does not support orderBy", path);
4032
+ if (!Array.isArray(orderBy)) throw new FilterValidationError("type_mismatch", "orderBy must be an array of { field: \"asc\" | \"desc\" } entries", path);
4033
+ orderBy.forEach((clause, i) => {
4034
+ if (clause === null || typeof clause !== "object" || Array.isArray(clause)) throw new FilterValidationError("type_mismatch", "each orderBy entry must be a { field: \"asc\" | \"desc\" } object", [...path, String(i)]);
4035
+ const entries = Object.entries(clause);
4036
+ if (entries.length !== 1) throw new FilterValidationError("type_mismatch", "each orderBy entry must have exactly one field", [...path, String(i)]);
4037
+ const [fieldName, dir] = entries[0];
4038
+ if (dir !== "asc" && dir !== "desc") throw new FilterValidationError("type_mismatch", `orderBy direction must be 'asc' or 'desc', got ${String(dir)}`, [
4039
+ ...path,
4040
+ String(i),
4041
+ fieldName
4042
+ ]);
4043
+ if (fieldName === "id") return;
4044
+ if (fieldName.startsWith("$")) {
4045
+ if (derived.has(fieldName.slice(1))) return;
4046
+ throw new FilterValidationError("derive_invalid", `orderBy '${fieldName}' needs derive.${fieldName.slice(1)} in params`, [
4047
+ ...path,
4048
+ String(i),
4049
+ fieldName
4050
+ ]);
4051
+ }
4052
+ const def = lookupField(fields, fieldName);
4053
+ if (!def) throw new FilterValidationError("unknown_field", `unknown field '${fieldName}' in orderBy${metadataHint(fieldName)}`, [
4054
+ ...path,
4055
+ String(i),
4056
+ fieldName
4057
+ ]);
4058
+ if (def.kind !== "scalar") throw new FilterValidationError("orderby_nonscalar", `orderBy on non-scalar field '${fieldName}' is not supported (kind=${def.kind})`, [
4059
+ ...path,
4060
+ String(i),
4061
+ fieldName
4062
+ ]);
4063
+ if (def.type === "json") throw new FilterValidationError("orderby_nonscalar", `orderBy on json field '${fieldName}' is not supported (opaque body)`, [
4064
+ ...path,
4065
+ String(i),
4066
+ fieldName
4067
+ ]);
4068
+ });
4069
+ }
4070
+ function validateFilter(input) {
4071
+ const fields = input.typeSchema.fields;
4072
+ const seed = {
4073
+ ...input.namespace !== void 0 ? { namespace: input.namespace } : {},
4074
+ ...input.schemaOf !== void 0 ? { schemaOf: input.schemaOf } : {},
4075
+ ...input.typeName !== void 0 ? { typeName: input.typeName } : {},
4076
+ fields,
4077
+ depth: 0,
4078
+ bindings: /* @__PURE__ */ new Map([["$", fields]]),
4079
+ hidden: /* @__PURE__ */ new Set(),
4080
+ underOrNot: false,
4081
+ groupBound: false,
4082
+ frameBindings: { count: 0 }
4083
+ };
4084
+ const h = frameHelpers(input.capabilities);
4085
+ const aggs = validateSelection(input.fields, ["fields"], seed, h);
4086
+ const scope = aggs.size > 0 ? {
4087
+ ...seed,
4088
+ aggs
4089
+ } : seed;
4090
+ if (input.where !== void 0) validateWhereAgainstFields(input.where, fields, ["where"], input.capabilities, { walk: scope });
4091
+ const derived = validateFrameParams(input, scope, h);
4092
+ if (input.orderBy !== void 0) validateOrderBy(input.orderBy, fields, input.capabilities, ["orderBy"], derived);
3248
4093
  }
3249
4094
 
3250
4095
  //#endregion
3251
- //#region ../../packages/substrate-core/src/engine/bridge.ts
4096
+ //#region ../../packages/substrate-core/src/filter/walk-validator.ts
4097
+ const MAX_WALK_DEPTH = 3;
4098
+ /** Joint quantification enumerates the product of the bound walks' neighbourhoods, so cap the factors. */
4099
+ const MAX_GROUP_BINDINGS = 3;
4100
+ const MAX_FRAME_BINDINGS = 6;
4101
+ const MAX_DATE_SHIFT_MS = 0x9184e72a000;
4102
+ const COMPARISON_OPS = /* @__PURE__ */ new Set([
4103
+ "eq",
4104
+ "neq",
4105
+ "gt",
4106
+ "gte",
4107
+ "lt",
4108
+ "lte"
4109
+ ]);
4110
+ const WALK_KEYS = /* @__PURE__ */ new Set([
4111
+ "as",
4112
+ "in",
4113
+ "out",
4114
+ "where",
4115
+ "quantifier",
4116
+ "pick"
4117
+ ]);
4118
+ const IDENT = /^[A-Za-z][A-Za-z0-9_]*$/;
4119
+ const isObj$1 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
4120
+ function fail(code, msg, path) {
4121
+ throw new FilterValidationError(code, msg, path);
4122
+ }
4123
+ /** A type's schema, or undefined for anything that is not one (e.g. a prototype key like `constructor`). */
4124
+ function schemaIn(schemaOf, type) {
4125
+ const s = schemaOf(type);
4126
+ return isObj$1(s) && isObj$1(s.fields) ? s : void 0;
4127
+ }
3252
4128
  /**
3253
- * Mark a key's result set partial, naming the bridge that could not be
3254
- * reached. Merges rather than overwrites, so a multi-bridge key accumulates.
4129
+ * Resolve a walk's `in` / `out` to the far type. Shared by `_walk` and the
4130
+ * where-side `_agg`, so both name edges the same way.
3255
4131
  */
3256
- function markIncomplete(envelope, key, bridgeName) {
3257
- if (envelope._completeness === void 0) envelope._completeness = {};
3258
- const completeness = envelope._completeness;
3259
- if (completeness[key] === void 0) completeness[key] = { complete: false };
3260
- const entry = completeness[key];
3261
- entry.complete = false;
3262
- if (entry.unreachable === void 0) entry.unreachable = [];
3263
- const unreachable = entry.unreachable;
3264
- if (!unreachable.includes(bridgeName)) unreachable.push(bridgeName);
4132
+ function resolveHop(node, path, scope) {
4133
+ const { namespace, schemaOf, typeName } = scope;
4134
+ if (namespace === void 0 || schemaOf === void 0 || typeName === void 0) fail("walk_unknown_ref", "walks are not available on this read", path);
4135
+ if (scope.depth >= 3) fail("walk_too_deep", `a walk chains at most ${3} hops`, path);
4136
+ const hasIn = node.in !== void 0;
4137
+ if (hasIn === (node.out !== void 0)) fail("walk_unknown_ref", "a walk names exactly one of 'in' or 'out'", path);
4138
+ const dir = hasIn ? "in" : "out";
4139
+ const spec = node[dir];
4140
+ const at = [...path, dir];
4141
+ if (typeof spec !== "string") fail("walk_unknown_ref", `'${dir}' must be a string`, at);
4142
+ let farType;
4143
+ let fieldPath;
4144
+ let fieldOwner;
4145
+ if (dir === "in") {
4146
+ const m = /^([^/]+)\/([^./]+)\.(.+)$/.exec(spec);
4147
+ if (m === null) fail("walk_unknown_ref", `'in' must be '<ns>/<Type>.<field>', got '${spec}'`, at);
4148
+ const [, ns, type, field] = m;
4149
+ if (ns !== namespace) fail("walk_cross_namespace", `a walk stays in namespace '${namespace}', not '${ns}'`, at);
4150
+ const far = schemaIn(schemaOf, type);
4151
+ if (far === void 0) fail("walk_unknown_ref", `unknown type '${ns}/${type}'`, at);
4152
+ farType = type;
4153
+ fieldPath = field;
4154
+ fieldOwner = far.fields;
4155
+ } else {
4156
+ farType = "";
4157
+ fieldPath = spec;
4158
+ fieldOwner = scope.fields;
4159
+ }
4160
+ const [head = "", ...rest] = fieldPath.split(".");
4161
+ const def = Object.hasOwn(fieldOwner, head) ? fieldOwner[head] : void 0;
4162
+ if (rest.length > 0 && def?.kind === "struct") fail("walk_unsupported_ref", `'${spec}' is a crossRef nested in a struct; walks follow top-level crossRefs`, at);
4163
+ if (def?.kind === "list" && def.of.kind === "crossRef") fail("walk_unsupported_ref", `'${spec}' is a list of crossRefs; walks follow scalar crossRefs`, at);
4164
+ if (rest.length > 0 || def === void 0 || def.kind !== "crossRef") fail("walk_unknown_ref", `'${spec}' is not a crossRef field`, at);
4165
+ if (def.ns !== namespace) fail("walk_cross_namespace", `'${spec}' points into namespace '${def.ns}'; a walk stays in '${namespace}'`, at);
4166
+ if (dir === "in") {
4167
+ if (def.type !== typeName) fail("walk_unknown_ref", `'${spec}' points at '${def.type}', not '${typeName}'`, at);
4168
+ return {
4169
+ typeName: farType,
4170
+ fields: fieldOwner
4171
+ };
4172
+ }
4173
+ const far = schemaIn(schemaOf, def.type);
4174
+ if (far === void 0) fail("walk_unknown_ref", `unknown type '${def.ns}/${def.type}'`, at);
4175
+ return {
4176
+ typeName: def.type,
4177
+ fields: far.fields
4178
+ };
4179
+ }
4180
+ /** The scope a walk's own `where` is validated in: the far type, one hop deeper, a fresh AND group. */
4181
+ function farScope(scope, hop) {
4182
+ return {
4183
+ ...scope,
4184
+ typeName: hop.typeName,
4185
+ fields: hop.fields,
4186
+ depth: scope.depth + 1,
4187
+ groupBound: false
4188
+ };
4189
+ }
4190
+ const isAny = (n) => (n.quantifier === void 0 || n.quantifier === "any") && n.pick === void 0;
4191
+ function checkAs(node, path) {
4192
+ if (node.as === void 0) return;
4193
+ if (!isAny(node)) fail("walk_quantifier", "only an 'any' walk may bind 'as'; none, all and pick walks cannot be referenced", [...path, "as"]);
4194
+ if (typeof node.as !== "string" || !IDENT.test(node.as)) fail("walk_binding", "'as' must be an identifier", [...path, "as"]);
4195
+ }
4196
+ /** `_walk` nodes in an AND group: the object's own key and, through AND, its conjuncts'. */
4197
+ function groupWalks(where, path, out) {
4198
+ if (!isObj$1(where)) return;
4199
+ if (isObj$1(where._walk)) out.push([where._walk, [...path, "_walk"]]);
4200
+ if (Array.isArray(where.AND)) where.AND.forEach((w, i) => {
4201
+ groupWalks(w, [
4202
+ ...path,
4203
+ "AND",
4204
+ String(i)
4205
+ ], out);
4206
+ });
4207
+ }
4208
+ /** Every `as` anywhere below an OR / NOT in this group. */
4209
+ function hiddenNames(where, under, out) {
4210
+ if (Array.isArray(where)) {
4211
+ for (const w of where) hiddenNames(w, under, out);
4212
+ return;
4213
+ }
4214
+ if (!isObj$1(where)) return;
4215
+ for (const [k, v] of Object.entries(where)) {
4216
+ if (k === "_walk" && under && isObj$1(v) && typeof v.as === "string") out.add(v.as);
4217
+ hiddenNames(v, under || k === "OR" || k === "NOT", out);
4218
+ }
3265
4219
  }
3266
4220
  /**
3267
- * True when the unreachable error was a 401/403 rather than an outage. Both
3268
- * surface as `BridgeUnreachableError` (§6.6), but §6 gives auth failures their
3269
- * own `bridge_auth_failed` metric. Delegates to `isAuthCause` so the metric
3270
- * and the error's message wording share one predicate.
4221
+ * Bind an AND group: every `any` walk with `as` in it is visible to all its
4222
+ * siblings and their descendants (joint quantification), so bind them all
4223
+ * before any member is validated.
3271
4224
  */
3272
- function isAuthFailure(err) {
3273
- return isAuthCause(err.cause);
4225
+ function bindGroup(where, path, scope) {
4226
+ const walks = [];
4227
+ groupWalks(where, path, walks);
4228
+ const hidden = new Set(scope.hidden);
4229
+ hiddenNames(where, false, hidden);
4230
+ if (walks.every(([n]) => n.as === void 0) && hidden.size === scope.hidden.size) return {
4231
+ ...scope,
4232
+ groupBound: true
4233
+ };
4234
+ const bound = walks.filter(([n]) => n.as !== void 0);
4235
+ if (bound.length > 3) fail("walk_binding", `an AND group binds at most ${3} walks with 'as', got ${bound.length}`, path);
4236
+ if (scope.frameBindings !== void 0) {
4237
+ scope.frameBindings.count += bound.length;
4238
+ if (scope.frameBindings.count > 6) fail("walk_binding", `a frame binds at most ${6} walks with 'as'`, path);
4239
+ }
4240
+ const bindings = new Map(scope.bindings);
4241
+ for (const [node, at] of walks) {
4242
+ checkAs(node, at);
4243
+ if (typeof node.as !== "string") continue;
4244
+ if (bindings.has(node.as)) fail("walk_binding", `'${node.as}' is already bound`, [...at, "as"]);
4245
+ bindings.set(node.as, resolveHop(node, at, scope).fields);
4246
+ }
4247
+ return {
4248
+ ...scope,
4249
+ bindings,
4250
+ hidden,
4251
+ groupBound: true
4252
+ };
3274
4253
  }
3275
- var BridgeSubsystem = class {
3276
- #bridges;
3277
- #metric;
3278
- constructor(deps) {
3279
- this.#bridges = deps.bridges;
3280
- this.#metric = deps.metric;
4254
+ const DATE_OR_NUMBER = /* @__PURE__ */ new Set(["scalar.number", "scalar.date"]);
4255
+ /** A `_walk` node. `validateWhere` validates its far-side where in `farScope`. */
4256
+ function validateWalk(node, path, scope, lookup, kindOf, validateWhere) {
4257
+ if (!isObj$1(node)) fail("type_mismatch", "_walk expects a walk object", path);
4258
+ for (const k of Object.keys(node)) if (!WALK_KEYS.has(k)) fail("type_mismatch", `unknown walk key '${k}'`, [...path, k]);
4259
+ const q = node.quantifier;
4260
+ if (q !== void 0 && q !== "any" && q !== "none" && q !== "all") fail("walk_quantifier", "quantifier must be 'any', 'none' or 'all'", [...path, "quantifier"]);
4261
+ checkAs(node, path);
4262
+ const hop = resolveHop(node, path, scope);
4263
+ const pick = node.pick;
4264
+ if (pick !== void 0 && (q === "none" || q === "all")) fail("walk_quantifier", `a pick walk picks one row; it takes no '${q}' quantifier`, [...path, "quantifier"]);
4265
+ if (pick !== void 0) {
4266
+ const entries = isObj$1(pick) ? Object.entries(pick) : [];
4267
+ const [k, field] = entries[0] ?? [];
4268
+ if (entries.length !== 1 || k !== "latest" && k !== "max" && k !== "min") fail("type_mismatch", "pick is one of { latest }, { max } or { min }", [...path, "pick"]);
4269
+ const def = typeof field === "string" ? lookup(hop.fields, field) : void 0;
4270
+ if (def === void 0) fail("unknown_field", `unknown field '${String(field)}' on '${hop.typeName}'`, [
4271
+ ...path,
4272
+ "pick",
4273
+ k
4274
+ ]);
4275
+ const kind = kindOf(def);
4276
+ if (k === "latest" ? kind !== "scalar.date" : !DATE_OR_NUMBER.has(kind)) fail("type_mismatch", `pick ${k} needs a ${k === "latest" ? "date" : "number or date"} field, '${String(field)}' is ${kind}`, [
4277
+ ...path,
4278
+ "pick",
4279
+ k
4280
+ ]);
3281
4281
  }
3282
- /**
3283
- * Proxy a per-bridge bucket through `BridgeClient.query`. §5.8 / §6.5.
3284
- *
3285
- * Unreachable bridges surface as per-key `__orphan: true, reason:
3286
- * 'bridge_unreachable'` entries on the envelope — "reads never fail" is the
3287
- * §6.5 invariant. Any merged `data`/`shapes` from a reachable bridge flow
3288
- * through verbatim; schemaVersion drift detection belongs to the client-side
3289
- * decoder (§7.1) and is not re-checked here.
3290
- *
3291
- * Bridge errors other than unreachable (e.g. remote HTTP 4xx) surface as
3292
- * per-key `bridge_error` entries — the caller asked for a read and the bridge
3293
- * refused; we don't synthesise an orphan because the row's state is unknown.
3294
- * They also mark the key incomplete: the two signals describe the same fact,
3295
- * so a consumer reading only `_completeness` must not conclude "complete".
3296
- */
3297
- async runQuery(ns, bucket, envelope) {
3298
- const bucketKeys = Object.keys(bucket);
3299
- const bridge = this.#bridges.get(ns);
3300
- if (bridge === void 0) {
3301
- for (const key of bucketKeys) addError(envelope, [key], `bridge for namespace '${ns}' not registered`, "unknown_namespace");
3302
- return;
3303
- }
3304
- if (this.#bridges.isUnreachable(ns)) {
3305
- for (const key of bucketKeys) {
3306
- envelope.data[key] = {
3307
- __orphan: true,
3308
- reason: "bridge_unreachable"
3309
- };
3310
- envelope.shapes[key] = "single";
3311
- markIncomplete(envelope, key, bridge.name);
4282
+ if (node.where !== void 0) validateWhere(node.where, [...path, "where"], farScope(scope, hop));
4283
+ }
4284
+ /**
4285
+ * A `$ref` operand on a comparison. Resolves `$.f` (the seed row) or
4286
+ * `<as>.f` (a visible binding) and requires the same number / date kind as
4287
+ * the field it is compared with.
4288
+ */
4289
+ function validateRef(fieldKind, op, operand, path, scope, lookup, kindOf) {
4290
+ if (!COMPARISON_OPS.has(op)) fail("type_mismatch", `a $ref operand is allowed on eq, neq, gt, gte, lt and lte, not '${op}'`, path);
4291
+ for (const [k, v] of Object.entries(operand)) {
4292
+ if (k === "$ref") continue;
4293
+ if (k !== "times" && k !== "plus" || typeof v !== "number" || !Number.isFinite(v)) fail("type_mismatch", `a $ref takes only numeric 'times' and 'plus' beside it, got '${k}'`, path);
4294
+ }
4295
+ if (!DATE_OR_NUMBER.has(fieldKind)) fail("ref_kind_mismatch", `a $ref compares number or date fields, not ${fieldKind}`, path);
4296
+ if (fieldKind === "scalar.date" && operand.times !== void 0) fail("ref_kind_mismatch", "a $ref on a date field takes 'plus' (milliseconds), not 'times'", path);
4297
+ if (fieldKind === "scalar.date" && typeof operand.plus === "number" && Math.abs(operand.plus) > 0x9184e72a000) fail("type_mismatch", `a date $ref shifts by at most ${MAX_DATE_SHIFT_MS} ms either way, got ${operand.plus}`, [...path, "plus"]);
4298
+ const ref = operand.$ref;
4299
+ const m = typeof ref === "string" ? /^([^.]+)\.(.+)$/.exec(ref) : null;
4300
+ if (m === null) fail("ref_unresolved", `$ref must be '$.<field>', '<as>.<field>' or '_agg.<name>', got '${String(ref)}'`, path);
4301
+ const [, name, field] = m;
4302
+ if (name === "_agg") {
4303
+ const aggKind = scope.aggs?.get(field);
4304
+ if (aggKind === void 0) fail("ref_unresolved", `$ref '${ref}': no _agg '${field}' in this frame's fields`, path);
4305
+ if (aggKind !== fieldKind) fail("ref_kind_mismatch", `$ref '${ref}' is ${aggKind}; it is compared with a ${fieldKind} field`, path);
4306
+ return;
4307
+ }
4308
+ if (name !== "$" && (scope.underOrNot || scope.hidden.has(name) && !scope.bindings.has(name))) fail("walk_binding", `$ref '${ref}' crosses an OR or NOT; a binding is referenceable only within its AND group`, path);
4309
+ const fields = scope.bindings.get(name);
4310
+ if (fields === void 0) fail("ref_unresolved", `$ref '${ref}': no binding '${name}' in scope`, path);
4311
+ const def = lookup(fields, field);
4312
+ if (def === void 0) fail("ref_unresolved", `$ref '${ref}': unknown field '${field}'`, path);
4313
+ const refKind = kindOf(def);
4314
+ if (refKind !== fieldKind) fail("ref_kind_mismatch", `$ref '${ref}' is ${refKind}; it is compared with a ${fieldKind} field`, path);
4315
+ }
4316
+ const AGG_FNS = /* @__PURE__ */ new Set([
4317
+ "count",
4318
+ "avg",
4319
+ "sum",
4320
+ "min",
4321
+ "max",
4322
+ "latest"
4323
+ ]);
4324
+ const WALK_AGG_KEYS = /* @__PURE__ */ new Set([
4325
+ "in",
4326
+ "out",
4327
+ "where"
4328
+ ]);
4329
+ const NO_KEYS = /* @__PURE__ */ new Set();
4330
+ /**
4331
+ * One aggregate function over `owner`'s fields, returning its value kind:
4332
+ * `count`, `avg` and `sum` are numbers; `min`, `max` and `latest` take their
4333
+ * field's kind. `latest` picks a row, so only a per-row walk aggregate has it.
4334
+ */
4335
+ function aggKind(agg, extra, owner, path, h, allowLatest) {
4336
+ for (const k of Object.keys(agg)) if (!extra.has(k) && !AGG_FNS.has(k)) fail("agg_invalid", `unknown aggregate key '${k}'`, [...path, k]);
4337
+ const fns = Object.keys(agg).filter((k) => AGG_FNS.has(k));
4338
+ if (fns.length !== 1) fail("agg_invalid", "an aggregate names exactly one of count, avg, sum, min, max or latest", path);
4339
+ const [fn] = fns;
4340
+ const at = [...path, fn];
4341
+ const v = agg[fn];
4342
+ const field = (name, p, ok, what) => {
4343
+ const def = typeof name === "string" ? h.lookup(owner.fields, name) : void 0;
4344
+ if (def === void 0) fail("agg_invalid", `unknown field '${String(name)}' on '${owner.typeName}'`, p);
4345
+ const kind = h.kindOf(def);
4346
+ if (!ok(kind)) fail("agg_invalid", `${fn} needs ${what}; '${String(name)}' is ${kind}`, p);
4347
+ return kind;
4348
+ };
4349
+ switch (fn) {
4350
+ case "count":
4351
+ if (v !== true) fail("agg_invalid", "count takes true", at);
4352
+ return "scalar.number";
4353
+ case "avg":
4354
+ case "sum":
4355
+ field(v, at, (k) => k === "scalar.number", "a number field");
4356
+ return "scalar.number";
4357
+ case "min":
4358
+ case "max": return field(v, at, (k) => DATE_OR_NUMBER.has(k), "a number or date field");
4359
+ default:
4360
+ if (!allowLatest) fail("agg_invalid", "latest picks one row per seed row; a frame aggregate takes count, avg, sum, min or max", at);
4361
+ if (!isObj$1(v) || Object.keys(v).some((k) => k !== "by" && k !== "value")) fail("agg_invalid", "latest takes { by: <dateField>, value: <field> }", at);
4362
+ field(v.by, [...at, "by"], (k) => k === "scalar.date", "a date field");
4363
+ return field(v.value, [...at, "value"], (k) => k.startsWith("scalar.") && k !== "scalar.json", "a scalar field");
4364
+ }
4365
+ }
4366
+ /** A walk aggregate (`fields._agg` entry or where-side `_agg`): its walk, far `where` and function. Returns its value kind. */
4367
+ function validateWalkAgg(agg, path, scope, h) {
4368
+ if (!isObj$1(agg)) fail("agg_invalid", "_agg expects an aggregate object", path);
4369
+ const hop = resolveHop(agg, path, scope);
4370
+ const kind = aggKind(agg, WALK_AGG_KEYS, hop, path, h, true);
4371
+ if (agg.where !== void 0) h.validateWhere(agg.where, [...path, "where"], farScope(scope, hop));
4372
+ return kind;
4373
+ }
4374
+ const NESTED_KEYS = /* @__PURE__ */ new Set([
4375
+ "_walk",
4376
+ "fields",
4377
+ "where",
4378
+ "orderBy",
4379
+ "limit"
4380
+ ]);
4381
+ /** Top-level row columns a nested row does not carry. */
4382
+ const NESTED_ROW_ONLY = [
4383
+ "_metadata",
4384
+ "shortId",
4385
+ "_deletedAt"
4386
+ ];
4387
+ /** A nested `{ _walk, fields, where?, orderBy?, limit? }` selection. Its `limit` max is the engine's page max. */
4388
+ function validateNested(sel, path, scope, h) {
4389
+ for (const k of Object.keys(sel)) if (!NESTED_KEYS.has(k)) fail("type_mismatch", `unknown nested selection key '${k}'`, [...path, k]);
4390
+ const walk = sel._walk;
4391
+ const wp = [...path, "_walk"];
4392
+ if (!isObj$1(walk)) fail("type_mismatch", "_walk expects { in | out, where? }", wp);
4393
+ for (const k of Object.keys(walk)) if (!WALK_AGG_KEYS.has(k)) fail("type_mismatch", `a nested _walk takes in, out and where, not '${k}'`, [...wp, k]);
4394
+ const hop = resolveHop(walk, wp, scope);
4395
+ const far = farScope(scope, hop);
4396
+ if (walk.where !== void 0) h.validateWhere(walk.where, [...wp, "where"], far);
4397
+ if (sel.where !== void 0) h.validateWhere(sel.where, [...path, "where"], far);
4398
+ if (sel.orderBy !== void 0) {
4399
+ for (const [i, clause] of (Array.isArray(sel.orderBy) ? sel.orderBy : []).entries()) if (isObj$1(clause) && Object.hasOwn(clause, "shortId")) fail("unknown_field", "shortId cannot order a nested list", [
4400
+ ...path,
4401
+ "orderBy",
4402
+ String(i),
4403
+ "shortId"
4404
+ ]);
4405
+ h.validateOrderBy(sel.orderBy, hop.fields, [...path, "orderBy"]);
4406
+ }
4407
+ const limit = sel.limit;
4408
+ if (limit !== void 0 && (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0)) fail("type_mismatch", "limit must be a non-negative integer", [...path, "limit"]);
4409
+ if (!isObj$1(sel.fields)) fail("type_mismatch", "a nested selection needs fields", [...path, "fields"]);
4410
+ for (const k of NESTED_ROW_ONLY) if (Object.hasOwn(sel.fields, k)) fail("unknown_field", `'${k}' is not available in nested selections`, [
4411
+ ...path,
4412
+ "fields",
4413
+ k
4414
+ ]);
4415
+ validateSelection(sel.fields, [...path, "fields"], far, h);
4416
+ }
4417
+ /**
4418
+ * A field selection's `_agg` and nested `{ _walk }` entries, which sit at the
4419
+ * top level of a selection only. Returns the `_agg` names and value kinds.
4420
+ */
4421
+ function validateSelection(fields, path, scope, h) {
4422
+ const aggs = /* @__PURE__ */ new Map();
4423
+ if (!isObj$1(fields)) return aggs;
4424
+ for (const [name, sel] of Object.entries(fields)) {
4425
+ const at = [...path, name];
4426
+ if (name === "_agg") {
4427
+ if (!isObj$1(sel)) fail("agg_invalid", "_agg maps names to aggregates", at);
4428
+ if (Object.keys(sel).length === 0) fail("agg_invalid", "_agg needs at least one entry", at);
4429
+ const own = {
4430
+ ...scope,
4431
+ aggs: /* @__PURE__ */ new Map()
4432
+ };
4433
+ for (const [n, agg] of Object.entries(sel)) {
4434
+ if (!IDENT.test(n)) fail("agg_invalid", `aggregate name '${n}' must be an identifier`, [...at, n]);
4435
+ aggs.set(n, validateWalkAgg(agg, [...at, n], own, h));
3312
4436
  }
3313
- this.#metric("engine_bridge_unreachable_read", {
3314
- ns,
3315
- keys: bucketKeys
3316
- });
3317
- return;
4437
+ } else if (isObj$1(sel) && Object.hasOwn(sel, "_walk")) {
4438
+ if (Object.hasOwn(scope.fields, name)) fail("walk_unsupported_ref", `a nested selection cannot reuse the declared field name '${name}'; name it something else`, at);
4439
+ validateNested(sel, at, scope, h);
4440
+ } else if (isObj$1(sel)) {
4441
+ const deep = walkGrammarPath({ fields: sel });
4442
+ if (deep !== null) fail("walk_unsupported_ref", `'${String(deep.at(-1))}' is valid only at the top level of a type's selection`, [...at, ...deep.slice(1)]);
3318
4443
  }
3319
- try {
3320
- const result = await bridge.query(toBridgeFrame(bucket));
3321
- for (const key of bucketKeys) {
3322
- const data = result.data?.[key];
3323
- const shape = result.shapes?.[key];
3324
- if (data !== void 0) envelope.data[key] = data;
3325
- if (shape !== void 0) envelope.shapes[key] = shape;
3326
- }
3327
- if (result.errors !== void 0 && result.errors.length > 0) {
3328
- if (envelope.errors === void 0) envelope.errors = [];
3329
- const errs = envelope.errors;
3330
- for (const err of result.errors) errs.push(err);
3331
- }
3332
- } catch (err) {
3333
- if (err instanceof BridgeUnreachableError) {
3334
- for (const key of bucketKeys) {
3335
- envelope.data[key] = {
3336
- __orphan: true,
3337
- reason: "bridge_unreachable"
3338
- };
3339
- envelope.shapes[key] = "single";
3340
- markIncomplete(envelope, key, bridge.name);
3341
- }
3342
- this.#metric(isAuthFailure(err) ? "bridge_auth_failed" : "engine_bridge_unreachable_read", {
3343
- ns,
3344
- keys: bucketKeys,
3345
- error: err.message
3346
- });
3347
- return;
3348
- }
3349
- this.#reportBridgeError(ns, bucketKeys, err);
3350
- for (const key of bucketKeys) {
3351
- addError(envelope, [key], `bridge '${bridge.name}' request failed`, "bridge_error");
3352
- markIncomplete(envelope, key, bridge.name);
3353
- }
4444
+ }
4445
+ return aggs;
4446
+ }
4447
+ /**
4448
+ * `count`, `aggregate`, `bucket` and `derive`, and what each excludes.
4449
+ * Returns the derive names `orderBy` may use as `$<name>`.
4450
+ */
4451
+ function validateFrameParams(p, scope, h) {
4452
+ if (p.count !== void 0 && typeof p.count !== "boolean") fail("type_mismatch", "count takes true or false", ["count"]);
4453
+ if (p.count === true) {
4454
+ for (const k of [
4455
+ "aggregate",
4456
+ "bucket",
4457
+ "derive",
4458
+ "orderBy",
4459
+ "cursor"
4460
+ ]) if (p[k] !== void 0) fail("count_conflict", `count returns a count; it takes no '${k}'`, [k]);
4461
+ for (const k of Object.keys(p.fields ?? {})) if (k !== "id") fail("count_conflict", `count returns no rows; it selects only id, not '${k}'`, ["fields", k]);
4462
+ }
4463
+ const seed = {
4464
+ typeName: scope.typeName ?? "",
4465
+ fields: scope.fields
4466
+ };
4467
+ if (p.aggregate !== void 0) {
4468
+ for (const k of [
4469
+ "derive",
4470
+ "orderBy",
4471
+ "cursor"
4472
+ ]) if (p[k] !== void 0) fail("agg_invalid", `aggregate returns aggregate rows; it takes no '${k}'`, [k]);
4473
+ for (const k of Object.keys(p.fields ?? {})) if (k !== "id") fail("agg_invalid", `aggregate returns aggregate rows; it selects only id, not '${k}'`, ["fields", k]);
4474
+ if (!isObj$1(p.aggregate)) fail("agg_invalid", "aggregate maps names to aggregates", ["aggregate"]);
4475
+ if (Object.keys(p.aggregate).length === 0) fail("agg_invalid", "aggregate needs at least one entry", ["aggregate"]);
4476
+ for (const [n, agg] of Object.entries(p.aggregate)) {
4477
+ const at = ["aggregate", n];
4478
+ if (!IDENT.test(n) || n === "bucket" && p.bucket !== void 0) fail("agg_invalid", `aggregate name '${n}' must be an identifier other than bucket`, at);
4479
+ if (!isObj$1(agg)) fail("agg_invalid", "an aggregate is an object such as { count: true }", at);
4480
+ aggKind(agg, NO_KEYS, seed, at, h, false);
4481
+ }
4482
+ }
4483
+ if (p.bucket !== void 0) {
4484
+ const b = p.bucket;
4485
+ if (p.aggregate === void 0) fail("bucket_invalid", "bucket groups an aggregate; it needs aggregate", ["bucket"]);
4486
+ if (!isObj$1(b) || Object.keys(b).some((k) => k !== "field" && k !== "by")) fail("bucket_invalid", "bucket takes { field, by }", ["bucket"]);
4487
+ if (b.by !== "day" && b.by !== "hour") fail("bucket_invalid", "bucket by is 'day' or 'hour'", ["bucket", "by"]);
4488
+ const def = typeof b.field === "string" ? h.lookup(scope.fields, b.field) : void 0;
4489
+ if (def === void 0 || h.kindOf(def) !== "scalar.date") fail("bucket_invalid", `bucket field '${String(b.field)}' is not a date field`, ["bucket", "field"]);
4490
+ }
4491
+ const derived = /* @__PURE__ */ new Set();
4492
+ if (p.derive !== void 0) {
4493
+ if (!isObj$1(p.derive)) fail("derive_invalid", "derive maps names to { diff } or { ratio }", ["derive"]);
4494
+ for (const [n, spec] of Object.entries(p.derive)) {
4495
+ const at = ["derive", n];
4496
+ if (!IDENT.test(n)) fail("derive_invalid", `derive name '${n}' must be an identifier`, at);
4497
+ const entries = isObj$1(spec) ? Object.entries(spec) : [];
4498
+ const [op, operands] = entries[0] ?? [];
4499
+ if (entries.length !== 1 || op !== "diff" && op !== "ratio" || !Array.isArray(operands) || operands.length !== 2) fail("derive_invalid", "a derive is { diff: [a, b] } or { ratio: [a, b] }", at);
4500
+ operands.forEach((o, i) => {
4501
+ deriveOperand(o, [
4502
+ ...at,
4503
+ op,
4504
+ String(i)
4505
+ ], scope, h);
4506
+ });
4507
+ derived.add(n);
3354
4508
  }
3355
4509
  }
3356
- /**
3357
- * Proxy a per-bridge bucket through `BridgeClient.mutate`. §5.8 / §6.5.
3358
- *
3359
- * Unreachable bridges surface as per-key `bridge_unreachable` errors on the
3360
- * envelope — "deletes never proceed silently across a network" (§6.5).
3361
- * G1 atomicity does NOT extend across bridges: each bridge's mutate is
3362
- * independent of the local tx and independent of other bridges.
3363
- */
3364
- async runMutate(ns, bucket, envelope) {
3365
- const bucketKeys = Object.keys(bucket);
3366
- const bridge = this.#bridges.get(ns);
3367
- if (bridge === void 0) {
3368
- for (const key of bucketKeys) addError(envelope, [key], `bridge for namespace '${ns}' not registered`, "unknown_namespace");
3369
- return;
4510
+ return derived;
4511
+ }
4512
+ /** `$.<number field>` of the seed row, or `_agg.<name>` of a number-valued frame aggregate. */
4513
+ function deriveOperand(o, path, scope, h) {
4514
+ const m = typeof o === "string" ? /^(\$|_agg)\.(.+)$/.exec(o) : null;
4515
+ let kind;
4516
+ if (m !== null) {
4517
+ const [, src, name] = m;
4518
+ if (src === "_agg") kind = scope.aggs?.get(name);
4519
+ else {
4520
+ const def = h.lookup(scope.fields, name);
4521
+ kind = def === void 0 ? void 0 : h.kindOf(def);
3370
4522
  }
3371
- if (this.#bridges.isUnreachable(ns)) {
3372
- for (const key of bucketKeys) addError(envelope, [key], `bridge '${ns}' unreachable`, "bridge_unreachable");
3373
- this.#metric("engine_bridge_unreachable_mutate", {
3374
- ns,
3375
- keys: bucketKeys
4523
+ }
4524
+ if (kind !== "scalar.number") fail("derive_invalid", `derive operand '${String(o)}' must be a number field '$.<field>' or a number-valued '_agg.<name>' in this frame's fields`, path);
4525
+ }
4526
+
4527
+ //#endregion
4528
+ //#region ../../packages/substrate-core/src/walk-types.ts
4529
+ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
4530
+ /** A `HopResolver` over one namespace's schema, sharing the validator's edge resolution. */
4531
+ function hopResolver(namespace, schemaOf) {
4532
+ return (node, from, path) => {
4533
+ const fields = schemaOf(from)?.fields;
4534
+ if (!isObj(fields)) throw new Error(`unknown type '${namespace}/${from}'`);
4535
+ return resolveHop(node, path, {
4536
+ namespace,
4537
+ schemaOf,
4538
+ typeName: from,
4539
+ fields,
4540
+ depth: 0,
4541
+ bindings: /* @__PURE__ */ new Map(),
4542
+ hidden: /* @__PURE__ */ new Set(),
4543
+ underOrNot: false,
4544
+ groupBound: false
4545
+ }).typeName;
4546
+ };
4547
+ }
4548
+ /** Walked types of a frame entry `{ params, fields }` seeded at `seed`, deduplicated by (type, where, unfiltered). */
4549
+ function walkedTypes(entry, seed, resolve) {
4550
+ const out = /* @__PURE__ */ new Map();
4551
+ const hop = (node, from, path, where = node.where) => {
4552
+ const type = resolve(node, from, path);
4553
+ const unfiltered = node.quantifier === "all" || node.pick !== void 0;
4554
+ const k = JSON.stringify([
4555
+ type,
4556
+ where ?? null,
4557
+ unfiltered
4558
+ ]);
4559
+ if (!out.has(k)) out.set(k, {
4560
+ type,
4561
+ path,
4562
+ ...where !== void 0 ? { where } : {},
4563
+ ...unfiltered ? { unfiltered: true } : {}
4564
+ });
4565
+ return type;
4566
+ };
4567
+ const inWhere = (v, type, path) => {
4568
+ if (Array.isArray(v)) {
4569
+ v.forEach((c, i) => {
4570
+ inWhere(c, type, [...path, String(i)]);
3376
4571
  });
3377
4572
  return;
3378
4573
  }
3379
- try {
3380
- const result = await bridge.mutate(toBridgeFrame(bucket));
3381
- for (const key of bucketKeys) {
3382
- const data = result.data?.[key];
3383
- const shape = result.shapes?.[key];
3384
- if (data !== void 0) envelope.data[key] = data;
3385
- if (shape !== void 0) envelope.shapes[key] = shape;
3386
- }
3387
- if (result.errors !== void 0 && result.errors.length > 0) {
3388
- if (envelope.errors === void 0) envelope.errors = [];
3389
- const errs = envelope.errors;
3390
- for (const err of result.errors) errs.push(err);
4574
+ if (!isObj(v)) return;
4575
+ for (const [k, child] of Object.entries(v)) {
4576
+ const at = [...path, k];
4577
+ if ((k === "_walk" || k === "_agg") && isObj(child)) {
4578
+ const far = hop(child, type, at);
4579
+ inWhere(child.where, far, [...at, "where"]);
4580
+ } else inWhere(child, type, at);
4581
+ }
4582
+ };
4583
+ const inFields = (fields, type, path) => {
4584
+ if (!isObj(fields)) return;
4585
+ for (const [name, sel] of Object.entries(fields)) {
4586
+ const at = [...path, name];
4587
+ if (name === "_agg" && isObj(sel)) for (const [n, agg] of Object.entries(sel)) {
4588
+ if (!isObj(agg)) continue;
4589
+ const far = hop(agg, type, [...at, n]);
4590
+ inWhere(agg.where, far, [
4591
+ ...at,
4592
+ n,
4593
+ "where"
4594
+ ]);
3391
4595
  }
3392
- } catch (err) {
3393
- if (err instanceof BridgeUnreachableError) {
3394
- const auth = isAuthFailure(err);
3395
- const message = auth ? `bridge '${bridge.name}' refused the request` : `bridge '${bridge.name}' unreachable`;
3396
- for (const key of bucketKeys) addError(envelope, [key], message, "bridge_unreachable");
3397
- this.#metric(auth ? "bridge_auth_failed" : "engine_bridge_unreachable_mutate", {
3398
- ns,
3399
- keys: bucketKeys,
3400
- error: err.message
3401
- });
3402
- return;
4596
+ else if (isObj(sel) && isObj(sel._walk)) {
4597
+ const walk = sel._walk;
4598
+ const wp = [...at, "_walk"];
4599
+ const where = walk.where !== void 0 && sel.where !== void 0 ? { AND: [walk.where, sel.where] } : walk.where ?? sel.where;
4600
+ const far = hop(walk, type, wp, where);
4601
+ inWhere(walk.where, far, [...wp, "where"]);
4602
+ inWhere(sel.where, far, [...at, "where"]);
4603
+ inFields(sel.fields, far, [...at, "fields"]);
3403
4604
  }
3404
- this.#reportBridgeError(ns, bucketKeys, err);
3405
- for (const key of bucketKeys) addError(envelope, [key], `bridge '${bridge.name}' request failed`, "bridge_error");
3406
4605
  }
3407
- }
3408
- /** The peer's own wording can carry its URL or body, so it stays server-side. */
3409
- #reportBridgeError(ns, keys, err) {
3410
- this.#metric("engine_bridge_error", {
3411
- ns,
3412
- keys,
3413
- error: err instanceof Error ? err.message : String(err)
3414
- });
3415
- }
3416
- };
4606
+ };
4607
+ inWhere((isObj(entry.params) ? entry.params : {}).where, seed, ["where"]);
4608
+ inFields(entry.fields, seed, ["fields"]);
4609
+ return [...out.values()];
4610
+ }
3417
4611
 
3418
4612
  //#endregion
3419
- //#region ../../packages/substrate-core/src/filter/validator.ts
4613
+ //#region ../../packages/substrate-core/src/engine/internals.ts
3420
4614
  /**
3421
- * Filter validator. Spec: §5.2.
3422
- *
3423
- * Pure function, no I/O. Walks a WhereClause / OrderByClause tree against a
3424
- * type's TypeSchema and a dataset's FilterCapabilities. Throws
3425
- * FilterValidationError on the first problem it finds; the engine catches it
3426
- * and surfaces a structured envelope error per-frame-entry.
3427
- *
3428
- * Error codes (see below) are stable — callers can switch on them.
3429
- *
3430
- * It does not evaluate, rewrite, or inject row-level policy predicates into
3431
- * the clause.
4615
+ * Engine internals — pure helpers, types, and constants used by the
4616
+ * engine and its subsystems. Nothing in here touches engine state.
3432
4617
  */
3433
- var FilterValidationError = class extends Error {
3434
- name = "FilterValidationError";
3435
- code;
3436
- path;
3437
- constructor(code, message, path) {
3438
- super(message);
3439
- this.code = code;
3440
- this.path = path;
3441
- }
3442
- };
3443
- const NUMBER_OPS = new Set(NUMBER_OPS$1);
3444
- const STRING_OPS = new Set(STRING_OPS$1);
3445
- const BOOLEAN_OPS = new Set(BOOLEAN_OPS$1);
3446
- const CROSSREF_OPS = new Set(CROSSREF_OPS$1);
3447
- const LIST_OPS = new Set(LIST_OPS$1);
3448
- const JSON_PATH_OPS = new Set(JSON_PATH_OPS$1);
4618
+ /** Duck-type guard: is this a ReadResult rather than a bare Row[]? */
4619
+ function isReadResult(v) {
4620
+ return v !== null && typeof v === "object" && !Array.isArray(v) && "rows" in v && Array.isArray(v.rows) && "hasMore" in v;
4621
+ }
3449
4622
  /**
3450
- * Always-allowed virtual filter fields: the row id and row-metadata columns,
3451
- * which datasets map onto row infrastructure rather than the body. Filterable
3452
- * on any type whether or not its schema declares them.
4623
+ * Duck-type guard for async iterables (§5.5). Plain arrays expose
4624
+ * `Symbol.iterator` but NOT `Symbol.asyncIterator`, so this cleanly separates
4625
+ * stream-shaped returns from the `Row[]` list shape without touching the
4626
+ * existing one-shot discriminators.
3453
4627
  */
3454
- const METADATA_VIRTUAL_FIELDS = METADATA_FILTER_FIELDS;
3455
- /** A declared field, else a metadata field. Own keys only: `constructor` is a caller's field name, not `Object.prototype`'s. */
3456
- function lookupField(fields, name) {
3457
- if (Object.hasOwn(fields, name)) return fields[name];
3458
- return Object.hasOwn(METADATA_VIRTUAL_FIELDS, name) ? METADATA_VIRTUAL_FIELDS[name] : void 0;
4628
+ function isAsyncIterable(v) {
4629
+ return v !== null && typeof v === "object" && Symbol.asyncIterator in v;
3459
4630
  }
3460
4631
  /**
3461
- * The suffix for an unknown field that looks like row metadata. The spellings
3462
- * the read path teaches are normalised before validation, so one reaching
3463
- * here is a variant none of them covers.
4632
+ * Deliver a frame the engine does not await. A rejection is counted on
4633
+ * `metric` and handed to `onReject`, so a failing transport never becomes an
4634
+ * unhandled rejection. A synchronous throw still reaches the caller.
3464
4635
  */
3465
- function metadataHint(fieldName) {
3466
- if (!/^(_metadata|createdBy|updatedBy)(\.|$)/.test(fieldName)) return "";
3467
- return " — row metadata is filterable as createdAt, updatedAt, createdBy / updatedBy (an identity id, or { kind, id }), or createdById, createdByKind, updatedById, updatedByKind, and seq on a visible-order type";
4636
+ function deliverFrame(onFrame, frame, metric, onReject) {
4637
+ Promise.resolve(onFrame(frame)).catch((err) => {
4638
+ metric("engine_frame_delivery_rejected", {
4639
+ id: frame.id,
4640
+ kind: frame.kind,
4641
+ error: err instanceof Error ? err.message : String(err)
4642
+ });
4643
+ onReject?.();
4644
+ });
3468
4645
  }
3469
- const LOGICAL_KEYS = /* @__PURE__ */ new Set([
3470
- "AND",
3471
- "OR",
3472
- "NOT"
3473
- ]);
3474
- function fieldKindOf(def) {
3475
- switch (def.kind) {
3476
- case "scalar": switch (def.type) {
3477
- case "number": return "scalar.number";
3478
- case "string": return "scalar.string";
3479
- case "boolean": return "scalar.boolean";
3480
- case "date": return "scalar.date";
3481
- case "json": return "scalar.json";
3482
- default: return assertNever(def);
3483
- }
3484
- case "crossRef": return "crossRef";
3485
- case "struct": return "struct";
3486
- case "list": return "list";
3487
- default: return assertNever(def);
3488
- }
3489
- }
3490
- function opsAllowedFor(kind) {
3491
- switch (kind) {
3492
- case "scalar.number":
3493
- case "scalar.date": return NUMBER_OPS;
3494
- case "scalar.string": return STRING_OPS;
3495
- case "scalar.boolean": return BOOLEAN_OPS;
3496
- case "crossRef": return CROSSREF_OPS;
3497
- case "list": return LIST_OPS;
3498
- case "scalar.json": return JSON_PATH_OPS;
3499
- default: return /* @__PURE__ */ new Set();
3500
- }
4646
+ /**
4647
+ * Client-facing text for a thrown error. A `ResolverFrameError` is written for
4648
+ * callers; anything else (a driver error naming a relation or a connection
4649
+ * string) goes to the metric only.
4650
+ */
4651
+ function clientErrorMessage(err, metric, key) {
4652
+ if (isResolverFrameError(err)) return err.message;
4653
+ metric("engine_internal_error", {
4654
+ key,
4655
+ error: err instanceof Error ? err.message : String(err)
4656
+ });
4657
+ return "internal error";
3501
4658
  }
3502
4659
  /**
3503
- * The kinds a dataset declares capabilities for. `struct` is deliberately
3504
- * absent: it is a ValidatorKind but not a FieldKind — a struct is walked INTO
3505
- * rather than filtered on, so there is no dataset capability to intersect.
4660
+ * No-op `BridgeRegistry` — used when no bridges are wired. Every namespace
4661
+ * routes locally and is reachable.
3506
4662
  */
3507
- const FIELD_KINDS = [
3508
- "scalar.number",
3509
- "scalar.string",
3510
- "scalar.boolean",
3511
- "scalar.date",
3512
- "scalar.json",
3513
- "crossRef",
3514
- "list"
3515
- ];
4663
+ const NO_BRIDGES$1 = {
4664
+ has: () => false,
4665
+ get: () => void 0,
4666
+ isUnreachable: () => false,
4667
+ entries: () => []
4668
+ };
3516
4669
  /**
3517
- * The operators `validateLeaf` will accept on each field kind for one
3518
- * dataset: the validator's builtin set intersected with the dataset's
3519
- * `capabilities.operators`. Both gates matter; a third-party dataset may
3520
- * declare less than the builtins.
4670
+ * Default idempotency dedup window (24h) per spec §5.13.
4671
+ */
4672
+ const DEFAULT_IDEMPOTENCY_TTL_MS = 864e5;
4673
+ /**
4674
+ * Per-frame authorisation gate (§5.12): checks that `identity`'s grant covers
4675
+ * `ns` AND allows `operation` there (`mutate` needs `mutate`; everything else
4676
+ * needs `read`). Returns which dimension failed.
3521
4677
  *
3522
- * Extension operators are excluded: they are valid on every kind and are
3523
- * listed separately by `Engine.listFilterOperators()`.
4678
+ * An absent identity, or one with no grant (a bare `{ id }`), passes: those
4679
+ * are direct-call tests and system actors. So an authenticator must give every
4680
+ * remote caller a `grants` object (`{}` for none), or that caller reaches
4681
+ * every namespace on transports that rely on this gate.
3524
4682
  */
3525
- function effectiveFilterOperators(capabilities) {
3526
- const out = {};
3527
- for (const kind of FIELD_KINDS) {
3528
- const builtin = opsAllowedFor(kind);
3529
- out[kind] = (capabilities.operators[kind] ?? []).filter((op) => builtin.has(op)).sort();
3530
- }
3531
- return out;
4683
+ function checkIdentityGrant(identity, ns, operation) {
4684
+ if (identity === null || identity === void 0) return { ok: true };
4685
+ const resolved = grantOf(identity);
4686
+ if (resolved === null) return { ok: true };
4687
+ if (!coversNamespace(resolved, ns)) return {
4688
+ ok: false,
4689
+ reason: "namespace"
4690
+ };
4691
+ const required = operation === "mutate" ? "mutate" : "read";
4692
+ return grantedIn(resolved, ns).includes(required) ? { ok: true } : {
4693
+ ok: false,
4694
+ reason: "capability",
4695
+ required
4696
+ };
3532
4697
  }
3533
- function isPrimitive(v) {
3534
- return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date;
4698
+ function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx, txEntries) {
4699
+ const args = { edges };
4700
+ if (dataset !== void 0) args.dataset = dataset;
4701
+ if (entry.params !== void 0) args.params = entry.params;
4702
+ if (entry.fields !== void 0) args.fields = entry.fields;
4703
+ if (onWrite !== void 0) args.onWrite = onWrite;
4704
+ if (signal !== void 0) args.signal = signal;
4705
+ if (resolveDataset !== void 0) args.resolveDataset = resolveDataset;
4706
+ if (afterTx !== void 0) args.afterTx = afterTx;
4707
+ if (txEntries !== void 0) args.txEntries = txEntries;
4708
+ return args;
3535
4709
  }
3536
4710
  /**
3537
- * Check the value shape for a given operator against the field's declared
3538
- * kind. Returns on success, throws on failure. Leniency rules — matching how
3539
- * substrates naturally coerce — kept tight on purpose (e.g. a `string` value
3540
- * on a numeric field is a caller bug, not a silent coerce).
3541
- *
3542
- * `nullable` — when true, `null` elements inside `in`/`nin` arrays are
3543
- * accepted (IS NULL membership semantics). Non-nullable fields still reject
3544
- * null array elements.
4711
+ * `params` with the type's natural order as `orderBy` when it names none: the
4712
+ * default read order of a query, a subscription's snapshot and a stream. A
4713
+ * single-row `id` read has no order, and get-shaped resolvers refuse one. An
4714
+ * extension operator (semantic, …) in `where` keeps its relevance order.
4715
+ * Returns `params` itself when nothing is added.
3545
4716
  */
3546
- function validateValueShape(fieldKind, op, value, path, nullable = false) {
3547
- if (op === "in" || op === "nin") {
3548
- if (!Array.isArray(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' requires an array value`, path);
3549
- for (const elt of value) {
3550
- if (nullable && elt === null) continue;
3551
- validatePrimitiveKind(fieldKind, elt, path, op);
3552
- }
3553
- return;
3554
- }
3555
- if (op === "between") {
3556
- if (!Array.isArray(value) || value.length !== 2) throw new FilterValidationError("invalid_between", "operator 'between' requires a [low, high] tuple", path);
3557
- validatePrimitiveKind(fieldKind, value[0], path, op);
3558
- validatePrimitiveKind(fieldKind, value[1], path, op);
3559
- return;
3560
- }
3561
- if ((op === "eq" || op === "neq") && value === null) return;
3562
- validatePrimitiveKind(fieldKind, value, path, op);
4717
+ function withNaturalOrder(params, entry, dataset) {
4718
+ if (entry.kind !== "type" || dataset?.capabilities.orderBy !== true || params?.id !== void 0 || params?.count === true || params?.aggregate !== void 0 || listExtensionOperators().some((op) => whereContainsOperator(params?.where, op))) return params;
4719
+ const orderBy = params?.orderBy;
4720
+ if (Array.isArray(orderBy) && orderBy.length > 0) return params;
4721
+ return {
4722
+ ...params,
4723
+ orderBy: [{ ...naturalOrderOf(entry) }]
4724
+ };
3563
4725
  }
3564
- function validatePrimitiveKind(fieldKind, value, path, op) {
3565
- if (!isPrimitive(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected a primitive value, got ${typeof value}`, path);
3566
- switch (fieldKind) {
3567
- case "scalar.number":
3568
- if (typeof value !== "number") throw new FilterValidationError("type_mismatch", `operator '${op}' expected number, got ${typeof value}`, path);
3569
- return;
3570
- case "scalar.string":
3571
- if (typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected string, got ${typeof value}`, path);
3572
- return;
3573
- case "scalar.boolean":
3574
- if (typeof value !== "boolean") throw new FilterValidationError("type_mismatch", `operator '${op}' expected boolean, got ${typeof value}`, path);
3575
- return;
3576
- case "scalar.date": {
3577
- if (!(value instanceof Date) && typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected Date or ISO string, got ${typeof value}`, path);
3578
- const field = path.slice(path[0] === "where" ? 1 : 0, -1).join(".");
3579
- if (value instanceof Date && Number.isNaN(value.getTime()) || typeof value === "string" && isImpossibleIsoTimestamp(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' on '${field}': ${String(value)} is not a real date`, path);
3580
- return;
3581
- }
3582
- case "crossRef":
3583
- if (typeof value !== "string" && typeof value !== "number") throw new FilterValidationError("type_mismatch", `crossRef '${op}' expected id (string or number), got ${typeof value}`, path);
3584
- return;
3585
- }
4726
+ /**
4727
+ * The frame with its `where` / `orderBy` metadata spellings rewritten onto the
4728
+ * canonical columns (`createdBy` -> `createdById`, …). Given `hop`, every walk
4729
+ * subtree is rewritten against its far type too: a `_walk` / `_agg` where, a
4730
+ * field `_agg`, and a nested `{ _walk }` selection's `where`, `orderBy` and
4731
+ * `fields`. Returns the same frame when there is nothing to rewrite.
4732
+ */
4733
+ function withCanonicalMetadataFilters(entry, fields, hop) {
4734
+ const params = canonicalParams(entry.params, fields, hop);
4735
+ const selection = hop !== void 0 ? canonicalFields(entry.fields, hop) : entry.fields;
4736
+ if (params === entry.params && selection === entry.fields) return entry;
4737
+ return {
4738
+ ...entry,
4739
+ ...params !== void 0 ? { params } : {},
4740
+ ...selection !== void 0 ? { fields: selection } : {}
4741
+ };
3586
4742
  }
3587
- function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, ctx) {
3588
- if (fieldDef.kind === "struct") {
3589
- if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' is a struct — expected a nested where clause object`, path);
3590
- validateWhereAgainstFields(leaf, fieldDef.fields, path, capabilities, {
3591
- ...ctx,
3592
- insideStruct: true
4743
+ function canonicalParams(params, fields, hop) {
4744
+ if (params === void 0 || params.where === void 0 && params.orderBy === void 0) return params;
4745
+ return {
4746
+ ...params,
4747
+ ...params.where !== void 0 ? { where: normaliseMetadataWhere(params.where, fields, hop) } : {},
4748
+ ...params.orderBy !== void 0 ? { orderBy: normaliseMetadataOrderBy(params.orderBy, fields) } : {}
4749
+ };
4750
+ }
4751
+ const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
4752
+ /** A field selection with its `_agg` wheres and nested `{ _walk }` selections rewritten. */
4753
+ function canonicalFields(selection, hop) {
4754
+ if (selection === void 0) return selection;
4755
+ let out;
4756
+ const set = (name, v) => {
4757
+ out ??= { ...selection };
4758
+ out[name] = v;
4759
+ };
4760
+ for (const [name, sel] of Object.entries(selection)) if (name === "_agg" && isPlainObject(sel)) set(name, Object.fromEntries(Object.entries(sel).map(([n, a]) => [n, normaliseWalkNode(a, hop)])));
4761
+ else if (isPlainObject(sel) && isPlainObject(sel._walk)) {
4762
+ const far = hop(sel._walk);
4763
+ if (far === void 0) continue;
4764
+ set(name, {
4765
+ ...canonicalParams(sel, far.fields, far.hop),
4766
+ _walk: normaliseWalkNode(sel._walk, hop),
4767
+ ...isPlainObject(sel.fields) ? { fields: canonicalFields(sel.fields, far.hop) } : {}
3593
4768
  });
3594
- return;
3595
- }
3596
- if (fieldDef.kind === "list") {
3597
- const listDef = fieldDef;
3598
- const elementKind = fieldKindOf(listDef.of);
3599
- if (elementKind === "struct" || elementKind === "list" || elementKind === "scalar.json") throw new FilterValidationError("unknown_operator", `field '${fieldName}' is a list of ${elementKind} — only lists of scalars / refs support 'has'`, path);
3600
- if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3601
- const datasetCapOps = new Set(capabilities.operators.list ?? []);
3602
- const elemNullable = listDef.of.kind === "scalar" && listDef.of.nullable === true;
3603
- for (const [op, value] of Object.entries(leaf)) {
3604
- if (!LIST_OPS.has(op)) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=list)`, [...path, op]);
3605
- if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'list'`, [...path, op]);
3606
- if (value === null) {
3607
- if (!elemNullable) throw new FilterValidationError("type_mismatch", `operator 'has' on non-nullable list element of '${fieldName}' cannot be null`, [...path, op]);
3608
- continue;
3609
- }
3610
- validateValueShape(elementKind, op, value, [...path, op], elemNullable);
3611
- }
3612
- return;
3613
- }
3614
- const kind = fieldKindOf(fieldDef);
3615
- if (kind === "scalar.json") {
3616
- if (ctx.insideStruct === true && isJsonPathPredicate(leaf)) throw new FilterValidationError("unknown_operator", `json path filters apply to top-level json fields only — '${fieldName}' is inside a struct (kind=scalar.json)`, [...path, "path"]);
3617
- validateJsonPathLeaf(fieldName, leaf, path, capabilities);
3618
- return;
3619
4769
  }
3620
- if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3621
- const allowedOps = opsAllowedFor(kind);
3622
- const datasetCapOps = new Set(capabilities.operators[kind] ?? []);
3623
- for (const [op, value] of Object.entries(leaf)) {
3624
- if (!allowedOps.has(op)) {
3625
- const extOp = getExtensionOperator(op);
3626
- if (extOp === void 0) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=${kind})`, [...path, op]);
3627
- const vResult = extOp.validate(value);
3628
- if (!vResult.ok) throw new FilterValidationError("type_mismatch", `operator '${op}' validation failed: ${vResult.reason}`, [...path, op]);
3629
- continue;
4770
+ return out ?? selection;
4771
+ }
4772
+ function addError(envelope, path, message, code, details) {
4773
+ const list = envelope.errors ?? [];
4774
+ const err = {
4775
+ message,
4776
+ path
4777
+ };
4778
+ if (code !== void 0) err.code = code;
4779
+ if (details !== void 0) err.details = details;
4780
+ list.push(err);
4781
+ envelope.errors = list;
4782
+ }
4783
+ function addTopLevelError(envelope, message, code) {
4784
+ const list = envelope.errors ?? [];
4785
+ list.push({
4786
+ message,
4787
+ code
4788
+ });
4789
+ envelope.errors = list;
4790
+ }
4791
+ /**
4792
+ * Stable per-caller component folded into the idempotency dedup key. A cache
4793
+ * hit short-circuits dispatch before gates and policy run, so two callers may
4794
+ * share a cached envelope ONLY when their authorization surface is identical.
4795
+ *
4796
+ * Captures the authz-relevant identity fields, sorted for order-independence;
4797
+ * a `null` identity collapses to one bucket. Volatile JWT claims (exp/iat/jti)
4798
+ * are deliberately excluded so retries across token refresh still hit.
4799
+ */
4800
+ function callerDedupComponent(identity) {
4801
+ if (identity === null || identity === void 0) return "\0anon";
4802
+ const sortedOrEmpty = (xs) => Array.isArray(xs) ? [...xs].sort() : [];
4803
+ const sortedGrant = (g) => {
4804
+ if (g === null || g === void 0 || typeof g !== "object") return [];
4805
+ return Object.entries(g).map(([ns, caps]) => [ns, Array.isArray(caps) ? [...caps].sort() : []]).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
4806
+ };
4807
+ return JSON.stringify({
4808
+ id: identity.id,
4809
+ roles: sortedOrEmpty(identity.roles),
4810
+ scopes: sortedOrEmpty(identity.scopes),
4811
+ grantOnly: true,
4812
+ grants: sortedGrant(identity.grants)
4813
+ });
4814
+ }
4815
+ /**
4816
+ * Frame-scoped idempotency key. §5.13 design call: dedup is per-frame (one
4817
+ * frame = one tx = one dedup record), not per-key. The sorted-keys prefix
4818
+ * ensures two frames with different operation sets but the same user-supplied
4819
+ * key don't collide. `caller` (see {@link callerDedupComponent}) scopes the key
4820
+ * to the requester so a cache hit never crosses authorization boundaries.
4821
+ */
4822
+ function makeDedupKey(keys, idempotencyKey, caller) {
4823
+ const sorted = [...keys].sort();
4824
+ return JSON.stringify({
4825
+ keys: sorted,
4826
+ idempotencyKey,
4827
+ caller
4828
+ });
4829
+ }
4830
+ /**
4831
+ * Per-frame dedup key for batched-array mutate (§5.13). The slot index is
4832
+ * included so two frames at different indices in the same array don't
4833
+ * collide even when their idempotencyKey values happen to match (as they
4834
+ * might under a naïve "retry the same batch" pattern). The op-key prefix
4835
+ * keeps arrays under different op-keys in different cache buckets, and `caller`
4836
+ * scopes the key to the requester.
4837
+ */
4838
+ function makeArrayDedupKey(key, index, idempotencyKey, caller) {
4839
+ return JSON.stringify({
4840
+ batched: true,
4841
+ key,
4842
+ index,
4843
+ idempotencyKey,
4844
+ caller
4845
+ });
4846
+ }
4847
+ /**
4848
+ * In-flight join key for a mutate made only of array op-keys whose every slot
4849
+ * carries an idempotencyKey: the op-keys, each slot's key, and the caller.
4850
+ * Undefined when any op is not covered by a key, since two requests could then
4851
+ * share this key and differ in what they write.
4852
+ */
4853
+ function batchedInFlightKey(frame, caller) {
4854
+ const slots = [];
4855
+ for (const [key, entry] of Object.entries(frame)) {
4856
+ if (!Array.isArray(entry) || entry.length === 0) return void 0;
4857
+ const ids = [];
4858
+ for (const f of entry) {
4859
+ if (f.idempotencyKey === void 0) return void 0;
4860
+ ids.push(f.idempotencyKey);
3630
4861
  }
3631
- if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind '${kind}'`, [...path, op]);
3632
- const nullable = fieldDef.kind === "scalar" && fieldDef.nullable === true;
3633
- validateValueShape(kind, op, value, [...path, op], nullable);
4862
+ slots.push([key, ids]);
3634
4863
  }
4864
+ if (slots.length === 0) return void 0;
4865
+ slots.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
4866
+ return JSON.stringify({
4867
+ batched: slots,
4868
+ caller
4869
+ });
3635
4870
  }
3636
- const JSON_PATH_HINT = "address inside it with { path: [...], <op>: ... }";
3637
4871
  /**
3638
- * A json field is filterable only through a path predicate. `eq`/`in`/`has`
3639
- * compile to containment, which the GIN derived for
3640
- * `field.json({ indexed: true })` serves; anything else scans the
3641
- * (namespace, type) partition. Either way it is accepted.
4872
+ * Narrow a `QualifiedFrame` bucket to a `BridgeFrame`. Bridges don't support
4873
+ * batched-array forwarding (§5.13); the mutate path filters array op-keys out
4874
+ * of bridge buckets before this runs, so any remaining entry is structurally
4875
+ * a single `FrameEntry`; the array skip only narrows the type.
3642
4876
  */
3643
- function validateJsonPathLeaf(fieldName, leaf, path, capabilities) {
3644
- const obj = leaf !== null && typeof leaf === "object" && !Array.isArray(leaf) ? leaf : null;
3645
- if (obj !== null && "path" in obj && !isJsonPathPredicate(obj)) throw new FilterValidationError("type_mismatch", `field '${fieldName}': path must be an array of keys (kind=scalar.json)`, [...path, "path"]);
3646
- if (!isJsonPathPredicate(leaf)) {
3647
- const op = obj !== null ? Object.keys(obj)[0] : void 0;
3648
- if (op !== void 0) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid for field '${fieldName}' (kind=scalar.json — opaque body; ${JSON_PATH_HINT})`, [...path, op]);
3649
- throw new FilterValidationError("type_mismatch", `field '${fieldName}' is json (opaque body) — predicate object cannot apply; ${JSON_PATH_HINT}`, path);
4877
+ function toBridgeFrame(bucket) {
4878
+ const out = {};
4879
+ for (const [key, entry] of Object.entries(bucket)) {
4880
+ if (Array.isArray(entry)) continue;
4881
+ out[key] = entry;
3650
4882
  }
3651
- const pathProblem = jsonPathProblem(leaf.path);
3652
- if (pathProblem !== null) throw new FilterValidationError("type_mismatch", `field '${fieldName}': ${pathProblem} (kind=scalar.json)`, [...path, "path"]);
3653
- const ops = Object.keys(leaf).filter((k) => k !== "path");
3654
- if (ops.length === 0) throw new FilterValidationError("type_mismatch", `field '${fieldName}': a json path needs at least one operator beside it (kind=scalar.json)`, [...path, "path"]);
3655
- const datasetCapOps = new Set(capabilities.operators["scalar.json"] ?? []);
3656
- for (const op of ops) {
3657
- const operand = leaf[op];
3658
- if (!JSON_PATH_OPS.has(op)) throw new FilterValidationError("unknown_operator", `operator '${op}' is not valid on a json path of field '${fieldName}' (kind=scalar.json)`, [...path, op]);
3659
- if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'scalar.json'`, [...path, op]);
3660
- const problem = jsonPathOperandProblem(op, operand);
3661
- if (problem !== null) throw new FilterValidationError(op === "between" ? "invalid_between" : "type_mismatch", `operator '${op}' on a json path of field '${fieldName}' ${problem}`, [...path, op]);
4883
+ return out;
4884
+ }
4885
+ /**
4886
+ * Scope each forwarded `idempotencyKey` to the local caller. The peer sees
4887
+ * every forwarded write under the bridge's one credential, so a key passed
4888
+ * verbatim lets two callers who pick the same key share one cached reply
4889
+ * there. The same caller retrying still forwards the same key.
4890
+ */
4891
+ function scopeBridgeIdempotency(bucket, caller) {
4892
+ const out = {};
4893
+ for (const [key, entry] of Object.entries(bucket)) out[key] = !Array.isArray(entry) && typeof entry.idempotencyKey === "string" ? {
4894
+ ...entry,
4895
+ idempotencyKey: createHash("sha256").update(JSON.stringify([caller, entry.idempotencyKey])).digest("hex")
4896
+ } : entry;
4897
+ return out;
4898
+ }
4899
+ /**
4900
+ * Snapshot obligation gate. Mirrors `applyRowFilters` from the SDK but on a
4901
+ * single row — we can't wrap every live push in an allocation when the vast
4902
+ * majority of rows pass the filter.
4903
+ */
4904
+ function obligationsPermitRow(obligations, ctx, row) {
4905
+ for (const ob of obligations) try {
4906
+ if (!ob.predicate(ctx, row)) return false;
4907
+ } catch {
4908
+ return false;
3662
4909
  }
4910
+ return true;
3663
4911
  }
3664
- function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
3665
- if (where === null || typeof where !== "object" || Array.isArray(where)) throw new FilterValidationError("type_mismatch", "where must be an object", path);
3666
- const keys = Object.keys(where);
3667
- const hasLogical = keys.some((k) => LOGICAL_KEYS.has(k));
3668
- const hasField = keys.some((k) => !LOGICAL_KEYS.has(k));
3669
- if (hasLogical && hasField) throw new FilterValidationError("invalid_logical", `mixing logical combinators (AND/OR/NOT) with field keys at the same level is not allowed`, path);
3670
- if (hasLogical) {
3671
- for (const k of keys) {
3672
- const child = where[k];
3673
- if (k === "AND" || k === "OR") {
3674
- if (!Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'${k}' expects an array of WhereClause`, [...path, k]);
3675
- child.forEach((sub, i) => {
3676
- validateWhereAgainstFields(sub, fields, [
3677
- ...path,
3678
- k,
3679
- String(i)
3680
- ], capabilities, ctx);
4912
+ function normaliseToRows(result) {
4913
+ if (result === null) return [];
4914
+ if (Array.isArray(result)) return result;
4915
+ if (typeof result === "object" && "rows" in result && Array.isArray(result.rows)) return result.rows;
4916
+ return [result];
4917
+ }
4918
+
4919
+ //#endregion
4920
+ //#region ../../packages/substrate-core/src/engine/bridge.ts
4921
+ /**
4922
+ * Mark a key's result set partial, naming the bridge that could not be
4923
+ * reached. Merges rather than overwrites, so a multi-bridge key accumulates.
4924
+ */
4925
+ function markIncomplete(envelope, key, bridgeName) {
4926
+ if (envelope._completeness === void 0) envelope._completeness = {};
4927
+ const completeness = envelope._completeness;
4928
+ if (completeness[key] === void 0) completeness[key] = { complete: false };
4929
+ const entry = completeness[key];
4930
+ entry.complete = false;
4931
+ if (entry.unreachable === void 0) entry.unreachable = [];
4932
+ const unreachable = entry.unreachable;
4933
+ if (!unreachable.includes(bridgeName)) unreachable.push(bridgeName);
4934
+ }
4935
+ /**
4936
+ * True when the unreachable error was a 401/403 rather than an outage. Both
4937
+ * surface as `BridgeUnreachableError` (§6.6), but §6 gives auth failures their
4938
+ * own `bridge_auth_failed` metric. Delegates to `isAuthCause` so the metric
4939
+ * and the error's message wording share one predicate.
4940
+ */
4941
+ function isAuthFailure(err) {
4942
+ return isAuthCause(err.cause);
4943
+ }
4944
+ var BridgeSubsystem = class {
4945
+ #bridges;
4946
+ #metric;
4947
+ constructor(deps) {
4948
+ this.#bridges = deps.bridges;
4949
+ this.#metric = deps.metric;
4950
+ }
4951
+ /**
4952
+ * Proxy a per-bridge bucket through `BridgeClient.query`. §5.8 / §6.5.
4953
+ *
4954
+ * Unreachable bridges surface as per-key `__orphan: true, reason:
4955
+ * 'bridge_unreachable'` entries on the envelope — "reads never fail" is the
4956
+ * §6.5 invariant. Any merged `data`/`shapes` from a reachable bridge flow
4957
+ * through verbatim; schemaVersion drift detection belongs to the client-side
4958
+ * decoder (§7.1) and is not re-checked here.
4959
+ *
4960
+ * Bridge errors other than unreachable (e.g. remote HTTP 4xx) surface as
4961
+ * per-key `bridge_error` entries — the caller asked for a read and the bridge
4962
+ * refused; we don't synthesise an orphan because the row's state is unknown.
4963
+ * They also mark the key incomplete: the two signals describe the same fact,
4964
+ * so a consumer reading only `_completeness` must not conclude "complete".
4965
+ */
4966
+ async runQuery(ns, bucket, envelope) {
4967
+ const bucketKeys = Object.keys(bucket);
4968
+ const bridge = this.#bridges.get(ns);
4969
+ if (bridge === void 0) {
4970
+ for (const key of bucketKeys) addError(envelope, [key], `bridge for namespace '${ns}' not registered`, "unknown_namespace");
4971
+ return;
4972
+ }
4973
+ if (this.#bridges.isUnreachable(ns)) {
4974
+ for (const key of bucketKeys) {
4975
+ envelope.data[key] = {
4976
+ __orphan: true,
4977
+ reason: "bridge_unreachable"
4978
+ };
4979
+ envelope.shapes[key] = "single";
4980
+ markIncomplete(envelope, key, bridge.name);
4981
+ }
4982
+ this.#metric("engine_bridge_unreachable_read", {
4983
+ ns,
4984
+ keys: bucketKeys
4985
+ });
4986
+ return;
4987
+ }
4988
+ try {
4989
+ const result = await bridge.query(toBridgeFrame(bucket));
4990
+ for (const key of bucketKeys) {
4991
+ const data = result.data?.[key];
4992
+ const shape = result.shapes?.[key];
4993
+ if (data !== void 0) envelope.data[key] = data;
4994
+ if (shape !== void 0) envelope.shapes[key] = shape;
4995
+ }
4996
+ if (result.errors !== void 0 && result.errors.length > 0) {
4997
+ if (envelope.errors === void 0) envelope.errors = [];
4998
+ const errs = envelope.errors;
4999
+ for (const err of result.errors) errs.push(err);
5000
+ }
5001
+ } catch (err) {
5002
+ if (err instanceof BridgeUnreachableError) {
5003
+ for (const key of bucketKeys) {
5004
+ envelope.data[key] = {
5005
+ __orphan: true,
5006
+ reason: "bridge_unreachable"
5007
+ };
5008
+ envelope.shapes[key] = "single";
5009
+ markIncomplete(envelope, key, bridge.name);
5010
+ }
5011
+ this.#metric(isAuthFailure(err) ? "bridge_auth_failed" : "engine_bridge_unreachable_read", {
5012
+ ns,
5013
+ keys: bucketKeys,
5014
+ error: err.message
3681
5015
  });
3682
- } else if (k === "NOT") {
3683
- if (child === null || typeof child !== "object" || Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'NOT' expects a single WhereClause`, [...path, k]);
3684
- validateWhereAgainstFields(child, fields, [...path, k], capabilities, ctx);
5016
+ return;
5017
+ }
5018
+ this.#reportBridgeError(ns, bucketKeys, err);
5019
+ for (const key of bucketKeys) {
5020
+ addError(envelope, [key], `bridge '${bridge.name}' request failed`, "bridge_error");
5021
+ markIncomplete(envelope, key, bridge.name);
3685
5022
  }
3686
5023
  }
3687
- return;
3688
5024
  }
3689
- for (const fieldName of keys) {
3690
- const def = lookupField(fields, fieldName);
3691
- if (!def) {
3692
- const extOp = getExtensionOperator(fieldName);
3693
- if (extOp !== void 0) {
3694
- const vResult = extOp.validate(where[fieldName]);
3695
- if (!vResult.ok) throw new FilterValidationError("type_mismatch", `operator '${fieldName}' validation failed: ${vResult.reason}`, [...path, fieldName]);
3696
- continue;
5025
+ /**
5026
+ * Proxy a per-bridge bucket through `BridgeClient.mutate`. §5.8 / §6.5.
5027
+ *
5028
+ * Unreachable bridges surface as per-key `bridge_unreachable` errors on the
5029
+ * envelope — "deletes never proceed silently across a network" (§6.5).
5030
+ * G1 atomicity does NOT extend across bridges: each bridge's mutate is
5031
+ * independent of the local tx and independent of other bridges.
5032
+ */
5033
+ async runMutate(ns, bucket, envelope) {
5034
+ const bucketKeys = Object.keys(bucket);
5035
+ const bridge = this.#bridges.get(ns);
5036
+ if (bridge === void 0) {
5037
+ for (const key of bucketKeys) addError(envelope, [key], `bridge for namespace '${ns}' not registered`, "unknown_namespace");
5038
+ return;
5039
+ }
5040
+ if (this.#bridges.isUnreachable(ns)) {
5041
+ for (const key of bucketKeys) addError(envelope, [key], `bridge '${ns}' unreachable`, "bridge_unreachable");
5042
+ this.#metric("engine_bridge_unreachable_mutate", {
5043
+ ns,
5044
+ keys: bucketKeys
5045
+ });
5046
+ return;
5047
+ }
5048
+ try {
5049
+ const result = await bridge.mutate(toBridgeFrame(bucket));
5050
+ for (const key of bucketKeys) {
5051
+ const data = result.data?.[key];
5052
+ const shape = result.shapes?.[key];
5053
+ if (data !== void 0) envelope.data[key] = data;
5054
+ if (shape !== void 0) envelope.shapes[key] = shape;
3697
5055
  }
3698
- throw new FilterValidationError("unknown_field", `unknown field '${fieldName}'${metadataHint(fieldName)}`, [...path, fieldName]);
5056
+ if (result.errors !== void 0 && result.errors.length > 0) {
5057
+ if (envelope.errors === void 0) envelope.errors = [];
5058
+ const errs = envelope.errors;
5059
+ for (const err of result.errors) errs.push(err);
5060
+ }
5061
+ } catch (err) {
5062
+ if (err instanceof BridgeUnreachableError) {
5063
+ const auth = isAuthFailure(err);
5064
+ const message = auth ? `bridge '${bridge.name}' refused the request` : `bridge '${bridge.name}' unreachable`;
5065
+ for (const key of bucketKeys) addError(envelope, [key], message, "bridge_unreachable");
5066
+ this.#metric(auth ? "bridge_auth_failed" : "engine_bridge_unreachable_mutate", {
5067
+ ns,
5068
+ keys: bucketKeys,
5069
+ error: err.message
5070
+ });
5071
+ return;
5072
+ }
5073
+ this.#reportBridgeError(ns, bucketKeys, err);
5074
+ for (const key of bucketKeys) addError(envelope, [key], `bridge '${bridge.name}' request failed`, "bridge_error");
3699
5075
  }
3700
- validateLeaf(fieldName, def, where[fieldName], [...path, fieldName], capabilities, ctx);
3701
- if (def === METADATA_VIRTUAL_FIELDS.seq) assertSeqIntegers(where[fieldName], [...path, fieldName]);
3702
5076
  }
3703
- }
3704
- /** `seq` is a bigint column: every numeric operand must be a safe integer. */
3705
- function assertSeqIntegers(leaf, path) {
3706
- for (const [op, operand] of Object.entries(leaf)) for (const v of Array.isArray(operand) ? operand : [operand]) if (typeof v === "number" && !Number.isSafeInteger(v)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an integer for 'seq', got ${v}`, [...path, op]);
3707
- }
3708
- function validateOrderBy(orderBy, fields, capabilities) {
3709
- if (!capabilities.orderBy) throw new FilterValidationError("capability_unsupported", "dataset does not support orderBy", ["orderBy"]);
3710
- if (!Array.isArray(orderBy)) throw new FilterValidationError("type_mismatch", "orderBy must be an array of { field: \"asc\" | \"desc\" } entries", ["orderBy"]);
3711
- orderBy.forEach((clause, i) => {
3712
- if (clause === null || typeof clause !== "object" || Array.isArray(clause)) throw new FilterValidationError("type_mismatch", "each orderBy entry must be a { field: \"asc\" | \"desc\" } object", ["orderBy", String(i)]);
3713
- const entries = Object.entries(clause);
3714
- if (entries.length !== 1) throw new FilterValidationError("type_mismatch", "each orderBy entry must have exactly one field", ["orderBy", String(i)]);
3715
- const [fieldName, dir] = entries[0];
3716
- if (dir !== "asc" && dir !== "desc") throw new FilterValidationError("type_mismatch", `orderBy direction must be 'asc' or 'desc', got ${String(dir)}`, [
3717
- "orderBy",
3718
- String(i),
3719
- fieldName
3720
- ]);
3721
- if (fieldName === "id") return;
3722
- const def = lookupField(fields, fieldName);
3723
- if (!def) throw new FilterValidationError("unknown_field", `unknown field '${fieldName}' in orderBy${metadataHint(fieldName)}`, [
3724
- "orderBy",
3725
- String(i),
3726
- fieldName
3727
- ]);
3728
- if (def.kind !== "scalar") throw new FilterValidationError("orderby_nonscalar", `orderBy on non-scalar field '${fieldName}' is not supported (kind=${def.kind})`, [
3729
- "orderBy",
3730
- String(i),
3731
- fieldName
3732
- ]);
3733
- if (def.type === "json") throw new FilterValidationError("orderby_nonscalar", `orderBy on json field '${fieldName}' is not supported (opaque body)`, [
3734
- "orderBy",
3735
- String(i),
3736
- fieldName
3737
- ]);
3738
- });
3739
- }
3740
- function validateFilter(input) {
3741
- if (input.where !== void 0) validateWhereAgainstFields(input.where, input.typeSchema.fields, ["where"], input.capabilities, {});
3742
- if (input.orderBy !== void 0) validateOrderBy(input.orderBy, input.typeSchema.fields, input.capabilities);
3743
- }
5077
+ /** The peer's own wording can carry its URL or body, so it stays server-side. */
5078
+ #reportBridgeError(ns, keys, err) {
5079
+ this.#metric("engine_bridge_error", {
5080
+ ns,
5081
+ keys,
5082
+ error: err instanceof Error ? err.message : String(err)
5083
+ });
5084
+ }
5085
+ };
3744
5086
 
3745
5087
  //#endregion
3746
5088
  //#region ../../packages/substrate-core/src/engine/filter-guard.ts
@@ -3781,7 +5123,7 @@ function runFilterGuard(deps, input) {
3781
5123
  if (entry.fields !== void 0) {
3782
5124
  const typeSchema = deps.schemaFor(ns).types[name];
3783
5125
  if (typeSchema) {
3784
- const unknown = Object.keys(entry.fields).filter((f) => !(f in typeSchema.fields) && !PROJECTION_VIRTUAL_KEYS.has(f) && computedFieldOwner(f) === void 0);
5126
+ const unknown = Object.keys(entry.fields).filter((f) => !(f in typeSchema.fields) && !PROJECTION_VIRTUAL_KEYS.has(f) && computedFieldOwner(f) === void 0 && !isWalkSelection(f, entry.fields[f]));
3785
5127
  if (unknown.length > 0) {
3786
5128
  envelope._diagnostics ??= {};
3787
5129
  envelope._diagnostics[key] = { unknownProjectionFields: unknown };
@@ -3792,7 +5134,8 @@ function runFilterGuard(deps, input) {
3792
5134
  }
3793
5135
  }
3794
5136
  }
3795
- if (where !== void 0 || orderBy !== void 0) try {
5137
+ const walks = usesWalkGrammar(entry);
5138
+ if (where !== void 0 || orderBy !== void 0 || walks) try {
3796
5139
  let typeSchema = deps.schemaFor(ns).types[name];
3797
5140
  if (typeSchema === void 0) {
3798
5141
  deps.invalidateSchemaCaches(ns);
@@ -3808,12 +5151,19 @@ function runFilterGuard(deps, input) {
3808
5151
  ...envelope._diagnostics[key] ?? {},
3809
5152
  filterValidationSkipped: `type '${name}' is registered but absent from the '${ns}' schema`
3810
5153
  };
3811
- } else validateFilter({
3812
- ...where !== void 0 ? { where } : {},
3813
- ...orderBy !== void 0 ? { orderBy } : {},
3814
- typeSchema,
3815
- capabilities: dataset.capabilities
3816
- });
5154
+ } else {
5155
+ const types = deps.schemaFor(ns).types;
5156
+ validateFilter({
5157
+ ...where !== void 0 ? { where } : {},
5158
+ ...orderBy !== void 0 ? { orderBy } : {},
5159
+ ...walks ? walkInput(entry) : {},
5160
+ typeSchema,
5161
+ capabilities: dataset.capabilities,
5162
+ schemaOf: (type) => Object.hasOwn(types, type) ? types[type] : void 0,
5163
+ namespace: ns,
5164
+ typeName: name
5165
+ });
5166
+ }
3817
5167
  } catch (err) {
3818
5168
  if (err instanceof FilterValidationError) {
3819
5169
  addError(envelope, [key, ...err.path], err.message, err.code);
@@ -3828,6 +5178,22 @@ function runFilterGuard(deps, input) {
3828
5178
  }
3829
5179
  return true;
3830
5180
  }
5181
+ /** `_agg` and nested `{ _walk }` selections are walk grammar, not projected fields. */
5182
+ function isWalkSelection(name, sel) {
5183
+ return name === "_agg" || typeof sel === "object" && sel !== null && "_walk" in sel;
5184
+ }
5185
+ /** The walk-grammar params and field selection `validateFilter` checks. */
5186
+ function walkInput(entry) {
5187
+ const { count, aggregate, bucket, derive, cursor } = entry.params ?? {};
5188
+ return {
5189
+ count,
5190
+ aggregate,
5191
+ bucket,
5192
+ derive,
5193
+ cursor,
5194
+ ...entry.fields !== void 0 ? { fields: entry.fields } : {}
5195
+ };
5196
+ }
3831
5197
 
3832
5198
  //#endregion
3833
5199
  //#region ../../packages/substrate-core/src/engine/mutate.ts
@@ -3996,6 +5362,19 @@ function shapeResult(input) {
3996
5362
  return;
3997
5363
  }
3998
5364
  if (isReadResult(result)) {
5365
+ if (result.count !== void 0) {
5366
+ envelope.data[key] = { count: result.count };
5367
+ envelope.shapes[key] = "count";
5368
+ return;
5369
+ }
5370
+ if (result.groups !== void 0) {
5371
+ envelope.data[key] = {
5372
+ groups: result.groups,
5373
+ ...result.truncated === true ? { truncated: true } : {}
5374
+ };
5375
+ envelope.shapes[key] = "groups";
5376
+ return;
5377
+ }
3999
5378
  const filtered = applyObligations(decision, result.rows, ctx);
4000
5379
  envelope.data[key] = filtered;
4001
5380
  envelope.shapes[key] = "list";
@@ -4079,6 +5458,34 @@ function publishSchema(registry) {
4079
5458
  mutations
4080
5459
  };
4081
5460
  }
5461
+ /**
5462
+ * `schema` with each type's same-namespace inbound crossRefs added. Rides
5463
+ * beside the hash like annotations: `publishSchema` knows no namespace, and
5464
+ * an inbound ref is derived from fields the hash already covers.
5465
+ */
5466
+ function withInboundRefs(schema, ns) {
5467
+ const inbound = /* @__PURE__ */ new Map();
5468
+ for (const [type, t] of Object.entries(schema.types)) for (const [field, def] of Object.entries(t.fields)) {
5469
+ if (def.kind !== "crossRef" || def.ns !== ns) continue;
5470
+ inbound.set(def.type, [...inbound.get(def.type) ?? [], {
5471
+ type,
5472
+ field
5473
+ }]);
5474
+ }
5475
+ if (inbound.size === 0) return schema;
5476
+ const types = {};
5477
+ for (const [name, t] of Object.entries(schema.types)) {
5478
+ const refs = inbound.get(name);
5479
+ types[name] = refs === void 0 ? t : {
5480
+ ...t,
5481
+ inboundRefs: refs
5482
+ };
5483
+ }
5484
+ return {
5485
+ ...schema,
5486
+ types
5487
+ };
5488
+ }
4082
5489
 
4083
5490
  //#endregion
4084
5491
  //#region ../../packages/substrate-core/src/engine/schema.ts
@@ -4109,7 +5516,7 @@ var SchemaSubsystem = class {
4109
5516
  const epoch = cfg.registry.epoch;
4110
5517
  const cached = epoch === void 0 ? void 0 : this.#schemaCache.get(ns);
4111
5518
  if (cached !== void 0 && cached.epoch === epoch) return cached.schema;
4112
- const schema = publishSchema(cfg.registry);
5519
+ const schema = withInboundRefs(publishSchema(cfg.registry), ns);
4113
5520
  const withVirtual = cfg.virtual === true ? {
4114
5521
  ...schema,
4115
5522
  virtual: true
@@ -4420,6 +5827,11 @@ var StreamSubsystem = class {
4420
5827
  }
4421
5828
  if ((decision.obligations?.length ?? 0) > 0) delete args.fields;
4422
5829
  if (registryEntry.kind === "type") {
5830
+ const walkPath = walkGrammarPath(frame);
5831
+ if (walkPath !== null) {
5832
+ await emitError("walks are not available in streams", WALKS_IN_SUBSCRIPTION, [key, ...walkPath]);
5833
+ return;
5834
+ }
4423
5835
  const params = frame.params;
4424
5836
  const where = params?.where;
4425
5837
  const orderBy = params?.orderBy;
@@ -4937,6 +6349,19 @@ var SubscribeSubsystem = class {
4937
6349
  return null;
4938
6350
  }
4939
6351
  if ((decision.obligations?.length ?? 0) > 0) delete args.fields;
6352
+ const walkPath = walkGrammarPath(frame);
6353
+ if (walkPath !== null) {
6354
+ deliverFrame(input.onFrame, {
6355
+ id: input.id,
6356
+ kind: "error",
6357
+ errors: [{
6358
+ message: `subscribe('${ns}/${name}'): walks are not available in subscriptions`,
6359
+ code: WALKS_IN_SUBSCRIPTION,
6360
+ path: [key, ...walkPath]
6361
+ }]
6362
+ }, this.#metric);
6363
+ return null;
6364
+ }
4940
6365
  const params = frame.params;
4941
6366
  if (params) {
4942
6367
  for (const paramKey of Object.keys(params)) if (!KNOWN_SUBSCRIBE_PARAMS.has(paramKey)) {
@@ -5655,8 +7080,8 @@ var Engine = class {
5655
7080
  * caller's `probe` context so policies reading headers, `clientIp`, `meta`
5656
7081
  * or `authEnabled` decide as they would in dispatch.
5657
7082
  */
5658
- evaluateReadPolicy(ns, type, identity, probe) {
5659
- return this.#evaluateEntryPolicy(ns, type, identity, "query", probe);
7083
+ evaluateReadPolicy(ns, type, identity, probe, args) {
7084
+ return this.#evaluateEntryPolicy(ns, type, identity, "query", probe, void 0, args);
5660
7085
  }
5661
7086
  /**
5662
7087
  * Shared body of the two out-of-band policy probes. Mirrors #runEntry's
@@ -5664,7 +7089,7 @@ var Engine = class {
5664
7089
  * with a synthetic ctx. Fails closed throughout: an out-of-band surface must
5665
7090
  * never be MORE permissive than dispatch.
5666
7091
  */
5667
- #evaluateEntryPolicy(ns, type, identity, operation, probe, verb) {
7092
+ #evaluateEntryPolicy(ns, type, identity, operation, probe, verb, args) {
5668
7093
  if (this.#tombstoned.has(ns)) return {
5669
7094
  allow: false,
5670
7095
  reason: `namespace '${ns}' was deleted`
@@ -5696,7 +7121,7 @@ var Engine = class {
5696
7121
  entry: type,
5697
7122
  ...verb !== void 0 ? { verb } : {}
5698
7123
  };
5699
- return evaluatePolicy(entry.policy, ctx, {});
7124
+ return evaluatePolicy(entry.policy, ctx, args ?? {});
5700
7125
  }
5701
7126
  /**
5702
7127
  * Refresh the cached schemas for every registered bridge. Callers invoke
@@ -5952,11 +7377,21 @@ var Engine = class {
5952
7377
  * no `limit`, and is refused above the maximum. Virtual types own their
5953
7378
  * params, so they pass through untouched.
5954
7379
  */
5955
- #applyPageLimits(envelope, key, entry, parsed, limits) {
7380
+ #applyPageLimits(envelope, key, input, parsed, limits) {
7381
+ let entry = input;
5956
7382
  if (limits === void 0 || parsed === null) return entry;
5957
7383
  const nsCfg = this.#namespaces.get(parsed.ns);
5958
7384
  if (nsCfg === void 0 || nsCfg.virtual === true) return entry;
5959
7385
  if (nsCfg.registry.get(parsed.name)?.kind !== "type") return entry;
7386
+ const nested = nestedOverLimit(entry.fields, ["fields"], limits.maxLimit);
7387
+ if (nested !== null) {
7388
+ addError(envelope, [key, ...nested], `nested limit exceeds the maximum page of ${limits.maxLimit}`, "limit_exceeds_max", { max: limits.maxLimit });
7389
+ return null;
7390
+ }
7391
+ if (entry.fields !== void 0) entry = {
7392
+ ...entry,
7393
+ fields: withNestedDefaultLimits(entry.fields, limits.defaultLimit)
7394
+ };
5960
7395
  const limit = entry.params?.limit;
5961
7396
  if (limit === void 0 || limit === null) return {
5962
7397
  ...entry,
@@ -6123,6 +7558,105 @@ var Engine = class {
6123
7558
  });
6124
7559
  return refused;
6125
7560
  }
7561
+ /** Far-type resolution for the metadata rewrite; a hop that does not resolve is left to the validator. */
7562
+ #metadataHop(ns, from) {
7563
+ const types = this.schemaFor(ns).types;
7564
+ const schemaOf = (t) => Object.hasOwn(types, t) ? types[t] : void 0;
7565
+ const resolve = hopResolver(ns, schemaOf);
7566
+ const hopFrom = (type) => (node) => {
7567
+ let far;
7568
+ try {
7569
+ far = resolve(node, type, []);
7570
+ } catch {
7571
+ return;
7572
+ }
7573
+ const fields = schemaOf(far)?.fields;
7574
+ return fields !== void 0 ? {
7575
+ fields,
7576
+ hop: hopFrom(far)
7577
+ } : void 0;
7578
+ };
7579
+ return hopFrom(from);
7580
+ }
7581
+ /** The walk sites of a walk-grammar query frame, or undefined for an ordinary one. */
7582
+ #walkSitesOf(frame, ns, seed) {
7583
+ if (!usesWalkGrammar(frame)) return void 0;
7584
+ const types = this.schemaFor(ns).types;
7585
+ const schemaOf = (t) => Object.hasOwn(types, t) ? types[t] : void 0;
7586
+ const resolve = hopResolver(ns, schemaOf);
7587
+ try {
7588
+ return {
7589
+ sites: walkSites(frame, seed, resolve),
7590
+ resolve,
7591
+ fieldsOf: (t) => schemaOf(t)?.fields
7592
+ };
7593
+ } catch {
7594
+ return;
7595
+ }
7596
+ }
7597
+ /**
7598
+ * The frame's clauses marked index-served (goal 7), from the store's index
7599
+ * plans. Undefined when the store has none (memory) or any type's plan is
7600
+ * unknown: a plan that cannot be judged is omitted, never guessed.
7601
+ */
7602
+ async #walkPlan(dataset, key, frame, ns, seed, scan) {
7603
+ if (dataset.indexPlan === void 0) return void 0;
7604
+ const types = [.../* @__PURE__ */ new Set([seed, ...scan.sites.map((s) => s.far)])];
7605
+ let plans;
7606
+ try {
7607
+ plans = await Promise.all(types.map((t) => dataset.indexPlan?.(t, ns)));
7608
+ } catch (err) {
7609
+ this.#metric("engine_walk_plan_failed", {
7610
+ key,
7611
+ error: err instanceof Error ? err.message : String(err)
7612
+ });
7613
+ return;
7614
+ }
7615
+ if (plans.some((p) => p === void 0)) return void 0;
7616
+ const byType = new Map(types.map((t, i) => [t, plans[i]?.indexes ?? []]));
7617
+ return classifyWalkService({
7618
+ entry: frame,
7619
+ seed,
7620
+ resolve: scan.resolve,
7621
+ fieldsOf: scan.fieldsOf
7622
+ }, (t) => byType.get(t) ?? []);
7623
+ }
7624
+ /**
7625
+ * Fail-closed policy for walk grammar (spec §2, §3). A walk is a read of
7626
+ * every type it touches: each walked, aggregated or nested type's read
7627
+ * policy runs with the walk's own `where`, and a deny refuses the frame. Any
7628
+ * obligation, on a walked type or on the seed, is refused too: obligations
7629
+ * filter rows after the read, which cannot reach rows a walk counted,
7630
+ * aggregated or joined. Records the error and returns true on refusal.
7631
+ */
7632
+ #refuseWalkPolicy(envelope, key, frame, ns, seed, ctx, decision) {
7633
+ const seedPath = walkGrammarPath(frame);
7634
+ if (seedPath === null) return false;
7635
+ const blocked = (d) => (d.obligations?.length ?? 0) > 0;
7636
+ const refuse = (path, message, code) => {
7637
+ addError(envelope, [key, ...path], message, code);
7638
+ this.#metric("engine_walk_policy_refused", {
7639
+ key,
7640
+ code,
7641
+ path
7642
+ });
7643
+ return true;
7644
+ };
7645
+ if (blocked(decision)) return refuse(seedPath, `'${ns}/${seed}' is row-filtered for this caller, so it cannot be walked from, counted or aggregated`, ROW_POLICY_BLOCKS_WALK);
7646
+ const types = this.schemaFor(ns).types;
7647
+ let walked;
7648
+ try {
7649
+ walked = walkedTypes(frame, seed, hopResolver(ns, (t) => Object.hasOwn(types, t) ? types[t] : void 0));
7650
+ } catch {
7651
+ return refuse(seedPath, "a walk in this frame does not resolve", "policy_denied");
7652
+ }
7653
+ for (const w of walked) {
7654
+ const d = this.evaluateReadPolicy(ns, w.type, ctx.identity ?? null, ctx, { params: w.where !== void 0 && w.unfiltered !== true ? { where: w.where } : {} });
7655
+ if (!d.allow) return refuse(w.path, d.reason ?? "policy denied", "policy_denied");
7656
+ if (blocked(d)) return refuse(w.path, `'${ns}/${w.type}' is row-filtered for this caller, so a walk cannot read it`, ROW_POLICY_BLOCKS_WALK);
7657
+ }
7658
+ return false;
7659
+ }
6126
7660
  async #runEntryInner(envelope, key, entry, ctxBase, operation, tx, txEdges, parsed, onWrite, signal, afterTx, txEntries) {
6127
7661
  if (!parsed) {
6128
7662
  addError(envelope, [key], `unqualified frame key '${key}' — expected '<ns>/<name>'`, "unqualified_key");
@@ -6161,7 +7695,7 @@ var Engine = class {
6161
7695
  });
6162
7696
  return false;
6163
7697
  }
6164
- const frame = operation === "query" && registryEntry.kind === "type" ? withCanonicalMetadataFilters(entry, registryEntry.fields) : entry;
7698
+ const frame = operation === "query" && registryEntry.kind === "type" ? withCanonicalMetadataFilters(entry, registryEntry.fields, usesWalkGrammar(entry) ? this.#metadataHop(ns, name) : void 0) : entry;
6165
7699
  const ctx = {
6166
7700
  ...ctxBase,
6167
7701
  namespace: ns,
@@ -6180,6 +7714,26 @@ var Engine = class {
6180
7714
  return false;
6181
7715
  }
6182
7716
  if ((decision.obligations?.length ?? 0) > 0) delete args.fields;
7717
+ if (operation === "mutate") {
7718
+ const walkPath = walkGrammarPath({ fields: frame.fields });
7719
+ if (walkPath) {
7720
+ addError(envelope, [key, ...walkPath], "walks are not available in a mutation", WALKS_IN_MUTATION);
7721
+ return false;
7722
+ }
7723
+ } else if (isVirtual) {
7724
+ const walkPath = walkGrammarPath(frame);
7725
+ if (walkPath) {
7726
+ addError(envelope, [key, ...walkPath], "walks are not available on virtual types", WALK_UNSUPPORTED_REF);
7727
+ return false;
7728
+ }
7729
+ }
7730
+ if (operation === "query" && registryEntry.kind === "type" && !isVirtual && dataset?.capabilities.walks !== true) {
7731
+ const walkPath = walkGrammarPath(frame);
7732
+ if (walkPath) {
7733
+ addError(envelope, [key, ...walkPath], `the '${ns}' store does not answer walks`, WALKS_UNSUPPORTED_STORE);
7734
+ return false;
7735
+ }
7736
+ }
6183
7737
  if (!runFilterGuard({
6184
7738
  schemaFor: (ns) => this.schemaFor(ns),
6185
7739
  invalidateSchemaCaches: (ns) => this.invalidateSchemaCaches(ns),
@@ -6195,6 +7749,7 @@ var Engine = class {
6195
7749
  isVirtual,
6196
7750
  dataset
6197
7751
  })) return false;
7752
+ if (operation === "query" && registryEntry.kind === "type" && this.#refuseWalkPolicy(envelope, key, frame, ns, name, ctx, decision)) return false;
6198
7753
  if (operation === "query" && !isVirtual) {
6199
7754
  const params = withNaturalOrder(args.params, registryEntry, dataset);
6200
7755
  if (params !== void 0) args.params = params;
@@ -6211,6 +7766,7 @@ var Engine = class {
6211
7766
  cursor: opened
6212
7767
  };
6213
7768
  }
7769
+ const walkScan = operation === "query" && registryEntry.kind === "type" && !isVirtual ? this.#walkSitesOf(frame, ns, name) : void 0;
6214
7770
  let result;
6215
7771
  const t0 = performance.now();
6216
7772
  try {
@@ -6234,7 +7790,21 @@ var Engine = class {
6234
7790
  }
6235
7791
  throw err;
6236
7792
  } finally {
6237
- if (operation === "query" && registryEntry.kind === "type" && !isVirtual && args.params?.id === void 0) this.#shapeRecorder?.observe(readShapeOf(ns, name, registryEntry.fields, args.params?.where, args.params?.orderBy), performance.now() - t0);
7793
+ if (operation === "query" && registryEntry.kind === "type" && !isVirtual && args.params?.id === void 0) {
7794
+ const ms = performance.now() - t0;
7795
+ this.#shapeRecorder?.observe(readShapeOf(ns, name, registryEntry.fields, args.params?.where, args.params?.orderBy), ms);
7796
+ if (walkScan !== void 0 && this.#shapeRecorder !== void 0) for (const s of walkShapesOf(ns, walkScan.sites, walkScan.fieldsOf)) this.#shapeRecorder.observe(s, ms);
7797
+ }
7798
+ }
7799
+ if (walkScan !== void 0 && dataset !== void 0) {
7800
+ const plan = await this.#walkPlan(dataset, key, frame, ns, name, walkScan);
7801
+ if (plan !== void 0) {
7802
+ envelope._diagnostics ??= {};
7803
+ envelope._diagnostics[key] = {
7804
+ ...envelope._diagnostics[key] ?? {},
7805
+ plan
7806
+ };
7807
+ }
6238
7808
  }
6239
7809
  shapeResult({
6240
7810
  envelope,
@@ -6401,7 +7971,7 @@ var Engine = class {
6401
7971
  const entry = {};
6402
7972
  if (key in scratch.data) entry.data = scratch.data[key];
6403
7973
  const shape = scratch.shapes[key];
6404
- if (typeof shape === "string") entry.shape = shape;
7974
+ if (shape === "single" || shape === "list") entry.shape = shape;
6405
7975
  if (scratch.errors !== void 0 && scratch.errors.length > 0) {
6406
7976
  entry.errors = scratch.errors;
6407
7977
  scratchResults[i] = entry;
@@ -6506,6 +8076,41 @@ var Engine = class {
6506
8076
  return this.#stream.stream(input);
6507
8077
  }
6508
8078
  };
8079
+ /** `fields` with every nested `{ _walk }` selection lacking a `limit` given `limit`, at any depth. */
8080
+ function withNestedDefaultLimits(fields, limit) {
8081
+ if (typeof fields !== "object" || fields === null || Array.isArray(fields)) return fields;
8082
+ return Object.fromEntries(Object.entries(fields).map(([name, sel]) => {
8083
+ if (name === "_agg" || typeof sel !== "object" || sel === null || Array.isArray(sel)) return [name, sel];
8084
+ const s = sel;
8085
+ if (!Object.hasOwn(s, "_walk")) return [name, withNestedDefaultLimits(s, limit)];
8086
+ return [name, {
8087
+ ...s,
8088
+ ...Object.hasOwn(s, "fields") ? { fields: withNestedDefaultLimits(s.fields, limit) } : {},
8089
+ ...s.limit === void 0 || s.limit === null ? { limit } : {}
8090
+ }];
8091
+ }));
8092
+ }
8093
+ /** Path to the first nested `{ _walk }` selection whose numeric `limit` exceeds `max`, at any depth. */
8094
+ function nestedOverLimit(fields, path, max) {
8095
+ if (typeof fields !== "object" || fields === null) return null;
8096
+ for (const [name, sel] of Object.entries(fields)) {
8097
+ if (name === "_agg" || typeof sel !== "object" || sel === null) continue;
8098
+ const s = sel;
8099
+ const walk = Object.hasOwn(s, "_walk");
8100
+ if (walk && typeof s.limit === "number" && s.limit > max) return [
8101
+ ...path,
8102
+ name,
8103
+ "limit"
8104
+ ];
8105
+ const deeper = walk ? nestedOverLimit(s.fields, [
8106
+ ...path,
8107
+ name,
8108
+ "fields"
8109
+ ], max) : nestedOverLimit(s, [...path, name], max);
8110
+ if (deeper !== null) return deeper;
8111
+ }
8112
+ return null;
8113
+ }
6509
8114
 
6510
8115
  //#endregion
6511
8116
  //#region ../../packages/substrate-core/src/load-plugins.ts
@@ -7405,7 +9010,25 @@ function dropUndefinedParams(params) {
7405
9010
  return Object.fromEntries(Object.entries(params).filter(([, v]) => v !== void 0));
7406
9011
  }
7407
9012
  /**
7408
- * Refuse an explicit `null` on a non-nullable scalar, on create and update
9013
+ * Whether a crossRef may be absent or null: as it says, or, when it says
9014
+ * nothing, only when its `onDelete` is `set_null` (deleting the target nulls it).
9015
+ */
9016
+ function isNullableCrossRef(def) {
9017
+ return def.nullable ?? def.onDelete === "set_null";
9018
+ }
9019
+ /**
9020
+ * Refuse a crossRef that is non-nullable but `onDelete: 'set_null'`: deleting
9021
+ * its target would null a field the type says cannot be null. Install-time.
9022
+ *
9023
+ * Throws a plain `Error` naming the type and every offending field.
9024
+ */
9025
+ function assertCrossRefDeletePolicies(typeName, fieldDefs) {
9026
+ const bad = Object.entries(fieldDefs).filter(([, def]) => def.kind === "crossRef" && def.onDelete === "set_null" && def.nullable === false).map(([name]) => `'${name}'`);
9027
+ if (bad.length === 0) return;
9028
+ throw new Error(`type '${typeName}': crossRef field(s) ${bad.join(", ")} are nullable: false but onDelete: 'set_null', which would null them when the target is deleted. Use onDelete 'cascade' or 'restrict', or make them nullable.`);
9029
+ }
9030
+ /**
9031
+ * Refuse an explicit `null` on a non-nullable scalar or crossRef, on create and update
7409
9032
  * alike. Presence is not completeness: a null passes `assertRequiredFields`'
7410
9033
  * key check and would store a row the type says cannot exist. A
7411
9034
  * `default` does not excuse it — the default fills an OMITTED key, and a
@@ -7414,7 +9037,8 @@ function dropUndefinedParams(params) {
7414
9037
  function assertNoNullOnNonNullable(params, fieldDefs, phase) {
7415
9038
  const offending = [];
7416
9039
  for (const [name, def] of Object.entries(fieldDefs)) {
7417
- if (name === "id" || def.kind !== "scalar" || def.nullable === true) continue;
9040
+ if (name === "id") continue;
9041
+ if (def.kind === "crossRef" ? isNullableCrossRef(def) : def.kind !== "scalar" || def.nullable === true) continue;
7418
9042
  if (Object.hasOwn(params, name) && params[name] === null) offending.push(name);
7419
9043
  }
7420
9044
  if (offending.length === 0) return;
@@ -7468,10 +9092,11 @@ function applyScalarDefaults(params, fieldDefs) {
7468
9092
  * `{id}`-only rows this guard exists to prevent).
7469
9093
  *
7470
9094
  * Run AFTER applyScalarDefaults so a defaulted field counts as supplied.
7471
- * Scoped to scalars: struct / list / crossRef required-ness is a separate
7472
- * concern (crossRefs are nullable-by-policy via onDelete). readonly fields
7473
- * (engine-allocated, e.g. shortId) and create-gated serverSet date fields
7474
- * (which clients may not supply) are exempt. Create-only.
9095
+ * Covers scalars and crossRefs (a crossRef is required when
9096
+ * `isNullableCrossRef` says it is not nullable); struct and list fields are
9097
+ * not checked. readonly fields (engine-allocated, e.g. shortId) and
9098
+ * create-gated serverSet date fields (which clients may not supply) are
9099
+ * exempt. Create-only.
7475
9100
  *
7476
9101
  * Throws `ResolverFrameError('missing_required_field', ...)` naming EVERY
7477
9102
  * missing field, not just the first, so one malformed create costs one
@@ -7482,6 +9107,10 @@ function assertRequiredFields(params, fieldDefs) {
7482
9107
  const missing = [];
7483
9108
  for (const [name, def] of Object.entries(fieldDefs)) {
7484
9109
  if (name === "id") continue;
9110
+ if (def.kind === "crossRef") {
9111
+ if (!isNullableCrossRef(def) && !Object.hasOwn(params, name)) missing.push(name);
9112
+ continue;
9113
+ }
7485
9114
  if (def.kind !== "scalar") continue;
7486
9115
  if (def.nullable === true || def.default !== void 0 || def.readonly === true) continue;
7487
9116
  if (def.type === "date" && (def.serverSet === "create" || def.serverSet === "both")) continue;
@@ -7688,7 +9317,11 @@ const KNOWN_LIST_PARAMS = /* @__PURE__ */ new Set([
7688
9317
  "limit",
7689
9318
  "cursor",
7690
9319
  "includeDeleted",
7691
- "_allowTableScan"
9320
+ "_allowTableScan",
9321
+ "count",
9322
+ "aggregate",
9323
+ "bucket",
9324
+ "derive"
7692
9325
  ]);
7693
9326
  function extractLimit(params) {
7694
9327
  if (!params) return void 0;
@@ -7714,8 +9347,22 @@ function listResolver(typeName, dataset, options = {}) {
7714
9347
  if (orderBy !== void 0) readParams.orderBy = orderBy;
7715
9348
  if (typeof cursor === "string") readParams.cursor = cursor;
7716
9349
  if (includeDeleted === true) readParams.includeDeleted = true;
9350
+ const p = args.params ?? {};
9351
+ if (p.count !== void 0) readParams.count = p.count;
9352
+ if (p.aggregate !== void 0) readParams.aggregate = p.aggregate;
9353
+ if (p.bucket !== void 0) readParams.bucket = p.bucket;
9354
+ if (p.derive !== void 0) readParams.derive = p.derive;
7717
9355
  const fields = args.fields;
7718
- if (fields !== void 0) readParams.fields = fields;
9356
+ if (fields !== void 0) {
9357
+ const entries = Object.entries(fields);
9358
+ const isNested = (v) => typeof v === "object" && v !== null && "_walk" in v;
9359
+ const agg = fields._agg;
9360
+ if (agg !== void 0) readParams.agg = agg;
9361
+ const nested = entries.filter(([, v]) => isNested(v));
9362
+ if (nested.length > 0) readParams.nested = Object.fromEntries(nested);
9363
+ readParams.fields = agg !== void 0 || nested.length > 0 ? Object.fromEntries(entries.filter(([k, v]) => k !== "_agg" && !isNested(v))) : fields;
9364
+ }
9365
+ if (args.signal !== void 0) readParams.signal = args.signal;
7719
9366
  return ds.read(typeName, readParams);
7720
9367
  };
7721
9368
  }
@@ -8106,6 +9753,7 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
8106
9753
  const postWrite = options.postWrite;
8107
9754
  if (fields !== void 0) {
8108
9755
  assertServerSetFieldsFillable(typeName, fields);
9756
+ assertCrossRefDeletePolicies(typeName, fields);
8109
9757
  assertVocabImplications(typeName, fields);
8110
9758
  }
8111
9759
  const list = listResolver(typeName, dataset, fields !== void 0 ? { fields } : {});
@@ -8483,6 +10131,7 @@ function defineNamespace(namespace, types, opts = {}) {
8483
10131
  if (typeInput.autoCrud === false) continue;
8484
10132
  for (const reserved of RESERVED_AUTOCRUD_FIELD_NAMES) if (Object.hasOwn(typeInput.fields, reserved)) throw new Error(`\`${reserved}\` is a reserved field name, auto-injected by the engine (type: ${typeName})`);
8485
10133
  assertServerSetFieldsFillable(typeName, typeInput.fields);
10134
+ assertCrossRefDeletePolicies(typeName, typeInput.fields);
8486
10135
  }
8487
10136
  for (const [typeName, typeInput] of Object.entries(types)) {
8488
10137
  for (const decl of typeInput.indexes ?? []) assertIndexDecl(typeName, typeInput.fields, decl);
@@ -11259,13 +12908,11 @@ var MemoryDataset = class MemoryDataset {
11259
12908
  txScopeId;
11260
12909
  #fieldDefLookup;
11261
12910
  typeDefLookup;
12911
+ walkBudget;
12912
+ walkReference;
11262
12913
  /** Last seq assigned per visible-order type; never decreases, as pg's `visible_seqs`. */
11263
12914
  seqs = /* @__PURE__ */ new Map();
11264
- capabilities = {
11265
- operators: fullBuiltinOperators(),
11266
- orderBy: true,
11267
- cursor: true
11268
- };
12915
+ capabilities;
11269
12916
  #advisoryLocks = createKeyedMutex();
11270
12917
  /** See `Dataset.withAdvisoryLock`. Excludes holders on this instance. */
11271
12918
  withAdvisoryLock(key, fn) {
@@ -11281,6 +12928,14 @@ var MemoryDataset = class MemoryDataset {
11281
12928
  this.txScopeId = options.txScopeId ?? `mem:${randomUUID()}`;
11282
12929
  this.#fieldDefLookup = options.fieldDefLookup;
11283
12930
  this.typeDefLookup = options.typeDefLookup;
12931
+ this.walkBudget = options.walkBudget ?? 1e6;
12932
+ this.walkReference = options.walkReference === true;
12933
+ this.capabilities = {
12934
+ operators: fullBuiltinOperators(),
12935
+ orderBy: true,
12936
+ cursor: true,
12937
+ walks: this.walkReference
12938
+ };
11284
12939
  }
11285
12940
  bucket(type) {
11286
12941
  let b = this.store.get(type);
@@ -11292,11 +12947,12 @@ var MemoryDataset = class MemoryDataset {
11292
12947
  }
11293
12948
  async read(type, params) {
11294
12949
  if (params.where !== void 0) assertWhereHonourable(params.where);
11295
- const b = this.store.get(type);
11296
- if (!b) return {
12950
+ const stored = this.store.get(type);
12951
+ if (!stored && params.count !== true && params.aggregate === void 0) return {
11297
12952
  rows: [],
11298
12953
  hasMore: false
11299
12954
  };
12955
+ const b = stored ?? /* @__PURE__ */ new Map();
11300
12956
  const includeDeleted = params.includeDeleted === true;
11301
12957
  const lookup = this.#fieldDefLookup;
11302
12958
  const fieldDefOf = (field) => lookup?.(type, field);
@@ -11323,7 +12979,28 @@ var MemoryDataset = class MemoryDataset {
11323
12979
  resolvedWhere = detailed.where;
11324
12980
  extMeta = detailed.meta;
11325
12981
  }
11326
- const pool = [];
12982
+ let pool = [];
12983
+ const walk = this.walkContext(type);
12984
+ const frameAggs = params.agg;
12985
+ const aggCache = /* @__PURE__ */ new Map();
12986
+ const ctxFor = (row) => {
12987
+ const ctx = {
12988
+ ...walk,
12989
+ seed: row,
12990
+ aggValue: (name) => {
12991
+ const spec = frameAggs !== void 0 && Object.hasOwn(frameAggs, name) ? frameAggs[name] : void 0;
12992
+ if (spec === void 0) throw new Error(`internal: '_agg.${name}' names no frame _agg`);
12993
+ let memo = aggCache.get(row);
12994
+ if (memo === void 0) {
12995
+ memo = /* @__PURE__ */ new Map();
12996
+ aggCache.set(row, memo);
12997
+ }
12998
+ if (!memo.has(name)) memo.set(name, computeAgg(row, spec, ctx));
12999
+ return memo.get(name);
13000
+ }
13001
+ };
13002
+ return ctx;
13003
+ };
11327
13004
  const candidates = hasIdFilter ? (function* () {
11328
13005
  for (const id of idFilter) {
11329
13006
  const row = b.get(id);
@@ -11332,9 +13009,40 @@ var MemoryDataset = class MemoryDataset {
11332
13009
  })() : b.values();
11333
13010
  for (const row of candidates) {
11334
13011
  if (!includeDeleted && row._deletedAt != null) continue;
11335
- if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere, fieldDefOf)) continue;
13012
+ if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere, fieldDefOf, ctxFor(row))) continue;
11336
13013
  pool.push(row);
11337
13014
  }
13015
+ if (params.count === true) return {
13016
+ rows: [],
13017
+ hasMore: false,
13018
+ count: pool.length
13019
+ };
13020
+ if (params.aggregate !== void 0) return aggregateGroups(pool, params.aggregate, params.bucket, limit, fieldDefOf);
13021
+ const original = /* @__PURE__ */ new Map();
13022
+ const derive = params.derive;
13023
+ if (derive !== void 0) pool = pool.map((row) => {
13024
+ const ctx = ctxFor(row);
13025
+ const operand = (ref) => {
13026
+ const v = ref.startsWith("_agg.") ? ctx.aggValue?.(ref.slice(5)) : getFieldValue(row, ref.slice(2));
13027
+ return typeof v === "number" ? v : null;
13028
+ };
13029
+ const values = Object.entries(derive).map(([name, spec]) => {
13030
+ const [op, [a, b]] = Object.entries(spec)[0];
13031
+ const x = operand(a);
13032
+ const y = operand(b);
13033
+ if (x === null || y === null || op === "ratio" && y === 0) return [`$${name}`, null];
13034
+ const v = op === "diff" ? x - y : x / y;
13035
+ const exactZero = op === "diff" ? x === y : x === 0;
13036
+ const m = Math.abs(v);
13037
+ return [`$${name}`, m <= 1e300 && (m >= 1e-300 || exactZero) ? v : null];
13038
+ });
13039
+ const copy = {
13040
+ ...row,
13041
+ ...Object.fromEntries(values)
13042
+ };
13043
+ original.set(copy, row);
13044
+ return copy;
13045
+ });
11338
13046
  const orderBy = normalizeOrderBy(params.orderBy);
11339
13047
  pool.sort((a, b2) => compareByClauses(a, b2, orderBy, fieldDefOf));
11340
13048
  let startIdx = 0;
@@ -11356,18 +13064,59 @@ var MemoryDataset = class MemoryDataset {
11356
13064
  rows: slice,
11357
13065
  hasMore
11358
13066
  };
13067
+ const page = (rows) => {
13068
+ const base = original.size === 0 ? rows : rows.map((r) => original.get(r) ?? r);
13069
+ if (params.agg === void 0 && params.nested === void 0) return base;
13070
+ return base.map((r) => ({
13071
+ ...r,
13072
+ ...walkProjection(r, params.agg, params.nested ?? {}, ctxFor(r), true)
13073
+ }));
13074
+ };
11359
13075
  const last = slice[slice.length - 1];
11360
13076
  if (hasMore && last !== void 0) out.nextCursor = encodeCursor({
11361
13077
  orderByValues: orderBy.map(([field]) => getFieldValue(last, field)),
11362
13078
  id: last.id,
11363
13079
  order: orderBy
11364
13080
  });
13081
+ out.rows = page(slice);
11365
13082
  if (extMeta !== null) out.rows = applyExtensionResultMeta(out.rows, extMeta, {
11366
13083
  hasExplicitOrderBy: params.orderBy !== void 0 && params.orderBy.length > 0,
11367
13084
  fields: params.fields
11368
13085
  });
11369
13086
  return out;
11370
13087
  }
13088
+ /**
13089
+ * Walks over this namespace's live rows, for one read. Neighbours follow the
13090
+ * row body's crossRef value (spec 2026-10-24-typed-edge-walks §1), indexed
13091
+ * per (type, field) on first use.
13092
+ */
13093
+ walkContext(type) {
13094
+ const lookup = this.#fieldDefLookup;
13095
+ const index = /* @__PURE__ */ new Map();
13096
+ const live = (r) => r === void 0 || r._deletedAt != null ? void 0 : r;
13097
+ return {
13098
+ type,
13099
+ bindings: /* @__PURE__ */ new Map(),
13100
+ budget: { left: this.walkBudget },
13101
+ fieldDefOf: (t) => (field) => lookup?.(t, field),
13102
+ get: (t, id) => live(this.store.get(t)?.get(id)),
13103
+ neighbours: (t, field, id) => {
13104
+ const key = `${t}\0${field}`;
13105
+ let byValue = index.get(key);
13106
+ if (byValue === void 0) {
13107
+ byValue = /* @__PURE__ */ new Map();
13108
+ for (const r of this.store.get(t)?.values() ?? []) {
13109
+ if (r._deletedAt != null || !Object.hasOwn(r, field)) continue;
13110
+ const list = byValue.get(r[field]);
13111
+ if (list === void 0) byValue.set(r[field], [r]);
13112
+ else list.push(r);
13113
+ }
13114
+ index.set(key, byValue);
13115
+ }
13116
+ return byValue.get(id) ?? [];
13117
+ }
13118
+ };
13119
+ }
11371
13120
  async write(type, rows, options) {
11372
13121
  if (options?.insertOnly !== true) assertNoRepeatedIds(type, rows);
11373
13122
  const b = this.bucket(type);
@@ -11635,6 +13384,8 @@ var MemoryDataset = class MemoryDataset {
11635
13384
  forNamespace(namespace) {
11636
13385
  return new MemoryDataset({
11637
13386
  namespace,
13387
+ walkBudget: this.walkBudget,
13388
+ walkReference: this.walkReference,
11638
13389
  ...this.#fieldDefLookup !== void 0 ? { fieldDefLookup: this.#fieldDefLookup } : {},
11639
13390
  ...this.typeDefLookup !== void 0 ? { typeDefLookup: this.typeDefLookup } : {}
11640
13391
  });
@@ -11655,6 +13406,78 @@ function conditionalMatchEq(actual, expected) {
11655
13406
  }
11656
13407
  return actual === expected;
11657
13408
  }
13409
+ /**
13410
+ * A whole-result aggregate: one group, or one per UTC day/hour bucket in
13411
+ * ascending order. A row whose bucket field is null or not a date is in no
13412
+ * bucket. Groups beyond `limit` are cut and say `truncated`.
13413
+ */
13414
+ function aggregateGroups(pool, aggregate, bucket, limit, fieldDefOf) {
13415
+ const values = (rows) => Object.fromEntries(Object.entries(aggregate).map(([name, fn]) => [name, applyAgg(rows, fn, fieldDefOf)]));
13416
+ if (bucket === void 0) return {
13417
+ rows: [],
13418
+ hasMore: false,
13419
+ groups: [values(pool)]
13420
+ };
13421
+ const byKey = /* @__PURE__ */ new Map();
13422
+ for (const row of pool) {
13423
+ const micros = storedMicros(getFieldValue(row, bucket.field));
13424
+ if (micros === void 0) continue;
13425
+ const ms = Number((micros - (micros % 1000n + 1000n) % 1000n) / 1000n);
13426
+ const key = new Date(ms).toISOString().slice(0, bucket.by === "day" ? 10 : 13);
13427
+ const list = byKey.get(key);
13428
+ if (list === void 0) byKey.set(key, [row]);
13429
+ else list.push(row);
13430
+ }
13431
+ const keys = [...byKey.keys()].sort();
13432
+ const truncated = limit !== void 0 && keys.length > limit;
13433
+ return {
13434
+ rows: [],
13435
+ hasMore: false,
13436
+ groups: (truncated ? keys.slice(0, limit) : keys).map((key) => ({
13437
+ bucket: key,
13438
+ ...values(byKey.get(key) ?? [])
13439
+ })),
13440
+ ...truncated ? { truncated: true } : {}
13441
+ };
13442
+ }
13443
+ /**
13444
+ * A row's walk selections: `_agg` values and nested lists, each list
13445
+ * filtered, ordered (id ascending last) and cut to its limit, with
13446
+ * `_truncated` naming the lists that were cut. Nested rows carry `id`, their
13447
+ * selected fields (null when absent) and their own walk selections.
13448
+ */
13449
+ function walkProjection(row, aggs, nested, ctx, top = false) {
13450
+ const out = [];
13451
+ if (aggs !== void 0) out.push(["_agg", Object.fromEntries(Object.entries(aggs).map(([name, spec]) => [name, top && ctx.aggValue !== void 0 ? ctx.aggValue(name) : computeAgg(row, spec, ctx)]))]);
13452
+ const truncated = [];
13453
+ for (const [name, sel] of Object.entries(nested)) {
13454
+ const { type, rows } = hop(row, sel._walk, ctx);
13455
+ const fieldDefOf = ctx.fieldDefOf(type);
13456
+ const far = {
13457
+ ...ctx,
13458
+ type
13459
+ };
13460
+ const keep = (n) => [sel._walk.where, sel.where].every((w) => w === void 0 || evaluateWhere(n, w, fieldDefOf, far));
13461
+ const order = normalizeOrderBy(sel.orderBy);
13462
+ let list = rows.filter(keep).sort((a, b) => compareByClauses(a, b, order, fieldDefOf));
13463
+ if (sel.limit !== void 0 && list.length > sel.limit) {
13464
+ list = list.slice(0, sel.limit);
13465
+ truncated.push([name, true]);
13466
+ }
13467
+ const fields = sel.fields;
13468
+ const isNested = (v) => typeof v === "object" && v !== null && Object.hasOwn(v, "_walk");
13469
+ const subAggs = Object.hasOwn(fields, "_agg") ? fields._agg : void 0;
13470
+ const subNested = Object.fromEntries(Object.entries(fields).filter(([, v]) => isNested(v)));
13471
+ const plain = Object.keys(fields).filter((k) => k !== "_agg" && !isNested(fields[k]));
13472
+ out.push([name, list.map((n) => ({
13473
+ id: n.id,
13474
+ ...Object.fromEntries(plain.map((k) => [k, Object.hasOwn(n, k) ? n[k] : null])),
13475
+ ...walkProjection(n, subAggs, subNested, far, false)
13476
+ }))]);
13477
+ }
13478
+ if (truncated.length > 0) out.push(["_truncated", Object.fromEntries(truncated)]);
13479
+ return Object.fromEntries(out);
13480
+ }
11658
13481
  function normalizeOrderBy(orderBy) {
11659
13482
  const out = [];
11660
13483
  let hasIdTail = false;
@@ -12551,6 +14374,7 @@ function healthRoute(deps) {
12551
14374
  return async () => jsonResponse(200, {
12552
14375
  status: "ok",
12553
14376
  version: deps.version,
14377
+ walks: true,
12554
14378
  uptimeSeconds: Math.floor((Date.now() - deps.startedAt) / 1e3)
12555
14379
  });
12556
14380
  }
@@ -13088,11 +14912,17 @@ function schemaForTypeRoute(engine) {
13088
14912
  ...base,
13089
14913
  storage
13090
14914
  };
13091
- return jsonResponse(200, shape === "fields" ? {
14915
+ const plan = await engine.datasetFor(ns)?.indexPlan?.(type, ns).catch(() => void 0);
14916
+ const crossRefs = Object.entries(typeSchema.fields).filter(([, d]) => d.kind === "crossRef");
14917
+ const withHops = plan === void 0 || crossRefs.length === 0 ? withStorage : {
13092
14918
  ...withStorage,
14919
+ servedAfterHop: Object.fromEntries(crossRefs.map(([f]) => [f, nextKeys(plan.indexes, f)]))
14920
+ };
14921
+ return jsonResponse(200, shape === "fields" ? {
14922
+ ...withHops,
13093
14923
  mutationNames: Object.keys(mutations).sort()
13094
14924
  } : {
13095
- ...withStorage,
14925
+ ...withHops,
13096
14926
  mutations
13097
14927
  });
13098
14928
  };
@@ -13763,7 +15593,7 @@ function encodeDataForPack(frame, fieldsByKey, engine) {
13763
15593
  continue;
13764
15594
  }
13765
15595
  const rawShape = frame.shapes?.[key];
13766
- encoded[key] = encodeByShape(value, fields, schema, name, Array.isArray(rawShape) ? void 0 : rawShape, {
15596
+ encoded[key] = encodeByShape(value, fields, schema, name, rawShape === "single" || rawShape === "list" ? rawShape : void 0, {
13767
15597
  schemas,
13768
15598
  currentNs: ns
13769
15599
  });
@@ -14750,4 +16580,4 @@ function kernelMigrationTracking(sql) {
14750
16580
  }
14751
16581
 
14752
16582
  //#endregion
14753
- export { assertJsonPathPredicate as $, createResolverWithEdges as A, normaliseMetadataWhere as At, UnattributedWriteError as B, ReservedField as Bt, queryOne as C, normaliseVocabWhere as Ct, isReservedAutoCrudField as D, METADATA_AUTHOR_FIELDS as Dt, RESERVED_AUTOCRUD_FIELD_NAMES as E, RegistryBase as Et, listResolver as F, assertHardDeleteAllowed as Ft, loadPlugins as G, isResolverFrameError as Gt, resolveEntityId as H, RestrictViolation as Ht, getResolver as I, validateHardDeleteEnv as It, applyObligations as J, ROW_METADATA_FIELDS as Jt, publishSchema as K, isRestrictViolation as Kt, deleteResolver as L, BridgeUnreachableError as Lt, applyUpdatePatch as M, isImpossibleIsoTimestamp as Mt, updateResolver as N, isIsoTimestamp as Nt, field as O, METADATA_FILTER_FIELDS as Ot, purgeResolver as P, normalizeIsoTimestamp as Pt, preResolveExtensionOperatorsDetailed as Q, defineBootstrap as Qt, deleteRow as R, MissingReferentError as Rt, queryAll as S, normaliseVocabValues as St, RESERVED_AUTOCRUD_FIELDS as T, vocabImplication as Tt, resolveEntityRow as U, UnsupportedFilterError as Ut, resolveIdentity as V, ResolverFrameError as Vt, MemoryEdgesStore as W, isAuthCause as Wt, runSweep as X, canonicalize as Xt, loadSweepState as Y, assertNoRepeatedIds as Yt, saveSweepState as Z, BootstrapConfigError as Zt, assertIndexDecl as _, signHs256 as _t, composeFromManifests as a, decodeCursor as at, EngineQueryError as b, WS_REASON_SUBSCRIPTION_OVERLOADED as bt, MemoryDataset as c, applyExtensionResultMeta as ct, uuidFromName as d, JSON_HEADERS as dt, isJsonPathPredicate as et, migrateFieldValues as f, buildContext as ft, INVITE_TYPE as g, parseAuthConfig as gt, AUDIT_EVENT_TYPE as h, parseJsonBody as ht, PluginLoadError as i, unregisterExtensionOperator as it, installAutoCrud as j, createKeyedMutex as jt, autoCrudOptionsOf as k, normaliseMetadataOrderBy as kt, planServesShape as l, fieldRequested as lt, buildAuditRow as m, jsonResponse as mt, kernelMigrationTracking as n, listExtensionOperators as nt, DEFAULT_NAMESPACE as o, encodeCursor as ot, runInviteSweep as p, error400 as pt, effectiveFilterOperators as q, CLIENT_SUPPLIED_SERVER_FIELD as qt, mountKernelRoute as r, registerExtensionOperator as rt, compose as s, fullBuiltinOperators as st, composeKernelPlugins as t, getExtensionOperator as tt, isStoreProfileName as u, HttpBridgeClient as ut, assertOrderedBy as v, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as vt, selectAll as w, storedVocabSpellings as wt, makeCtx as x, canonicalVocabValue as xt, defineNamespace as y, WS_REASON_SERVER_RESTART as yt, createResolver as z, NamespaceMismatch as zt };
16583
+ export { bindingWalks as $, WALKS_IN_SUBSCRIPTION as $t, createResolverWithEdges as A, storedVocabSpellings as At, UnattributedWriteError as B, isIsoTimestamp as Bt, queryOne as C, signHs256 as Ct, isReservedAutoCrudField as D, canonicalVocabValue as Dt, RESERVED_AUTOCRUD_FIELD_NAMES as E, WS_REASON_SUBSCRIPTION_OVERLOADED as Et, listResolver as F, normaliseMetadataOrderBy as Ft, loadPlugins as G, MissingReferentError as Gt, resolveEntityId as H, assertHardDeleteAllowed as Ht, getResolver as I, normaliseMetadataWhere as It, applyObligations as J, ReservedField as Jt, publishSchema as K, NamespaceMismatch as Kt, deleteResolver as L, normaliseWalkNode as Lt, applyUpdatePatch as M, RegistryBase as Mt, updateResolver as N, METADATA_AUTHOR_FIELDS as Nt, field as O, normaliseVocabValues as Ot, purgeResolver as P, METADATA_FILTER_FIELDS as Pt, isDateField as Q, WALKS_IN_MUTATION as Qt, deleteRow as R, createKeyedMutex as Rt, queryAll as S, parseAuthConfig as St, RESERVED_AUTOCRUD_FIELDS as T, WS_REASON_SERVER_RESTART as Tt, resolveEntityRow as U, validateHardDeleteEnv as Ut, resolveIdentity as V, normalizeIsoTimestamp as Vt, MemoryEdgesStore as W, BridgeUnreachableError as Wt, runSweep as X, RestrictViolation as Xt, loadSweepState as Y, ResolverFrameError as Yt, saveSweepState as Z, UnsupportedFilterError as Zt, assertIndexDecl as _, JSON_HEADERS as _t, composeFromManifests as a, isResolverFrameError as an, isJsonPathPredicate as at, EngineQueryError as b, jsonResponse as bt, MemoryDataset as c, ROW_METADATA_FIELDS as cn, registerExtensionOperator as ct, uuidFromName as d, BootstrapConfigError as dn, decodeCursor as dt, WALKS_NEED_PARTITIONED as en, groupConjuncts as et, migrateFieldValues as f, defineBootstrap as fn, encodeCursor as ft, INVITE_TYPE as g, HttpBridgeClient as gt, AUDIT_EVENT_TYPE as h, fieldRequested as ht, PluginLoadError as i, isAuthCause as in, assertJsonPathPredicate as it, installAutoCrud as j, vocabImplication as jt, autoCrudOptionsOf as k, normaliseVocabWhere as kt, planServesShape as l, assertNoRepeatedIds as ln, unregisterExtensionOperator as lt, buildAuditRow as m, applyExtensionResultMeta as mt, kernelMigrationTracking as n, WALK_BUDGET_EXCEEDED as nn, refNames as nt, DEFAULT_NAMESPACE as o, isRestrictViolation as on, getExtensionOperator as ot, runInviteSweep as p, fullBuiltinOperators as pt, effectiveFilterOperators as q, ROW_POLICY_BLOCKS_WALK as qt, mountKernelRoute as r, WALK_UNSUPPORTED_REF as rn, preResolveExtensionOperatorsDetailed as rt, compose as s, CLIENT_SUPPLIED_SERVER_FIELD as sn, listExtensionOperators as st, composeKernelPlugins as t, WALKS_UNSUPPORTED_STORE as tn, isRefOperand as tt, isStoreProfileName as u, canonicalize as un, CursorDecodeError as ut, assertOrderedBy as v, buildContext as vt, selectAll as w, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as wt, makeCtx as x, parseJsonBody as xt, defineNamespace as y, error400 as yt, createResolver as z, isImpossibleIsoTimestamp as zt };