@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 { $ as assertJsonPathPredicate, Bt as ReservedField, Pt as normalizeIsoTimestamp, Q as preResolveExtensionOperatorsDetailed, Ut as UnsupportedFilterError, Yt as assertNoRepeatedIds, at as decodeCursor, ct as applyExtensionResultMeta, et as isJsonPathPredicate, jt as createKeyedMutex, lt as fieldRequested, ot as encodeCursor, st as fullBuiltinOperators, zt as NamespaceMismatch } from "./src-5SJ5GEIM.js";
3
- import { x as naturalOrderOf } from "./src-hZb8wfvg.js";
2
+ import { $ as bindingWalks, Jt as ReservedField, Kt as NamespaceMismatch, Q as isDateField, Rt as createKeyedMutex, Vt as normalizeIsoTimestamp, Yt as ResolverFrameError, Zt as UnsupportedFilterError, at as isJsonPathPredicate, dt as decodeCursor, en as WALKS_NEED_PARTITIONED, et as groupConjuncts, ft as encodeCursor, ht as fieldRequested, it as assertJsonPathPredicate, ln as assertNoRepeatedIds, mt as applyExtensionResultMeta, nt as refNames, pt as fullBuiltinOperators, rn as WALK_UNSUPPORTED_REF, rt as preResolveExtensionOperatorsDetailed, tt as isRefOperand, ut as CursorDecodeError } from "./src-DK7VEQT6.js";
3
+ import { x as naturalOrderOf } from "./src-Dbvuel6w.js";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
 
6
6
  //#region ../../packages/substrate-dataset-pg/src/advisory-lock.ts
@@ -460,9 +460,9 @@ function resolvePromotedColumns(map) {
460
460
  }
461
461
  return (field) => resolved.get(field);
462
462
  }
463
- /** The qualified expression source for a promoted column — `r.<column>`. */
464
- function promotedColumnSql(def) {
465
- return `r.${def.column}`;
463
+ /** The qualified expression source for a promoted column — `r.<column>`, or `<alias>.<column>`. */
464
+ function promotedColumnSql(def, alias = "r") {
465
+ return `${qualifier(alias)}${def.column}`;
466
466
  }
467
467
  /**
468
468
  * Row-shape keys that DO NOT live in `r.body` — they're synthesised from
@@ -510,36 +510,44 @@ function sqlStringLiteral(s) {
510
510
  /**
511
511
  * Body-field expressions as SQL TEXT, with every name inlined as a literal.
512
512
  * The compiler and the index DDL both build from these, because an
513
- * expression index serves only a filter whose expression matches it.
513
+ * expression index serves only a filter whose expression matches it. An
514
+ * `alias` qualifies `body` (a walk's far row); without one the text is the
515
+ * index DDL's.
514
516
  */
515
- const jsonSql = (path) => `body${path.map((p) => ` -> ${sqlStringLiteral(p)}`).join("")}`;
516
- const rawTextSql = (path) => `(${jsonSql(path.slice(0, -1))} ->> ${sqlStringLiteral(path[path.length - 1])})`;
517
- const textSql = (path) => `(${rawTextSql(path)} COLLATE "C")`;
518
- const numSql = (path) => `substrate_num(${jsonSql(path)})`;
519
- const tsSql = (path) => `substrate_ts(${jsonSql(path)})`;
517
+ /** `<alias>.`, checked as a bare identifier since it reaches `sql.unsafe`; empty without one. */
518
+ function qualifier(alias) {
519
+ if (alias === void 0) return "";
520
+ if (!COLUMN_NAME_PATTERN.test(alias)) throw new Error(`internal: '${alias}' is not a table alias`);
521
+ return `${alias}.`;
522
+ }
523
+ const jsonSql = (path, alias) => `${qualifier(alias)}body${path.map((p) => ` -> ${sqlStringLiteral(p)}`).join("")}`;
524
+ const rawTextSql = (path, alias) => `(${jsonSql(path.slice(0, -1), alias)} ->> ${sqlStringLiteral(path[path.length - 1])})`;
525
+ const textSql = (path, alias) => `(${rawTextSql(path, alias)} COLLATE "C")`;
526
+ const numSql = (path, alias) => `substrate_num(${jsonSql(path, alias)})`;
527
+ const tsSql = (path, alias) => `substrate_ts(${jsonSql(path, alias)})`;
520
528
  /** `((body -> 'a' ->> 'b') COLLATE "C")`: the one text expression for compares and sorts. */
521
- function bodyText(sql, path) {
522
- return sql.unsafe(textSql(path));
529
+ function bodyText(sql, path, alias) {
530
+ return sql.unsafe(textSql(path, alias));
523
531
  }
524
532
  /** `(body -> 'a' ->> 'b')` uncollated, for ILIKE, which a "C" collation would not case-fold. */
525
- function bodyRawText(sql, path) {
526
- return sql.unsafe(rawTextSql(path));
533
+ function bodyRawText(sql, path, alias) {
534
+ return sql.unsafe(rawTextSql(path, alias));
527
535
  }
528
536
  /** `(body -> 'a' -> 'b')`: the leaf stays jsonb. */
529
- function bodyJson(sql, path) {
530
- return sql.unsafe(`(${jsonSql(path)})`);
537
+ function bodyJson(sql, path, alias) {
538
+ return sql.unsafe(`(${jsonSql(path, alias)})`);
531
539
  }
532
540
  /** `substrate_num(body -> …)`: the number, or NULL for any other jsonb. */
533
- function bodyNum(sql, path) {
534
- return sql.unsafe(numSql(path));
541
+ function bodyNum(sql, path, alias) {
542
+ return sql.unsafe(numSql(path, alias));
535
543
  }
536
544
  /** `substrate_ts(body -> …)`: the instant, or NULL for anything but an ISO date or date-time string. */
537
- function bodyTs(sql, path) {
538
- return sql.unsafe(tsSql(path));
545
+ function bodyTs(sql, path, alias) {
546
+ return sql.unsafe(tsSql(path, alias));
539
547
  }
540
- /** The DDL text of the expression the compiler emits for a top-level field. */
541
- function indexExpressionSql(kind, field) {
542
- return kind === "text" ? textSql([field]) : kind === "number" ? numSql([field]) : tsSql([field]);
548
+ /** The DDL text of the expression the compiler emits for a top-level field (qualified by `alias`, if given). */
549
+ function indexExpressionSql(kind, field, alias) {
550
+ return kind === "text" ? textSql([field], alias) : kind === "number" ? numSql([field], alias) : tsSql([field], alias);
543
551
  }
544
552
  /**
545
553
  * `cond` where `expr` is not NULL, else FALSE, never NULL, so a caller's NOT
@@ -1535,7 +1543,7 @@ async function reconcileStatistics(conn, args, target, specs, signal) {
1535
1543
  WHERE statistics_schemaname = current_schema()
1536
1544
  AND statistics_name = ANY(${held}) AND null_frac IS NULL
1537
1545
  LIMIT 1`).length > 0)) return;
1538
- await cancellable(conn, `ANALYZE ${ident(target)}`, signal);
1546
+ await cancellable$1(conn, `ANALYZE ${ident(target)}`, signal);
1539
1547
  out.analyzed = true;
1540
1548
  });
1541
1549
  return out;
@@ -1926,7 +1934,7 @@ async function build(conn, args, target, spec, name, opts) {
1926
1934
  }
1927
1935
  opts.onBuild?.(spec.name);
1928
1936
  try {
1929
- await cancellable(conn, createSql(spec, target, name, true), spec.unique ? void 0 : opts.signal);
1937
+ await cancellable$1(conn, createSql(spec, target, name, true), spec.unique ? void 0 : opts.signal);
1930
1938
  return;
1931
1939
  } catch (err) {
1932
1940
  if (spec.unique) throw err;
@@ -1977,7 +1985,7 @@ async function buildEstimate(conn, target, name) {
1977
1985
  return Number(row?.n ?? 0);
1978
1986
  }
1979
1987
  /** Runs `text` on `conn`, cancelling it in flight when `signal` aborts. */
1980
- async function cancellable(conn, text, signal) {
1988
+ async function cancellable$1(conn, text, signal) {
1981
1989
  const query = conn.unsafe(text);
1982
1990
  const cancel = () => {
1983
1991
  Promise.resolve(query.cancel()).catch(() => void 0);
@@ -1991,7 +1999,7 @@ async function cancellable(conn, text, signal) {
1991
1999
  }
1992
2000
  }
1993
2001
  async function dropConcurrently(conn, name, signal) {
1994
- await cancellable(conn, `DROP INDEX CONCURRENTLY IF EXISTS ${name}`, signal);
2002
+ await cancellable$1(conn, `DROP INDEX CONCURRENTLY IF EXISTS ${name}`, signal);
1995
2003
  }
1996
2004
  async function mark(conn, name) {
1997
2005
  await conn.unsafe(`COMMENT ON INDEX ${name} IS '${MARK}'`);
@@ -2142,6 +2150,150 @@ var PgShortIdStore = class {
2142
2150
  }
2143
2151
  };
2144
2152
 
2153
+ //#endregion
2154
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-metadata.ts
2155
+ /**
2156
+ * WHERE predicates against the native row-metadata columns on `rows`,
2157
+ * rather than `body ->> field` extraction.
2158
+ */
2159
+ /**
2160
+ * Builds WHERE predicates against a metadata column (e.g. `r.created_at`).
2161
+ * Returns null when no operator produced a predicate; throws
2162
+ * `UnsupportedFilterError` on an unknown operator.
2163
+ *
2164
+ * Timestamp columns take equality and range operators; the `*ByKind` /
2165
+ * `*ById` text columns take equality, range and pattern operators. The column
2166
+ * comes from the constant `METADATA_COLUMNS`, so `sql.unsafe` is safe here.
2167
+ */
2168
+ /** `r.<column>`, or the same column of `alias`'s row. */
2169
+ function metadataColumnSql(field, alias) {
2170
+ const col = METADATA_COLUMNS$1[field];
2171
+ return alias === void 0 ? col : `${qualifier(alias)}${col.slice(2)}`;
2172
+ }
2173
+ function buildMetadataColumnPredicate(sql, field, predicate, alias) {
2174
+ const colName = metadataColumnSql(field, alias);
2175
+ const col = sql.unsafe(colName);
2176
+ if (field === "seq") {
2177
+ const n = (v) => sql`${String(v)}::bigint`;
2178
+ return orderedColumnPredicate(sql, field, col, predicate, {
2179
+ one: n,
2180
+ bound: n,
2181
+ many: (vs) => sql`${vs.map(String)}::bigint[]`,
2182
+ strictBetween: true
2183
+ });
2184
+ }
2185
+ if (field === "createdAt" || field === "updatedAt") return orderedColumnPredicate(sql, field, col, predicate, {
2186
+ one: (v) => typeof v === "string" || v instanceof Date ? tsParam(sql, v) : null,
2187
+ bound: (v) => tsParam(sql, v),
2188
+ many: (vs) => tsArrayParam(sql, vs),
2189
+ strictBetween: false
2190
+ });
2191
+ const fragments = [];
2192
+ for (const [op, operand] of Object.entries(predicate)) {
2193
+ let frag = null;
2194
+ switch (op) {
2195
+ case "eq":
2196
+ if (operand === null) frag = sql`${col} IS NULL`;
2197
+ else if (typeof operand === "string") frag = sql`${col} = ${operand}`;
2198
+ break;
2199
+ case "neq":
2200
+ if (operand === null) frag = sql`${col} IS NOT NULL`;
2201
+ else if (typeof operand === "string") frag = sql`${col} IS DISTINCT FROM ${operand}`;
2202
+ break;
2203
+ case "in":
2204
+ case "nin":
2205
+ if (Array.isArray(operand)) {
2206
+ const member = memberOf(sql, col, sql`${operand.filter((v) => typeof v === "string")}::text[]`, operand);
2207
+ frag = op === "in" ? member : sql`NOT ${member}`;
2208
+ }
2209
+ break;
2210
+ case "contains":
2211
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}%`}`;
2212
+ break;
2213
+ case "startsWith":
2214
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`${escapeLike(operand)}%`}`;
2215
+ break;
2216
+ case "endsWith":
2217
+ if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}`}`;
2218
+ break;
2219
+ case "gt":
2220
+ frag = sql`${col} COLLATE "C" > ${metaStr(field, op, operand)}`;
2221
+ break;
2222
+ case "gte":
2223
+ frag = sql`${col} COLLATE "C" >= ${metaStr(field, op, operand)}`;
2224
+ break;
2225
+ case "lt":
2226
+ frag = sql`${col} COLLATE "C" < ${metaStr(field, op, operand)}`;
2227
+ break;
2228
+ case "lte":
2229
+ frag = sql`${col} COLLATE "C" <= ${metaStr(field, op, operand)}`;
2230
+ break;
2231
+ case "between":
2232
+ if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2233
+ frag = sql`${col} COLLATE "C" BETWEEN ${metaStr(field, op, operand[0])} AND ${metaStr(field, op, operand[1])}`;
2234
+ break;
2235
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2236
+ }
2237
+ if (frag !== null) fragments.push(frag);
2238
+ }
2239
+ if (fragments.length === 0) return null;
2240
+ return combineAnd(sql, fragments);
2241
+ }
2242
+ /** Equality, range and membership predicates on one ordered column (`seq`, a timestamp). */
2243
+ function orderedColumnPredicate(sql, field, col, predicate, bind) {
2244
+ const fragments = [];
2245
+ for (const [op, operand] of Object.entries(predicate)) {
2246
+ let frag = null;
2247
+ const v = bind.one(operand);
2248
+ switch (op) {
2249
+ case "eq":
2250
+ if (operand === null) frag = sql`${col} IS NULL`;
2251
+ else if (v !== null) frag = sql`${col} = ${v}`;
2252
+ break;
2253
+ case "neq":
2254
+ if (operand === null) frag = sql`${col} IS NOT NULL`;
2255
+ else if (v !== null) frag = sql`${col} IS DISTINCT FROM ${v}`;
2256
+ break;
2257
+ case "gt":
2258
+ if (v !== null) frag = sql`${col} > ${v}`;
2259
+ break;
2260
+ case "gte":
2261
+ if (v !== null) frag = sql`${col} >= ${v}`;
2262
+ break;
2263
+ case "lt":
2264
+ if (v !== null) frag = sql`${col} < ${v}`;
2265
+ break;
2266
+ case "lte":
2267
+ if (v !== null) frag = sql`${col} <= ${v}`;
2268
+ break;
2269
+ case "between":
2270
+ if (Array.isArray(operand) && operand.length === 2) frag = sql`${col} BETWEEN ${bind.bound(operand[0])} AND ${bind.bound(operand[1])}`;
2271
+ else if (bind.strictBetween) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2272
+ break;
2273
+ case "in":
2274
+ case "nin":
2275
+ if (Array.isArray(operand)) {
2276
+ const member = memberOf(sql, col, bind.many(operand.filter((e) => e !== null)), operand);
2277
+ frag = op === "in" ? member : sql`NOT ${member}`;
2278
+ }
2279
+ break;
2280
+ default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2281
+ }
2282
+ if (frag !== null) fragments.push(frag);
2283
+ }
2284
+ if (fragments.length === 0) return null;
2285
+ return combineAnd(sql, fragments);
2286
+ }
2287
+ /**
2288
+ * Membership of `col` in `operand`, never NULL: an empty list matches nothing,
2289
+ * and a null element matches a null column, as the memory evaluator does.
2290
+ */
2291
+ function memberOf(sql, col, values, operand) {
2292
+ const parts = [sql`COALESCE(${col} = ANY(${values}), FALSE)`];
2293
+ if (operand.includes(null)) parts.push(sql`${col} IS NULL`);
2294
+ return combineOr(sql, parts);
2295
+ }
2296
+
2145
2297
  //#endregion
2146
2298
  //#region ../../packages/substrate-dataset-pg/src/pg-sql/projection.ts
2147
2299
  /**
@@ -2161,9 +2313,16 @@ function buildBodyProjection(sql, fields) {
2161
2313
  if (NON_BODY_FIELD_KEYS.has(key)) continue;
2162
2314
  bodyKeys.add(key);
2163
2315
  }
2164
- const keyArr = Array.from(bodyKeys);
2165
- if (keyArr.length === 0) return sql`'{}'::jsonb`;
2166
- const pairs = keyArr.map((k) => sql`${k}::text, r.body->${k}`);
2316
+ return buildObject(sql, Array.from(bodyKeys, (k) => sql`${k}::text, r.body->${k}`));
2317
+ }
2318
+ /**
2319
+ * A jsonb object from `'k'::text, <value>` pairs (the output key needs
2320
+ * `::text`: jsonb_build_object's VARIADIC any cannot infer a parameter's
2321
+ * type). pg caps a call at 100 arguments, so each call takes at most 50 keys
2322
+ * and the objects are concatenated with `||`.
2323
+ */
2324
+ function buildObject(sql, pairs) {
2325
+ if (pairs.length === 0) return sql`'{}'::jsonb`;
2167
2326
  const objects = [];
2168
2327
  for (let i = 0; i < pairs.length; i += MAX_KEYS_PER_CALL) objects.push(sql`jsonb_build_object(${join(pairs.slice(i, i + MAX_KEYS_PER_CALL), sql`,`)})`);
2169
2328
  return sql`${join(objects, sql` || `)}`;
@@ -2199,6 +2358,13 @@ function assembleRowMetadata(record) {
2199
2358
 
2200
2359
  //#endregion
2201
2360
  //#region ../../packages/substrate-dataset-pg/src/pg-sql/sorting.ts
2361
+ /**
2362
+ * ORDER BY + keyset-cursor → SQL translation.
2363
+ *
2364
+ * `sortExpr` is the single source for ORDER BY and both halves of the keyset
2365
+ * cursor comparison, so sorting and paging cannot diverge.
2366
+ */
2367
+ const noDerived = () => void 0;
2202
2368
  function normalizeOrderBy(orderBy) {
2203
2369
  const out = [];
2204
2370
  if (orderBy !== void 0) for (const clause of orderBy) for (const [field, dir] of Object.entries(clause)) out.push([field, dir]);
@@ -2231,10 +2397,10 @@ function resolveBodyOrderByCast(def) {
2231
2397
  default: return null;
2232
2398
  }
2233
2399
  }
2234
- function buildOrderBy(sql, orderBy, castFor, promotedFor) {
2400
+ function buildOrderBy(sql, orderBy, castFor, promotedFor, derivedFor = noDerived) {
2235
2401
  if (orderBy.length === 0) return sql``;
2236
2402
  const parts = [];
2237
- for (const [field, dir] of orderBy) parts.push(orderByFragment(sql, field, dir, castFor(field), promotedFor));
2403
+ for (const [field, dir] of orderBy) parts.push(orderByFragment(sql, field, dir, castFor(field), promotedFor, derivedFor));
2238
2404
  if (parts.length === 1) return sql`ORDER BY ${parts[0]}`;
2239
2405
  const commaFragment = sql`,`;
2240
2406
  const interleaved = [parts[0]];
@@ -2248,8 +2414,10 @@ function buildOrderBy(sql, orderBy, castFor, promotedFor) {
2248
2414
  * Do not case out field kinds anywhere else: if sorting and paging use
2249
2415
  * different expressions, rows silently vanish from later pages.
2250
2416
  */
2251
- function sortExpr(sql, field, bodyCast, promotedFor) {
2417
+ function sortExpr(sql, field, bodyCast, promotedFor, derivedFor) {
2252
2418
  if (field === "id") return sql`id`;
2419
+ const derived = derivedFor(field);
2420
+ if (derived !== void 0) return derived;
2253
2421
  if (field === "shortId") return sql`s.short_id`;
2254
2422
  if (isMetadataField(field)) {
2255
2423
  const col = METADATA_COLUMNS$1[field];
@@ -2271,7 +2439,7 @@ function sortExpr(sql, field, bodyCast, promotedFor) {
2271
2439
  * Aliases are POSITIONAL (`__sort_0`, ...), not field-derived: pg truncates
2272
2440
  * identifiers at 63 bytes, so long field names could collide.
2273
2441
  */
2274
- function buildSortKeyProjection(sql, orderBy, castFor, promotedFor) {
2442
+ function buildSortKeyProjection(sql, orderBy, castFor, promotedFor, derivedFor = noDerived) {
2275
2443
  const aliases = /* @__PURE__ */ new Map();
2276
2444
  const fragments = [];
2277
2445
  for (const [field] of orderBy) {
@@ -2279,7 +2447,7 @@ function buildSortKeyProjection(sql, orderBy, castFor, promotedFor) {
2279
2447
  const alias = `__sort_${aliases.size}`;
2280
2448
  aliases.set(field, alias);
2281
2449
  const cast = castFor(field);
2282
- const expr = sortExpr(sql, field, cast, promotedFor);
2450
+ const expr = sortExpr(sql, field, cast, promotedFor, derivedFor);
2283
2451
  fragments.push(sortKeyIsTimestamp(field, cast, promotedFor) ? sql`, (${expr})::text AS ${sql(alias)}` : sql`, ${expr} AS ${sql(alias)}`);
2284
2452
  }
2285
2453
  if (fragments.length === 0) return {
@@ -2319,8 +2487,12 @@ function buildProjectedOrderBy(sql, orderBy, aliases, castFor, promotedFor, rel)
2319
2487
  * The parameter side of a comparison against `sortExpr(field)`, cast to match
2320
2488
  * it. Keep its cases in step with `sortExpr`.
2321
2489
  */
2322
- function sortParam(sql, field, value, bodyCast, promotedFor) {
2490
+ function sortParam(sql, field, value, bodyCast, promotedFor, derivedFor) {
2323
2491
  if (field === "id") return sql`${idToText(value)}`;
2492
+ if (derivedFor(field) !== void 0) {
2493
+ if (typeof value !== "number" || !Number.isFinite(value)) throw new CursorDecodeError(`cursor value for '${field}' is not a finite number`);
2494
+ return sql`${value}::float8`;
2495
+ }
2324
2496
  if (field === "shortId") return sql`${value}`;
2325
2497
  if (field === "seq") return sql`${String(value)}::bigint`;
2326
2498
  if (isMetadataField(field)) return field === "createdAt" || field === "updatedAt" ? tsParam(sql, value) : sql`${value}`;
@@ -2328,8 +2500,8 @@ function sortParam(sql, field, value, bodyCast, promotedFor) {
2328
2500
  if (promoted !== void 0) return promoted.kind === "boolean" ? sql`${Boolean(value)}::boolean` : sql`${String(value)}::text`;
2329
2501
  return castParam(sql, value, bodyCast);
2330
2502
  }
2331
- function orderByFragment(sql, field, dir, bodyCast, promotedFor) {
2332
- const expr = sortExpr(sql, field, bodyCast, promotedFor);
2503
+ function orderByFragment(sql, field, dir, bodyCast, promotedFor, derivedFor) {
2504
+ const expr = sortExpr(sql, field, bodyCast, promotedFor, derivedFor);
2333
2505
  return dir === "asc" ? sql`${expr} ASC NULLS LAST` : sql`${expr} DESC NULLS LAST`;
2334
2506
  }
2335
2507
  /**
@@ -2364,16 +2536,16 @@ function bodyOrderByExpr(sql, field, cast) {
2364
2536
  * We build the disjunction explicitly — postgres's ROW(...) tuple compare
2365
2537
  * would be simpler but doesn't honour per-column direction mixing.
2366
2538
  */
2367
- function buildCursorCompare(sql, orderBy, values, cursorId, castFor, promotedFor) {
2539
+ function buildCursorCompare(sql, orderBy, values, cursorId, castFor, promotedFor, derivedFor = noDerived) {
2368
2540
  const resolved = resolveCursorKeys(orderBy, values, cursorId);
2369
2541
  const [lead, ...rest] = resolved;
2370
2542
  if (lead === void 0) return null;
2371
- if (lead.field === "id") return cursorDisjunction(sql, resolved, castFor, promotedFor);
2372
- const restCmp = cursorDisjunction(sql, rest, castFor, promotedFor);
2543
+ if (lead.field === "id") return cursorDisjunction(sql, resolved, castFor, promotedFor, derivedFor);
2544
+ const restCmp = cursorDisjunction(sql, rest, castFor, promotedFor, derivedFor);
2373
2545
  const cast = castFor(lead.field);
2374
- const eq = cursorEqFragment(sql, lead.field, lead.value, cast, promotedFor);
2546
+ const eq = cursorEqFragment(sql, lead.field, lead.value, cast, promotedFor, derivedFor);
2375
2547
  if (lead.value === null || lead.value === void 0) return combineAnd(sql, [eq, restCmp]);
2376
- const cmp = (op) => sql`${sortExpr(sql, lead.field, cast, promotedFor)} ${sql.unsafe(op)} ${sortParam(sql, lead.field, lead.value, cast, promotedFor)}`;
2548
+ const cmp = (op) => sql`${sortExpr(sql, lead.field, cast, promotedFor, derivedFor)} ${sql.unsafe(op)} ${sortParam(sql, lead.field, lead.value, cast, promotedFor, derivedFor)}`;
2377
2549
  const asc = lead.dir === "asc";
2378
2550
  return combineAnd(sql, [cmp(asc ? ">=" : "<="), combineOr(sql, [cmp(asc ? ">" : "<"), combineAnd(sql, [eq, restCmp])])]);
2379
2551
  }
@@ -2384,11 +2556,11 @@ function buildCursorCompare(sql, orderBy, values, cursorId, castFor, promotedFor
2384
2556
  * tail query needs no other cursor condition. `createdAt` and `updatedAt` count
2385
2557
  * as nullable: their columns are nullable in both baselines.
2386
2558
  */
2387
- function buildCursorNullTail(sql, orderBy, values, castFor, promotedFor) {
2559
+ function buildCursorNullTail(sql, orderBy, values, castFor, promotedFor, derivedFor = noDerived) {
2388
2560
  const lead = orderBy[0];
2389
2561
  if (lead === void 0 || lead[0] === "id") return null;
2390
2562
  if (values[0] === null || values[0] === void 0) return null;
2391
- return sql`${sortExpr(sql, lead[0], castFor(lead[0]), promotedFor)} IS NULL`;
2563
+ return sql`${sortExpr(sql, lead[0], castFor(lead[0]), promotedFor, derivedFor)} IS NULL`;
2392
2564
  }
2393
2565
  /** Pairs each orderBy key with its cursor value: `id` from `cursorId`, the rest from `values` in order. */
2394
2566
  function resolveCursorKeys(orderBy, values, cursorId) {
@@ -2410,16 +2582,16 @@ function resolveCursorKeys(orderBy, values, cursorId) {
2410
2582
  return resolved;
2411
2583
  }
2412
2584
  /** The OR over i of (eq₁ AND ... AND eqᵢ₋₁ AND cmpᵢ). */
2413
- function cursorDisjunction(sql, resolved, castFor, promotedFor) {
2585
+ function cursorDisjunction(sql, resolved, castFor, promotedFor, derivedFor) {
2414
2586
  const orParts = [];
2415
2587
  for (let i = 0; i < resolved.length; i++) {
2416
2588
  const parts = [];
2417
2589
  for (let j = 0; j < i; j++) {
2418
2590
  const prior = resolved[j];
2419
- parts.push(cursorEqFragment(sql, prior.field, prior.value, castFor(prior.field), promotedFor));
2591
+ parts.push(cursorEqFragment(sql, prior.field, prior.value, castFor(prior.field), promotedFor, derivedFor));
2420
2592
  }
2421
2593
  const cur = resolved[i];
2422
- parts.push(cursorCmpFragment(sql, cur.field, cur.dir, cur.value, castFor(cur.field), promotedFor));
2594
+ parts.push(cursorCmpFragment(sql, cur.field, cur.dir, cur.value, castFor(cur.field), promotedFor, derivedFor));
2423
2595
  orParts.push(combineAnd(sql, parts));
2424
2596
  }
2425
2597
  return combineOr(sql, orParts);
@@ -2428,10 +2600,10 @@ function cursorDisjunction(sql, resolved, castFor, promotedFor) {
2428
2600
  * Equality against the sort key, for the `eq₁ AND ... AND cmpᵢ` prefix of the
2429
2601
  * keyset disjunction. A NULL sort key compares with `IS NULL`, never `= NULL`.
2430
2602
  */
2431
- function cursorEqFragment(sql, field, value, bodyCast, promotedFor) {
2432
- const expr = sortExpr(sql, field, bodyCast, promotedFor);
2603
+ function cursorEqFragment(sql, field, value, bodyCast, promotedFor, derivedFor) {
2604
+ const expr = sortExpr(sql, field, bodyCast, promotedFor, derivedFor);
2433
2605
  if (value === null || value === void 0) return sql`${expr} IS NULL`;
2434
- return sql`${expr} = ${sortParam(sql, field, value, bodyCast, promotedFor)}`;
2606
+ return sql`${expr} = ${sortParam(sql, field, value, bodyCast, promotedFor, derivedFor)}`;
2435
2607
  }
2436
2608
  /**
2437
2609
  * "Strictly after the cursor" for one sort key, under `NULLS LAST`. On a
@@ -2447,10 +2619,10 @@ function cursorEqFragment(sql, field, value, bodyCast, promotedFor) {
2447
2619
  * with `eq` on the preceding keys, and returning `IS NULL` here would
2448
2620
  * re-emit every null row that has already been served.
2449
2621
  */
2450
- function cursorCmpFragment(sql, field, dir, value, bodyCast, promotedFor) {
2451
- const expr = sortExpr(sql, field, bodyCast, promotedFor);
2622
+ function cursorCmpFragment(sql, field, dir, value, bodyCast, promotedFor, derivedFor) {
2623
+ const expr = sortExpr(sql, field, bodyCast, promotedFor, derivedFor);
2452
2624
  if (value === null || value === void 0) return sql`false`;
2453
- const param = sortParam(sql, field, value, bodyCast, promotedFor);
2625
+ const param = sortParam(sql, field, value, bodyCast, promotedFor, derivedFor);
2454
2626
  if (field === "id") return dir === "asc" ? sql`${expr} > ${param}` : sql`${expr} < ${param}`;
2455
2627
  return dir === "asc" ? sql`(${expr} > ${param} OR ${expr} IS NULL)` : sql`(${expr} < ${param} OR ${expr} IS NULL)`;
2456
2628
  }
@@ -2493,12 +2665,12 @@ function nestPath(path, leaf) {
2493
2665
  for (let i = path.length - 1; i >= 0; i--) doc = { [path[i]]: doc };
2494
2666
  return doc;
2495
2667
  }
2496
- function buildJsonPathPredicate(sql, field, predicate) {
2668
+ function buildJsonPathPredicate(sql, field, predicate, alias) {
2497
2669
  assertJsonPathPredicate(field, predicate);
2498
2670
  const path = predicate.path;
2499
- const x = bodyJson(sql, [field, ...path]);
2671
+ const x = bodyJson(sql, [field, ...path], alias);
2500
2672
  const text = sql`(${x} #>> '{}')`;
2501
- const fieldExpr = bodyJson(sql, [field]);
2673
+ const fieldExpr = bodyJson(sql, [field], alias);
2502
2674
  const containsDoc = (leaf) => sql`${fieldExpr} @> ${sql.json(asJsonValue(nestPath(path, leaf)))}`;
2503
2675
  const contains = (leaf) => sql`(${fieldExpr} IS NOT NULL AND ${containsDoc(leaf)})`;
2504
2676
  const isNull = sql`(${x} IS NULL OR jsonb_typeof(${x}) = 'null')`;
@@ -2575,145 +2747,6 @@ function buildJsonPathPredicate(sql, field, predicate) {
2575
2747
  return combineAnd(sql, fragments);
2576
2748
  }
2577
2749
 
2578
- //#endregion
2579
- //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-metadata.ts
2580
- /**
2581
- * WHERE predicates against the native row-metadata columns on `rows`,
2582
- * rather than `body ->> field` extraction.
2583
- */
2584
- /**
2585
- * Builds WHERE predicates against a metadata column (e.g. `r.created_at`).
2586
- * Returns null when no operator produced a predicate; throws
2587
- * `UnsupportedFilterError` on an unknown operator.
2588
- *
2589
- * Timestamp columns take equality and range operators; the `*ByKind` /
2590
- * `*ById` text columns take equality, range and pattern operators. The column
2591
- * comes from the constant `METADATA_COLUMNS`, so `sql.unsafe` is safe here.
2592
- */
2593
- function buildMetadataColumnPredicate(sql, field, predicate) {
2594
- const colName = METADATA_COLUMNS$1[field];
2595
- const col = sql.unsafe(colName);
2596
- if (field === "seq") {
2597
- const n = (v) => sql`${String(v)}::bigint`;
2598
- return orderedColumnPredicate(sql, field, col, predicate, {
2599
- one: n,
2600
- bound: n,
2601
- many: (vs) => sql`${vs.map(String)}::bigint[]`,
2602
- strictBetween: true
2603
- });
2604
- }
2605
- if (field === "createdAt" || field === "updatedAt") return orderedColumnPredicate(sql, field, col, predicate, {
2606
- one: (v) => typeof v === "string" || v instanceof Date ? tsParam(sql, v) : null,
2607
- bound: (v) => tsParam(sql, v),
2608
- many: (vs) => tsArrayParam(sql, vs),
2609
- strictBetween: false
2610
- });
2611
- const fragments = [];
2612
- for (const [op, operand] of Object.entries(predicate)) {
2613
- let frag = null;
2614
- switch (op) {
2615
- case "eq":
2616
- if (operand === null) frag = sql`${col} IS NULL`;
2617
- else if (typeof operand === "string") frag = sql`${col} = ${operand}`;
2618
- break;
2619
- case "neq":
2620
- if (operand === null) frag = sql`${col} IS NOT NULL`;
2621
- else if (typeof operand === "string") frag = sql`${col} IS DISTINCT FROM ${operand}`;
2622
- break;
2623
- case "in":
2624
- case "nin":
2625
- if (Array.isArray(operand)) {
2626
- const member = memberOf(sql, col, sql`${operand.filter((v) => typeof v === "string")}::text[]`, operand);
2627
- frag = op === "in" ? member : sql`NOT ${member}`;
2628
- }
2629
- break;
2630
- case "contains":
2631
- if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}%`}`;
2632
- break;
2633
- case "startsWith":
2634
- if (typeof operand === "string") frag = sql`${col} ILIKE ${`${escapeLike(operand)}%`}`;
2635
- break;
2636
- case "endsWith":
2637
- if (typeof operand === "string") frag = sql`${col} ILIKE ${`%${escapeLike(operand)}`}`;
2638
- break;
2639
- case "gt":
2640
- frag = sql`${col} COLLATE "C" > ${metaStr(field, op, operand)}`;
2641
- break;
2642
- case "gte":
2643
- frag = sql`${col} COLLATE "C" >= ${metaStr(field, op, operand)}`;
2644
- break;
2645
- case "lt":
2646
- frag = sql`${col} COLLATE "C" < ${metaStr(field, op, operand)}`;
2647
- break;
2648
- case "lte":
2649
- frag = sql`${col} COLLATE "C" <= ${metaStr(field, op, operand)}`;
2650
- break;
2651
- case "between":
2652
- if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2653
- frag = sql`${col} COLLATE "C" BETWEEN ${metaStr(field, op, operand[0])} AND ${metaStr(field, op, operand[1])}`;
2654
- break;
2655
- default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2656
- }
2657
- if (frag !== null) fragments.push(frag);
2658
- }
2659
- if (fragments.length === 0) return null;
2660
- return combineAnd(sql, fragments);
2661
- }
2662
- /** Equality, range and membership predicates on one ordered column (`seq`, a timestamp). */
2663
- function orderedColumnPredicate(sql, field, col, predicate, bind) {
2664
- const fragments = [];
2665
- for (const [op, operand] of Object.entries(predicate)) {
2666
- let frag = null;
2667
- const v = bind.one(operand);
2668
- switch (op) {
2669
- case "eq":
2670
- if (operand === null) frag = sql`${col} IS NULL`;
2671
- else if (v !== null) frag = sql`${col} = ${v}`;
2672
- break;
2673
- case "neq":
2674
- if (operand === null) frag = sql`${col} IS NOT NULL`;
2675
- else if (v !== null) frag = sql`${col} IS DISTINCT FROM ${v}`;
2676
- break;
2677
- case "gt":
2678
- if (v !== null) frag = sql`${col} > ${v}`;
2679
- break;
2680
- case "gte":
2681
- if (v !== null) frag = sql`${col} >= ${v}`;
2682
- break;
2683
- case "lt":
2684
- if (v !== null) frag = sql`${col} < ${v}`;
2685
- break;
2686
- case "lte":
2687
- if (v !== null) frag = sql`${col} <= ${v}`;
2688
- break;
2689
- case "between":
2690
- if (Array.isArray(operand) && operand.length === 2) frag = sql`${col} BETWEEN ${bind.bound(operand[0])} AND ${bind.bound(operand[1])}`;
2691
- else if (bind.strictBetween) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2692
- break;
2693
- case "in":
2694
- case "nin":
2695
- if (Array.isArray(operand)) {
2696
- const member = memberOf(sql, col, bind.many(operand.filter((e) => e !== null)), operand);
2697
- frag = op === "in" ? member : sql`NOT ${member}`;
2698
- }
2699
- break;
2700
- default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2701
- }
2702
- if (frag !== null) fragments.push(frag);
2703
- }
2704
- if (fragments.length === 0) return null;
2705
- return combineAnd(sql, fragments);
2706
- }
2707
- /**
2708
- * Membership of `col` in `operand`, never NULL: an empty list matches nothing,
2709
- * and a null element matches a null column, as the memory evaluator does.
2710
- */
2711
- function memberOf(sql, col, values, operand) {
2712
- const parts = [sql`COALESCE(${col} = ANY(${values}), FALSE)`];
2713
- if (operand.includes(null)) parts.push(sql`${col} IS NULL`);
2714
- return combineOr(sql, parts);
2715
- }
2716
-
2717
2750
  //#endregion
2718
2751
  //#region ../../packages/substrate-dataset-pg/src/pg-sql/predicates-promoted.ts
2719
2752
  /**
@@ -2728,8 +2761,8 @@ function memberOf(sql, col, values, operand) {
2728
2761
  * Per value V: `col = V::T` (text under `COLLATE "C"`), or `col IS NULL` when V is null. `in` / `nin`
2729
2762
  * OR/AND the per-value predicates.
2730
2763
  */
2731
- function buildPromotedBodyColumnPredicate(sql, field, meta, predicate) {
2732
- const col = sql.unsafe(promotedColumnSql(meta));
2764
+ function buildPromotedBodyColumnPredicate(sql, field, meta, predicate, alias) {
2765
+ const col = sql.unsafe(promotedColumnSql(meta, alias));
2733
2766
  const isBool = meta.kind === "boolean";
2734
2767
  const fragments = [];
2735
2768
  /** Operand-shape guard. A wrong-typed operand is a caller error, not a non-match. */
@@ -2836,10 +2869,22 @@ function buildPromotedBodyColumnPredicate(sql, field, meta, predicate) {
2836
2869
  * dispatch (id / shortId / metadata / promoted-column / body-path), the
2837
2870
  * operator-fragment compiler, and the `conditionalUpdate` match fragment.
2838
2871
  */
2839
- function buildWhere(sql, where, castFor, promotedFor) {
2872
+ /**
2873
+ * The WHERE fragment for `where`, or null when it constrains nothing. With a
2874
+ * `scope`, expressions are qualified by `scope.alias` and the walk grammar
2875
+ * (`_walk`, `$ref`) compiles; an AND group's `any` walks with `as` become one
2876
+ * jointly quantified `EXISTS` (see `buildGroup`). Without one the text is
2877
+ * exactly what it was before walks, and `_walk` / `$ref` are refused.
2878
+ */
2879
+ function buildWhere(sql, where, castFor, promotedFor, scope) {
2840
2880
  if (where === null || typeof where !== "object" || Array.isArray(where)) return null;
2841
2881
  const keys = Object.keys(where);
2842
2882
  if (keys.length === 0) return null;
2883
+ if (Object.hasOwn(where, "_agg")) {
2884
+ if (scope === void 0) throw new ResolverFrameError(WALK_UNSUPPORTED_REF, `'_agg' is not supported here`);
2885
+ return buildAggPredicate(sql, where, promotedFor, scope);
2886
+ }
2887
+ if (scope !== void 0 && bindingWalks(where).length > 0) return buildGroup(sql, where, castFor, promotedFor, scope);
2843
2888
  const fragments = [];
2844
2889
  for (const k of keys) {
2845
2890
  const child = where[k];
@@ -2847,15 +2892,18 @@ function buildWhere(sql, where, castFor, promotedFor) {
2847
2892
  if (!Array.isArray(child)) continue;
2848
2893
  const subs = [];
2849
2894
  for (const sub of child) {
2850
- const frag = buildWhere(sql, sub, castFor, promotedFor);
2895
+ const frag = buildWhere(sql, sub, castFor, promotedFor, scope);
2851
2896
  if (frag !== null) subs.push(frag);
2852
2897
  }
2853
2898
  if (subs.length > 0) fragments.push(k === "AND" ? combineAnd(sql, subs) : combineOr(sql, subs));
2854
2899
  } else if (k === "NOT") {
2855
- const inner = buildWhere(sql, child, castFor, promotedFor);
2900
+ const inner = buildWhere(sql, child, castFor, promotedFor, scope);
2856
2901
  if (inner !== null) fragments.push(sql`NOT (${inner})`);
2902
+ } else if (k === "_walk") {
2903
+ if (scope === void 0) throw new ResolverFrameError(WALK_UNSUPPORTED_REF, `'_walk' is not supported here`);
2904
+ fragments.push(buildWalk(sql, child, promotedFor, scope));
2857
2905
  } else {
2858
- const frag = buildFieldPredicate(sql, k, child, castFor, promotedFor);
2906
+ const frag = buildFieldPredicate(sql, k, child, castFor, promotedFor, scope);
2859
2907
  if (frag !== null) fragments.push(frag);
2860
2908
  }
2861
2909
  }
@@ -2873,23 +2921,32 @@ function whereReferencesField(where, field) {
2873
2921
  }
2874
2922
  return false;
2875
2923
  }
2876
- function buildFieldPredicate(sql, field, predicate, castFor, promotedFor) {
2924
+ function buildFieldPredicate(sql, field, predicate, castFor, promotedFor, scope) {
2877
2925
  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}`);
2878
- if (field === "id") return buildIdPredicate(sql, predicate);
2879
- if (field === "shortId") return buildShortIdPredicate(sql, predicate);
2880
- if (isMetadataField(field)) return buildMetadataColumnPredicate(sql, field, predicate);
2926
+ const entries = Object.entries(predicate);
2927
+ if (entries.some(([, v]) => isRefOperand(v))) {
2928
+ if (scope === void 0) throw new UnsupportedFilterError(field, "$ref", "needs a walk scope");
2929
+ const frags = entries.filter(([, v]) => isRefOperand(v)).map(([op, v]) => buildRefCompare(sql, field, op, v, castFor, scope));
2930
+ const rest = entries.filter(([, v]) => !isRefOperand(v));
2931
+ const restFrag = rest.length === 0 ? null : buildFieldPredicate(sql, field, Object.fromEntries(rest), castFor, promotedFor, scope);
2932
+ return combineAnd(sql, restFrag === null ? frags : [...frags, restFrag]);
2933
+ }
2934
+ const alias = scope?.alias;
2935
+ if (field === "id") return buildIdPredicate(sql, predicate, alias);
2936
+ if (field === "shortId") return buildShortIdPredicate(sql, predicate, scope === void 0 || scope.alias === scope.seedAlias ? sql`s.short_id` : sql`${sql.unsafe(`(SELECT ws.short_id FROM short_ids ws WHERE ws.namespace = ${alias}.namespace AND ws.type = ${alias}.type AND ws.row_id = ${alias}.id LIMIT 1)`)}`);
2937
+ if (isMetadataField(field)) return buildMetadataColumnPredicate(sql, field, predicate, alias);
2881
2938
  const promotedField = promotedFor(field);
2882
- if (promotedField !== void 0) return buildPromotedBodyColumnPredicate(sql, field, promotedField, predicate);
2883
- if (isJsonPathPredicate(predicate)) return buildJsonPathPredicate(sql, field, predicate);
2884
- return buildFieldPredicateForPath(sql, [field], predicate, castFor);
2939
+ if (promotedField !== void 0) return buildPromotedBodyColumnPredicate(sql, field, promotedField, predicate, alias);
2940
+ if (isJsonPathPredicate(predicate)) return buildJsonPathPredicate(sql, field, predicate, alias);
2941
+ return buildFieldPredicateForPath(sql, [field], predicate, castFor, alias);
2885
2942
  }
2886
- function buildFieldPredicateForPath(sql, path, predicate, castFor) {
2943
+ function buildFieldPredicateForPath(sql, path, predicate, castFor, alias) {
2887
2944
  const field = path.join(".");
2888
2945
  const entries = Object.entries(predicate);
2889
2946
  if (entries.length > 0 && !entries.some(([k]) => KNOWN_BODY_OPS.has(k)) && entries.every(([, v]) => v !== null && typeof v === "object" && !Array.isArray(v))) {
2890
2947
  const subs = [];
2891
2948
  for (const [subField, subPredicate] of entries) {
2892
- const frag = buildBodyPathPredicate(sql, [...path, subField], subPredicate, castFor);
2949
+ const frag = buildBodyPathPredicate(sql, [...path, subField], subPredicate, castFor, alias);
2893
2950
  if (frag !== null) subs.push(frag);
2894
2951
  }
2895
2952
  if (subs.length === 0) return null;
@@ -2898,7 +2955,7 @@ function buildFieldPredicateForPath(sql, path, predicate, castFor) {
2898
2955
  const declaredCast = path.length === 1 ? castFor(field) : null;
2899
2956
  const fragments = [];
2900
2957
  for (const [op, operand] of entries) {
2901
- const frag = buildOpFragment(sql, path, op, operand, declaredCast);
2958
+ const frag = buildOpFragment(sql, path, op, operand, declaredCast, alias);
2902
2959
  if (frag !== null) fragments.push(frag);
2903
2960
  }
2904
2961
  if (fragments.length === 0) return null;
@@ -2925,9 +2982,9 @@ const KNOWN_BODY_OPS = /* @__PURE__ */ new Set([
2925
2982
  "has"
2926
2983
  ]);
2927
2984
  /** Recurse into a struct sub-clause, carrying the accumulated body path. */
2928
- function buildBodyPathPredicate(sql, path, predicate, castFor) {
2985
+ function buildBodyPathPredicate(sql, path, predicate, castFor, alias) {
2929
2986
  if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) throw new UnsupportedFilterError(path.join("."), "<none>", `expected a predicate object such as { eq: ... }, got ${Array.isArray(predicate) ? "an array" : typeof predicate}`);
2930
- return buildFieldPredicateForPath(sql, path, predicate, castFor);
2987
+ return buildFieldPredicateForPath(sql, path, predicate, castFor, alias);
2931
2988
  }
2932
2989
  /**
2933
2990
  * Build WHERE predicates against the native `id` column (the row PK).
@@ -2935,50 +2992,51 @@ function buildBodyPathPredicate(sql, path, predicate, castFor) {
2935
2992
  * Range operators compare the text ids lexicographically. Numeric ids
2936
2993
  * stringify cleanly.
2937
2994
  */
2938
- function buildIdPredicate(sql, predicate) {
2995
+ function buildIdPredicate(sql, predicate, alias) {
2996
+ const id = sql.unsafe(`${qualifier(alias)}id`);
2939
2997
  const fragments = [];
2940
2998
  for (const [op, operand] of Object.entries(predicate)) {
2941
2999
  let frag = null;
2942
3000
  switch (op) {
2943
3001
  case "eq":
2944
- if (operand === null || operand === void 0) frag = sql`id IS NULL`;
2945
- else frag = sql`id = ${idToText(operand)}`;
3002
+ if (operand === null || operand === void 0) frag = sql`${id} IS NULL`;
3003
+ else frag = sql`${id} = ${idToText(operand)}`;
2946
3004
  break;
2947
3005
  case "neq":
2948
- if (operand === null || operand === void 0) frag = sql`id IS NOT NULL`;
2949
- else frag = sql`id IS DISTINCT FROM ${idToText(operand)}`;
3006
+ if (operand === null || operand === void 0) frag = sql`${id} IS NOT NULL`;
3007
+ else frag = sql`${id} IS DISTINCT FROM ${idToText(operand)}`;
2950
3008
  break;
2951
3009
  case "in":
2952
- if (Array.isArray(operand) && operand.length > 0) frag = sql`id IN ${sql(operand.map((v) => idToText(v)))}`;
3010
+ if (Array.isArray(operand) && operand.length > 0) frag = sql`${id} IN ${sql(operand.map((v) => idToText(v)))}`;
2953
3011
  else if (Array.isArray(operand) && operand.length === 0) frag = sql`FALSE`;
2954
3012
  break;
2955
3013
  case "nin":
2956
- if (Array.isArray(operand) && operand.length > 0) frag = sql`id NOT IN ${sql(operand.map((v) => idToText(v)))}`;
3014
+ if (Array.isArray(operand) && operand.length > 0) frag = sql`${id} NOT IN ${sql(operand.map((v) => idToText(v)))}`;
2957
3015
  break;
2958
3016
  case "contains":
2959
- if (typeof operand === "string") frag = sql`id ILIKE ${`%${escapeLike(operand)}%`}`;
3017
+ if (typeof operand === "string") frag = sql`${id} ILIKE ${`%${escapeLike(operand)}%`}`;
2960
3018
  break;
2961
3019
  case "startsWith":
2962
- if (typeof operand === "string") frag = sql`id ILIKE ${`${escapeLike(operand)}%`}`;
3020
+ if (typeof operand === "string") frag = sql`${id} ILIKE ${`${escapeLike(operand)}%`}`;
2963
3021
  break;
2964
3022
  case "endsWith":
2965
- if (typeof operand === "string") frag = sql`id ILIKE ${`%${escapeLike(operand)}`}`;
3023
+ if (typeof operand === "string") frag = sql`${id} ILIKE ${`%${escapeLike(operand)}`}`;
2966
3024
  break;
2967
3025
  case "gt":
2968
- frag = sql`id > ${metaStr("id", op, operand)}`;
3026
+ frag = sql`${id} > ${metaStr("id", op, operand)}`;
2969
3027
  break;
2970
3028
  case "gte":
2971
- frag = sql`id >= ${metaStr("id", op, operand)}`;
3029
+ frag = sql`${id} >= ${metaStr("id", op, operand)}`;
2972
3030
  break;
2973
3031
  case "lt":
2974
- frag = sql`id < ${metaStr("id", op, operand)}`;
3032
+ frag = sql`${id} < ${metaStr("id", op, operand)}`;
2975
3033
  break;
2976
3034
  case "lte":
2977
- frag = sql`id <= ${metaStr("id", op, operand)}`;
3035
+ frag = sql`${id} <= ${metaStr("id", op, operand)}`;
2978
3036
  break;
2979
3037
  case "between":
2980
3038
  if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError("id", op, "requires a two-element [low, high] array");
2981
- frag = sql`id BETWEEN ${metaStr("id", op, operand[0])} AND ${metaStr("id", op, operand[1])}`;
3039
+ frag = sql`${id} BETWEEN ${metaStr("id", op, operand[0])} AND ${metaStr("id", op, operand[1])}`;
2982
3040
  break;
2983
3041
  default: throw new UnsupportedFilterError("id", op, "is not a recognised filter operator");
2984
3042
  }
@@ -2997,8 +3055,7 @@ function numArray(field, op, v) {
2997
3055
  return v;
2998
3056
  }
2999
3057
  /** Build WHERE predicates against `s.short_id` (the LEFT-joined sidecar column). */
3000
- function buildShortIdPredicate(sql, predicate) {
3001
- const col = sql`s.short_id`;
3058
+ function buildShortIdPredicate(sql, predicate, col) {
3002
3059
  const fragments = [];
3003
3060
  for (const [op, operand] of Object.entries(predicate)) {
3004
3061
  let frag = null;
@@ -3049,11 +3106,11 @@ function buildShortIdPredicate(sql, predicate) {
3049
3106
  * Case-sensitivity note (design call): `contains` / `startsWith` / `endsWith`
3050
3107
  * use ILIKE for case-INSENSITIVE matching. Memory dataset mirrors this.
3051
3108
  */
3052
- function buildOpFragment(sql, path, op, operand, declaredCast) {
3109
+ function buildOpFragment(sql, path, op, operand, declaredCast, alias) {
3053
3110
  const field = path.join(".");
3054
- const textExpr = bodyText(sql, path);
3055
- const num = bodyNum(sql, path);
3056
- const ts = bodyTs(sql, path);
3111
+ const textExpr = bodyText(sql, path, alias);
3112
+ const num = bodyNum(sql, path, alias);
3113
+ const ts = bodyTs(sql, path, alias);
3057
3114
  const isTs = (v) => v instanceof Date || declaredCast === "timestamptz" && typeof v === "string";
3058
3115
  const anyOf = (values) => {
3059
3116
  const nums = values.filter((v) => typeof v === "number");
@@ -3076,10 +3133,10 @@ function buildOpFragment(sql, path, op, operand, declaredCast) {
3076
3133
  if (typeof operand === "number") return sql`NOT ${notNullAnd(sql, num, sql`${num} = ${operand}`)}`;
3077
3134
  if (isTs(operand)) return sql`${ts} IS DISTINCT FROM ${tsParam(sql, operand)}`;
3078
3135
  return sql`${textExpr} IS DISTINCT FROM ${scalarParam(operand)}`;
3079
- case "gt": return rangeCmp(sql, path, operand, ">", declaredCast);
3080
- case "gte": return rangeCmp(sql, path, operand, ">=", declaredCast);
3081
- case "lt": return rangeCmp(sql, path, operand, "<", declaredCast);
3082
- case "lte": return rangeCmp(sql, path, operand, "<=", declaredCast);
3136
+ case "gt": return rangeCmp(sql, path, operand, ">", declaredCast, alias);
3137
+ case "gte": return rangeCmp(sql, path, operand, ">=", declaredCast, alias);
3138
+ case "lt": return rangeCmp(sql, path, operand, "<", declaredCast, alias);
3139
+ case "lte": return rangeCmp(sql, path, operand, "<=", declaredCast, alias);
3083
3140
  case "between": {
3084
3141
  if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
3085
3142
  const low = operand[0];
@@ -3111,11 +3168,11 @@ function buildOpFragment(sql, path, op, operand, declaredCast) {
3111
3168
  if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
3112
3169
  const e = escapeLike(operand);
3113
3170
  const pattern = op === "contains" ? `%${e}%` : op === "startsWith" ? `${e}%` : `%${e}`;
3114
- return sql`${bodyRawText(sql, path)} ILIKE ${pattern}`;
3171
+ return sql`${bodyRawText(sql, path, alias)} ILIKE ${pattern}`;
3115
3172
  }
3116
3173
  case "has": {
3117
3174
  const elem = operand instanceof Date ? operand.toISOString() : operand;
3118
- return sql`${bodyJson(sql, path)} @> ${sql.json(asJsonValue([elem]))}`;
3175
+ return sql`${bodyJson(sql, path, alias)} @> ${sql.json(asJsonValue([elem]))}`;
3119
3176
  }
3120
3177
  default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
3121
3178
  }
@@ -3126,7 +3183,7 @@ function buildOpFragment(sql, path, op, operand, declaredCast) {
3126
3183
  * `substrate_ts`, plain strings as collated text. A stored value of another
3127
3184
  * shape reads as NULL and never matches.
3128
3185
  */
3129
- function rangeCmp(sql, path, operand, cmp, declaredCast) {
3186
+ function rangeCmp(sql, path, operand, cmp, declaredCast, alias) {
3130
3187
  const compare = (expr, param) => {
3131
3188
  switch (cmp) {
3132
3189
  case ">": return sql`${expr} > ${param}`;
@@ -3136,14 +3193,14 @@ function rangeCmp(sql, path, operand, cmp, declaredCast) {
3136
3193
  }
3137
3194
  };
3138
3195
  if (typeof operand === "number") {
3139
- const num = bodyNum(sql, path);
3196
+ const num = bodyNum(sql, path, alias);
3140
3197
  return notNullAnd(sql, num, compare(num, operand));
3141
3198
  }
3142
3199
  if (operand instanceof Date || declaredCast === "timestamptz" && typeof operand === "string") {
3143
- const ts = bodyTs(sql, path);
3200
+ const ts = bodyTs(sql, path, alias);
3144
3201
  return notNullAnd(sql, ts, compare(ts, tsParam(sql, operand)));
3145
3202
  }
3146
- if (typeof operand === "string") return compare(bodyText(sql, path), operand);
3203
+ if (typeof operand === "string") return compare(bodyText(sql, path, alias), operand);
3147
3204
  throw new UnsupportedFilterError(path.join("."), cmp, `cannot compare against a ${operand === null ? "null" : typeof operand} value`);
3148
3205
  }
3149
3206
  /**
@@ -3165,6 +3222,599 @@ function conditionalMatchFragment(sql, field, expected) {
3165
3222
  return sql`${textExpr} = ${String(expected)}`;
3166
3223
  }
3167
3224
 
3225
+ //#endregion
3226
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/walk.ts
3227
+ /**
3228
+ * Typed edge walks in `where`, compiled to SQL (spec 2026-10-24-typed-edge-walks
3229
+ * §1, §3, §5). The memory dataset's evaluator (`@mnmal-ai/substrate-filter`
3230
+ * walk.ts) is the reference; these fragments answer the same rows:
3231
+ *
3232
+ * - a hop follows the crossRef value in the row BODY: inbound through the
3233
+ * eager crossRef index expression, outbound through the far row's id;
3234
+ * - every far row is pinned to its namespace and type (partition pruning) and
3235
+ * must be live;
3236
+ * - `any` → EXISTS, `none` → NOT EXISTS, `all` → NOT EXISTS of a neighbour
3237
+ * whose predicate IS NOT TRUE, `pick` → the one neighbour `firstRow`
3238
+ * finds by index probes;
3239
+ * - the `any` walks with `as` in one AND group are ONE EXISTS over all their
3240
+ * rows, so they are jointly quantified;
3241
+ * - a `$ref` comparison is never true when either side is NULL, eq and neq
3242
+ * included; numbers compare as float8 (IEEE double, as JS does).
3243
+ *
3244
+ * The tree is assumed validated (substrate-core walk-validator).
3245
+ */
3246
+ /** The scope of a read's top-level where, over `type` rows aliased `alias`. */
3247
+ function walkScope(namespace, type, alias, fieldDef) {
3248
+ let n = 0;
3249
+ return {
3250
+ namespace,
3251
+ alias,
3252
+ type,
3253
+ seedAlias: alias,
3254
+ seedType: type,
3255
+ bindings: /* @__PURE__ */ new Map(),
3256
+ nextAlias: () => `w${++n}`,
3257
+ fieldDef
3258
+ };
3259
+ }
3260
+ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
3261
+ /** True when `where` uses the walk grammar (`_walk`, `_agg` or a `$ref` operand) anywhere. */
3262
+ function whereUsesWalks(where) {
3263
+ if (Array.isArray(where)) return where.some(whereUsesWalks);
3264
+ if (!isObj(where)) return false;
3265
+ return Object.entries(where).some(([k, v]) => k === "_walk" || k === "_agg" || k === "$ref" || whereUsesWalks(v));
3266
+ }
3267
+ const castFor = (scope, type) => (field) => resolveBodyOrderByCast(scope.fieldDef(type, field));
3268
+ /**
3269
+ * The far type of one hop from `scope`'s row, and the condition that pins the
3270
+ * far row `alias` to it: namespace, type, live, and the crossRef join.
3271
+ */
3272
+ function hop(sql, node, scope, alias) {
3273
+ let type;
3274
+ let join;
3275
+ const near = qualifier(scope.alias);
3276
+ if (node.in !== void 0) {
3277
+ const m = /^[^/]+\/([^./]+)\.(.+)$/.exec(node.in);
3278
+ if (m === null) throw new Error(`internal: walk 'in' '${node.in}' is not '<ns>/<Type>.<field>'`);
3279
+ const [, farType, field] = m;
3280
+ type = farType;
3281
+ join = sql.unsafe(`${indexExpressionSql("text", field, alias)} = (${near}id::text COLLATE "C")`);
3282
+ } else {
3283
+ const field = node.out ?? "";
3284
+ const def = scope.fieldDef(scope.type, field);
3285
+ if (def?.kind !== "crossRef") throw new Error(`internal: walk 'out' '${field}' is not a crossRef on '${scope.type}'`);
3286
+ type = def.type;
3287
+ join = sql`${sql.unsafe(`${qualifier(alias)}id::text`)} = ${bodyRawText(sql, [field], scope.alias)}`;
3288
+ }
3289
+ const far = qualifier(alias);
3290
+ return {
3291
+ type,
3292
+ cond: sql`${sql.unsafe(`${far}namespace = ${sqlStringLiteral(scope.namespace)} AND ${far}type = ${sqlStringLiteral(type)} AND ${far}deleted_at IS NULL`)} AND ${join}`
3293
+ };
3294
+ }
3295
+ /** A walk without `as` (any, none, all or pick), under the current bindings. */
3296
+ function buildWalk(sql, node, promotedFor, scope) {
3297
+ const alias = scope.nextAlias();
3298
+ const a = sql.unsafe(alias);
3299
+ const { type, cond } = hop(sql, node, scope, alias);
3300
+ const far = node.where === void 0 ? null : buildWhere(sql, node.where, castFor(scope, type), promotedFor, {
3301
+ ...scope,
3302
+ alias,
3303
+ type
3304
+ });
3305
+ if (node.pick !== void 0) {
3306
+ const [dir, field] = Object.entries(node.pick)[0];
3307
+ const key = sortKey(sql, field, castFor(scope, type)(field), alias);
3308
+ return sql`EXISTS (SELECT 1 FROM (${firstRow(sql, sql`${a}.*`, alias, cond, key, dir === "min" ? "ASC" : "DESC")}) ${a}${far === null ? sql`` : sql` WHERE ${far}`})`;
3309
+ }
3310
+ const rows = sql`SELECT 1 FROM rows ${a} WHERE ${cond}`;
3311
+ switch (node.quantifier ?? "any") {
3312
+ case "none": return sql`NOT EXISTS (${rows}${far === null ? sql`` : sql` AND ${far}`})`;
3313
+ case "all": return far === null ? sql`TRUE` : sql`NOT EXISTS (${rows} AND (${far}) IS NOT TRUE)`;
3314
+ default: return sql`EXISTS (${rows}${far === null ? sql`` : sql` AND ${far}`})`;
3315
+ }
3316
+ }
3317
+ /**
3318
+ * `select` of the first `alias` row passing `where` by `key` in `dir`, nulls
3319
+ * last, ties id ascending: at most one row. Not `ORDER BY key … LIMIT 1`,
3320
+ * which only an index in exactly that direction serves: min/max(key) is an
3321
+ * index probe in either direction, then the rows at that key are fetched by
3322
+ * it, and only when no key is present (and `nullable`), the least id with a
3323
+ * null key. The subquery repeats `where` under the same alias, shadowing the
3324
+ * outer row; `where` is so written out three times, with its parameters,
3325
+ * which compounds per nesting level (bounded by walk depth, far below pg's
3326
+ * 65,535-parameter cap).
3327
+ */
3328
+ function firstRow(sql, select, alias, where, key, dir, nullable = true) {
3329
+ const a = sql.unsafe(alias);
3330
+ const best = sql.unsafe(dir === "ASC" ? "min" : "max");
3331
+ const byId = sql.unsafe(`ORDER BY ${alias}.id COLLATE "C" ASC LIMIT 1`);
3332
+ const keyed = sql`SELECT ${select} FROM rows ${a} WHERE ${where} AND ${key} = (SELECT ${best}(${key}) FROM rows ${a} WHERE ${where}) ${byId}`;
3333
+ if (!nullable) return keyed;
3334
+ return sql`(${keyed}) UNION ALL (SELECT ${select} FROM rows ${a} WHERE ${where} AND ${key} IS NULL ${byId}) LIMIT 1`;
3335
+ }
3336
+ /** A pick's ordering key: an instant for a date, a number for a number. */
3337
+ function sortKey(sql, field, cast, alias) {
3338
+ if (isMetadataField(field)) {
3339
+ const col = metadataColumnSql(field, alias);
3340
+ const ordered = field === "createdAt" || field === "updatedAt" || field === "seq";
3341
+ return sql.unsafe(ordered ? col : `${col} COLLATE "C"`);
3342
+ }
3343
+ if (cast === "numeric") return bodyNum(sql, [field], alias);
3344
+ if (cast === "timestamptz") return bodyTs(sql, [field], alias);
3345
+ return bodyText(sql, [field], alias);
3346
+ }
3347
+ /**
3348
+ * An AND group whose `any` walks with `as` are jointly quantified: one EXISTS
3349
+ * with a `rows` alias per binding, holding each binding's hop and where and
3350
+ * every conjunct that reads a binding. Conjuncts that read none stay outside,
3351
+ * where they constrain the outer row directly (∃b: A ∧ P(b) ≡ A ∧ ∃b: P(b)).
3352
+ */
3353
+ function buildGroup(sql, where, rowCastFor, promotedFor, scope) {
3354
+ const { binds, items } = groupConjuncts(where);
3355
+ const bindings = new Map(scope.bindings);
3356
+ const hops = binds.map((node) => {
3357
+ const alias = scope.nextAlias();
3358
+ const h = hop(sql, node, scope, alias);
3359
+ bindings.set(node.as, {
3360
+ alias,
3361
+ type: h.type
3362
+ });
3363
+ return {
3364
+ node,
3365
+ alias,
3366
+ ...h
3367
+ };
3368
+ });
3369
+ const group = {
3370
+ ...scope,
3371
+ bindings
3372
+ };
3373
+ const inside = hops.map((h) => h.cond);
3374
+ for (const h of hops) {
3375
+ if (h.node.where === void 0) continue;
3376
+ const f = buildWhere(sql, h.node.where, castFor(scope, h.type), promotedFor, {
3377
+ ...group,
3378
+ alias: h.alias,
3379
+ type: h.type
3380
+ });
3381
+ if (f !== null) inside.push(f);
3382
+ }
3383
+ const names = new Set(binds.map((b) => b.as));
3384
+ const outside = [];
3385
+ for (const item of items) {
3386
+ const bound = [...refNames(item)].some((n) => names.has(n));
3387
+ const f = buildWhere(sql, item, rowCastFor, promotedFor, bound ? group : scope);
3388
+ if (f !== null) (bound ? inside : outside).push(f);
3389
+ }
3390
+ const from = sql.unsafe(hops.map((h) => `rows ${h.alias}`).join(", "));
3391
+ outside.push(sql`EXISTS (SELECT 1 FROM ${from} WHERE ${combineAnd(sql, inside)})`);
3392
+ return combineAnd(sql, outside);
3393
+ }
3394
+ /** The value a `$ref` comparison reads from `field` of `alias`'s row, by kind. */
3395
+ function refValue(sql, field, kind, alias) {
3396
+ if (isMetadataField(field)) {
3397
+ const col = metadataColumnSql(field, alias);
3398
+ return sql.unsafe(kind === "number" ? `${col}::float8` : col);
3399
+ }
3400
+ return kind === "number" ? sql`${bodyNum(sql, [field], alias)}::float8` : bodyTs(sql, [field], alias);
3401
+ }
3402
+ /**
3403
+ * `field <op> $ref`, never NULL and true only when both sides are present:
3404
+ * a null `$ref` matches nothing, eq and neq included. `neq` is true for an
3405
+ * absent or unreadable `field` against a present `$ref`, as memory's
3406
+ * `!equals` is. Numbers are float8 on both sides with `times`/`plus`
3407
+ * inlined; a date shifts by `plus` milliseconds, to the microsecond.
3408
+ */
3409
+ function buildRefCompare(sql, field, op, ref, rowCastFor, scope) {
3410
+ const cast = isMetadataField(field) ? field === "seq" ? "numeric" : field === "createdAt" || field === "updatedAt" ? "timestamptz" : null : rowCastFor(field);
3411
+ if (cast !== "numeric" && cast !== "timestamptz") throw new UnsupportedFilterError(field, op, "a $ref compares number or date fields");
3412
+ const kind = cast === "numeric" ? "number" : "date";
3413
+ const right = refOperand(sql, field, op, ref, kind, scope);
3414
+ return compareRef(sql, field, op, refValue(sql, field, kind, scope.alias), right, refIsCostly(ref));
3415
+ }
3416
+ /** A `$ref` operand that compiles to a subquery (an _agg, or guarded arithmetic), so is read once. */
3417
+ const refIsCostly = (ref) => ref.$ref.startsWith("_agg.") || ref.times !== void 0 || ref.plus !== void 0;
3418
+ /**
3419
+ * A `$ref` operand's value, typed by `kind`: `$.f` reads the seed, `<as>.f` a
3420
+ * binding, `_agg.<name>` the frame's aggregate for the seed row. Numbers are
3421
+ * float8 with `times`/`plus` inlined; a date shifts by `plus` milliseconds,
3422
+ * to the microsecond. NULL where memory's `resolveRef` is null.
3423
+ */
3424
+ function refOperand(sql, field, op, ref, kind, scope) {
3425
+ const dot = ref.$ref.indexOf(".");
3426
+ const name = ref.$ref.slice(0, dot);
3427
+ const refField = ref.$ref.slice(dot + 1);
3428
+ let right;
3429
+ if (name === "_agg") {
3430
+ if (scope.aggValue === void 0) throw new UnsupportedFilterError(field, op, `$ref '${ref.$ref}' names no _agg in this frame`);
3431
+ const v = scope.aggValue(refField);
3432
+ right = kind === "number" ? sql`substrate_num(${v})::float8` : sql`substrate_ts(${v})`;
3433
+ } else {
3434
+ const target = name === "$" ? {
3435
+ alias: scope.seedAlias,
3436
+ type: scope.seedType
3437
+ } : scope.bindings.get(name);
3438
+ if (dot < 0 || target === void 0) throw new UnsupportedFilterError(field, op, `$ref '${ref.$ref}' names no binding in scope`);
3439
+ right = refValue(sql, refField, kind, target.alias);
3440
+ }
3441
+ if (kind === "number") {
3442
+ if (ref.times === void 0 && ref.plus === void 0) return sql`(${right})`;
3443
+ const guards = [];
3444
+ let value = sql`rv`;
3445
+ if (ref.times !== void 0) {
3446
+ const m = Math.abs(ref.times);
3447
+ if (m > 1) {
3448
+ const hi = float8Lit(sql, field, op, largest((x) => Number.isFinite(x * m)));
3449
+ guards.push(sql`abs(rv) <= ${hi}`);
3450
+ } else if (m > 0 && m < 1) {
3451
+ const lo = float8Lit(sql, field, op, nextUp(largest((x) => x * m === 0)));
3452
+ guards.push(sql`rv = 0 OR abs(rv) >= ${lo}`);
3453
+ }
3454
+ value = sql`rv * ${float8Lit(sql, field, op, ref.times)}`;
3455
+ }
3456
+ if (ref.plus !== void 0) {
3457
+ const p = ref.plus;
3458
+ const edge = float8Lit(sql, field, op, largest((x) => Number.isFinite(x + Math.abs(p))));
3459
+ guards.push(p >= 0 ? sql`${value} <= ${edge}` : sql`${value} >= -${edge}`);
3460
+ value = sql`${value} + ${float8Lit(sql, field, op, p)}`;
3461
+ }
3462
+ return sql`(SELECT ${guards.reduceRight((inner, g) => sql`CASE WHEN ${g} THEN ${inner} END`, value)} FROM (SELECT ${right} AS rv OFFSET 0) ref_g)`;
3463
+ }
3464
+ if (ref.times !== void 0) throw new UnsupportedFilterError(field, op, "a date $ref takes 'plus', not 'times'");
3465
+ if (ref.plus !== void 0) float8Lit(sql, field, op, ref.plus);
3466
+ const micros = ref.plus === void 0 ? 0 : Math.round(ref.plus * 1e3);
3467
+ return micros === 0 ? right : sql`(${right} + ${sql.unsafe(`(${micros})`)} * interval '1 microsecond')`;
3468
+ }
3469
+ /**
3470
+ * A `params.derive` value for the seed row, as float8: `diff` is a − b and
3471
+ * `ratio` a / b, NULL for a null or non-numeric operand or a zero divisor, as
3472
+ * memory's. Operands are `$.<field>` or `_agg.<name>`, read as `$ref`s are.
3473
+ *
3474
+ * As memory's: a magnitude outside [1e-300, 1e300] is NULL, and 0 stays only
3475
+ * when exact (x = y, or a zero numerator). float8 raises on overflow and on a
3476
+ * division that underflows to 0, so the guard computes only where neither can
3477
+ * happen (operands within 1e307 or of one sign; a log ratio within ±692, which
3478
+ * is ±(ln 1e300 + 1.2)), and anything it skips lies outside the range anyway.
3479
+ * One expression, so ORDER BY, the cursor compare and the null tail share it.
3480
+ */
3481
+ function buildDerive(sql, name, spec, scope) {
3482
+ const [op, [a, b]] = Object.entries(spec)[0];
3483
+ const operand = (r) => refOperand(sql, `$${name}`, op, { $ref: r }, "number", scope);
3484
+ return sql`(SELECT ${op === "diff" ? sql.unsafe(`CASE WHEN sign(x) * sign(y) >= 0 OR greatest(abs(x), abs(y)) <= 1e307
3485
+ THEN CASE WHEN x = y OR abs(x - y) BETWEEN 1e-300 AND 1e300 THEN x - y END END`) : sql.unsafe(`CASE WHEN y = 0 THEN NULL WHEN x = 0 THEN x / y
3486
+ WHEN abs(ln(abs(x)) - ln(abs(y))) <= 692
3487
+ THEN CASE WHEN abs(x / y) BETWEEN 1e-300 AND 1e300 THEN x / y END END`)} FROM (SELECT ${operand(a)} AS x, ${operand(b)} AS y OFFSET 0) d)`;
3488
+ }
3489
+ const f64 = /* @__PURE__ */ new Float64Array(1);
3490
+ const u64 = new BigUint64Array(f64.buffer);
3491
+ function bitsOf(x) {
3492
+ f64[0] = x;
3493
+ return u64[0];
3494
+ }
3495
+ function fromBits(b) {
3496
+ u64[0] = b;
3497
+ return f64[0];
3498
+ }
3499
+ const nextUp = (x) => fromBits(bitsOf(x) + 1n);
3500
+ /** The largest double in [0, MAX_VALUE] passing `ok`, which holds at 0 and fails past one point. */
3501
+ function largest(ok) {
3502
+ let lo = 0n;
3503
+ let hi = bitsOf(Number.MAX_VALUE) + 1n;
3504
+ while (hi - lo > 1n) {
3505
+ const mid = (lo + hi) / 2n;
3506
+ if (ok(fromBits(mid))) lo = mid;
3507
+ else hi = mid;
3508
+ }
3509
+ return fromBits(lo);
3510
+ }
3511
+ /** `'<n>'::float8`, inlined: only a finite number reaches the text. */
3512
+ function float8Lit(sql, field, op, n) {
3513
+ if (typeof n !== "number" || !Number.isFinite(n)) throw new UnsupportedFilterError(field, op, "numeric operands must be finite numbers");
3514
+ return sql.unsafe(`'${String(n)}'::float8`);
3515
+ }
3516
+ /**
3517
+ * `left <op> right`, never NULL and true only when both sides are present;
3518
+ * `neq` is true for a NULL `left` against a present `right`, as memory's
3519
+ * `!equals` is. `once` reads `right` once, through a subquery, for an
3520
+ * operand too costly to repeat.
3521
+ */
3522
+ function compareRef(sql, field, op, left, right, once = false) {
3523
+ if (once) return sql`(SELECT ${compareRef(sql, field, op, left, sql`cv`)} FROM (SELECT ${right} AS cv OFFSET 0) cmp_g)`;
3524
+ const cmp = (o) => sql`(${left} IS NOT NULL AND ${right} IS NOT NULL AND ${left} ${sql.unsafe(o)} ${right})`;
3525
+ switch (op) {
3526
+ case "eq": return cmp("=");
3527
+ case "neq": return sql`(${right} IS NOT NULL AND NOT (${left} IS NOT NULL AND ${left} = ${right}))`;
3528
+ case "gt": return cmp(">");
3529
+ case "gte": return cmp(">=");
3530
+ case "lt": return cmp("<");
3531
+ case "lte": return cmp("<=");
3532
+ default: throw new UnsupportedFilterError(field, op, "a $ref operand is allowed on eq, neq, gt, gte, lt and lte");
3533
+ }
3534
+ }
3535
+
3536
+ //#endregion
3537
+ //#region ../../packages/substrate-dataset-pg/src/pg-sql/aggregate.ts
3538
+ /**
3539
+ * Walk aggregates (`_agg`, in fields and where) and nested projection,
3540
+ * compiled to SQL (spec 2026-10-24-typed-edge-walks §1, §3, §5). The memory
3541
+ * reference (`@mnmal-ai/substrate-filter` walk.ts `applyAgg`, and the memory
3542
+ * dataset's `walkProjection`) is what these fragments answer:
3543
+ *
3544
+ * - an aggregate is a correlated scalar subquery over the hop's live rows
3545
+ * that pass the walk's `where`, valued as jsonb exactly as memory returns
3546
+ * it: a count, float8 avg/sum/min/max over numbers, and for a date min/max
3547
+ * or a `latest` the winning row's STORED value (ties id ascending, nulls last);
3548
+ * - a nested list is `jsonb_agg` over `ORDER BY …, id LIMIT limit+1`; the
3549
+ * extra row only says the list was cut, as `_truncated: { <name>: true }`.
3550
+ *
3551
+ * The tree is assumed validated (substrate-core walk-validator).
3552
+ */
3553
+ const AGG_OPS = [
3554
+ "avg",
3555
+ "sum",
3556
+ "min",
3557
+ "max"
3558
+ ];
3559
+ /** A field of `alias`'s row as memory's `getFieldValue` reads it, as jsonb. */
3560
+ function valueJson(sql, field, alias) {
3561
+ if (!isMetadataField(field)) return bodyJson(sql, [field], alias);
3562
+ const col = metadataColumnSql(field, alias);
3563
+ return sql.unsafe(field === "createdAt" || field === "updatedAt" ? `to_jsonb(to_char(${col} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))` : `to_jsonb(${col})`);
3564
+ }
3565
+ /**
3566
+ * `spec` over the rows aliased `alias`, and the kind it compares as: an
3567
+ * aggregate expression (jsonb, NULL where memory gives null), or for a date
3568
+ * min/max or a `latest` the pick its caller runs as a bounded top-1.
3569
+ */
3570
+ function aggOver(sql, spec, alias, fieldDef) {
3571
+ const isDate = (f) => isDateField(f, fieldDef);
3572
+ if (Object.hasOwn(spec, "count")) return {
3573
+ agg: sql`to_jsonb(count(*))`,
3574
+ kind: "number"
3575
+ };
3576
+ if ("latest" in spec && Object.hasOwn(spec, "latest")) {
3577
+ const { by, value } = spec.latest;
3578
+ const key = sortKey(sql, by, resolveBodyOrderByCast(fieldDef(by)), alias);
3579
+ const numeric = value === "seq" || resolveBodyOrderByCast(fieldDef(value)) === "numeric";
3580
+ return {
3581
+ pick: {
3582
+ value,
3583
+ key,
3584
+ dir: "DESC"
3585
+ },
3586
+ kind: isDate(value) ? "date" : numeric ? "number" : "other"
3587
+ };
3588
+ }
3589
+ const op = AGG_OPS.find((k) => Object.hasOwn(spec, k));
3590
+ if (op === void 0) throw new Error("internal: aggregate names no function");
3591
+ const field = spec[op];
3592
+ if ((op === "min" || op === "max") && isDate(field)) {
3593
+ const ts = refValue(sql, field, "date", alias);
3594
+ return {
3595
+ pick: {
3596
+ value: field,
3597
+ key: ts,
3598
+ dir: op === "min" ? "ASC" : "DESC",
3599
+ filter: sql`${ts} IS NOT NULL`
3600
+ },
3601
+ kind: "date"
3602
+ };
3603
+ }
3604
+ const n = refValue(sql, field, "number", alias);
3605
+ if (op === "min" || op === "max") return {
3606
+ agg: sql`to_jsonb(${sql.unsafe(op)}(${n}))`,
3607
+ kind: "number"
3608
+ };
3609
+ const v = isMetadataField(field) ? sql.unsafe(`${metadataColumnSql(field, alias)}::numeric`) : bodyNum(sql, [field], alias);
3610
+ const s = sql`${sql.unsafe(op)}(${v})`;
3611
+ return {
3612
+ agg: sql`to_jsonb(CASE WHEN abs(${s}) >= ${sql.unsafe(OVERFLOW)} THEN NULL
3613
+ WHEN abs(${s}) <= ${sql.unsafe(UNDERFLOW)} THEN 0::float8 ELSE ${s}::float8 END)`,
3614
+ kind: "number"
3615
+ };
3616
+ }
3617
+ /** 2^1024 − 2^970, the least value float8 rounds to Infinity, as an exact numeric. */
3618
+ const OVERFLOW = `${2n ** 1024n - 2n ** 970n}::numeric`;
3619
+ /** 2^-1075 (= 5^1075 / 10^1075), the greatest value float8 rounds to 0, as an exact numeric. */
3620
+ const UNDERFLOW = `0.${(5n ** 1075n).toString().padStart(1075, "0")}::numeric`;
3621
+ /** `p` over the rows aliased `alias` passing `where`: a top-1 an index can serve, never a sort of every row. */
3622
+ function pickRow(sql, p, alias, where) {
3623
+ const a = sql.unsafe(alias);
3624
+ const rows = combineAnd(sql, p.filter === void 0 ? [where] : [where, p.filter]);
3625
+ return sql`(SELECT ${valueJson(sql, p.value, alias)} FROM rows ${a} WHERE ${rows} ORDER BY ${p.key} ${sql.unsafe(p.dir)} NULLS LAST, ${a}.id COLLATE "C" ASC LIMIT 1)`;
3626
+ }
3627
+ /**
3628
+ * A walk aggregate for `scope`'s row: a scalar subquery valued as jsonb (SQL
3629
+ * NULL or jsonb null where memory gives null), and the kind it compares as.
3630
+ */
3631
+ function buildWalkAgg(sql, spec, promotedFor, scope) {
3632
+ const alias = scope.nextAlias();
3633
+ const { type, cond } = hop(sql, spec, scope, alias);
3634
+ const far = spec.where === void 0 ? null : buildWhere(sql, spec.where, (f) => resolveBodyOrderByCast(scope.fieldDef(type, f)), promotedFor, {
3635
+ ...scope,
3636
+ alias,
3637
+ type
3638
+ });
3639
+ const { agg, pick, kind } = aggOver(sql, spec, alias, (f) => scope.fieldDef(type, f));
3640
+ const rows = combineAnd(sql, far === null ? [cond] : [cond, far]);
3641
+ return {
3642
+ value: pick === void 0 ? sql`(SELECT ${agg} FROM rows ${sql.unsafe(alias)} WHERE ${rows})` : sql`(${firstRow(sql, valueJson(sql, pick.value, alias), alias, pick.filter === void 0 ? rows : combineAnd(sql, [rows, pick.filter]), pick.key, pick.dir, pick.filter === void 0)})`,
3643
+ kind
3644
+ };
3645
+ }
3646
+ /**
3647
+ * A row's `_agg` selections as one jsonb object. Counts, sums, averages and
3648
+ * numeric min/max over the same hop and `where` are one scan of the
3649
+ * neighbourhood, not one each; a pick is its own probe.
3650
+ */
3651
+ function buildWalkAggs(sql, aggs, promotedFor, scope) {
3652
+ const shared = /* @__PURE__ */ new Map();
3653
+ const parts = [];
3654
+ const own = [];
3655
+ for (const [name, spec] of Object.entries(aggs)) {
3656
+ const { type } = hop(sql, spec, scope, "x");
3657
+ if (aggOver(sql, spec, "x", (f) => scope.fieldDef(type, f)).pick !== void 0) {
3658
+ own.push(sql`${name}::text, ${buildWalkAgg(sql, spec, promotedFor, scope).value}`);
3659
+ continue;
3660
+ }
3661
+ const key = JSON.stringify([
3662
+ spec.in,
3663
+ spec.out,
3664
+ spec.where
3665
+ ]);
3666
+ shared.set(key, [...shared.get(key) ?? [], [name, spec]]);
3667
+ }
3668
+ for (const group of shared.values()) {
3669
+ const [, first] = group[0];
3670
+ const alias = scope.nextAlias();
3671
+ const { type, cond } = hop(sql, first, scope, alias);
3672
+ const far = first.where === void 0 ? null : buildWhere(sql, first.where, (f) => resolveBodyOrderByCast(scope.fieldDef(type, f)), promotedFor, {
3673
+ ...scope,
3674
+ alias,
3675
+ type
3676
+ });
3677
+ const values = group.map(([name, spec]) => {
3678
+ const { agg } = aggOver(sql, spec, alias, (f) => scope.fieldDef(type, f));
3679
+ return sql`${name}::text, ${agg}`;
3680
+ });
3681
+ const rows = combineAnd(sql, far === null ? [cond] : [cond, far]);
3682
+ parts.push(sql`(SELECT ${buildObject(sql, values)} FROM rows ${sql.unsafe(alias)} WHERE ${rows})`);
3683
+ }
3684
+ if (own.length > 0 || parts.length === 0) parts.push(buildObject(sql, own));
3685
+ return parts.reduce((a, b) => sql`${a} || ${b}`);
3686
+ }
3687
+ /** The number of `scope`'s rows matching `where`, as one row `{ n }`. */
3688
+ function buildFrameCount(sql, where, scope) {
3689
+ return sql`SELECT count(*)::float8 AS n FROM rows ${sql.unsafe(scope.alias)} WHERE ${where}`;
3690
+ }
3691
+ /**
3692
+ * A whole-result aggregate over `scope`'s rows matching `where`, one row
3693
+ * `{ g }` per group: one group, or one per UTC day/hour of `bucket.field`
3694
+ * ascending, rows with no readable date in none, at most `limit` groups.
3695
+ * A pick reads the whole result through `pickRow`, shadowing the outer
3696
+ * alias; in a bucket it runs in two phases: GROUP BY finds the winning key,
3697
+ * then a top-1 on `key = it` (the indexed expression; the bucket key only
3698
+ * pins the lookup, never the frame's WHERE) fetches that row's stored value.
3699
+ */
3700
+ function buildFrameAggregate(sql, aggregate, bucket, where, limit, scope) {
3701
+ const r = scope.alias;
3702
+ const R = sql.unsafe(r);
3703
+ const fieldDef = (f) => scope.fieldDef(scope.type, f);
3704
+ const aggs = [];
3705
+ const picks = [];
3706
+ for (const [name, spec] of Object.entries(aggregate)) {
3707
+ const { agg, pick } = aggOver(sql, spec, r, fieldDef);
3708
+ if (pick === void 0) aggs.push(sql`${name}::text, ${agg}`);
3709
+ else picks.push([name, pick]);
3710
+ }
3711
+ if (bucket === void 0) {
3712
+ const picked = picks.map(([name, p]) => sql`${name}::text, ${pickRow(sql, p, r, where)}`);
3713
+ return sql`SELECT ${aggs.length === 0 ? sql`'{}'::jsonb` : sql`(SELECT ${buildObject(sql, aggs)} FROM rows ${R} WHERE ${where})`} || ${buildObject(sql, picked)} AS g`;
3714
+ }
3715
+ const [by, fmt] = bucket.by === "day" ? ["day", "YYYY-MM-DD"] : ["hour", "YYYY-MM-DD\"T\"HH24"];
3716
+ const key = sql`to_char(date_trunc(${sql.unsafe(`'${by}'`)}, ${refValue(sql, bucket.field, "date", r)} AT TIME ZONE 'UTC'), ${sql.unsafe(`'${fmt}'`)})`;
3717
+ const winners = picks.reduce((acc, [, p], i) => sql`${acc}, ${sql.unsafe(p.dir === "ASC" ? "min" : "max")}(${p.key}) AS ${sql.unsafe(`m${i}`)}`, sql``);
3718
+ const picked = picks.map(([name, p], i) => {
3719
+ const at = combineAnd(sql, [
3720
+ where,
3721
+ sql`${p.key} = ${sql.unsafe(`x.m${i}`)}`,
3722
+ sql`${key} = x.b`
3723
+ ]);
3724
+ return sql`${name}::text, ${pickRow(sql, p, r, at)}`;
3725
+ });
3726
+ const cut = limit === void 0 ? sql`` : sql`LIMIT ${limit + 1}`;
3727
+ return sql`SELECT jsonb_build_object('bucket', x.b) || x.g || ${buildObject(sql, picked)} AS g FROM (SELECT ${key} AS b, ${buildObject(sql, aggs)} AS g${winners} FROM rows ${R} WHERE ${where} GROUP BY 1) x WHERE x.b IS NOT NULL ORDER BY x.b COLLATE "C" ${cut}`;
3728
+ }
3729
+ /**
3730
+ * `{ _agg, <cmp>: operand }`: never NULL, false for a null aggregate or a
3731
+ * null operand. Dates compare as instants; a number operand (or any operand
3732
+ * of a number aggregate) as float8; anything else as stored, eq/neq by jsonb
3733
+ * equality and ranges by text in byte order, as memory's `applyOp`.
3734
+ */
3735
+ function buildAggPredicate(sql, where, promotedFor, scope) {
3736
+ const { value, kind } = buildWalkAgg(sql, where._agg, promotedFor, scope);
3737
+ const x = scope.nextAlias();
3738
+ const v = sql.unsafe(`${x}.v`);
3739
+ const parts = [sql`${v} IS NOT NULL AND ${v} <> 'null'::jsonb`];
3740
+ for (const [op, raw] of Object.entries(where)) {
3741
+ if (op === "_agg") continue;
3742
+ if (raw == null) parts.push(sql`FALSE`);
3743
+ else if (isRefOperand(raw)) {
3744
+ if (kind === "other") throw new UnsupportedFilterError("_agg", op, "a $ref compares number or date aggregates");
3745
+ const left = kind === "date" ? sql`substrate_ts(${v})` : sql`substrate_num(${v})::float8`;
3746
+ const right = refOperand(sql, "_agg", op, raw, kind, scope);
3747
+ parts.push(compareRef(sql, "_agg", op, left, right, refIsCostly(raw)));
3748
+ } else if (kind === "date") parts.push(compareRef(sql, "_agg", op, sql`substrate_ts(${v})`, tsParam(sql, raw)));
3749
+ else if (kind === "number" || typeof raw === "number") {
3750
+ const right = float8Lit(sql, "_agg", op, raw);
3751
+ parts.push(compareRef(sql, "_agg", op, sql`substrate_num(${v})::float8`, right));
3752
+ } else if (op === "eq" || op === "neq") parts.push(sql`${v} ${sql.unsafe(op === "eq" ? "=" : "<>")} ${JSON.stringify(raw)}::text::jsonb`);
3753
+ else {
3754
+ const text = sql`(${v} #>> '{}') COLLATE "C"`;
3755
+ parts.push(compareRef(sql, "_agg", op, text, sql`${String(raw)}::text`));
3756
+ }
3757
+ }
3758
+ return sql`EXISTS (SELECT 1 FROM (SELECT ${value} AS v) ${sql.unsafe(x)} WHERE ${combineAnd(sql, parts)})`;
3759
+ }
3760
+ const isNested = (v) => typeof v === "object" && v !== null && Object.hasOwn(v, "_walk");
3761
+ /**
3762
+ * A row's walk selections as one jsonb object: `_agg`, each nested list and,
3763
+ * only when a list was cut, `_truncated`. Null when there are none. Each list
3764
+ * is computed once, in a FROM-less subquery, and read twice: its first
3765
+ * `limit` rows, and whether it holds one more.
3766
+ */
3767
+ function buildWalkProjection(sql, aggs, nested, promotedFor, scope) {
3768
+ const pairs = [];
3769
+ if (aggs !== void 0) pairs.push(sql`'_agg'::text, ${buildWalkAggs(sql, aggs, promotedFor, scope)}`);
3770
+ const lists = Object.entries(nested);
3771
+ if (lists.length === 0) return pairs.length === 0 ? null : buildObject(sql, pairs);
3772
+ const x = scope.nextAlias();
3773
+ const cols = [];
3774
+ const cut = [];
3775
+ for (const [i, [name, sel]] of lists.entries()) {
3776
+ const col = sql.unsafe(`${x}.c${i}`);
3777
+ cols.push(sql`${buildNested(sql, sel, promotedFor, scope)} AS ${sql.unsafe(`c${i}`)}`);
3778
+ if (sel.limit === void 0) pairs.push(sql`${name}::text, ${col}`);
3779
+ else {
3780
+ pairs.push(sql`${name}::text, ${col} - ${sel.limit}::int`);
3781
+ cut.push(sql`${name}::text, CASE WHEN jsonb_array_length(${col}) > ${sel.limit}::int THEN true END`);
3782
+ }
3783
+ }
3784
+ const truncated = cut.length === 0 ? sql`` : sql` || jsonb_strip_nulls(jsonb_build_object('_truncated', NULLIF(jsonb_strip_nulls(${buildObject(sql, cut)}), '{}'::jsonb)))`;
3785
+ const list = cols.flatMap((c, i) => i === 0 ? [c] : [sql`,`, c]);
3786
+ return sql`(SELECT ${buildObject(sql, pairs)}${truncated} FROM (SELECT ${list} OFFSET 0) ${sql.unsafe(x)})`;
3787
+ }
3788
+ /**
3789
+ * One nested selection for `scope`'s row: a jsonb array of up to `limit + 1`
3790
+ * far rows, each `id`, its selected fields (null when absent) and its own
3791
+ * walk selections; no `_metadata`.
3792
+ */
3793
+ function buildNested(sql, sel, promotedFor, scope) {
3794
+ const alias = scope.nextAlias();
3795
+ const a = sql.unsafe(alias);
3796
+ const { type, cond } = hop(sql, sel._walk, scope, alias);
3797
+ const castFor = (f) => resolveBodyOrderByCast(scope.fieldDef(type, f));
3798
+ const farScope = {
3799
+ ...scope,
3800
+ alias,
3801
+ type
3802
+ };
3803
+ const filters = [sel._walk.where, sel.where].filter((w) => w !== void 0).map((w) => buildWhere(sql, w, castFor, promotedFor, farScope)).filter((f) => f !== null);
3804
+ const orderBy = normalizeOrderBy(sel.orderBy).map(([field, dir]) => {
3805
+ return sql`${field === "id" ? sql.unsafe(`${alias}.id COLLATE "C"`) : sortKey(sql, field, castFor(field), alias)} ${sql.unsafe(dir === "asc" ? "ASC" : "DESC")} NULLS LAST`;
3806
+ }).flatMap((o, i) => i === 0 ? [o] : [sql`,`, o]);
3807
+ const limit = sel.limit === void 0 ? sql`` : sql`LIMIT ${sel.limit + 1}`;
3808
+ const fields = sel.fields;
3809
+ const subNested = Object.fromEntries(Object.entries(fields).filter(([, v]) => isNested(v)));
3810
+ const subAggs = Object.hasOwn(fields, "_agg") ? fields._agg : void 0;
3811
+ const plain = Object.keys(fields).filter((k) => k !== "id" && k !== "_agg" && !NON_BODY_FIELD_KEYS.has(k) && !isNested(fields[k]));
3812
+ const id = sql.unsafe(`CASE WHEN jsonb_typeof(${alias}.body -> 'id') IN ('number', 'string') THEN ${alias}.body -> 'id' ELSE to_jsonb(${alias}.id) END`);
3813
+ const obj = buildObject(sql, [sql`'id'::text, ${id}`, ...plain.map((k) => sql`${k}::text, ${bodyJson(sql, [k], alias)}`)]);
3814
+ const sub = buildWalkProjection(sql, subAggs, subNested, promotedFor, farScope);
3815
+ return sql`(SELECT COALESCE(jsonb_agg(${sub === null ? obj : sql`${obj} || ${sub}`} ORDER BY ${orderBy}), '[]'::jsonb) FROM (SELECT ${a}.* FROM rows ${a} WHERE ${combineAnd(sql, [cond, ...filters])} ORDER BY ${orderBy} ${limit}) ${a})`;
3816
+ }
3817
+
3168
3818
  //#endregion
3169
3819
  //#region ../../packages/substrate-dataset-pg/src/tx-scope.ts
3170
3820
  /**
@@ -3273,7 +3923,8 @@ var PgDataset = class PgDataset {
3273
3923
  capabilities = {
3274
3924
  operators: fullBuiltinOperators(),
3275
3925
  orderBy: true,
3276
- cursor: true
3926
+ cursor: true,
3927
+ walks: true
3277
3928
  };
3278
3929
  txScopeId;
3279
3930
  #sql;
@@ -3324,11 +3975,29 @@ var PgDataset = class PgDataset {
3324
3975
  const ns = `${alias}namespace = ${sqlStringLiteral(this.namespace)}`;
3325
3976
  return this.#sql.unsafe(type === void 0 ? ns : `${ns} AND ${alias}type = ${sqlStringLiteral(type)}`);
3326
3977
  }
3978
+ /**
3979
+ * The walk grammar (spec 2026-10-24-typed-edge-walks §3) runs on the
3980
+ * partitioned layout only, and in a transaction under a `SET LOCAL`
3981
+ * statement timeout, since pg has no walk evaluation budget. Other reads
3982
+ * are unchanged.
3983
+ */
3327
3984
  async read(type, params) {
3985
+ if (!usesWalkGrammar(params)) return this.#read(type, params, false);
3986
+ if (await this.#layout() !== "partitioned") throw new ResolverFrameError(WALKS_NEED_PARTITIONED, "walks need the partitioned storage layout; move this store onto it with `substrate-admin migrate-store`");
3987
+ if (!this.#inTx) return this.withTransaction((tx) => tx.read(type, params));
3988
+ const ms = String(WALK_STATEMENT_TIMEOUT_MS);
3989
+ await cancellable(this.#sql`
3990
+ SELECT set_config('statement_timeout', ${ms}, true) FROM pg_settings
3991
+ WHERE name = 'statement_timeout' AND (setting::bigint = 0 OR setting::bigint > ${ms}::bigint)`, params.signal);
3992
+ return this.#read(type, params, true);
3993
+ }
3994
+ async #read(type, params, walks) {
3328
3995
  const sql = this.#sql;
3329
3996
  const includeDeleted = params.includeDeleted === true;
3330
3997
  const limit = typeof params.limit === "number" && Number.isFinite(params.limit) && params.limit >= 0 ? Math.floor(params.limit) : void 0;
3331
- if (limit === 0) return {
3998
+ params.signal?.throwIfAborted();
3999
+ const wholeResult = params.count === true || params.aggregate !== void 0;
4000
+ if (limit === 0 && !wholeResult) return {
3332
4001
  rows: [],
3333
4002
  hasMore: false
3334
4003
  };
@@ -3351,6 +4020,14 @@ var PgDataset = class PgDataset {
3351
4020
  return resolveBodyOrderByCast(this.#fieldDefLookup(type, field));
3352
4021
  };
3353
4022
  let extMeta = null;
4023
+ const lookup = this.#fieldDefLookup;
4024
+ const scope = walks ? walkScope(this.namespace, type, "r", (t, f) => lookup?.(t, f)) : void 0;
4025
+ const frameAggs = params.agg;
4026
+ if (scope !== void 0 && frameAggs !== void 0) scope.aggValue = (name) => {
4027
+ const spec = Object.hasOwn(frameAggs, name) ? frameAggs[name] : void 0;
4028
+ if (spec === void 0) throw new Error(`internal: '_agg.${name}' names no frame _agg`);
4029
+ return buildWalkAgg(sql, spec, this.#promotedFor, scope).value;
4030
+ };
3354
4031
  if (params.where !== void 0) {
3355
4032
  const detailed = await preResolveExtensionOperatorsDetailed(params.where, {
3356
4033
  namespace: this.namespace,
@@ -3359,32 +4036,65 @@ var PgDataset = class PgDataset {
3359
4036
  ...fieldRequested(params.fields, "_vector") ? { returnVector: true } : {}
3360
4037
  });
3361
4038
  extMeta = detailed.meta;
3362
- const whereFragment = buildWhere(sql, detailed.where, bodyCastFor, this.#promotedFor);
4039
+ const whereFragment = buildWhere(sql, detailed.where, bodyCastFor, this.#promotedFor, scope);
3363
4040
  if (whereFragment !== null) clauses.push(whereFragment);
3364
4041
  }
4042
+ if (wholeResult && scope !== void 0) {
4043
+ const matched = combineAnd(sql, clauses);
4044
+ if (params.count === true) {
4045
+ const [row] = await cancellable(sql`${buildFrameCount(sql, matched, scope)}`, params.signal);
4046
+ return {
4047
+ rows: [],
4048
+ hasMore: false,
4049
+ count: row?.n ?? 0
4050
+ };
4051
+ }
4052
+ const aggregate = params.aggregate ?? {};
4053
+ const groups = (await cancellable(sql`${buildFrameAggregate(sql, aggregate, params.bucket, matched, limit, scope)}`, params.signal)).map((x) => x.g);
4054
+ const truncated = params.bucket !== void 0 && limit !== void 0 && groups.length > limit;
4055
+ return {
4056
+ rows: [],
4057
+ hasMore: false,
4058
+ groups: truncated ? groups.slice(0, limit) : groups,
4059
+ ...truncated ? { truncated: true } : {}
4060
+ };
4061
+ }
3365
4062
  const orderBy = normalizeOrderBy(params.orderBy);
3366
4063
  const orderByCastFor = bodyCastFor;
3367
- let whereSql = combineAnd(sql, clauses);
4064
+ const joinShortIds = whereReferencesField(params.where, "shortId") || orderBy.some(([f]) => f === "shortId");
4065
+ const derive = params.derive;
4066
+ const derivedExpr = (field) => {
4067
+ const name = field.slice(1);
4068
+ if (scope === void 0 || derive === void 0 || !field.startsWith("$")) return void 0;
4069
+ const spec = Object.hasOwn(derive, name) ? derive[name] : void 0;
4070
+ return spec === void 0 ? void 0 : buildDerive(sql, name, spec, scope);
4071
+ };
4072
+ const lead = orderBy[0]?.[0] ?? "id";
4073
+ const fenced = joinShortIds ? void 0 : derivedExpr(lead);
4074
+ const derivedFor = (field) => fenced !== void 0 && field === lead ? sql`r.__derive_0` : derivedExpr(field);
4075
+ const from = fenced === void 0 ? sql`rows r` : sql`(SELECT r.*, ${fenced} AS __derive_0 FROM rows r WHERE ${combineAnd(sql, clauses)} OFFSET 0) r`;
4076
+ const base = fenced === void 0 ? clauses : [];
4077
+ let whereSql = combineAnd(sql, base);
3368
4078
  let tailSql = null;
3369
4079
  if (params.cursor !== void 0 && params.cursor !== "") {
3370
4080
  const cursor = decodeCursor(params.cursor, orderBy);
3371
- const cursorFragment = buildCursorCompare(sql, orderBy, cursor.orderByValues, cursor.id, orderByCastFor, this.#promotedFor);
3372
- const tail = buildCursorNullTail(sql, orderBy, cursor.orderByValues, orderByCastFor, this.#promotedFor);
3373
- if (tail !== null) tailSql = combineAnd(sql, [...clauses, tail]);
3374
- if (cursorFragment !== null) whereSql = combineAnd(sql, [...clauses, cursorFragment]);
4081
+ const cursorFragment = buildCursorCompare(sql, orderBy, cursor.orderByValues, cursor.id, orderByCastFor, this.#promotedFor, derivedFor);
4082
+ const tail = buildCursorNullTail(sql, orderBy, cursor.orderByValues, orderByCastFor, this.#promotedFor, derivedFor);
4083
+ if (tail !== null) tailSql = combineAnd(sql, [...base, tail]);
4084
+ if (cursorFragment !== null) whereSql = combineAnd(sql, [...base, cursorFragment]);
3375
4085
  }
3376
- const orderBySql = buildOrderBy(sql, orderBy, orderByCastFor, this.#promotedFor);
4086
+ const orderBySql = buildOrderBy(sql, orderBy, orderByCastFor, this.#promotedFor, derivedFor);
3377
4087
  const fetchLimit = limit !== void 0 ? limit + 1 : void 0;
3378
- const bodyProjection = buildBodyProjection(sql, params.fields);
3379
- const { fragment: sortKeyProjection, aliases: sortKeyAliases } = buildSortKeyProjection(sql, orderBy, bodyCastFor, this.#promotedFor);
3380
- const joinShortIds = whereReferencesField(params.where, "shortId") || orderBy.some(([f]) => f === "shortId");
4088
+ const walkProjection = scope === void 0 ? null : buildWalkProjection(sql, frameAggs, params.nested ?? {}, this.#promotedFor, scope);
4089
+ const bodyProjection = walkProjection === null ? buildBodyProjection(sql, params.fields) : sql`(${buildBodyProjection(sql, params.fields)} || ${walkProjection})`;
4090
+ const { fragment: sortKeyProjection, aliases: sortKeyAliases } = buildSortKeyProjection(sql, orderBy, bodyCastFor, this.#promotedFor, derivedFor);
3381
4091
  const inlineLimit = (n) => n !== void 0 ? sql.unsafe(`LIMIT ${BigInt(n)}`) : sql``;
3382
4092
  const page = (where, n) => joinShortIds ? sql`
3383
4093
  SELECT r.id, ${bodyProjection} AS body, r.deleted_at, s.short_id,
3384
4094
  r.created_at, r.updated_at,
3385
4095
  r.created_by_kind, r.created_by_id,
3386
4096
  r.updated_by_kind, r.updated_by_id, r.seq${sortKeyProjection}
3387
- FROM rows r
4097
+ FROM ${from}
3388
4098
  LEFT JOIN short_ids s
3389
4099
  ON s.namespace = r.namespace
3390
4100
  AND s.type = r.type
@@ -3400,7 +4110,7 @@ var PgDataset = class PgDataset {
3400
4110
  r.created_by_kind, r.created_by_id,
3401
4111
  r.updated_by_kind, r.updated_by_id, r.seq,
3402
4112
  r.namespace, r.type${sortKeyProjection}
3403
- FROM rows r
4113
+ FROM ${from}
3404
4114
  WHERE ${where}
3405
4115
  ${orderBySql}
3406
4116
  ${inlineLimit(n)}
@@ -3412,10 +4122,10 @@ var PgDataset = class PgDataset {
3412
4122
  ) s ON true
3413
4123
  ${buildProjectedOrderBy(sql, orderBy, sortKeyAliases, orderByCastFor, this.#promotedFor, "p")}
3414
4124
  `;
3415
- let rows = await page(whereSql, fetchLimit);
4125
+ let rows = await cancellable(page(whereSql, fetchLimit), params.signal);
3416
4126
  if (tailSql !== null && (fetchLimit === void 0 || rows.length < fetchLimit)) {
3417
4127
  const unseen = sql`r.id <> ALL(${rows.map((r) => r.id)})`;
3418
- const tail = await page(combineAnd(sql, [tailSql, unseen]), fetchLimit);
4128
+ const tail = await cancellable(page(combineAnd(sql, [tailSql, unseen]), fetchLimit), params.signal);
3419
4129
  rows = rows.concat(fetchLimit === void 0 ? tail : tail.slice(0, fetchLimit - rows.length));
3420
4130
  }
3421
4131
  const materialised = rows.map((r) => this.materialize(r));
@@ -3594,7 +4304,9 @@ var PgDataset = class PgDataset {
3594
4304
  AND s.type = u.type
3595
4305
  AND s.row_id = u.id
3596
4306
  ORDER BY i.ord
3597
- `).map((r) => this.materialize(r));
4307
+ `.catch((err) => {
4308
+ throw this.#uniqueViolation(type, err);
4309
+ })).map((r) => this.materialize(r));
3598
4310
  return {
3599
4311
  written: merged.length,
3600
4312
  ids: merged.map((r) => r.id),
@@ -3971,6 +4683,22 @@ var PgDataset = class PgDataset {
3971
4683
  };
3972
4684
  });
3973
4685
  }
4686
+ /**
4687
+ * A write's error as the caller should see it: a declared unique index's
4688
+ * conflict (23505) becomes `unique_violation` naming the index and its
4689
+ * fields; anything else is returned unchanged.
4690
+ */
4691
+ #uniqueViolation(type, err) {
4692
+ const pgErr = err;
4693
+ if (pgErr?.code !== "23505" || typeof pgErr.constraint_name !== "string") return err;
4694
+ const index = pgErr.constraint_name;
4695
+ const layout = this.#layoutCache.layout;
4696
+ const fields = (layout === void 0 ? void 0 : desiredIndexKeys(this.#indexArgs(type, this.namespace, layout)).find((d) => d.name === index))?.keys.map(([field]) => field) ?? [];
4697
+ return new ResolverFrameError("unique_violation", `${this.namespace}/${type}: a row already holds these values for unique index ${index}` + (fields.length > 0 ? ` (${fields.join(", ")})` : ""), {
4698
+ index,
4699
+ fields
4700
+ });
4701
+ }
3974
4702
  #indexArgs(type, namespace, layout) {
3975
4703
  const def = this.#typeDefLookup?.(type, namespace);
3976
4704
  return {
@@ -4328,6 +5056,42 @@ var PgDataset = class PgDataset {
4328
5056
  return textId;
4329
5057
  }
4330
5058
  };
5059
+ /** The statement timeout a walk read runs under, in milliseconds, unless a shorter one is set. */
5060
+ const WALK_STATEMENT_TIMEOUT_MS = 3e4;
5061
+ /** The walk-only params a read actually uses: `count: true`, and each non-empty object. */
5062
+ function walkParams(params) {
5063
+ const used = [
5064
+ "aggregate",
5065
+ "bucket",
5066
+ "derive",
5067
+ "agg",
5068
+ "nested"
5069
+ ].filter((k) => {
5070
+ const v = params[k];
5071
+ return typeof v === "object" && v !== null && Object.keys(v).length > 0;
5072
+ });
5073
+ return params.count === true ? ["count", ...used] : used;
5074
+ }
5075
+ /** True when a read uses the walk grammar: in its where, or a walk-only param. */
5076
+ function usesWalkGrammar(params) {
5077
+ return whereUsesWalks(params.where) || walkParams(params).length > 0;
5078
+ }
5079
+ /** Awaits `query`, cancelling the statement in flight when `signal` aborts. */
5080
+ async function cancellable(query, signal) {
5081
+ const cancel = () => {
5082
+ Promise.resolve(query.cancel()).catch(() => void 0);
5083
+ };
5084
+ signal?.addEventListener("abort", cancel, { once: true });
5085
+ try {
5086
+ if (signal?.aborted === true) cancel();
5087
+ return await query;
5088
+ } catch (err) {
5089
+ if (signal?.aborted === true) signal.throwIfAborted();
5090
+ throw err;
5091
+ } finally {
5092
+ signal?.removeEventListener("abort", cancel);
5093
+ }
5094
+ }
4331
5095
 
4332
5096
  //#endregion
4333
5097
  export { tryWithPgAdvisoryLock as _, PLAIN_SCHEMA_NAME as a, assertStoreSchema as c, isDerivedMigration as d, pendingMigrations as f, detectLayout as g, UUID_REGEX as h, MIGRATE_STORE_MARKER_TABLE as i, deriveListIndexMigration as l, runMigrations as m, txScopeIdFor as n, UUID_CHECK_MIGRATION as o, runDerivedMigrations as p, seqName as r, assertNotMigrating as s, PgDataset as t, getMigrationList as u };