@mnmal-ai/substrate 1.0.0-alpha.16 → 1.0.0-alpha.18

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 (40) hide show
  1. package/README.md +5 -4
  2. package/dist/{boot-store-HxCgbvNl.js → boot-store-C8KrACZ5.js} +51 -72
  3. package/dist/{bridge-CvZGzNIO.d.ts → bridge-5VHZiH9o.d.ts} +1 -1
  4. package/dist/{cli-6mjAWiEZ.js → cli-zZ7nHhY5.js} +235 -16
  5. package/dist/client.d.ts +8 -3
  6. package/dist/client.js +4 -4
  7. package/dist/{errors-BXxm9eZF.d.ts → errors-DHgT7Fa8.d.ts} +8 -2
  8. package/dist/{index-EN-nQsX8.d.ts → index-DKJXQ031.d.ts} +1 -1
  9. package/dist/{node-version-C5FSmwJX.js → node-version-CxqcqECU.js} +1 -1
  10. package/dist/pack.d.ts +18 -2
  11. package/dist/pack.js +2 -2
  12. package/dist/{pg-edges-store-De5F1tUf.js → pg-edges-store-D7etFxNK.js} +1 -1
  13. package/dist/{plugin-Dpa_Y7Ep.js → plugin-DcoJGEMM.js} +2 -2
  14. package/dist/proposals-bootstrap.js +2 -2
  15. package/dist/proposals.d.ts +5 -3
  16. package/dist/proposals.js +1 -1
  17. package/dist/recall-bootstrap.js +2 -2
  18. package/dist/recall.d.ts +1 -1
  19. package/dist/recall.js +2 -2
  20. package/dist/{repl-2WfRPUb0.js → repl-SY8cLOZl.js} +1 -1
  21. package/dist/{row-Dh57ShWL.d.ts → row-DHxnCnhA.d.ts} +10 -8
  22. package/dist/{run-ChcHBIN3.js → run-Cr-53N3F.js} +142 -106
  23. package/dist/{schema-B--_bHjn.d.ts → schema-B5WBO8yh.d.ts} +79 -19
  24. package/dist/{script-C6DSa_Na.js → script-B-32wZGY.js} +11 -1
  25. package/dist/script-runner.js +78 -0
  26. package/dist/sdk.d.ts +51 -8
  27. package/dist/sdk.js +4 -4
  28. package/dist/{src-B4sqnLRy.js → src-B4dTiEWw.js} +77 -28
  29. package/dist/{src-DHLw3eCn.js → src-BcuotITf.js} +1016 -231
  30. package/dist/{src-DWqzrm3O.js → src-CdbUzLhB.js} +209 -36
  31. package/dist/{src-BMHI_rTJ.js → src-D55T3ZcP.js} +2203 -499
  32. package/dist/{src-Bi3NhEsT.js → src-DR_hUj2p.js} +1 -1
  33. package/dist/{src-CHND7-Pm.js → src-DV6PcXym.js} +2 -2
  34. package/dist/{src--uyAqssS.js → src-DZfgQ2gR.js} +3 -3
  35. package/dist/substrate-admin.js +2 -2
  36. package/dist/substrate.js +2 -2
  37. package/dist/testing.d.ts +5 -3
  38. package/dist/testing.js +4 -4
  39. package/dist/{ws-CpHWxwp9.d.ts → ws-BL9nSELO.d.ts} +2 -2
  40. package/package.json +21 -21
@@ -1,6 +1,6 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-Bi3NhEsT.js";
3
- import { C as formatQualifiedKey, E as assertNever, S as naturalOrderOf, T as DEFAULT_FILTER_WRITE_LIMITS, _ as encodeEnvelope, c as isPlainRequestData, o as decodeWsEnvelope, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, v as encodePositional, w as parseQualifiedKey, x as isColumnField } from "./src-DWqzrm3O.js";
2
+ import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-DR_hUj2p.js";
3
+ import { A as parseInt64, D as parseQualifiedKey, E as formatQualifiedKey, F as EXPR_FUNCTIONS, I as EXPR_LIMITS, L as DEFAULT_FILTER_WRITE_LIMITS, N as DATE_UNITS, O as isInt16, P as EXPR_AGGREGATES, R as assertNever, S as withData, T as naturalOrderOf, _ as encodeEnvelope, b as packEnvelopeParts, c as isPlainRequestData, j as stringifyJson, k as isInt32, o as decodeWsEnvelope, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, v as encodePositional, w as isColumnField, x as positionValue } from "./src-CdbUzLhB.js";
4
4
  import { n as acceptsPack, t as PACK_MIME } from "./content-type-C7T28xNb.js";
5
5
  import { readFileSync } from "node:fs";
6
6
  import { createCipheriv, createDecipheriv, createHash, createHmac, createPrivateKey, createPublicKey, createVerify, hkdfSync, randomBytes, randomUUID, sign, timingSafeEqual, verify } from "node:crypto";
@@ -99,6 +99,12 @@ const WALK_BUDGET_EXCEEDED = "walk_budget_exceeded";
99
99
  const WALKS_UNSUPPORTED_STORE = "walks_unsupported_store";
100
100
  /** A read cancelled by the store's statement timeout; `details: { timeoutMs }`. */
101
101
  const QUERY_TIMEOUT = "query_timeout";
102
+ /** No store connection came free within the wait limit, so the request never started; retry later. */
103
+ const STORE_BUSY = "store_busy";
104
+ /** An aggregate or expression whose value leaves its type's range (an int64 sum past 2^63-1); the same code on every engine. */
105
+ const VALUE_OUT_OF_RANGE = "value_out_of_range";
106
+ /** A regex call on the memory evaluator that would take more steps than its budget; `details: { budget }`. */
107
+ const REGEX_BUDGET_EXCEEDED = "regex_budget_exceeded";
102
108
  /**
103
109
  * A walk construct refused where it cannot be answered: inside a struct, over
104
110
  * a list or struct-nested crossRef, under a reused field name, on a virtual
@@ -1194,18 +1200,8 @@ function nestedFields(sel) {
1194
1200
  function projectEnvelope(envelope, frame) {
1195
1201
  const data = {};
1196
1202
  for (const [key, value] of Object.entries(envelope.data)) {
1197
- const entry = frame[key];
1198
- if (entry === void 0 || Array.isArray(entry)) {
1199
- data[key] = value;
1200
- continue;
1201
- }
1202
- const fields = entry.fields;
1203
- const shape = envelope.shapes[key];
1204
- if (fields === void 0 || shape === "count" || shape === "groups") {
1205
- data[key] = value;
1206
- continue;
1207
- }
1208
- data[key] = projectValue(value, fields);
1203
+ const project = rowProjector(envelope, frame, key);
1204
+ data[key] = Array.isArray(value) ? value.map(project) : project(value, 0);
1209
1205
  }
1210
1206
  return {
1211
1207
  ...envelope,
@@ -1213,6 +1209,27 @@ function projectEnvelope(envelope, frame) {
1213
1209
  };
1214
1210
  }
1215
1211
  /**
1212
+ * How to project row `i` of `envelope.data[key]`. A batched mutate's element
1213
+ * `i` is frame `i`'s result, so it takes frame `i`'s own `fields`.
1214
+ */
1215
+ function rowProjector(envelope, frame, key) {
1216
+ const entry = frame[key];
1217
+ if (Array.isArray(entry)) return (row, i) => {
1218
+ const fields = entry[i]?.fields;
1219
+ return fields === void 0 ? row : projectValue(row, fields);
1220
+ };
1221
+ const fields = projectionFields(envelope, frame, key);
1222
+ return (row) => fields === void 0 ? row : projectValue(row, fields);
1223
+ }
1224
+ /** The selection `envelope.data[key]` is projected through, or undefined when it passes through whole. */
1225
+ function projectionFields(envelope, frame, key) {
1226
+ const entry = frame[key];
1227
+ if (entry === void 0 || Array.isArray(entry)) return void 0;
1228
+ const shape = envelope.shapes[key];
1229
+ if (shape === "count" || shape === "groups") return void 0;
1230
+ return entry.fields;
1231
+ }
1232
+ /**
1216
1233
  * WS analog of `projectEnvelope` — applies the same row-trimming to the
1217
1234
  * `data` payload of a `WsResponseFrame` using the per-key `fieldsByKey`
1218
1235
  * map the route layer captures at subscribe / stream time.
@@ -1240,6 +1257,94 @@ function projectWsFrame(frame, fieldsByKey) {
1240
1257
  };
1241
1258
  }
1242
1259
 
1260
+ //#endregion
1261
+ //#region ../../packages/substrate-compose/src/routes/body-stream.ts
1262
+ /**
1263
+ * A query body large enough to hold the event loop is built and sent a batch
1264
+ * of rows at a time, with a macrotask yield between batches: the same bytes
1265
+ * as the unstreamed body, JSON or substrate-pack.
1266
+ */
1267
+ /** A body streams once one `data` key holds more rows than this. */
1268
+ const STREAM_ROWS = 2e4;
1269
+ /** Rows projected and serialised per chunk (a few ms of work). */
1270
+ const ROWS_PER_CHUNK = 2e3;
1271
+ /** True when some `data` value is a row list longer than `STREAM_ROWS`. */
1272
+ function streamsRows(envelope) {
1273
+ return Object.values(envelope.data).some((v) => Array.isArray(v) && v.length > 2e4);
1274
+ }
1275
+ function jsonEnvelopeStream(envelope, frame) {
1276
+ return partsStream(jsonParts(envelope, frame));
1277
+ }
1278
+ /**
1279
+ * The substrate-pack body as a stream. Rows are positioned up front, a batch
1280
+ * at a time, so an encode error still fails the request before any byte is sent.
1281
+ */
1282
+ async function packEnvelopeStream(envelope, ctx) {
1283
+ const data = {};
1284
+ for (const [key, value] of Object.entries(envelope.data)) {
1285
+ if (envelope.shapes[key] !== "list" || !Array.isArray(value)) {
1286
+ data[key] = positionValue(envelope, ctx, key);
1287
+ continue;
1288
+ }
1289
+ const rows = [];
1290
+ for (let i = 0; i < value.length; i += ROWS_PER_CHUNK) {
1291
+ if (i > 0) await nextTurn();
1292
+ const part = positionValue(envelope, ctx, key, value.slice(i, i + ROWS_PER_CHUNK));
1293
+ for (const r of part) rows.push(r);
1294
+ }
1295
+ data[key] = rows;
1296
+ }
1297
+ return partsStream(packEnvelopeParts(withData(envelope, data), ROWS_PER_CHUNK));
1298
+ }
1299
+ function partsStream(parts) {
1300
+ const encoder = new TextEncoder();
1301
+ return new ReadableStream({ async pull(controller) {
1302
+ await nextTurn();
1303
+ const next = parts.next();
1304
+ if (next.done) controller.close();
1305
+ else controller.enqueue(typeof next.value === "string" ? encoder.encode(next.value) : next.value);
1306
+ } });
1307
+ }
1308
+ function nextTurn() {
1309
+ return new Promise((resolve) => setImmediate(resolve));
1310
+ }
1311
+ /** `JSON.stringify(projectEnvelope(envelope, frame))` in pieces, a long row list `ROWS_PER_CHUNK` rows per piece. */
1312
+ function* jsonParts(envelope, frame) {
1313
+ yield "{";
1314
+ let sep = "";
1315
+ for (const [k, v] of Object.entries(envelope)) {
1316
+ if (k !== "data") {
1317
+ const s = stringifyJson(v);
1318
+ if (s === void 0) continue;
1319
+ yield `${sep}${JSON.stringify(k)}:${s}`;
1320
+ sep = ",";
1321
+ continue;
1322
+ }
1323
+ yield `${sep}"data":{`;
1324
+ sep = ",";
1325
+ let dsep = "";
1326
+ for (const [key, value] of Object.entries(envelope.data)) {
1327
+ const project = rowProjector(envelope, frame, key);
1328
+ if (!Array.isArray(value) || value.length <= ROWS_PER_CHUNK) {
1329
+ const s = stringifyJson(Array.isArray(value) ? value.map(project) : project(value, 0));
1330
+ if (s === void 0) continue;
1331
+ yield `${dsep}${JSON.stringify(key)}:${s}`;
1332
+ dsep = ",";
1333
+ continue;
1334
+ }
1335
+ yield `${dsep}${JSON.stringify(key)}:[`;
1336
+ dsep = ",";
1337
+ for (let i = 0; i < value.length; i += ROWS_PER_CHUNK) {
1338
+ const chunk = stringifyJson(value.slice(i, i + ROWS_PER_CHUNK).map((row, j) => project(row, i + j)));
1339
+ yield `${i === 0 ? "" : ","}${chunk.slice(1, -1)}`;
1340
+ }
1341
+ yield "]";
1342
+ }
1343
+ yield "}";
1344
+ }
1345
+ yield "}";
1346
+ }
1347
+
1243
1348
  //#endregion
1244
1349
  //#region ../../packages/substrate-compose/src/routes/helpers.ts
1245
1350
  /**
@@ -1255,7 +1360,7 @@ function jsonResponse(status, value, extraHeaders) {
1255
1360
  ...JSON_HEADERS,
1256
1361
  ...extraHeaders
1257
1362
  },
1258
- body: Buffer.from(JSON.stringify(value), "utf8")
1363
+ body: Buffer.from(stringifyJson(value), "utf8")
1259
1364
  };
1260
1365
  }
1261
1366
  function error400(message) {
@@ -1405,20 +1510,25 @@ function readAcceptHeader(req) {
1405
1510
  * msgpack wrapper. This handles error-only envelopes (unqualified/unknown_name)
1406
1511
  * without a schema lookup.
1407
1512
  */
1408
- function serializeEnvelope(req, envelope, engine, frame, opts = {}) {
1513
+ async function serializeEnvelope(req, envelope, engine, frame, opts = {}) {
1409
1514
  if (!acceptsPack(readAcceptHeader(req))) {
1515
+ if (streamsRows(envelope)) return {
1516
+ status: 200,
1517
+ headers: JSON_HEADERS,
1518
+ body: jsonEnvelopeStream(envelope, frame)
1519
+ };
1410
1520
  const projected = projectEnvelope(envelope, frame);
1411
1521
  return {
1412
1522
  status: 200,
1413
1523
  headers: JSON_HEADERS,
1414
- body: Buffer.from(JSON.stringify(projected), "utf8")
1524
+ body: Buffer.from(stringifyJson(projected), "utf8")
1415
1525
  };
1416
1526
  }
1417
1527
  const ctx = buildEncodeCtx(engine, frame, opts);
1418
1528
  return {
1419
1529
  status: 200,
1420
1530
  headers: PACK_HEADERS,
1421
- body: encodeEnvelope(envelope, ctx)
1531
+ body: streamsRows(envelope) ? await packEnvelopeStream(envelope, ctx) : encodeEnvelope(envelope, ctx)
1422
1532
  };
1423
1533
  }
1424
1534
  function buildEncodeCtx(engine, frame, opts) {
@@ -1898,6 +2008,8 @@ const STRING_OPS$1 = [
1898
2008
  "contains",
1899
2009
  "startsWith",
1900
2010
  "endsWith",
2011
+ "like",
2012
+ "notLike",
1901
2013
  "in",
1902
2014
  "nin"
1903
2015
  ];
@@ -1938,6 +2050,9 @@ const JSON_PATH_OPS$1 = [
1938
2050
  function fullBuiltinOperators() {
1939
2051
  return {
1940
2052
  "scalar.number": [...NUMBER_OPS$1],
2053
+ "scalar.int16": [...NUMBER_OPS$1],
2054
+ "scalar.int32": [...NUMBER_OPS$1],
2055
+ "scalar.int64": [...NUMBER_OPS$1],
1941
2056
  "scalar.string": [...STRING_OPS$1],
1942
2057
  "scalar.boolean": [...BOOLEAN_OPS$1],
1943
2058
  "scalar.date": [...NUMBER_OPS$1],
@@ -1964,7 +2079,7 @@ var CursorDecodeError = class extends ResolverFrameError {
1964
2079
  }
1965
2080
  };
1966
2081
  function encodeCursor(input) {
1967
- const json = JSON.stringify(input);
2082
+ const json = stringifyJson(input);
1968
2083
  return Buffer.from(json, "utf8").toString("base64url");
1969
2084
  }
1970
2085
  const orderText = (order) => order.map(([f, d]) => `${f} ${d}`).join(", ");
@@ -2021,168 +2136,508 @@ function normalizeOrderBy(orderBy) {
2021
2136
  }
2022
2137
 
2023
2138
  //#endregion
2024
- //#region ../../packages/substrate-filter/src/extension-operators.ts
2139
+ //#region ../../packages/substrate-filter/src/regex-ast.ts
2140
+ function parse(pattern) {
2141
+ const cps = Array.from(pattern, (c) => c.codePointAt(0));
2142
+ let i = 0;
2143
+ let groups = 0;
2144
+ let reps = 0;
2145
+ const ch = (c) => c.codePointAt(0);
2146
+ const peek = () => cps[i];
2147
+ const alt = () => {
2148
+ const items = [seq()];
2149
+ while (peek() === ch("|")) {
2150
+ i++;
2151
+ items.push(seq());
2152
+ }
2153
+ return items.length === 1 ? items[0] : {
2154
+ t: "alt",
2155
+ items
2156
+ };
2157
+ };
2158
+ const seq = () => {
2159
+ const items = [];
2160
+ for (;;) {
2161
+ const c = peek();
2162
+ if (c === void 0 || c === ch("|") || c === ch(")")) break;
2163
+ items.push(quant(atom()));
2164
+ }
2165
+ return {
2166
+ t: "cat",
2167
+ items
2168
+ };
2169
+ };
2170
+ const atom = () => {
2171
+ const c = cps[i++];
2172
+ if (c === ch("(")) {
2173
+ let cap = null;
2174
+ if (peek() === ch("?")) i += 2;
2175
+ else cap = groups++;
2176
+ const body = alt();
2177
+ i++;
2178
+ return {
2179
+ t: "group",
2180
+ cap,
2181
+ body
2182
+ };
2183
+ }
2184
+ if (c === ch("[")) return cls();
2185
+ if (c === ch(".")) return { t: "any" };
2186
+ if (c === ch("^")) return { t: "bol" };
2187
+ if (c === ch("$")) return { t: "eol" };
2188
+ if (c === ch("\\")) return {
2189
+ t: "char",
2190
+ c: cps[i++]
2191
+ };
2192
+ return {
2193
+ t: "char",
2194
+ c
2195
+ };
2196
+ };
2197
+ const cls = () => {
2198
+ const neg = peek() === ch("^");
2199
+ if (neg) i++;
2200
+ const ranges = [];
2201
+ const cchar = () => {
2202
+ const c = cps[i++];
2203
+ return c === ch("\\") ? cps[i++] : c;
2204
+ };
2205
+ while (peek() !== ch("]")) {
2206
+ const lo = cchar();
2207
+ if (peek() === ch("-") && cps[i + 1] !== ch("]")) {
2208
+ i++;
2209
+ ranges.push([lo, cchar()]);
2210
+ } else ranges.push([lo, lo]);
2211
+ }
2212
+ i++;
2213
+ return {
2214
+ t: "class",
2215
+ neg,
2216
+ ranges
2217
+ };
2218
+ };
2219
+ const quant = (body) => {
2220
+ const c = peek();
2221
+ const simple = {
2222
+ [ch("*")]: [0, Number.POSITIVE_INFINITY],
2223
+ [ch("+")]: [1, Number.POSITIVE_INFINITY],
2224
+ [ch("?")]: [0, 1]
2225
+ };
2226
+ const bounds = c === void 0 ? void 0 : simple[c];
2227
+ if (bounds) {
2228
+ i++;
2229
+ return {
2230
+ t: "rep",
2231
+ body,
2232
+ min: bounds[0],
2233
+ max: bounds[1],
2234
+ id: reps++
2235
+ };
2236
+ }
2237
+ if (c !== ch("{")) return body;
2238
+ const close = cps.indexOf(ch("}"), i);
2239
+ const [lo, comma, hi] = String.fromCodePoint(...cps.slice(i + 1, close)).split(/(,)/);
2240
+ i = close + 1;
2241
+ const min = Number(lo);
2242
+ return {
2243
+ t: "rep",
2244
+ body,
2245
+ min,
2246
+ max: comma ? hi ? Number(hi) : Number.POSITIVE_INFINITY : min,
2247
+ id: reps++
2248
+ };
2249
+ };
2250
+ return {
2251
+ node: alt(),
2252
+ groups,
2253
+ reps
2254
+ };
2255
+ }
2256
+ /** True when the node can match the empty string. */
2257
+ function nullable(n) {
2258
+ switch (n.t) {
2259
+ case "bol":
2260
+ case "eol": return true;
2261
+ case "group": return nullable(n.body);
2262
+ case "cat": return n.items.every(nullable);
2263
+ case "alt": return n.items.some(nullable);
2264
+ case "rep": return n.min === 0 || nullable(n.body);
2265
+ default: return false;
2266
+ }
2267
+ }
2268
+ /** The number of instructions the matcher emits for a node (counted repeats are unrolled). */
2269
+ function nodeSize(n) {
2270
+ switch (n.t) {
2271
+ case "group": return nodeSize(n.body) + (n.cap === null ? 0 : 2);
2272
+ case "cat": return n.items.reduce((s, x) => s + nodeSize(x), 0);
2273
+ case "alt": return n.items.reduce((s, x) => s + nodeSize(x), 0) + 2 * (n.items.length - 1);
2274
+ case "rep": {
2275
+ const b = nodeSize(n.body);
2276
+ const opt = b + (nullable(n.body) ? 2 : 0);
2277
+ const tail = n.max === Number.POSITIVE_INFINITY ? opt + 2 : (n.max - n.min) * (opt + 1);
2278
+ return n.min * b + tail;
2279
+ }
2280
+ default: return 1;
2281
+ }
2282
+ }
2283
+ /** Instructions in a whole program: the node plus the two capture saves and the match. */
2284
+ /**
2285
+ * True when the pattern has both a capturing group and an alternation. Postgres
2286
+ * then assigns captures by POSIX subexpression rules the VM does not follow, so
2287
+ * `regexpReplace` refuses it.
2288
+ */
2289
+ function capturesWithAlternation(pattern) {
2290
+ const { node, groups } = parse(pattern);
2291
+ const alt = (n) => n.t === "alt" || (n.t === "group" || n.t === "rep") && alt(n.body) || n.t === "cat" && n.items.some(alt);
2292
+ return groups > 0 && alt(node);
2293
+ }
2294
+ const programSize = (n) => nodeSize(n) + 3;
2295
+
2296
+ //#endregion
2297
+ //#region ../../packages/substrate-filter/src/regex-subset.ts
2025
2298
  /**
2026
- * Extension-operator registry. Spec: §5.2.
2299
+ * The portable regex subset: the syntax on which Postgres (POSIX ARE) and
2300
+ * JavaScript agree.
2027
2301
  *
2028
- * Substrate plugins (e.g. substrate-recall's `embeddingSimilar`) register custom
2029
- * where-clause operators here at compose-time. The registry is module-scope
2030
- * state shared between:
2031
- * - substrate-core's filter validator (accepts the operator key during
2032
- * where-clause validation)
2033
- * - substrate-dataset-pg's pre-resolver (dispatches op.execute(...) before SQL
2034
- * translation, substitutes the result into an `id IN (...)` clause)
2302
+ * regex := alt
2303
+ * alt := seq ('|' seq)*
2304
+ * seq := (atom quant?)*
2305
+ * atom := '(' '?:'? alt ')' | '[' '^'? item+ ']' | '.' | '^' | '$'
2306
+ * | '\' esc | char
2307
+ * item := cchar ('-' cchar)? (a range may not chain, as in a-c-e)
2308
+ * cchar := '\' (esc | '-') | any char but ] [ \ newline
2309
+ * quant := '*' | '+' | '?' | '{' n '}' | '{' n ',' '}' | '{' n ',' m '}' (n, m <= 255)
2310
+ * esc := one of ^ $ \ . * + ? ( ) [ ] { } | /
2311
+ * char := any character but ( ) [ ] { } | * + ? \ newline
2035
2312
  *
2036
- * Tests should call `clearExtensionOperators()` in afterEach to prevent
2037
- * cross-test leakage.
2313
+ * The pattern is read by code point. `.` matches a newline on both engines
2314
+ * (Postgres by default, JavaScript under the `s` flag), so JavaScript compiles
2315
+ * it with flags `us`; every accepted pattern constructs under `new RegExp(p, 'us')`.
2038
2316
  *
2039
- * The backing Maps hang off `globalThis` under `Symbol.for` keys because a
2040
- * process can hold more than one copy of this package (a plugin resolving its
2041
- * own `substrate-filter`); module-scope Maps would split the registry, and an
2042
- * operator registered through one copy would be silently unknown to the other.
2317
+ * Bounded for linear-ish matching: a pattern is at most 256 code points, and a
2318
+ * quantifier may not apply to a group that itself contains a quantifier or an
2319
+ * alternation (star height at most 1), so `(a+)+`, `(a|aa)*` and `(?:a*)*` are refused.
2043
2320
  *
2044
- * The keys carry `.v1` so two copies with incompatible `FilterOperatorDef`
2045
- * shapes fall back to separate registries rather than reading each other's
2046
- * entries. Bump the suffix when `FilterOperatorDef` changes shape.
2047
- */
2048
- const REGISTRY_KEY = Symbol.for("substrate.filter.extensionOperators.v1");
2049
- const OWNERS_KEY = Symbol.for("substrate.filter.computedFieldOwners.v1");
2050
- const host = globalThis;
2051
- const extensionOperators = host[REGISTRY_KEY] ?? /* @__PURE__ */ new Map();
2052
- host[REGISTRY_KEY] = extensionOperators;
2053
- /**
2054
- * computedField → owning operator name. An operator may declare
2055
- * `computedFields` (e.g. embeddingSimilar owns `_score` + `_vector`): fields
2056
- * that only exist on a row when the operator runs. The engine's computed-field
2057
- * gate reads this map to refuse projecting a computed field without its operator in
2058
- * the where-clause.
2059
- */
2060
- const computedFieldOwners = host[OWNERS_KEY] ?? /* @__PURE__ */ new Map();
2061
- host[OWNERS_KEY] = computedFieldOwners;
2062
- /** Where-clause keys the grammar already owns: combinators, ids and row metadata. */
2063
- function isReservedName(name) {
2064
- return [
2065
- "AND",
2066
- "OR",
2067
- "NOT",
2068
- "shortId",
2069
- "_metadata"
2070
- ].includes(name) || Object.hasOwn(METADATA_FILTER_FIELDS, name) || Object.hasOwn(METADATA_AUTHOR_FIELDS, name);
2071
- }
2072
- /**
2073
- * Register a custom where-clause operator under `name`. Throws if `name` is a
2074
- * reserved where-clause key or already registered, or if any of its
2075
- * `computedFields` is already claimed by another operator. `name` comes from the Record key in
2076
- * `KernelPlugin.filterOperators`.
2321
+ * Its compiled program is bounded too: counted repeats are unrolled, and a pattern
2322
+ * whose program would exceed 2,000 instructions is refused ('program too large').
2077
2323
  *
2078
- * Computed-field collisions throw rather than overwrite: silently overwriting
2079
- * ownership would make the computed-field gate name the wrong operator.
2080
- */
2081
- function registerExtensionOperator(name, op) {
2082
- if (isReservedName(name)) throw new Error(`Filter operator name '${name}' is reserved by the where-clause grammar`);
2083
- if (extensionOperators.has(name)) throw new Error(`Filter operator '${name}' already registered`);
2084
- for (const cf of op.computedFields ?? []) {
2085
- const existing = computedFieldOwners.get(cf);
2086
- if (existing !== void 0) throw new Error(`Computed field '${cf}' is already owned by operator '${existing}'; '${name}' cannot also claim it`);
2087
- }
2088
- extensionOperators.set(name, op);
2089
- for (const cf of op.computedFields ?? []) computedFieldOwners.set(cf, name);
2090
- }
2091
- /**
2092
- * The operator name owning a computed projection field, or undefined when no
2093
- * registered operator claims it. Used by the engine's computed-field gate to refuse
2094
- * projecting a computed field without its operator present in where.
2095
- */
2096
- function computedFieldOwner(field) {
2097
- return computedFieldOwners.get(field);
2098
- }
2099
- /**
2100
- * True when any registered operator declares computed fields. Common-case
2101
- * fast-path for the engine's computed-field gate (no semantic operator composed → skip
2102
- * the per-frame fields walk entirely); the per-field `computedFieldOwner`
2103
- * check remains authoritative.
2104
- */
2105
- function hasComputedFields() {
2106
- return computedFieldOwners.size > 0;
2107
- }
2108
- /** Look up a registered extension operator by name. Returns undefined when absent. */
2109
- function getExtensionOperator(name) {
2110
- return extensionOperators.get(name);
2111
- }
2112
- /**
2113
- * Sorted list of registered extension-operator names. Surfaced by
2114
- * `/substrate/v1/onboard` so HTTP consumers can branch on "is `embeddingSimilar`
2115
- * composed?" without sniffing error strings from a failed query.
2116
- */
2117
- function listExtensionOperators() {
2118
- return Array.from(extensionOperators.keys()).sort();
2119
- }
2120
- /** Remove `name` and the computed fields it owns. A no-op when `name` is not registered. */
2121
- function unregisterExtensionOperator(name) {
2122
- const op = extensionOperators.get(name);
2123
- if (op === void 0) return;
2124
- extensionOperators.delete(name);
2125
- for (const cf of op.computedFields ?? []) if (computedFieldOwners.get(cf) === name) computedFieldOwners.delete(cf);
2126
- }
2127
- /**
2128
- * True when any key in the where-tree (root, nested under AND/OR/NOT, or
2129
- * inside a struct-field sub-clause) is a registered extension operator.
2130
- * Used by the subscribe path to refuse semantic filters at registration —
2131
- * extension operators have no incremental evaluation, so a subscription
2132
- * carrying one would silently degrade. Leaf predicate objects ({ eq: 'x' }) recurse harmlessly: their
2133
- * keys are not registered operators and their values are not objects.
2134
- */
2135
- function whereContainsExtensionOperator(where) {
2136
- if (Array.isArray(where)) return where.some((w) => whereContainsExtensionOperator(w));
2137
- if (where === null || typeof where !== "object") return false;
2138
- for (const [key, value] of Object.entries(where)) {
2139
- if (key === "AND" || key === "OR") {
2140
- if (Array.isArray(value) && value.some((w) => whereContainsExtensionOperator(w))) return true;
2141
- continue;
2324
+ * Refused: classes such as `\d`, backreferences, lookaround, inline flags,
2325
+ * lazy quantifiers, POSIX bracket classes, quantified anchors, newlines.
2326
+ */
2327
+ const MAX_REPEAT = 255;
2328
+ const MAX_PATTERN = 256;
2329
+ /** The most instructions a pattern may compile to once counted repeats are unrolled. */
2330
+ const MAX_PROGRAM = 2e3;
2331
+ function checkRegexSubset(pattern) {
2332
+ if (/[\r\n]/.test(pattern)) return "a newline is not allowed in a pattern";
2333
+ const cps = Array.from(pattern);
2334
+ if (cps.length > MAX_PATTERN) return `a pattern longer than ${MAX_PATTERN} code points`;
2335
+ let i = 0;
2336
+ let marks = 0;
2337
+ const fail = (why) => {
2338
+ throw new RegexRefusal(`${why} at position ${i}`);
2339
+ };
2340
+ const ESCAPABLE = "^$\\.*+?()[]{}|/";
2341
+ const escapable = (c, inClass = false) => c !== void 0 && (ESCAPABLE.includes(c) || inClass && c === "-");
2342
+ const alt = (depth) => {
2343
+ seq(depth);
2344
+ while (cps[i] === "|") {
2345
+ i++;
2346
+ marks++;
2347
+ seq(depth);
2142
2348
  }
2143
- if (key === "NOT") {
2144
- if (whereContainsExtensionOperator(value)) return true;
2145
- continue;
2349
+ };
2350
+ const seq = (depth) => {
2351
+ for (;;) {
2352
+ const c = cps[i];
2353
+ if (c === void 0 || c === "|" || c === ")" && depth > 0) return;
2354
+ let quantifiable = true;
2355
+ let before = marks;
2356
+ let group = false;
2357
+ if (c === "(") {
2358
+ i++;
2359
+ if (cps[i] === "?") {
2360
+ if (cps.slice(i, i + 2).join("") !== "?:") fail("only the non-capturing group (?: is allowed after (?");
2361
+ i += 2;
2362
+ }
2363
+ before = marks;
2364
+ group = true;
2365
+ alt(depth + 1);
2366
+ if (cps[i] !== ")") fail("unclosed group");
2367
+ i++;
2368
+ } else if (c === "[") cls();
2369
+ else if (c === "^" || c === "$") {
2370
+ quantifiable = false;
2371
+ i++;
2372
+ } else if (c === "\\") {
2373
+ const n = cps[i + 1];
2374
+ if (!escapable(n)) fail("only an escaped syntax character is allowed (no \\d, \\w, \\1)");
2375
+ i += 2;
2376
+ } else if (c === ".") i++;
2377
+ else if (")]}{*+?".includes(c)) fail(`unexpected '${c}'`);
2378
+ else i++;
2379
+ const risky = group && marks > before;
2380
+ if (quant(quantifiable) && risky) fail("a quantifier on a group that contains a quantifier or alternation");
2146
2381
  }
2147
- if (getExtensionOperator(key) !== void 0) return true;
2148
- if (value !== null && typeof value === "object" && !Array.isArray(value)) {
2149
- if (whereContainsExtensionOperator(value)) return true;
2382
+ };
2383
+ const quant = (quantifiable) => {
2384
+ const c = cps[i];
2385
+ if (c === "*" || c === "+" || c === "?") i++;
2386
+ else if (c === "{") {
2387
+ const m = /^\{(\d+)(?:(,)(\d*))?\}/.exec(cps.slice(i).join(""));
2388
+ if (!m) fail("malformed {n,m} quantifier");
2389
+ else {
2390
+ if (Number(m[1]) > MAX_REPEAT || Number(m[3] || 0) > MAX_REPEAT) fail(`a repetition count above ${MAX_REPEAT}`);
2391
+ if (m[3] && Number(m[3]) < Number(m[1])) fail("{n,m} with m below n");
2392
+ i += m[0].length;
2393
+ }
2394
+ } else return false;
2395
+ marks++;
2396
+ if (!quantifiable) fail("an anchor cannot be quantified");
2397
+ const n = cps[i];
2398
+ if (n === "?") fail("lazy quantifiers are not allowed");
2399
+ if (n === "*" || n === "+" || n === "{") fail("a quantifier cannot follow a quantifier");
2400
+ return true;
2401
+ };
2402
+ const cls = () => {
2403
+ i++;
2404
+ if (cps[i] === "^") i++;
2405
+ let items = 0;
2406
+ const cchar = () => {
2407
+ const c = cps[i];
2408
+ if (c === void 0) return fail("unclosed class");
2409
+ if (c === "[") return fail("'[' is not allowed in a class (no POSIX classes)");
2410
+ if (c === "\\") {
2411
+ const n = cps[i + 1];
2412
+ if (!escapable(n, true)) return fail("only an escaped syntax character is allowed in a class");
2413
+ i += 2;
2414
+ return n;
2415
+ }
2416
+ i++;
2417
+ return c;
2418
+ };
2419
+ while (cps[i] !== "]") {
2420
+ const lo = cchar();
2421
+ items++;
2422
+ if (cps[i] === "-" && cps[i + 1] !== "]" && cps[i + 1] !== void 0) {
2423
+ i++;
2424
+ const hi = cchar();
2425
+ if (lo.codePointAt(0) > hi.codePointAt(0)) fail("class range out of order");
2426
+ if (cps[i] === "-" && cps[i + 1] !== "]") fail("chained class ranges such as a-c-e are not allowed");
2427
+ }
2150
2428
  }
2429
+ if (items === 0) fail("empty class");
2430
+ i++;
2431
+ };
2432
+ try {
2433
+ alt(0);
2434
+ if (i < cps.length) fail("unbalanced )");
2435
+ if (programSize(parse(pattern).node) > 2e3) fail("program too large");
2436
+ return null;
2437
+ } catch (e) {
2438
+ if (e instanceof RegexRefusal) return e.message;
2439
+ throw e;
2151
2440
  }
2152
- return false;
2153
2441
  }
2154
- /**
2155
- * True when the where-tree contains a key equal to `opName` in operator
2156
- * position (root, AND/OR/NOT combinator, struct-field sub-clause, or array
2157
- * element). The named variant of `whereContainsExtensionOperator`: the
2158
- * computed-field gate needs the operator that OWNS the projected field present,
2159
- * not merely SOME registered operator. Same structural walk; matches by name
2160
- * rather than registry membership.
2161
- */
2162
- function whereContainsOperator(where, opName) {
2163
- if (Array.isArray(where)) return where.some((w) => whereContainsOperator(w, opName));
2164
- if (where === null || typeof where !== "object") return false;
2165
- for (const [key, value] of Object.entries(where)) {
2166
- if (key === "AND" || key === "OR") {
2167
- if (Array.isArray(value) && value.some((w) => whereContainsOperator(w, opName))) return true;
2168
- continue;
2442
+ var RegexRefusal = class extends Error {};
2443
+
2444
+ //#endregion
2445
+ //#region ../../packages/substrate-filter/src/expr-check.ts
2446
+ /**
2447
+ * Type checker for read-grammar expressions. Infers the type of every node,
2448
+ * refuses mismatches, unknown functions and fields, and enforces the per-
2449
+ * expression limits (`EXPR_LIMITS`). `int64` mixed with `number` widens to
2450
+ * `number`; a safe-integer literal beside an int64 stays int64.
2451
+ */
2452
+ const SIGS = new Map(EXPR_FUNCTIONS.map((s) => [s.name, s]));
2453
+ const isNumeric = (t) => t === "number" || t === "int64";
2454
+ var Refusal = class extends Error {
2455
+ at;
2456
+ constructor(message, at) {
2457
+ super(message);
2458
+ this.at = at;
2459
+ }
2460
+ };
2461
+ const LIKE_TRAILING_ESCAPE = "LIKE pattern must not end with escape character";
2462
+ /** Whether a LIKE pattern ends in an unescaped backslash. */
2463
+ const endsWithEscape = (text) => /(^|[^\\])(\\\\)*\\$/.test(text);
2464
+ function checkExpr(expr, scope, path) {
2465
+ let nodes = 0;
2466
+ const refuse = (msg, at) => {
2467
+ throw new Refusal(`${at.join(".")}: ${msg}`, at);
2468
+ };
2469
+ const checkDepth = (depth, at) => {
2470
+ if (depth > EXPR_LIMITS.maxDepth) refuse(`expression is deeper than maxDepth (${EXPR_LIMITS.maxDepth})`, at);
2471
+ };
2472
+ const count = (at) => {
2473
+ if (++nodes > EXPR_LIMITS.maxNodesPerExpr) refuse(`expression has more than maxNodesPerExpr (${EXPR_LIMITS.maxNodesPerExpr}) nodes`, at);
2474
+ };
2475
+ const unify = (items, what, at) => {
2476
+ const types = items.map((x) => x.type).filter((t) => t !== null);
2477
+ if (types.length === 0) return refuse(`${what}: cannot infer a type from null alone`, at);
2478
+ if (types.every(isNumeric)) {
2479
+ if (types.includes("int64")) {
2480
+ if (items.some((x) => x.bigLiteral)) refuse(`${what}: a number beside an int64 must be a safe integer`, at);
2481
+ return items.every((x) => x.type === "int64" || x.type === null || x.intLiteral) ? "int64" : "number";
2482
+ }
2483
+ return "number";
2169
2484
  }
2170
- if (key === "NOT") {
2171
- if (whereContainsOperator(value, opName)) return true;
2172
- continue;
2485
+ const first = types[0];
2486
+ if (types.some((t) => t !== first)) refuse(`${what}: arguments must share a type, got ${types.join(" and ")}`, at);
2487
+ return first;
2488
+ };
2489
+ const need = (a, want, what, at) => {
2490
+ if (a.type === null) return;
2491
+ if (!(want === "number" ? isNumeric(a.type) : a.type === want)) refuse(`${what}: expected ${want}, got ${a.type}`, at);
2492
+ };
2493
+ const lit = (arg, what, at) => {
2494
+ if (typeof arg === "object" && arg !== null && typeof arg.lit === "string") return arg.lit;
2495
+ return refuse(`${what}: expected a { lit } string`, at);
2496
+ };
2497
+ const walk = (e, at, depth) => {
2498
+ if (depth > EXPR_LIMITS.maxDepth) refuse(`expression is deeper than maxDepth (${EXPR_LIMITS.maxDepth})`, at);
2499
+ count(at);
2500
+ if (e === null) return {
2501
+ t: { type: null },
2502
+ depth
2503
+ };
2504
+ if (typeof e === "boolean") return {
2505
+ t: { type: "boolean" },
2506
+ depth
2507
+ };
2508
+ if (typeof e === "number") {
2509
+ if (!Number.isFinite(e)) return refuse("number literal must be finite", at);
2510
+ return {
2511
+ t: {
2512
+ type: "number",
2513
+ intLiteral: Number.isSafeInteger(e),
2514
+ bigLiteral: Number.isInteger(e) && !Number.isSafeInteger(e)
2515
+ },
2516
+ depth
2517
+ };
2173
2518
  }
2174
- if (key === opName) return true;
2175
- if (value !== null && typeof value === "object" && !Array.isArray(value)) {
2176
- if (whereContainsOperator(value, opName)) return true;
2519
+ if (typeof e === "string") {
2520
+ const t = scope.field(e);
2521
+ if (t === void 0) return refuse(`unknown field '${e}'`, at);
2522
+ return {
2523
+ t: { type: t },
2524
+ depth
2525
+ };
2177
2526
  }
2178
- }
2179
- return false;
2180
- }
2181
-
2182
- //#endregion
2183
- //#region ../../packages/substrate-filter/src/json-path.ts
2184
- /**
2185
- * Path-addressed predicates on json fields.
2527
+ if (typeof e !== "object" || Array.isArray(e)) return refuse("not an expression", at);
2528
+ const keys = Object.keys(e);
2529
+ if (keys.length !== 1) return refuse(`an expression object has exactly one key, got ${keys.length}`, at);
2530
+ const key = keys[0];
2531
+ const val = e[key];
2532
+ if (key === "lit") return typeof val === "string" ? {
2533
+ t: { type: "string" },
2534
+ depth
2535
+ } : refuse("lit takes a string", at);
2536
+ if (key === "int64") return typeof val === "string" && parseInt64(val) !== void 0 ? {
2537
+ t: { type: "int64" },
2538
+ depth
2539
+ } : refuse(`int64 takes a decimal string within the int64 range, got ${JSON.stringify(val)}`, at);
2540
+ const sig = SIGS.get(key);
2541
+ if (!sig) return refuse(`unknown function '${key}'`, at);
2542
+ if (!Array.isArray(val)) return refuse(`'${key}' takes an array of arguments`, at);
2543
+ const fnAt = [...at, key];
2544
+ let maxDepth = depth;
2545
+ const arg = (a, idx) => {
2546
+ const r = walk(a, [...fnAt, String(idx)], depth + 1);
2547
+ maxDepth = Math.max(maxDepth, r.depth);
2548
+ return r.t;
2549
+ };
2550
+ const arity = (n) => {
2551
+ const [lo, hi] = Array.isArray(n) ? [n[0], n[1]] : [n, n];
2552
+ if (val.length < lo || hi !== void 0 && val.length > hi) refuse(`'${key}' takes ${hi === lo ? lo : `at least ${lo}`} argument(s), got ${val.length}`, fnAt);
2553
+ };
2554
+ const result = (type) => ({
2555
+ t: { type },
2556
+ depth: maxDepth
2557
+ });
2558
+ const where = (i) => [...fnAt, String(i)];
2559
+ if (key === "case") {
2560
+ arity([2]);
2561
+ const branches = [];
2562
+ for (let i = 0; i < val.length - 1; i++) {
2563
+ const pair = val[i];
2564
+ if (!Array.isArray(pair) || pair.length !== 2) return refuse(`'case' branch ${i} must be [cond, then]`, where(i));
2565
+ need(arg(pair[0], `${i}.0`), "boolean", `'case' condition ${i}`, where(i));
2566
+ branches.push(arg(pair[1], `${i}.1`));
2567
+ }
2568
+ branches.push(arg(val[val.length - 1], val.length - 1));
2569
+ return result(unify(branches, "'case' branches", fnAt));
2570
+ }
2571
+ if (key === "coalesce") {
2572
+ arity([1]);
2573
+ return result(unify(val.map((a, i) => arg(a, i)), "'coalesce'", fnAt));
2574
+ }
2575
+ if (key === "in") {
2576
+ arity([2]);
2577
+ unify(val.map((a, i) => arg(a, i)), "'in'", fnAt);
2578
+ return result("boolean");
2579
+ }
2580
+ if (key === "and" || key === "or") {
2581
+ arity([1]);
2582
+ for (const [i, a] of val.entries()) need(arg(a, i), "boolean", `'${key}'`, where(i));
2583
+ return result("boolean");
2584
+ }
2585
+ if (key === "concat") {
2586
+ arity([1]);
2587
+ for (const [i, a] of val.entries()) need(arg(a, i), "string", "'concat'", where(i));
2588
+ return result("string");
2589
+ }
2590
+ const kinds = sig.args;
2591
+ arity(kinds.length);
2592
+ const group = [];
2593
+ for (const [i, a] of val.entries()) {
2594
+ const kind = kinds[i];
2595
+ if (kind === "unit" || kind === "pattern" || kind === "likePattern") {
2596
+ const text = lit(a, `'${key}' ${kind}`, where(i));
2597
+ checkDepth(depth + 1, where(i));
2598
+ count(where(i));
2599
+ if (kind === "unit" && !DATE_UNITS.includes(text)) refuse(`'${key}' unit '${text}' is not one of ${DATE_UNITS.join(", ")}`, where(i));
2600
+ if (kind === "likePattern" && endsWithEscape(text)) refuse(LIKE_TRAILING_ESCAPE, where(i));
2601
+ if (kind === "pattern") {
2602
+ const why = checkRegexSubset(text);
2603
+ if (why) refuse(`'${key}' regex is outside the portable subset: ${why}`, where(i));
2604
+ if (key === "regexpReplace" && capturesWithAlternation(text)) refuse(`'regexpReplace' regex may use capturing groups or '|', not both: the engines pick different captures`, where(i));
2605
+ }
2606
+ maxDepth = Math.max(maxDepth, depth + 1);
2607
+ continue;
2608
+ }
2609
+ const t = arg(a, i);
2610
+ if (kind !== "any" && !(kind === "int64" && t.intLiteral)) need(t, kind, `'${key}' argument ${i}`, where(i));
2611
+ if (kind === "any" || kind === "number" && sig.returns === "any") group.push(t);
2612
+ }
2613
+ if (sig.returns === "any") return result(unify(group, `'${key}'`, fnAt));
2614
+ if (group.length > 1) unify(group, `'${key}'`, fnAt);
2615
+ return result(sig.returns);
2616
+ };
2617
+ try {
2618
+ const { t, depth } = walk(expr, path, 1);
2619
+ if (t.type === null) return refuse("cannot infer a type from null alone", path);
2620
+ return {
2621
+ ok: true,
2622
+ type: t.type,
2623
+ nodes,
2624
+ depth
2625
+ };
2626
+ } catch (e) {
2627
+ if (e instanceof Refusal) return {
2628
+ ok: false,
2629
+ code: "expr_invalid",
2630
+ message: e.message,
2631
+ path: e.at
2632
+ };
2633
+ throw e;
2634
+ }
2635
+ }
2636
+
2637
+ //#endregion
2638
+ //#region ../../packages/substrate-filter/src/json-path.ts
2639
+ /**
2640
+ * Path-addressed predicates on json fields.
2186
2641
  *
2187
2642
  * `{ values: { path: ['year'], gt: 1990 } }`. The data keys live inside the
2188
2643
  * `path` ARRAY, so a key an end user invented — `contains`, `in`, `has` — can
@@ -2196,7 +2651,7 @@ function whereContainsOperator(where, opName) {
2196
2651
  const JSON_PATH_MAX_DEPTH = 16;
2197
2652
  /** Most `in` / `nin` members both substrates accept (pg binds two per member). */
2198
2653
  const JSON_PATH_MAX_IN = 1e4;
2199
- const OPS = new Set(JSON_PATH_OPS$1);
2654
+ const OPS$1 = new Set(JSON_PATH_OPS$1);
2200
2655
  const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
2201
2656
  function isJsonPathPredicate(p) {
2202
2657
  return p !== null && typeof p === "object" && !Array.isArray(p) && Array.isArray(p.path);
@@ -2209,7 +2664,7 @@ function jsonPathProblem(path) {
2209
2664
  }
2210
2665
  /** Why `operand` cannot go with `op` on a json path, or null when it can. */
2211
2666
  function jsonPathOperandProblem(op, operand) {
2212
- if (!OPS.has(op)) return "is not a recognised filter operator";
2667
+ if (!OPS$1.has(op)) return "is not a recognised filter operator";
2213
2668
  if (operand instanceof Date) return "cannot take a Date — json has no date type, pass an ISO string";
2214
2669
  if ((Array.isArray(operand) ? operand : [operand]).some((m) => typeof m === "number" && !Number.isFinite(m))) return "requires finite numbers — json has no NaN or Infinity";
2215
2670
  switch (op) {
@@ -2320,103 +2775,215 @@ function applyJsonPathOp(op, value, operand) {
2320
2775
  }
2321
2776
 
2322
2777
  //#endregion
2323
- //#region ../../packages/substrate-filter/src/pre-resolve-extension-operators.ts
2778
+ //#region ../../packages/substrate-filter/src/expr-scope.ts
2779
+ /** `number`, `int16` and `int32` (as `int64`), `int64`, `string`, `boolean` and `date` fields, and a crossRef's id (a string); json, list and struct fields are not usable. */
2780
+ function exprTypeOfField(def) {
2781
+ if (def === void 0) return void 0;
2782
+ if (def.kind === "crossRef") return "string";
2783
+ if (def.kind !== "scalar") return void 0;
2784
+ if (def.type === "json") return void 0;
2785
+ return def.type === "int16" || def.type === "int32" ? "int64" : def.type;
2786
+ }
2787
+ /**
2788
+ * The type of a date or number metadata name (`createdAt`, `updatedAt`, `seq`), which an
2789
+ * expression reads as metadata; the names are reserved, so no declared field shares them. The
2790
+ * string metadata names are not expression fields.
2791
+ */
2792
+ function metadataExprType(name) {
2793
+ if (typeof name !== "string" || !Object.hasOwn(METADATA_FILTER_FIELDS, name)) return void 0;
2794
+ const t = exprTypeOfField(METADATA_FILTER_FIELDS[name]);
2795
+ return t === "date" || t === "number" ? t : void 0;
2796
+ }
2797
+ const lookups = /* @__PURE__ */ new WeakMap();
2798
+ /**
2799
+ * A stable `fieldType` lookup per `fieldDefOf`: the evaluator keys its per-node
2800
+ * type cache on the lookup, so one read must reuse one.
2801
+ */
2802
+ function fieldTypeLookup(fieldDefOf) {
2803
+ if (fieldDefOf === void 0) return metadataExprType;
2804
+ let f = lookups.get(fieldDefOf);
2805
+ if (f === void 0) {
2806
+ f = (name) => metadataExprType(name) ?? exprTypeOfField(fieldDefOf(name));
2807
+ lookups.set(fieldDefOf, f);
2808
+ }
2809
+ return f;
2810
+ }
2811
+ /**
2812
+ * The expression type of a frame `_agg`'s value: `number` for count, sum and
2813
+ * avg, else the type of the field it reads on the far type. `near` is the seed
2814
+ * type; `fieldDef` resolves any type's field.
2815
+ */
2816
+ function walkAggExprType(spec, near, fieldDef) {
2817
+ const rec = spec;
2818
+ if (Object.hasOwn(rec, "count") || Object.hasOwn(rec, "sum") || Object.hasOwn(rec, "avg")) return "number";
2819
+ const latest = Object.hasOwn(rec, "latest") ? rec.latest : void 0;
2820
+ const field = latest !== void 0 ? latest.value : rec.min ?? rec.max;
2821
+ let far;
2822
+ if (spec.in !== void 0) far = /^[^/]+\/([^./]+)\./.exec(spec.in)?.[1];
2823
+ else {
2824
+ const def = fieldDef(near, spec.out ?? "");
2825
+ far = def?.kind === "crossRef" ? def.type : void 0;
2826
+ }
2827
+ return far === void 0 || typeof field !== "string" ? void 0 : exprTypeOfField(fieldDef(far, field));
2828
+ }
2829
+
2830
+ //#endregion
2831
+ //#region ../../packages/substrate-filter/src/extension-operators.ts
2324
2832
  /**
2325
- * Thrown when a registered extension operator's `execute` resolves to
2326
- * anything other than `{ hits: [...] }`.
2833
+ * Extension-operator registry. Spec: §5.2.
2834
+ *
2835
+ * Substrate plugins (e.g. substrate-recall's `embeddingSimilar`) register custom
2836
+ * where-clause operators here at compose-time. The registry is module-scope
2837
+ * state shared between:
2838
+ * - substrate-core's filter validator (accepts the operator key during
2839
+ * where-clause validation)
2840
+ * - substrate-dataset-pg's pre-resolver (dispatches op.execute(...) before SQL
2841
+ * translation, substitutes the result into an `id IN (...)` clause)
2842
+ *
2843
+ * Tests should call `clearExtensionOperators()` in afterEach to prevent
2844
+ * cross-test leakage.
2845
+ *
2846
+ * The backing Maps hang off `globalThis` under `Symbol.for` keys because a
2847
+ * process can hold more than one copy of this package (a plugin resolving its
2848
+ * own `substrate-filter`); module-scope Maps would split the registry, and an
2849
+ * operator registered through one copy would be silently unknown to the other.
2850
+ *
2851
+ * The keys carry `.v1` so two copies with incompatible `FilterOperatorDef`
2852
+ * shapes fall back to separate registries rather than reading each other's
2853
+ * entries. Bump the suffix when `FilterOperatorDef` changes shape.
2327
2854
  */
2328
- var ExtensionOperatorResultError = class extends Error {
2329
- operator;
2330
- constructor(operator) {
2331
- super(`extension operator '${operator}' must resolve to { hits: [{ id, score, vector? }] }`);
2332
- this.name = "ExtensionOperatorResultError";
2333
- this.operator = operator;
2334
- }
2335
- };
2855
+ const REGISTRY_KEY = Symbol.for("substrate.filter.extensionOperators.v1");
2856
+ const OWNERS_KEY = Symbol.for("substrate.filter.computedFieldOwners.v1");
2857
+ const host = globalThis;
2858
+ const extensionOperators = host[REGISTRY_KEY] ?? /* @__PURE__ */ new Map();
2859
+ host[REGISTRY_KEY] = extensionOperators;
2336
2860
  /**
2337
- * Walks a where-tree, replaces every registered extension-operator entry with
2338
- * an order-preserving `{ id: { in: [...] } }`, and returns BOTH the
2339
- * rewritten where and a `meta` side-channel.
2861
+ * computedField → owning operator name. An operator may declare
2862
+ * `computedFields` (e.g. embeddingSimilar owns `_score` + `_vector`): fields
2863
+ * that only exist on a row when the operator runs. The engine's computed-field
2864
+ * gate reads this map to refuse projecting a computed field without its operator in
2865
+ * the where-clause.
2866
+ */
2867
+ const computedFieldOwners = host[OWNERS_KEY] ?? /* @__PURE__ */ new Map();
2868
+ host[OWNERS_KEY] = computedFieldOwners;
2869
+ /** Where-clause keys the grammar already owns: combinators, ids and row metadata. */
2870
+ function isReservedName(name) {
2871
+ return [
2872
+ "AND",
2873
+ "OR",
2874
+ "NOT",
2875
+ "shortId",
2876
+ "_metadata"
2877
+ ].includes(name) || Object.hasOwn(METADATA_FILTER_FIELDS, name) || Object.hasOwn(METADATA_AUTHOR_FIELDS, name);
2878
+ }
2879
+ /**
2880
+ * Register a custom where-clause operator under `name`. Throws if `name` is a
2881
+ * reserved where-clause key or already registered, or if any of its
2882
+ * `computedFields` is already claimed by another operator. `name` comes from the Record key in
2883
+ * `KernelPlugin.filterOperators`.
2340
2884
  *
2341
- * Returns a new where object — the input is not mutated.
2885
+ * Computed-field collisions throw rather than overwrite: silently overwriting
2886
+ * ownership would make the computed-field gate name the wrong operator.
2342
2887
  */
2343
- async function preResolveExtensionOperatorsDetailed(where, context) {
2344
- const holder = { current: null };
2345
- return {
2346
- where: await walk(where, context, holder),
2347
- meta: holder.current
2348
- };
2888
+ function registerExtensionOperator(name, op) {
2889
+ if (isReservedName(name)) throw new Error(`Filter operator name '${name}' is reserved by the where-clause grammar`);
2890
+ if (extensionOperators.has(name)) throw new Error(`Filter operator '${name}' already registered`);
2891
+ for (const cf of op.computedFields ?? []) {
2892
+ const existing = computedFieldOwners.get(cf);
2893
+ if (existing !== void 0) throw new Error(`Computed field '${cf}' is already owned by operator '${existing}'; '${name}' cannot also claim it`);
2894
+ }
2895
+ extensionOperators.set(name, op);
2896
+ for (const cf of op.computedFields ?? []) computedFieldOwners.set(cf, name);
2349
2897
  }
2350
- /** Recursive tree walk behind {@link preResolveExtensionOperatorsDetailed}. */
2351
- async function walk(where, context, holder) {
2352
- if (where === null || typeof where !== "object" || Array.isArray(where)) return where;
2353
- const keys = Object.keys(where);
2354
- if (keys.length === 0) return where;
2355
- const out = {};
2356
- const idClauses = [];
2357
- for (const key of keys) {
2358
- const value = where[key];
2898
+ /**
2899
+ * The operator name owning a computed projection field, or undefined when no
2900
+ * registered operator claims it. Used by the engine's computed-field gate to refuse
2901
+ * projecting a computed field without its operator present in where.
2902
+ */
2903
+ function computedFieldOwner(field) {
2904
+ return computedFieldOwners.get(field);
2905
+ }
2906
+ /**
2907
+ * True when any registered operator declares computed fields. Common-case
2908
+ * fast-path for the engine's computed-field gate (no semantic operator composed → skip
2909
+ * the per-frame fields walk entirely); the per-field `computedFieldOwner`
2910
+ * check remains authoritative.
2911
+ */
2912
+ function hasComputedFields() {
2913
+ return computedFieldOwners.size > 0;
2914
+ }
2915
+ /** Look up a registered extension operator by name. Returns undefined when absent. */
2916
+ function getExtensionOperator(name) {
2917
+ return extensionOperators.get(name);
2918
+ }
2919
+ /**
2920
+ * Sorted list of registered extension-operator names. Surfaced by
2921
+ * `/substrate/v1/onboard` so HTTP consumers can branch on "is `embeddingSimilar`
2922
+ * composed?" without sniffing error strings from a failed query.
2923
+ */
2924
+ function listExtensionOperators() {
2925
+ return Array.from(extensionOperators.keys()).sort();
2926
+ }
2927
+ /** Remove `name` and the computed fields it owns. A no-op when `name` is not registered. */
2928
+ function unregisterExtensionOperator(name) {
2929
+ const op = extensionOperators.get(name);
2930
+ if (op === void 0) return;
2931
+ extensionOperators.delete(name);
2932
+ for (const cf of op.computedFields ?? []) if (computedFieldOwners.get(cf) === name) computedFieldOwners.delete(cf);
2933
+ }
2934
+ /**
2935
+ * True when any key in the where-tree (root, nested under AND/OR/NOT, or
2936
+ * inside a struct-field sub-clause) is a registered extension operator.
2937
+ * Used by the subscribe path to refuse semantic filters at registration —
2938
+ * extension operators have no incremental evaluation, so a subscription
2939
+ * carrying one would silently degrade. Leaf predicate objects ({ eq: 'x' }) recurse harmlessly: their
2940
+ * keys are not registered operators and their values are not objects.
2941
+ */
2942
+ function whereContainsExtensionOperator(where) {
2943
+ if (Array.isArray(where)) return where.some((w) => whereContainsExtensionOperator(w));
2944
+ if (where === null || typeof where !== "object") return false;
2945
+ for (const [key, value] of Object.entries(where)) {
2359
2946
  if (key === "AND" || key === "OR") {
2360
- if (Array.isArray(value)) out[key] = await Promise.all(value.map((sub) => walk(sub, context, holder)));
2361
- else out[key] = value;
2947
+ if (Array.isArray(value) && value.some((w) => whereContainsExtensionOperator(w))) return true;
2362
2948
  continue;
2363
2949
  }
2364
2950
  if (key === "NOT") {
2365
- if (value !== null && typeof value === "object" && !Array.isArray(value)) out[key] = await walk(value, context, holder);
2366
- else out[key] = value;
2951
+ if (whereContainsExtensionOperator(value)) return true;
2367
2952
  continue;
2368
2953
  }
2369
- const op = getExtensionOperator(key);
2370
- if (op === void 0) {
2371
- out[key] = value;
2372
- continue;
2954
+ if (getExtensionOperator(key) !== void 0) return true;
2955
+ if (value !== null && typeof value === "object" && !Array.isArray(value)) {
2956
+ if (whereContainsExtensionOperator(value)) return true;
2373
2957
  }
2374
- const result = await op.execute(value, context);
2375
- if (!isHitsResult(result)) throw new ExtensionOperatorResultError(key);
2376
- const meta = buildMeta(result.hits);
2377
- holder.current = meta;
2378
- idClauses.push({ id: { in: [...meta.orderedIds] } });
2379
2958
  }
2380
- if (idClauses.length === 0) return out;
2381
- if (out.id !== void 0) idClauses.unshift({ id: out.id });
2382
- if (idClauses.length === 1) return {
2383
- ...out,
2384
- ...idClauses[0]
2385
- };
2386
- delete out.id;
2387
- return { AND: [out, ...idClauses] };
2388
- }
2389
- /** Narrow an operator result to the hits envelope. */
2390
- function isHitsResult(result) {
2391
- return result !== null && typeof result === "object" && Array.isArray(result.hits);
2959
+ return false;
2392
2960
  }
2393
2961
  /**
2394
- * Build the ordered-ids list + computed Map from a hits array. Hits with a
2395
- * non-string id are skipped (defensive — bad input becomes "no match" rather
2396
- * than an error). The vector key is spread conditionally so a hit without a
2397
- * vector yields a computed entry with NO `vector` key (exactOptionalPropertyTypes).
2962
+ * True when the where-tree contains a key equal to `opName` in operator
2963
+ * position (root, AND/OR/NOT combinator, struct-field sub-clause, or array
2964
+ * element). The named variant of `whereContainsExtensionOperator`: the
2965
+ * computed-field gate needs the operator that OWNS the projected field present,
2966
+ * not merely SOME registered operator. Same structural walk; matches by name
2967
+ * rather than registry membership.
2398
2968
  */
2399
- function buildMeta(hits) {
2400
- const orderedIds = [];
2401
- const computed = /* @__PURE__ */ new Map();
2402
- for (const hit of hits) {
2403
- if (hit === null || typeof hit !== "object") continue;
2404
- const id = hit.id;
2405
- if (typeof id !== "string") continue;
2406
- const rawScore = hit.score;
2407
- const score = typeof rawScore === "number" ? rawScore : 0;
2408
- const rawVector = hit.vector;
2409
- const hasVector = Array.isArray(rawVector);
2410
- orderedIds.push(id);
2411
- computed.set(id, {
2412
- score,
2413
- ...hasVector ? { vector: rawVector } : {}
2414
- });
2969
+ function whereContainsOperator(where, opName) {
2970
+ if (Array.isArray(where)) return where.some((w) => whereContainsOperator(w, opName));
2971
+ if (where === null || typeof where !== "object") return false;
2972
+ for (const [key, value] of Object.entries(where)) {
2973
+ if (key === "AND" || key === "OR") {
2974
+ if (Array.isArray(value) && value.some((w) => whereContainsOperator(w, opName))) return true;
2975
+ continue;
2976
+ }
2977
+ if (key === "NOT") {
2978
+ if (whereContainsOperator(value, opName)) return true;
2979
+ continue;
2980
+ }
2981
+ if (key === opName) return true;
2982
+ if (value !== null && typeof value === "object" && !Array.isArray(value)) {
2983
+ if (whereContainsOperator(value, opName)) return true;
2984
+ }
2415
2985
  }
2416
- return {
2417
- orderedIds,
2418
- computed
2419
- };
2986
+ return false;
2420
2987
  }
2421
2988
 
2422
2989
  //#endregion
@@ -2641,21 +3208,20 @@ function applyAgg(rows, fn, fieldDefOf) {
2641
3208
  const v = one === void 0 ? void 0 : getFieldValue(one, field);
2642
3209
  return v == null || storedMicros(v) === void 0 ? null : v;
2643
3210
  }
2644
- let n = 0;
2645
- let acc = 0;
2646
- for (const r of rows) {
2647
- const v = getFieldValue(r, field);
2648
- if (typeof v !== "number") continue;
2649
- acc = n === 0 ? v : op === "min" ? Math.min(acc, v) : op === "max" ? Math.max(acc, v) : acc + v;
2650
- n++;
2651
- }
3211
+ return numericAgg(rows.map((r) => getFieldValue(r, field)), op);
3212
+ }
3213
+ /** avg/sum/min/max over the numbers among `values` (the rest drop out), null over none; float64, a sum past its range is null. */
3214
+ function numericAgg(values, op) {
3215
+ const nums = values.filter((v) => typeof v === "number");
3216
+ const n = nums.length;
2652
3217
  if (n === 0) return null;
3218
+ let acc = 0;
3219
+ nums.forEach((v, i) => {
3220
+ acc = i === 0 ? v : op === "min" ? Math.min(acc, v) : op === "max" ? Math.max(acc, v) : acc + v;
3221
+ });
2653
3222
  if (!Number.isFinite(acc) && (op === "sum" || op === "avg")) {
2654
3223
  let scaled = 0;
2655
- for (const r of rows) {
2656
- const v = getFieldValue(r, field);
2657
- if (typeof v === "number") scaled += v * 2 ** -64;
2658
- }
3224
+ for (const v of nums) scaled += v * 2 ** -64;
2659
3225
  const out = (op === "avg" ? scaled / n : scaled) * 2 ** 64;
2660
3226
  return Number.isFinite(out) ? out : null;
2661
3227
  }
@@ -2752,6 +3318,27 @@ function isDateField(field, fieldDefOf) {
2752
3318
  const def = METADATA_FILTER_FIELDS[field] ?? fieldDefOf?.(field);
2753
3319
  return def?.kind === "scalar" && def.type === "date";
2754
3320
  }
3321
+ function isInt64Field(field, fieldDefOf) {
3322
+ const def = fieldDefOf?.(field);
3323
+ return def?.kind === "scalar" && def.type === "int64";
3324
+ }
3325
+ /**
3326
+ * A predicate on an int64 field with its operands read as bigints, the way pg
3327
+ * casts them. An operand that is not an int64 is a caller error; `null` and
3328
+ * `$ref` operands pass through.
3329
+ */
3330
+ function int64Predicate(field, predicate) {
3331
+ if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) return predicate;
3332
+ const one = (op, v) => {
3333
+ if (v === null || isRefOperand(v)) return v;
3334
+ const n = parseInt64(v);
3335
+ if (n === void 0) throw new UnsupportedFilterError(field, op, "requires an int64 operand");
3336
+ return n;
3337
+ };
3338
+ const out = {};
3339
+ for (const [op, v] of Object.entries(predicate)) out[op] = Array.isArray(v) && (op === "in" || op === "nin" || op === "between") ? v.map((e) => one(op, e)) : KNOWN_OPS.has(op) ? one(op, v) : v;
3340
+ return out;
3341
+ }
2755
3342
  const KNOWN_OPS = /* @__PURE__ */ new Set([
2756
3343
  "eq",
2757
3344
  "neq",
@@ -2765,6 +3352,8 @@ const KNOWN_OPS = /* @__PURE__ */ new Set([
2765
3352
  "contains",
2766
3353
  "startsWith",
2767
3354
  "endsWith",
3355
+ "like",
3356
+ "notLike",
2768
3357
  "has"
2769
3358
  ]);
2770
3359
  /**
@@ -2787,6 +3376,7 @@ function assertWhereHonourable(where) {
2787
3376
  if (where === null || typeof where !== "object" || Array.isArray(where)) return;
2788
3377
  if (Object.hasOwn(where, "_agg")) return;
2789
3378
  for (const [key, child] of Object.entries(where)) {
3379
+ if (key === "$expr") continue;
2790
3380
  if (key === "AND" || key === "OR") {
2791
3381
  if (Array.isArray(child)) for (const sub of child) assertWhereHonourable(sub);
2792
3382
  continue;
@@ -2830,7 +3420,11 @@ function assertFieldPredicateHonourable(field, predicate) {
2830
3420
  break;
2831
3421
  case "contains":
2832
3422
  case "startsWith":
2833
- case "endsWith": if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
3423
+ case "endsWith":
3424
+ case "like":
3425
+ case "notLike":
3426
+ if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
3427
+ if ((op === "like" || op === "notLike") && endsWithEscape(operand)) throw new UnsupportedFilterError(field, op, LIKE_TRAILING_ESCAPE);
2834
3428
  }
2835
3429
  }
2836
3430
  /**
@@ -2876,6 +3470,8 @@ function evaluateMembers(row, where, fieldDefOf, walk, bound) {
2876
3470
  }
2877
3471
  } else if (k === "NOT") {
2878
3472
  if (evaluateWhere(row, child, fieldDefOf, walk)) return false;
3473
+ } else if (k === "$expr") {
3474
+ if (evalExpr(child, row, { fieldType: fieldTypeLookup(fieldDefOf) }) !== true) return false;
2879
3475
  } else if (k === "_walk") {
2880
3476
  if (walk === void 0) throw new UnsupportedFilterError(k, "<none>", "walks need a walk context");
2881
3477
  const node = child;
@@ -2883,7 +3479,8 @@ function evaluateMembers(row, where, fieldDefOf, walk, bound) {
2883
3479
  } else {
2884
3480
  const asDate = isDateField(k, fieldDefOf);
2885
3481
  const ref = walk === void 0 ? void 0 : (r) => resolveRef(r, asDate, walk);
2886
- if (!evaluateFieldPredicate(k, getFieldValue(row, k), child, asDate, ref)) return false;
3482
+ const pred = isInt64Field(k, fieldDefOf) ? int64Predicate(k, child) : child;
3483
+ if (!evaluateFieldPredicate(k, getFieldValue(row, k), pred, asDate, ref)) return false;
2887
3484
  }
2888
3485
  return true;
2889
3486
  }
@@ -2952,6 +3549,12 @@ function applyOp(field, op, value, operand, asDate) {
2952
3549
  if (op === "startsWith") return v.startsWith(o);
2953
3550
  return v.endsWith(o);
2954
3551
  }
3552
+ case "like":
3553
+ case "notLike":
3554
+ if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
3555
+ if (endsWithEscape(operand)) throw new UnsupportedFilterError(field, op, LIKE_TRAILING_ESCAPE);
3556
+ if (typeof value !== "string") return false;
3557
+ return likeMatch(value, operand) === (op === "like");
2955
3558
  case "has": return Array.isArray(value) && value.some((e) => equals(e, operand));
2956
3559
  default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2957
3560
  }
@@ -2990,6 +3593,11 @@ function compareFilterValues(a, b, asDate = false) {
2990
3593
  const bt = toMicros(b);
2991
3594
  if (at !== void 0 && bt !== void 0) return at < bt ? -1 : at > bt ? 1 : 0;
2992
3595
  }
3596
+ if (typeof a === "bigint" || typeof b === "bigint") {
3597
+ const x = parseInt64(a);
3598
+ const y = parseInt64(b);
3599
+ if (x !== void 0 && y !== void 0) return x < y ? -1 : x > y ? 1 : 0;
3600
+ }
2993
3601
  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
2994
3602
  return compareCodePoints(String(a), String(b));
2995
3603
  }
@@ -3012,6 +3620,7 @@ function asSortValue(field, value, fieldDefOf) {
3012
3620
  if (isDateField(field, fieldDefOf)) return storedMicros(value) === void 0 ? null : value;
3013
3621
  const def = METADATA_FILTER_FIELDS[field] ?? fieldDefOf?.(field);
3014
3622
  if (def?.kind === "scalar" && def.type === "number" && typeof value !== "number") return null;
3623
+ if (def?.kind === "scalar" && def.type === "int64" && parseInt64(value) === void 0) return null;
3015
3624
  return value;
3016
3625
  }
3017
3626
  /**
@@ -3038,6 +3647,824 @@ function msToMicros(ms) {
3038
3647
  return BigInt(whole) * 1000n + BigInt(Math.round((ms - whole) * 1e3));
3039
3648
  }
3040
3649
 
3650
+ //#endregion
3651
+ //#region ../../packages/substrate-filter/src/regex-vm.ts
3652
+ /**
3653
+ * A Pike VM (Thompson NFA simulation with thread priorities and capture slots)
3654
+ * for exactly the portable subset `checkRegexSubset` accepts. Matching is
3655
+ * O(subject length x program length) with no recursion over the subject, and a
3656
+ * call past MAX_STEPS throws, so a caller's pattern cannot block the event loop. It works over code points; `.`
3657
+ * matches any code point including a newline, `^` and `$` match only at the
3658
+ * subject's start and end. The match is the leftmost-longest one Postgres (POSIX
3659
+ * ARE) reports; among equally long matches, thread priority picks the captures.
3660
+ */
3661
+ function emit(node, out, base) {
3662
+ switch (node.t) {
3663
+ case "char":
3664
+ out.push({
3665
+ op: "char",
3666
+ c: node.c
3667
+ });
3668
+ return;
3669
+ case "any":
3670
+ case "bol":
3671
+ case "eol":
3672
+ out.push({ op: node.t });
3673
+ return;
3674
+ case "class":
3675
+ out.push({
3676
+ op: "class",
3677
+ neg: node.neg,
3678
+ ranges: node.ranges
3679
+ });
3680
+ return;
3681
+ case "group":
3682
+ if (node.cap === null) {
3683
+ emit(node.body, out, base);
3684
+ return;
3685
+ }
3686
+ out.push({
3687
+ op: "save",
3688
+ slot: 2 * node.cap + 2
3689
+ });
3690
+ emit(node.body, out, base);
3691
+ out.push({
3692
+ op: "save",
3693
+ slot: 2 * node.cap + 3
3694
+ });
3695
+ return;
3696
+ case "cat":
3697
+ for (const n of node.items) emit(n, out, base);
3698
+ return;
3699
+ case "alt": {
3700
+ const jumps = [];
3701
+ node.items.forEach((n, k) => {
3702
+ if (k < node.items.length - 1) {
3703
+ const split = out.length;
3704
+ out.push({
3705
+ op: "split",
3706
+ x: split + 1,
3707
+ y: 0
3708
+ });
3709
+ emit(n, out, base);
3710
+ jumps.push(out.length);
3711
+ out.push({
3712
+ op: "jmp",
3713
+ x: 0
3714
+ });
3715
+ out[split].y = out.length;
3716
+ } else emit(n, out, base);
3717
+ });
3718
+ for (const j of jumps) out[j].x = out.length;
3719
+ return;
3720
+ }
3721
+ case "rep": {
3722
+ for (let k = 0; k < node.min; k++) emit(node.body, out, base);
3723
+ const slot = base + node.id;
3724
+ const guarded = nullable(node.body);
3725
+ const iteration = () => {
3726
+ if (guarded) out.push({
3727
+ op: "mark",
3728
+ slot
3729
+ });
3730
+ emit(node.body, out, base);
3731
+ if (guarded) out.push({
3732
+ op: "progress",
3733
+ slot
3734
+ });
3735
+ };
3736
+ if (node.max === Number.POSITIVE_INFINITY) {
3737
+ const split = out.length;
3738
+ out.push({
3739
+ op: "split",
3740
+ x: split + 1,
3741
+ y: 0
3742
+ });
3743
+ iteration();
3744
+ out.push({
3745
+ op: "jmp",
3746
+ x: split
3747
+ });
3748
+ out[split].y = out.length;
3749
+ return;
3750
+ }
3751
+ const splits = [];
3752
+ for (let k = node.min; k < node.max; k++) {
3753
+ splits.push(out.length);
3754
+ out.push({
3755
+ op: "split",
3756
+ x: out.length + 1,
3757
+ y: 0
3758
+ });
3759
+ iteration();
3760
+ }
3761
+ for (const s of splits) out[s].y = out.length;
3762
+ }
3763
+ }
3764
+ }
3765
+ /** Compiles a pattern the subset accepts; throws on one it refuses. */
3766
+ function compileRegex(pattern) {
3767
+ const bad = checkRegexSubset(pattern);
3768
+ if (bad) throw new Error(`invalid regex: ${bad}`);
3769
+ const { node, groups, reps } = parse(pattern);
3770
+ if (programSize(node) > 2e3) throw new Error("invalid regex: program too large");
3771
+ const insts = [{
3772
+ op: "save",
3773
+ slot: 0
3774
+ }];
3775
+ emit(node, insts, 2 * groups + 2);
3776
+ insts.push({
3777
+ op: "save",
3778
+ slot: 1
3779
+ }, { op: "match" });
3780
+ return {
3781
+ insts,
3782
+ groups,
3783
+ slots: 2 * groups + 2 + reps
3784
+ };
3785
+ }
3786
+ /** Steps one call may take, about 200 ms: a 10 KB value against the largest program takes ~15M. */
3787
+ const MAX_STEPS = 4e6;
3788
+ /** The leftmost-longest match of `prog` in `subject`, as Postgres reports it, or null. */
3789
+ function execRegex(prog, subject) {
3790
+ const { insts } = prog;
3791
+ const cps = [];
3792
+ const offsets = [];
3793
+ for (let k = 0; k < subject.length;) {
3794
+ const cp = subject.codePointAt(k);
3795
+ offsets.push(k);
3796
+ cps.push(cp);
3797
+ k += cp > 65535 ? 2 : 1;
3798
+ }
3799
+ offsets.push(subject.length);
3800
+ const n = cps.length;
3801
+ const nslots = prog.slots;
3802
+ const seen = new Int32Array(insts.length).fill(-1);
3803
+ let clist = [];
3804
+ let nlist = [];
3805
+ let found = null;
3806
+ let steps = 0;
3807
+ const step = () => {
3808
+ if (++steps > 4e6) throw new ResolverFrameError(REGEX_BUDGET_EXCEEDED, `regex needs more than ${MAX_STEPS} steps on this value; use a shorter pattern or value`, { budget: MAX_STEPS });
3809
+ };
3810
+ const add = (list, startPc, startCaps, pos, gen) => {
3811
+ const stack = [{
3812
+ pc: startPc,
3813
+ caps: startCaps
3814
+ }];
3815
+ while (stack.length > 0) {
3816
+ step();
3817
+ const { pc, caps } = stack.pop();
3818
+ const inst = insts[pc];
3819
+ if (inst.op === "progress" && caps[inst.slot] === pos) continue;
3820
+ if (seen[pc] === gen) continue;
3821
+ seen[pc] = gen;
3822
+ switch (inst.op) {
3823
+ case "jmp":
3824
+ stack.push({
3825
+ pc: inst.x,
3826
+ caps
3827
+ });
3828
+ break;
3829
+ case "split":
3830
+ stack.push({
3831
+ pc: inst.y,
3832
+ caps
3833
+ }, {
3834
+ pc: inst.x,
3835
+ caps
3836
+ });
3837
+ break;
3838
+ case "progress":
3839
+ stack.push({
3840
+ pc: pc + 1,
3841
+ caps
3842
+ });
3843
+ break;
3844
+ case "mark":
3845
+ case "save": {
3846
+ const next = caps.slice();
3847
+ next[inst.slot] = pos;
3848
+ stack.push({
3849
+ pc: pc + 1,
3850
+ caps: next
3851
+ });
3852
+ break;
3853
+ }
3854
+ case "bol":
3855
+ if (pos === 0) stack.push({
3856
+ pc: pc + 1,
3857
+ caps
3858
+ });
3859
+ break;
3860
+ case "eol":
3861
+ if (pos === n) stack.push({
3862
+ pc: pc + 1,
3863
+ caps
3864
+ });
3865
+ break;
3866
+ default: list.push({
3867
+ pc,
3868
+ caps
3869
+ });
3870
+ }
3871
+ }
3872
+ };
3873
+ const blank = new Array(nslots).fill(-1);
3874
+ for (let pos = 0; pos <= n; pos++) {
3875
+ if (found === null) add(clist, 0, blank, pos, pos);
3876
+ if (clist.length === 0 && found !== null) break;
3877
+ const cp = pos < n ? cps[pos] : -1;
3878
+ for (const t of clist) {
3879
+ step();
3880
+ const inst = insts[t.pc];
3881
+ if (found !== null && t.caps[0] > found[0]) continue;
3882
+ if (inst.op === "match") {
3883
+ if (found === null || t.caps[0] < found[0] || pos > found[1]) found = t.caps;
3884
+ continue;
3885
+ }
3886
+ if (cp < 0) continue;
3887
+ if (inst.op === "char" ? inst.c === cp : inst.op === "any" ? true : inst.op === "class" && inst.ranges.some(([lo, hi]) => cp >= lo && cp <= hi) !== inst.neg) add(nlist, t.pc + 1, t.caps, pos + 1, pos + 1);
3888
+ }
3889
+ [clist, nlist] = [nlist, clist];
3890
+ nlist.length = 0;
3891
+ }
3892
+ if (found === null) return null;
3893
+ const at = (s) => offsets[s];
3894
+ const groups = [];
3895
+ for (let g = 0; g < prog.groups; g++) {
3896
+ const s = found[2 * g + 2];
3897
+ const e = found[2 * g + 3];
3898
+ groups.push(s === void 0 || s < 0 || e === void 0 || e < 0 ? void 0 : subject.slice(at(s), at(e)));
3899
+ }
3900
+ return {
3901
+ index: at(found[0]),
3902
+ end: at(found[1]),
3903
+ groups
3904
+ };
3905
+ }
3906
+
3907
+ //#endregion
3908
+ //#region ../../packages/substrate-filter/src/expr-eval.ts
3909
+ const MIN_INT64$1 = -(2n ** 63n);
3910
+ const MAX_INT64$1 = 2n ** 63n - 1n;
3911
+ const int64 = (n) => {
3912
+ if (n < MIN_INT64$1 || n > MAX_INT64$1) throw new RangeError("bigint out of range");
3913
+ return n;
3914
+ };
3915
+ /** A small Map-based LRU: bounded so caller-supplied patterns cannot grow memory. */
3916
+ function lru(max, make) {
3917
+ const m = /* @__PURE__ */ new Map();
3918
+ return (k) => {
3919
+ let v = m.get(k);
3920
+ if (v !== void 0) m.delete(k);
3921
+ else {
3922
+ v = make(k);
3923
+ if (m.size >= max) m.delete(m.keys().next().value);
3924
+ }
3925
+ m.set(k, v);
3926
+ return v;
3927
+ };
3928
+ }
3929
+ const compile = lru(256, compileRegex);
3930
+ function likeTokens(pattern) {
3931
+ const cps = Array.from(pattern);
3932
+ const out = [];
3933
+ for (let i = 0; i < cps.length; i++) {
3934
+ const c = cps[i];
3935
+ if (c === "\\") out.push({ lit: i + 1 < cps.length ? cps[++i] : c });
3936
+ else if (c === "%" || c === "_") out.push(c);
3937
+ else out.push({ lit: c });
3938
+ }
3939
+ return out;
3940
+ }
3941
+ /** Linear-time-ish wildcard match (backtracks only to the last `%`), over code points. */
3942
+ /** Parsed once per pattern, not per row. */
3943
+ const likeTokensOf = lru(256, likeTokens);
3944
+ function likeMatch(text, pattern) {
3945
+ const toks = likeTokensOf(pattern);
3946
+ const t = Array.from(text);
3947
+ let ti = 0;
3948
+ let pi = 0;
3949
+ let star = -1;
3950
+ let mark = 0;
3951
+ while (ti < t.length) {
3952
+ const tok = toks[pi];
3953
+ if (tok === "%") {
3954
+ star = pi++;
3955
+ mark = ti;
3956
+ } else if (tok !== void 0 && (tok === "_" || tok.lit === t[ti])) {
3957
+ pi++;
3958
+ ti++;
3959
+ } else if (star >= 0) {
3960
+ pi = star + 1;
3961
+ ti = ++mark;
3962
+ } else return false;
3963
+ }
3964
+ while (toks[pi] === "%") pi++;
3965
+ return pi === toks.length;
3966
+ }
3967
+ /** Maps ASCII letters only, as pg does under the "C" collation; every other code point is unchanged. */
3968
+ const asciiCase = (s, from, f) => s.replace(from, f);
3969
+ /** float8 arithmetic as Postgres does it: a non-finite result from finite operands, or a nonzero product or quotient that underflows to 0, raises. */
3970
+ function float8(v, a, b, underflows) {
3971
+ if (!Number.isFinite(v) && Number.isFinite(a) && Number.isFinite(b)) throw new Error("value out of range: overflow");
3972
+ if (underflows && v === 0 && a !== 0 && b !== 0) throw new Error("value out of range: underflow");
3973
+ return v;
3974
+ }
3975
+ /** The replacement's `\1`-`\9` as group references, `\&` as the whole match; `\\` is a backslash; everything else is literal. */
3976
+ function expandReplacement(rep, whole, groups) {
3977
+ let out = "";
3978
+ const cps = Array.from(rep);
3979
+ for (let i = 0; i < cps.length; i++) {
3980
+ const c = cps[i];
3981
+ const next = cps[i + 1];
3982
+ if (c === "\\" && next !== void 0 && /[1-9]/.test(next)) {
3983
+ out += groups[Number(next) - 1] ?? "";
3984
+ i++;
3985
+ } else if (c === "\\" && next === "&") {
3986
+ out += whole;
3987
+ i++;
3988
+ } else if (c === "\\" && next === "\\") {
3989
+ out += "\\";
3990
+ i++;
3991
+ } else out += c;
3992
+ }
3993
+ return out;
3994
+ }
3995
+ /** A date value as microseconds, read by the shared ISO grammar (no offset is UTC); null when unreadable, as pg's substrate_ts. */
3996
+ const microsOf = (v) => storedMicros(v) ?? null;
3997
+ /** The millisecond Date of an instant in microseconds, floored. */
3998
+ const dateOf = (m) => new Date(Number((m - (m % 1000n + 1000n) % 1000n) / 1000n));
3999
+ /** A UTC Date; unlike Date.UTC, years 0-99 stay as given. */
4000
+ function utc(y, mo, da, h = 0, mi = 0, s = 0) {
4001
+ const d = /* @__PURE__ */ new Date(0);
4002
+ d.setUTCFullYear(y, mo, da);
4003
+ d.setUTCHours(h, mi, s, 0);
4004
+ return d;
4005
+ }
4006
+ function trunc(unit, d) {
4007
+ const [y, mo, da, h, mi, s] = [
4008
+ d.getUTCFullYear(),
4009
+ d.getUTCMonth(),
4010
+ d.getUTCDate(),
4011
+ d.getUTCHours(),
4012
+ d.getUTCMinutes(),
4013
+ d.getUTCSeconds()
4014
+ ];
4015
+ switch (unit) {
4016
+ case "year": return utc(y, 0, 1);
4017
+ case "month": return utc(y, mo, 1);
4018
+ case "week": return utc(y, mo, da - (d.getUTCDay() + 6) % 7);
4019
+ case "day": return utc(y, mo, da);
4020
+ case "hour": return utc(y, mo, da, h);
4021
+ case "minute": return utc(y, mo, da, h, mi);
4022
+ default: return utc(y, mo, da, h, mi, s);
4023
+ }
4024
+ }
4025
+ function isoWeek(d) {
4026
+ const day = (d.getUTCDay() + 6) % 7;
4027
+ const thursday = utc(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - day + 3);
4028
+ const jan1 = utc(thursday.getUTCFullYear(), 0, 1);
4029
+ return Math.floor((thursday.getTime() - jan1.getTime()) / 6048e5) + 1;
4030
+ }
4031
+ function extract(unit, m) {
4032
+ const d = dateOf(m);
4033
+ switch (unit) {
4034
+ case "year": return d.getUTCFullYear();
4035
+ case "month": return d.getUTCMonth() + 1;
4036
+ case "week": return isoWeek(d);
4037
+ case "day": return d.getUTCDate();
4038
+ case "hour": return d.getUTCHours();
4039
+ case "minute": return d.getUTCMinutes();
4040
+ default: {
4041
+ const frac = (m % 1000000n + 1000000n) % 1000000n;
4042
+ return Number(`${d.getUTCSeconds()}.${frac.toString().padStart(6, "0")}`);
4043
+ }
4044
+ }
4045
+ }
4046
+ const widen = (x, y) => typeof x === "bigint" && typeof y === "number" ? [Number(x), y] : typeof x === "number" && typeof y === "bigint" ? [x, Number(y)] : [x, y];
4047
+ /** SQL order of two non-null operands: int64 beside number as number, text by code point (pg's "C" collation). */
4048
+ function compare$1(x, y) {
4049
+ const [a, b] = widen(x, y);
4050
+ if (typeof a === "string" && typeof b === "string") return compareCodePoints(a, b);
4051
+ return a < b ? -1 : a > b ? 1 : 0;
4052
+ }
4053
+ const isSafeIntLiteral = (e) => typeof e === "number" && Number.isSafeInteger(e);
4054
+ const ARITH = {
4055
+ add: [(a, b) => a + b, (a, b) => a + b],
4056
+ sub: [(a, b) => a - b, (a, b) => a - b],
4057
+ mul: [(a, b) => a * b, (a, b) => a * b]
4058
+ };
4059
+ function evalExpr(expr, row, env) {
4060
+ if (expr === null) return null;
4061
+ if (typeof expr === "string") {
4062
+ const v = env.output !== void 0 && Object.hasOwn(env.output, expr) ? env.output[expr] : getFieldValue(row, expr) ?? null;
4063
+ if (v === void 0 || v === null) return null;
4064
+ if (typeof v !== "number" && env.fieldType(expr) === "number") return null;
4065
+ if (typeof v === "number" && env.fieldType(expr) === "int64") return Number.isSafeInteger(v) ? BigInt(v) : null;
4066
+ if (env.fieldType(expr) === "date" || v instanceof Date) {
4067
+ const m = microsOf(v);
4068
+ return m === null ? null : isoFromMicros(m);
4069
+ }
4070
+ return v;
4071
+ }
4072
+ if (typeof expr !== "object") return expr;
4073
+ if ("lit" in expr) return expr.lit;
4074
+ if ("int64" in expr) return BigInt(expr.int64);
4075
+ const key = Object.keys(expr)[0];
4076
+ const args = expr[key];
4077
+ const ev = (e) => evalExpr(e, row, env);
4078
+ switch (key) {
4079
+ case "case":
4080
+ for (let i = 0; i < args.length - 1; i++) {
4081
+ const [cond, then] = args[i];
4082
+ if (ev(cond) === true) return unified(expr, ev(then), env);
4083
+ }
4084
+ return unified(expr, ev(args[args.length - 1]), env);
4085
+ case "coalesce":
4086
+ for (const a of args) {
4087
+ const v = ev(a);
4088
+ if (v !== null) return unified(expr, v, env);
4089
+ }
4090
+ return null;
4091
+ case "isNull": return ev(args[0]) === null;
4092
+ case "and":
4093
+ case "or": {
4094
+ const stop = key === "or";
4095
+ let sawNull = false;
4096
+ for (const a of args) {
4097
+ const v = ev(a);
4098
+ if (v === null) sawNull = true;
4099
+ else if (v === stop) return stop;
4100
+ }
4101
+ return sawNull ? null : !stop;
4102
+ }
4103
+ }
4104
+ const vals = args.map(ev);
4105
+ if (key === "in") {
4106
+ const [needle, ...rest] = vals;
4107
+ if (needle === null) return null;
4108
+ const hit = (v) => v !== null && compare$1(needle, v) === 0;
4109
+ if (rest.some(hit)) return true;
4110
+ return rest.includes(null) ? null : false;
4111
+ }
4112
+ if (key === "dateTrunc" || key === "extract") {
4113
+ const m = microsOf(vals[1]);
4114
+ if (m === null) return null;
4115
+ return key === "extract" ? extract(vals[0], m) : isoFromMicros(BigInt(trunc(vals[0], dateOf(m)).getTime()) * 1000n);
4116
+ }
4117
+ if (vals.some((v) => v === null)) return null;
4118
+ const [a, b, c] = vals;
4119
+ switch (key) {
4120
+ case "add":
4121
+ case "sub":
4122
+ case "mul": {
4123
+ const [big, num] = ARITH[key];
4124
+ return arith(args, vals, big, num, key === "mul");
4125
+ }
4126
+ case "div": return Number(b) === 0 ? null : float8(Number(a) / Number(b), Number(a), Number(b), true);
4127
+ case "mod": return BigInt(b) === 0n ? null : int64(BigInt(a) % BigInt(b));
4128
+ case "neg": return typeof a === "bigint" ? int64(-a) : -a;
4129
+ case "eq": return compare$1(a, b) === 0;
4130
+ case "neq": return compare$1(a, b) !== 0;
4131
+ case "gt": return compare$1(a, b) > 0;
4132
+ case "gte": return compare$1(a, b) >= 0;
4133
+ case "lt": return compare$1(a, b) < 0;
4134
+ case "lte": return compare$1(a, b) <= 0;
4135
+ case "not": return !a;
4136
+ case "length": return Array.from(a).length;
4137
+ case "lower": return asciiCase(a, /[A-Z]/g, (x) => x.toLowerCase());
4138
+ case "upper": return asciiCase(a, /[a-z]/g, (x) => x.toUpperCase());
4139
+ case "substring": {
4140
+ const int4 = (x, lo) => Math.min(Math.max(Math.round(Number(x)), lo), 2 ** 31 - 1);
4141
+ const start = int4(b, -(2 ** 31));
4142
+ const end = start + int4(c, 0);
4143
+ return Array.from(a).slice(Math.max(start, 1) - 1, Math.max(end - 1, 0)).join("");
4144
+ }
4145
+ case "concat": return vals.join("");
4146
+ case "like": return likeMatch(a, b);
4147
+ case "notLike": return !likeMatch(a, b);
4148
+ case "regexpMatch": return execRegex(compile(b), a) !== null;
4149
+ case "regexpReplace": {
4150
+ const m = execRegex(compile(b), a);
4151
+ if (!m) return a;
4152
+ return a.slice(0, m.index) + expandReplacement(c, a.slice(m.index, m.end), m.groups) + a.slice(m.end);
4153
+ }
4154
+ default: throw new Error(`unknown function '${key}'`);
4155
+ }
4156
+ }
4157
+ /** int64 when both operands are int64 (a safe-integer literal counts), else number. */
4158
+ function arith(args, vals, big, num, mulUnderflow = false) {
4159
+ const [a, b] = vals;
4160
+ const lift = (v, e, other) => typeof v === "number" && typeof other === "bigint" && isSafeIntLiteral(e) ? BigInt(v) : v;
4161
+ const x = lift(a, args[0], b);
4162
+ const y = lift(b, args[1], a);
4163
+ if (typeof x === "bigint" && typeof y === "bigint") return int64(big(x, y));
4164
+ return float8(num(Number(x), Number(y)), Number(x), Number(y), mulUnderflow);
4165
+ }
4166
+ /** A case or coalesce value in the type the checker gives the whole call: int64 widens to number, a number literal adopts int64. */
4167
+ function unified(expr, v, env) {
4168
+ if (typeof v !== "bigint" && typeof v !== "number") return v;
4169
+ const t = callType(expr, env);
4170
+ if (t === "number" && typeof v === "bigint") return Number(v);
4171
+ if (t === "int64" && typeof v === "number") return BigInt(v);
4172
+ return v;
4173
+ }
4174
+ /** Each call node's checked type, computed once per node and field-type lookup, never per row. */
4175
+ const callTypes = /* @__PURE__ */ new WeakMap();
4176
+ function callType(expr, env) {
4177
+ const byNode = callTypes.get(env.fieldType) ?? /* @__PURE__ */ new WeakMap();
4178
+ callTypes.set(env.fieldType, byNode);
4179
+ const hit = byNode.get(expr);
4180
+ if (hit !== void 0) return hit;
4181
+ const c = checkExpr(expr, { field: env.fieldType }, []);
4182
+ const t = c.ok ? c.type : null;
4183
+ byNode.set(expr, t);
4184
+ return t;
4185
+ }
4186
+
4187
+ //#endregion
4188
+ //#region ../../packages/substrate-filter/src/grouped.ts
4189
+ /**
4190
+ * Grouped reads (`aggregate` with `groupBy`, `having`, `orderBy`, `offset`) in
4191
+ * memory: the reference the Postgres compiler is held to. Groups are keyed by
4192
+ * a stable encoding of the key tuple; nulls form one group, as SQL's GROUP BY.
4193
+ */
4194
+ const ARITHMETIC = /* @__PURE__ */ new Set([
4195
+ "add",
4196
+ "sub",
4197
+ "mul",
4198
+ "div",
4199
+ "mod",
4200
+ "neg"
4201
+ ]);
4202
+ /** Whether evaluating `e` can raise a range error (arithmetic anywhere in it). */
4203
+ function canRaise(e) {
4204
+ if (Array.isArray(e)) return e.some(canRaise);
4205
+ if (typeof e !== "object" || e === null || "lit" in e || "int64" in e) return false;
4206
+ return Object.entries(e).some(([k, v]) => ARITHMETIC.has(k) || canRaise(v));
4207
+ }
4208
+ const MIN_INT64 = -(2n ** 63n);
4209
+ const MAX_INT64 = 2n ** 63n - 1n;
4210
+ const OPS = [
4211
+ "count",
4212
+ "countDistinct",
4213
+ "avg",
4214
+ "sum",
4215
+ "min",
4216
+ "max"
4217
+ ];
4218
+ /** An aggregate's function and argument. */
4219
+ function aggParts(spec) {
4220
+ const op = OPS.find((k) => Object.hasOwn(spec, k));
4221
+ if (op === void 0) throw new Error("internal: aggregate names no function");
4222
+ return {
4223
+ op,
4224
+ arg: spec[op]
4225
+ };
4226
+ }
4227
+ /** The type an aggregate over an argument of type `arg` returns (`count` is a number). */
4228
+ function aggType(op, arg) {
4229
+ if (op === "count" || op === "countDistinct" || op === "avg") return "number";
4230
+ return arg ?? "string";
4231
+ }
4232
+ const isoMicros$1 = (v) => {
4233
+ const m = storedMicros(v);
4234
+ return m === void 0 ? null : isoFromMicros(m);
4235
+ };
4236
+ /** A value as a Map key, equal exactly when SQL would put two values in one group. */
4237
+ function encode(v, t) {
4238
+ if (v === null || v === void 0) return "n";
4239
+ if (t === "date") return `d${storedMicros(v)}`;
4240
+ if (typeof v === "bigint") return `i${v}`;
4241
+ if (typeof v === "number") return `f${v === 0 ? 0 : v}`;
4242
+ return `${typeof v === "string" ? "s" : "b"}${JSON.stringify(v)}`;
4243
+ }
4244
+ /** A date value `substrate_ts` cannot read is NULL on pg; so here. */
4245
+ const readable = (v, t) => t === "date" && v !== null && storedMicros(v) === void 0 ? null : v;
4246
+ const bytes = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
4247
+ /** Nulls compare after everything; otherwise by type, as pg sorts it (text in byte order). */
4248
+ function compare(a, b, t) {
4249
+ if (a === null && b === null) return 0;
4250
+ if (a === null) return 1;
4251
+ if (b === null) return -1;
4252
+ if (t === "date") return Number(storedMicros(a) - storedMicros(b));
4253
+ if (t === "string") return bytes(a, b);
4254
+ return a < b ? -1 : a > b ? 1 : 0;
4255
+ }
4256
+ /** The evaluator's int64 range error and its float overflow/underflow error: pg's 22003. */
4257
+ const isRangeError = (err) => err instanceof RangeError && err.message === "bigint out of range" || err instanceof Error && err.message.startsWith("value out of range: ");
4258
+ function outOfRange(err) {
4259
+ if (isRangeError(err)) throw new ResolverFrameError(VALUE_OUT_OF_RANGE, err.message);
4260
+ throw err;
4261
+ }
4262
+ function aggregateOf(op, arg, t, values, rows) {
4263
+ if (op === "count") return arg === true ? rows : values.filter((v) => v !== null).length;
4264
+ const present = values.filter((v) => v !== null);
4265
+ if (op === "countDistinct") return new Set(present.map((v) => encode(v, t))).size;
4266
+ if (present.length === 0) return null;
4267
+ if (t === "int64") {
4268
+ const ns = present;
4269
+ if (op === "min" || op === "max") return ns.reduce((a, b) => (op === "min" ? b < a : b > a) ? b : a);
4270
+ const sum = ns.reduce((a, b) => a + b, 0n);
4271
+ if (op === "avg") return Number(sum) / ns.length;
4272
+ if (sum < MIN_INT64 || sum > MAX_INT64) outOfRange(/* @__PURE__ */ new RangeError("bigint out of range"));
4273
+ return sum;
4274
+ }
4275
+ if (t === "string" || t === "date") {
4276
+ const best = present.reduce((a, b) => (op === "min" ? compare(b, a, t) < 0 : compare(b, a, t) > 0) ? b : a);
4277
+ return t === "date" ? isoMicros$1(best) : best;
4278
+ }
4279
+ return numericAgg(present, op);
4280
+ }
4281
+ /**
4282
+ * `pool`'s rows grouped, aggregated, filtered by `having`, ordered (default:
4283
+ * the group keys ascending, ties by them too), then cut to `limit` after `offset`.
4284
+ * `fieldType` must be one stable lookup per read: the evaluator caches on it.
4285
+ */
4286
+ function groupRows(pool, p, fieldType, limit) {
4287
+ const keys = Object.entries(p.groupBy ?? {});
4288
+ const aggs = Object.entries(p.aggregate).map(([name, spec]) => ({
4289
+ name,
4290
+ ...aggParts(spec)
4291
+ }));
4292
+ const typeOf = (e) => {
4293
+ const r = checkExpr(e, { field: fieldType }, []);
4294
+ return r.ok ? r.type : null;
4295
+ };
4296
+ const keyTypes = keys.map(([, e]) => typeOf(e));
4297
+ const argTypes = aggs.map((a) => typeOf(a.arg));
4298
+ const outTypes = new Map([...keys.map(([n], i) => [n, keyTypes[i]]), ...aggs.map((a, i) => [a.name, aggType(a.op, argTypes[i])])]);
4299
+ const outType = (name) => outTypes.get(name) ?? void 0;
4300
+ const env = { fieldType };
4301
+ const buckets = /* @__PURE__ */ new Map();
4302
+ try {
4303
+ for (const row of pool) {
4304
+ const key = keys.map(([, e], i) => readable(evalExpr(e, row, env) ?? null, keyTypes[i]));
4305
+ const id = key.map((v, i) => encode(v, keyTypes[i])).join("\0");
4306
+ const b = buckets.get(id);
4307
+ if (b === void 0) buckets.set(id, {
4308
+ key,
4309
+ rows: [row]
4310
+ });
4311
+ else b.rows.push(row);
4312
+ }
4313
+ if (keys.length === 0 && buckets.size === 0) buckets.set("", {
4314
+ key: [],
4315
+ rows: []
4316
+ });
4317
+ } catch (err) {
4318
+ outOfRange(err);
4319
+ }
4320
+ let groups = [];
4321
+ try {
4322
+ for (const { key, rows } of buckets.values()) {
4323
+ const g = {};
4324
+ keys.forEach(([n], i) => {
4325
+ g[n] = keyTypes[i] === "date" ? isoMicros$1(key[i]) : key[i];
4326
+ });
4327
+ aggs.forEach((a, i) => {
4328
+ const at = argTypes[i];
4329
+ const values = rows.map((r) => readable(evalExpr(a.arg, r, env) ?? null, at));
4330
+ g[a.name] = aggregateOf(a.op, a.arg, argTypes[i], values, rows.length);
4331
+ });
4332
+ groups.push(g);
4333
+ }
4334
+ } catch (err) {
4335
+ outOfRange(err);
4336
+ }
4337
+ if (p.having !== void 0) {
4338
+ const having = p.having;
4339
+ try {
4340
+ groups = groups.filter((g) => evalExpr(having, {}, {
4341
+ output: g,
4342
+ fieldType: outType
4343
+ }) === true);
4344
+ } catch (err) {
4345
+ outOfRange(err);
4346
+ }
4347
+ }
4348
+ const order = [...(p.orderBy ?? []).map((c) => Object.entries(c)[0]), ...keys.map(([n]) => [n, "asc"])];
4349
+ groups.sort((a, b) => {
4350
+ for (const [name, dir] of order) {
4351
+ const t = outTypes.get(name) ?? null;
4352
+ const x = a[name];
4353
+ const y = b[name];
4354
+ const c = compare(x ?? null, y ?? null, t);
4355
+ if (c !== 0) return dir === "desc" && x != null && y != null ? -c : c;
4356
+ }
4357
+ return 0;
4358
+ });
4359
+ const start = p.offset ?? 0;
4360
+ const end = limit === void 0 ? void 0 : start + limit;
4361
+ const truncated = end !== void 0 && groups.length > end;
4362
+ return {
4363
+ groups: groups.slice(start, end),
4364
+ truncated
4365
+ };
4366
+ }
4367
+
4368
+ //#endregion
4369
+ //#region ../../packages/substrate-filter/src/pre-resolve-extension-operators.ts
4370
+ /**
4371
+ * Thrown when a registered extension operator's `execute` resolves to
4372
+ * anything other than `{ hits: [...] }`.
4373
+ */
4374
+ var ExtensionOperatorResultError = class extends Error {
4375
+ operator;
4376
+ constructor(operator) {
4377
+ super(`extension operator '${operator}' must resolve to { hits: [{ id, score, vector? }] }`);
4378
+ this.name = "ExtensionOperatorResultError";
4379
+ this.operator = operator;
4380
+ }
4381
+ };
4382
+ /**
4383
+ * Walks a where-tree, replaces every registered extension-operator entry with
4384
+ * an order-preserving `{ id: { in: [...] } }`, and returns BOTH the
4385
+ * rewritten where and a `meta` side-channel.
4386
+ *
4387
+ * Returns a new where object — the input is not mutated.
4388
+ */
4389
+ async function preResolveExtensionOperatorsDetailed(where, context) {
4390
+ const holder = { current: null };
4391
+ return {
4392
+ where: await walk(where, context, holder),
4393
+ meta: holder.current
4394
+ };
4395
+ }
4396
+ /** Recursive tree walk behind {@link preResolveExtensionOperatorsDetailed}. */
4397
+ async function walk(where, context, holder) {
4398
+ if (where === null || typeof where !== "object" || Array.isArray(where)) return where;
4399
+ const keys = Object.keys(where);
4400
+ if (keys.length === 0) return where;
4401
+ const out = {};
4402
+ const idClauses = [];
4403
+ for (const key of keys) {
4404
+ const value = where[key];
4405
+ if (key === "AND" || key === "OR") {
4406
+ if (Array.isArray(value)) out[key] = await Promise.all(value.map((sub) => walk(sub, context, holder)));
4407
+ else out[key] = value;
4408
+ continue;
4409
+ }
4410
+ if (key === "NOT") {
4411
+ if (value !== null && typeof value === "object" && !Array.isArray(value)) out[key] = await walk(value, context, holder);
4412
+ else out[key] = value;
4413
+ continue;
4414
+ }
4415
+ const op = getExtensionOperator(key);
4416
+ if (op === void 0) {
4417
+ out[key] = value;
4418
+ continue;
4419
+ }
4420
+ const result = await op.execute(value, context);
4421
+ if (!isHitsResult(result)) throw new ExtensionOperatorResultError(key);
4422
+ const meta = buildMeta(result.hits);
4423
+ holder.current = meta;
4424
+ idClauses.push({ id: { in: [...meta.orderedIds] } });
4425
+ }
4426
+ if (idClauses.length === 0) return out;
4427
+ if (out.id !== void 0) idClauses.unshift({ id: out.id });
4428
+ if (idClauses.length === 1) return {
4429
+ ...out,
4430
+ ...idClauses[0]
4431
+ };
4432
+ delete out.id;
4433
+ return { AND: [out, ...idClauses] };
4434
+ }
4435
+ /** Narrow an operator result to the hits envelope. */
4436
+ function isHitsResult(result) {
4437
+ return result !== null && typeof result === "object" && Array.isArray(result.hits);
4438
+ }
4439
+ /**
4440
+ * Build the ordered-ids list + computed Map from a hits array. Hits with a
4441
+ * non-string id are skipped (defensive — bad input becomes "no match" rather
4442
+ * than an error). The vector key is spread conditionally so a hit without a
4443
+ * vector yields a computed entry with NO `vector` key (exactOptionalPropertyTypes).
4444
+ */
4445
+ function buildMeta(hits) {
4446
+ const orderedIds = [];
4447
+ const computed = /* @__PURE__ */ new Map();
4448
+ for (const hit of hits) {
4449
+ if (hit === null || typeof hit !== "object") continue;
4450
+ const id = hit.id;
4451
+ if (typeof id !== "string") continue;
4452
+ const rawScore = hit.score;
4453
+ const score = typeof rawScore === "number" ? rawScore : 0;
4454
+ const rawVector = hit.vector;
4455
+ const hasVector = Array.isArray(rawVector);
4456
+ orderedIds.push(id);
4457
+ computed.set(id, {
4458
+ score,
4459
+ ...hasVector ? { vector: rawVector } : {}
4460
+ });
4461
+ }
4462
+ return {
4463
+ orderedIds,
4464
+ computed
4465
+ };
4466
+ }
4467
+
3041
4468
  //#endregion
3042
4469
  //#region ../../packages/substrate-filter/src/walk-forms.ts
3043
4470
  /**
@@ -3353,8 +4780,8 @@ const nextKeys = (indexes, lead) => [...new Set(indexes.flatMap((i) => i.only ==
3353
4780
  * list's order when its keys follow in its directions too (after an
3354
4781
  * outbound hop the far row is one primary-key read, so all of it is served);
3355
4782
  * - a `$ref` predicate is a residual on rows already narrowed: always served;
3356
- * - a seed filter, or a bucket's field, is served by an index leading with it;
3357
- * - a derived ordering is served only when a served seed filter bounds the
4783
+ * - a seed filter, or the field a group key truncates, is served by an index leading with it;
4784
+ * - an ordering by a select name is served only when a served seed filter bounds the
3358
4785
  * result (AND-ed, not under OR or NOT, and not only `neq`); no index ever
3359
4786
  * serves it, so it recommends none;
3360
4787
  * - anything else is unserved, recommending the index that would serve it
@@ -3430,14 +4857,15 @@ function classifyWalkService(input, indexesOf) {
3430
4857
  served: true
3431
4858
  });
3432
4859
  }
3433
- if (isObj$3(params.bucket) && typeof params.bucket.field === "string") {
3434
- const field = params.bucket.field;
3435
- clause(["bucket"], "bucket", leads(seedIndexes, [field], []), seed, [field]);
4860
+ if (isObj$3(params.groupBy)) for (const [name, e] of Object.entries(params.groupBy)) {
4861
+ const field = (isObj$3(e) && Array.isArray(e.dateTrunc) ? e.dateTrunc : void 0)?.[1];
4862
+ if (typeof field === "string") clause(["groupBy", name], "group", leads(seedIndexes, [field], []), seed, [field]);
3436
4863
  }
4864
+ const selected = isObj$3(params.select) ? params.select : {};
3437
4865
  orderOf(params.orderBy).forEach(([f], i) => {
3438
- if (f.startsWith("$")) out.push({
4866
+ if (Object.hasOwn(selected, f)) out.push({
3439
4867
  path: ["orderBy", String(i)],
3440
- kind: "derive",
4868
+ kind: "select",
3441
4869
  served: bounded
3442
4870
  });
3443
4871
  });
@@ -3911,8 +5339,9 @@ var Registry = class extends RegistryBase {
3911
5339
  /** Structural detector for the typed-edge-walk query grammar. Subscriptions and streams use it to refuse walks (query-only). */
3912
5340
  const WALK_PARAM_KEYS = [
3913
5341
  "aggregate",
3914
- "bucket",
3915
- "derive"
5342
+ "groupBy",
5343
+ "having",
5344
+ "offset"
3916
5345
  ];
3917
5346
  const isObj$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
3918
5347
  function inWhere(v, path) {
@@ -4021,6 +5450,9 @@ function fieldKindOf(def) {
4021
5450
  switch (def.kind) {
4022
5451
  case "scalar": switch (def.type) {
4023
5452
  case "number": return "scalar.number";
5453
+ case "int16": return "scalar.int16";
5454
+ case "int32": return "scalar.int32";
5455
+ case "int64": return "scalar.int64";
4024
5456
  case "string": return "scalar.string";
4025
5457
  case "boolean": return "scalar.boolean";
4026
5458
  case "date": return "scalar.date";
@@ -4036,6 +5468,9 @@ function fieldKindOf(def) {
4036
5468
  function opsAllowedFor(kind) {
4037
5469
  switch (kind) {
4038
5470
  case "scalar.number":
5471
+ case "scalar.int16":
5472
+ case "scalar.int32":
5473
+ case "scalar.int64":
4039
5474
  case "scalar.date": return NUMBER_OPS;
4040
5475
  case "scalar.string": return STRING_OPS;
4041
5476
  case "scalar.boolean": return BOOLEAN_OPS;
@@ -4052,6 +5487,9 @@ function opsAllowedFor(kind) {
4052
5487
  */
4053
5488
  const FIELD_KINDS = [
4054
5489
  "scalar.number",
5490
+ "scalar.int16",
5491
+ "scalar.int32",
5492
+ "scalar.int64",
4055
5493
  "scalar.string",
4056
5494
  "scalar.boolean",
4057
5495
  "scalar.date",
@@ -4077,7 +5515,7 @@ function effectiveFilterOperators(capabilities) {
4077
5515
  return out;
4078
5516
  }
4079
5517
  function isPrimitive(v) {
4080
- return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date;
5518
+ return v === null || typeof v === "string" || typeof v === "number" || typeof v === "bigint" || typeof v === "boolean" || v instanceof Date;
4081
5519
  }
4082
5520
  /**
4083
5521
  * Check the value shape for a given operator against the field's declared
@@ -4113,6 +5551,15 @@ function validatePrimitiveKind(fieldKind, value, path, op) {
4113
5551
  case "scalar.number":
4114
5552
  if (typeof value !== "number") throw new FilterValidationError("type_mismatch", `operator '${op}' expected number, got ${typeof value}`, path);
4115
5553
  return;
5554
+ case "scalar.int16":
5555
+ if (!isInt16(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an int16 (an integer from -32768 to 32767), got ${JSON.stringify(String(value))}`, path);
5556
+ return;
5557
+ case "scalar.int32":
5558
+ if (!isInt32(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an int32 (an integer from -2147483648 to 2147483647), got ${JSON.stringify(String(value))}`, path);
5559
+ return;
5560
+ case "scalar.int64":
5561
+ if (parseInt64(value) === void 0) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an int64 (a safe integer, a decimal string or a bigint), got ${JSON.stringify(String(value))}`, path);
5562
+ return;
4116
5563
  case "scalar.string":
4117
5564
  if (typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected string, got ${typeof value}`, path);
4118
5565
  return;
@@ -4219,7 +5666,8 @@ function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
4219
5666
  ...ctx,
4220
5667
  walk: bindGroup(where, path, ctx.walk)
4221
5668
  };
4222
- const keys = Object.keys(where);
5669
+ if (Object.hasOwn(where, "$expr")) validateWhereExpr(where, path, ctx);
5670
+ const keys = Object.keys(where).filter((k) => k !== "$expr");
4223
5671
  const hasLogical = keys.some((k) => LOGICAL_KEYS.has(k));
4224
5672
  const hasField = keys.some((k) => !LOGICAL_KEYS.has(k));
4225
5673
  if (hasLogical && hasField) throw new FilterValidationError("invalid_logical", `mixing logical combinators (AND/OR/NOT) with field keys at the same level is not allowed`, path);
@@ -4267,6 +5715,13 @@ function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
4267
5715
  if (def === METADATA_VIRTUAL_FIELDS.seq) assertSeqIntegers(where[fieldName], [...path, fieldName]);
4268
5716
  }
4269
5717
  }
5718
+ /** `where.$expr`: a boolean expression over the seed row's fields, outside walks and structs. */
5719
+ function validateWhereExpr(where, path, ctx) {
5720
+ const at = [...path, "$expr"];
5721
+ if (ctx.walk.depth > 0 || ctx.insideStruct === true) throw new FilterValidationError("expr_invalid", "$expr is valid only in the frame's own where, not inside a walk or struct", at);
5722
+ const type = checkFrameExpr(where.$expr, ctx.walk, false, at);
5723
+ if (type !== "boolean") throw new FilterValidationError("expr_invalid", `$expr must be boolean, got ${type}`, at);
5724
+ }
4270
5725
  const AGG_COMPARATORS = /* @__PURE__ */ new Set([
4271
5726
  "eq",
4272
5727
  "neq",
@@ -4313,7 +5768,7 @@ function validateAggPredicate(record, path, scope, h) {
4313
5768
  function assertSeqIntegers(leaf, path) {
4314
5769
  for (const [op, operand] of Object.entries(leaf)) for (const v of Array.isArray(operand) ? operand : [operand]) if (typeof v === "number" && !Number.isSafeInteger(v)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an integer for 'seq', got ${v}`, [...path, op]);
4315
5770
  }
4316
- function validateOrderBy(orderBy, fields, capabilities, path = ["orderBy"], derived = /* @__PURE__ */ new Set()) {
5771
+ function validateOrderBy(orderBy, fields, capabilities, path = ["orderBy"], selected = /* @__PURE__ */ new Set()) {
4317
5772
  if (!capabilities.orderBy) throw new FilterValidationError("capability_unsupported", "dataset does not support orderBy", path);
4318
5773
  if (!Array.isArray(orderBy)) throw new FilterValidationError("type_mismatch", "orderBy must be an array of { field: \"asc\" | \"desc\" } entries", path);
4319
5774
  orderBy.forEach((clause, i) => {
@@ -4327,14 +5782,7 @@ function validateOrderBy(orderBy, fields, capabilities, path = ["orderBy"], deri
4327
5782
  fieldName
4328
5783
  ]);
4329
5784
  if (fieldName === "id") return;
4330
- if (fieldName.startsWith("$")) {
4331
- if (derived.has(fieldName.slice(1))) return;
4332
- throw new FilterValidationError("derive_invalid", `orderBy '${fieldName}' needs derive.${fieldName.slice(1)} in params`, [
4333
- ...path,
4334
- String(i),
4335
- fieldName
4336
- ]);
4337
- }
5785
+ if (selected.has(fieldName)) return;
4338
5786
  const def = lookupField(fields, fieldName);
4339
5787
  if (!def) throw new FilterValidationError("unknown_field", `unknown field '${fieldName}' in orderBy${metadataHint(fieldName)}`, [
4340
5788
  ...path,
@@ -4365,7 +5813,8 @@ function validateFilter(input) {
4365
5813
  hidden: /* @__PURE__ */ new Set(),
4366
5814
  underOrNot: false,
4367
5815
  groupBound: false,
4368
- frameBindings: { count: 0 }
5816
+ frameBindings: { count: 0 },
5817
+ exprNodes: { count: 0 }
4369
5818
  };
4370
5819
  const h = frameHelpers(input.capabilities);
4371
5820
  const aggs = validateSelection(input.fields, ["fields"], seed, h);
@@ -4374,12 +5823,21 @@ function validateFilter(input) {
4374
5823
  aggs
4375
5824
  } : seed;
4376
5825
  if (input.where !== void 0) validateWhereAgainstFields(input.where, fields, ["where"], input.capabilities, { walk: scope });
4377
- const derived = validateFrameParams(input, scope, h);
4378
- if (input.orderBy !== void 0) validateOrderBy(input.orderBy, fields, input.capabilities, ["orderBy"], derived);
5826
+ const { selected } = validateFrameParams(input, scope, h);
5827
+ if (input.orderBy !== void 0) validateOrderBy(input.orderBy, fields, input.capabilities, ["orderBy"], selected);
4379
5828
  }
4380
5829
 
4381
5830
  //#endregion
4382
5831
  //#region ../../packages/substrate-core/src/filter/walk-validator.ts
5832
+ /**
5833
+ * Typed edge walk validation (spec 2026-10-24-typed-edge-walks §1, §2).
5834
+ *
5835
+ * Checks `_walk` nodes, `_agg` aggregates (where-side and in `fields`),
5836
+ * nested `{ _walk }` selections, `$ref` operands, and the frame params
5837
+ * `count`, `aggregate`, `groupBy` and `select`. The recursion into a walk's far-side `where` is handed back to the
5838
+ * filter validator, so the far type's fields and operators are checked exactly
5839
+ * as a top-level read of that type would be.
5840
+ */
4383
5841
  const MAX_WALK_DEPTH = 3;
4384
5842
  /** Joint quantification enumerates the product of the bound walks' neighbourhoods, so cap the factors. */
4385
5843
  const MAX_GROUP_BINDINGS = 3;
@@ -4612,14 +6070,13 @@ const WALK_AGG_KEYS = /* @__PURE__ */ new Set([
4612
6070
  "out",
4613
6071
  "where"
4614
6072
  ]);
4615
- const NO_KEYS = /* @__PURE__ */ new Set();
4616
6073
  /**
4617
6074
  * One aggregate function over `owner`'s fields, returning its value kind:
4618
6075
  * `count`, `avg` and `sum` are numbers; `min`, `max` and `latest` take their
4619
- * field's kind. `latest` picks a row, so only a per-row walk aggregate has it.
6076
+ * field's kind. `latest` picks a row: it belongs to a per-row walk aggregate.
4620
6077
  */
4621
- function aggKind(agg, extra, owner, path, h, allowLatest) {
4622
- for (const k of Object.keys(agg)) if (!extra.has(k) && !AGG_FNS.has(k)) fail("agg_invalid", `unknown aggregate key '${k}'`, [...path, k]);
6078
+ function aggKind(agg, owner, path, h) {
6079
+ for (const k of Object.keys(agg)) if (!WALK_AGG_KEYS.has(k) && !AGG_FNS.has(k)) fail("agg_invalid", `unknown aggregate key '${k}'`, [...path, k]);
4623
6080
  const fns = Object.keys(agg).filter((k) => AGG_FNS.has(k));
4624
6081
  if (fns.length !== 1) fail("agg_invalid", "an aggregate names exactly one of count, avg, sum, min, max or latest", path);
4625
6082
  const [fn] = fns;
@@ -4643,7 +6100,6 @@ function aggKind(agg, extra, owner, path, h, allowLatest) {
4643
6100
  case "min":
4644
6101
  case "max": return field(v, at, (k) => DATE_OR_NUMBER.has(k), "a number or date field");
4645
6102
  default:
4646
- if (!allowLatest) fail("agg_invalid", "latest picks one row per seed row; a frame aggregate takes count, avg, sum, min or max", at);
4647
6103
  if (!isObj$1(v) || Object.keys(v).some((k) => k !== "by" && k !== "value")) fail("agg_invalid", "latest takes { by: <dateField>, value: <field> }", at);
4648
6104
  field(v.by, [...at, "by"], (k) => k === "scalar.date", "a date field");
4649
6105
  return field(v.value, [...at, "value"], (k) => k.startsWith("scalar.") && k !== "scalar.json", "a scalar field");
@@ -4653,7 +6109,7 @@ function aggKind(agg, extra, owner, path, h, allowLatest) {
4653
6109
  function validateWalkAgg(agg, path, scope, h) {
4654
6110
  if (!isObj$1(agg)) fail("agg_invalid", "_agg expects an aggregate object", path);
4655
6111
  const hop = resolveHop(agg, path, scope);
4656
- const kind = aggKind(agg, WALK_AGG_KEYS, hop, path, h, true);
6112
+ const kind = aggKind(agg, hop, path, h);
4657
6113
  if (agg.where !== void 0) h.validateWhere(agg.where, [...path, "where"], farScope(scope, hop));
4658
6114
  return kind;
4659
6115
  }
@@ -4730,90 +6186,180 @@ function validateSelection(fields, path, scope, h) {
4730
6186
  }
4731
6187
  return aggs;
4732
6188
  }
6189
+ /** Row keys a read projects besides the type's fields, which a select value must not overwrite. */
6190
+ const RESERVED_ROW_KEYS = /* @__PURE__ */ new Set([
6191
+ "id",
6192
+ "shortId",
6193
+ "_metadata",
6194
+ "_deletedAt",
6195
+ "createdAt",
6196
+ "updatedAt",
6197
+ "createdBy",
6198
+ "updatedBy",
6199
+ "createdById",
6200
+ "createdByKind",
6201
+ "updatedById",
6202
+ "updatedByKind",
6203
+ "seq"
6204
+ ]);
6205
+ /** The expression type of a walk aggregate's value kind; a boolean or int64 value is not usable. */
6206
+ const AGG_EXPR_TYPE = {
6207
+ "scalar.number": "number",
6208
+ "scalar.date": "date",
6209
+ "scalar.string": "string"
6210
+ };
6211
+ function exprScopeOf(scope, withAgg) {
6212
+ return { field(name) {
6213
+ if (name.startsWith("_agg.")) {
6214
+ const kind = withAgg ? scope.aggs?.get(name.slice(5)) : void 0;
6215
+ return kind === void 0 ? void 0 : AGG_EXPR_TYPE[kind];
6216
+ }
6217
+ return (scope.outputsOnly ? void 0 : metadataExprType(name)) ?? (Object.hasOwn(scope.fields, name) ? exprTypeOfField(scope.fields[name]) : void 0);
6218
+ } };
6219
+ }
6220
+ /** Refuses a bare `_agg.<name>` whose value type (boolean, int64, ...) no expression can use. */
6221
+ function refuseUnusableAgg(expr, scope, path, depth = 0) {
6222
+ if (depth > 2 * EXPR_LIMITS.maxDepth + 2) return;
6223
+ if (typeof expr === "string") {
6224
+ const kind = expr.startsWith("_agg.") ? scope.aggs?.get(expr.slice(5)) : void 0;
6225
+ if (kind !== void 0 && AGG_EXPR_TYPE[kind] === void 0) fail("expr_invalid", `'${expr}' has a ${kind.replace("scalar.", "")} value, which an expression cannot use (only number, date and string aggregates)`, path);
6226
+ } else if (Array.isArray(expr)) for (const e of expr) refuseUnusableAgg(e, scope, path, depth + 1);
6227
+ else if (isObj$1(expr)) {
6228
+ for (const [k, v] of Object.entries(expr)) if (k !== "lit" && k !== "int64") refuseUnusableAgg(v, scope, path, depth + 1);
6229
+ }
6230
+ }
6231
+ /** Checks one expression of the frame, charging its nodes to the frame's budget; returns its type. */
6232
+ function checkFrameExpr(expr, scope, withAgg, path) {
6233
+ if (withAgg) refuseUnusableAgg(expr, scope, path);
6234
+ const r = checkExpr(expr, exprScopeOf(scope, withAgg), path);
6235
+ if (!r.ok) fail("expr_invalid", r.message, r.path);
6236
+ const used = scope.exprNodes ?? { count: 0 };
6237
+ used.count += r.nodes;
6238
+ if (used.count > EXPR_LIMITS.maxNodesPerFrame) fail("expr_invalid", `the frame's expressions have more than maxNodesPerFrame (${EXPR_LIMITS.maxNodesPerFrame}) nodes`, path);
6239
+ return r.type;
6240
+ }
4733
6241
  /**
4734
- * `count`, `aggregate`, `bucket` and `derive`, and what each excludes.
4735
- * Returns the derive names `orderBy` may use as `$<name>`.
6242
+ * `count`, `aggregate`, `groupBy` and `select`, and what each excludes.
6243
+ * Returns the names `orderBy` may use: select names and group outputs.
4736
6244
  */
4737
6245
  function validateFrameParams(p, scope, h) {
4738
6246
  if (p.count !== void 0 && typeof p.count !== "boolean") fail("type_mismatch", "count takes true or false", ["count"]);
4739
6247
  if (p.count === true) {
4740
6248
  for (const k of [
4741
6249
  "aggregate",
4742
- "bucket",
4743
- "derive",
6250
+ "select",
4744
6251
  "orderBy",
4745
6252
  "cursor"
4746
6253
  ]) if (p[k] !== void 0) fail("count_conflict", `count returns a count; it takes no '${k}'`, [k]);
4747
6254
  for (const k of Object.keys(p.fields ?? {})) if (k !== "id") fail("count_conflict", `count returns no rows; it selects only id, not '${k}'`, ["fields", k]);
4748
6255
  }
4749
- const seed = {
4750
- typeName: scope.typeName ?? "",
4751
- fields: scope.fields
4752
- };
6256
+ const outputs = /* @__PURE__ */ new Map();
6257
+ const grouped = p.aggregate !== void 0;
6258
+ for (const k of [
6259
+ "groupBy",
6260
+ "having",
6261
+ "offset"
6262
+ ]) if (p[k] !== void 0 && !grouped) fail("agg_invalid", `${k} shapes an aggregate's groups; it needs aggregate`, [k]);
4753
6263
  if (p.aggregate !== void 0) {
4754
- for (const k of [
4755
- "derive",
6264
+ const refused = p.groupBy !== void 0 ? ["select", "cursor"] : [
6265
+ "select",
4756
6266
  "orderBy",
4757
6267
  "cursor"
4758
- ]) if (p[k] !== void 0) fail("agg_invalid", `aggregate returns aggregate rows; it takes no '${k}'`, [k]);
6268
+ ];
6269
+ for (const k of refused) if (p[k] !== void 0) fail("agg_invalid", `aggregate returns aggregate rows; it takes no '${k}'`, [k]);
4759
6270
  for (const k of Object.keys(p.fields ?? {})) if (k !== "id") fail("agg_invalid", `aggregate returns aggregate rows; it selects only id, not '${k}'`, ["fields", k]);
4760
6271
  if (!isObj$1(p.aggregate)) fail("agg_invalid", "aggregate maps names to aggregates", ["aggregate"]);
4761
6272
  if (Object.keys(p.aggregate).length === 0) fail("agg_invalid", "aggregate needs at least one entry", ["aggregate"]);
4762
6273
  for (const [n, agg] of Object.entries(p.aggregate)) {
4763
6274
  const at = ["aggregate", n];
4764
- if (!IDENT.test(n) || n === "bucket" && p.bucket !== void 0) fail("agg_invalid", `aggregate name '${n}' must be an identifier other than bucket`, at);
6275
+ if (!IDENT.test(n)) fail("agg_invalid", `aggregate name '${n}' must be an identifier`, at);
4765
6276
  if (!isObj$1(agg)) fail("agg_invalid", "an aggregate is an object such as { count: true }", at);
4766
- aggKind(agg, NO_KEYS, seed, at, h, false);
4767
- }
4768
- }
4769
- if (p.bucket !== void 0) {
4770
- const b = p.bucket;
4771
- if (p.aggregate === void 0) fail("bucket_invalid", "bucket groups an aggregate; it needs aggregate", ["bucket"]);
4772
- if (!isObj$1(b) || Object.keys(b).some((k) => k !== "field" && k !== "by")) fail("bucket_invalid", "bucket takes { field, by }", ["bucket"]);
4773
- if (b.by !== "day" && b.by !== "hour") fail("bucket_invalid", "bucket by is 'day' or 'hour'", ["bucket", "by"]);
4774
- const def = typeof b.field === "string" ? h.lookup(scope.fields, b.field) : void 0;
4775
- if (def === void 0 || h.kindOf(def) !== "scalar.date") fail("bucket_invalid", `bucket field '${String(b.field)}' is not a date field`, ["bucket", "field"]);
4776
- }
4777
- const derived = /* @__PURE__ */ new Set();
4778
- if (p.derive !== void 0) {
4779
- if (!isObj$1(p.derive)) fail("derive_invalid", "derive maps names to { diff }, { ratio } or { value }", ["derive"]);
4780
- for (const [n, spec] of Object.entries(p.derive)) {
4781
- const at = ["derive", n];
4782
- if (!IDENT.test(n)) fail("derive_invalid", `derive name '${n}' must be an identifier`, at);
4783
- const entries = isObj$1(spec) ? Object.entries(spec) : [];
4784
- const [op, operands] = entries[0] ?? [];
4785
- if (entries.length === 1 && op === "value") {
4786
- if (typeof operands !== "string") fail("derive_invalid", "a derive { value } takes one operand such as '_agg.x'", at);
4787
- deriveOperand(operands, [...at, op], scope, h);
4788
- derived.add(n);
4789
- continue;
4790
- }
4791
- if (entries.length !== 1 || op !== "diff" && op !== "ratio" || !Array.isArray(operands) || operands.length !== 2) fail("derive_invalid", "a derive is { diff: [a, b] }, { ratio: [a, b] } or { value: a }", at);
4792
- operands.forEach((o, i) => {
4793
- deriveOperand(o, [
4794
- ...at,
4795
- op,
4796
- String(i)
4797
- ], scope, h);
4798
- });
4799
- derived.add(n);
6277
+ outputs.set(n, frameAggType(agg, scope, at));
4800
6278
  }
4801
6279
  }
4802
- return derived;
4803
- }
4804
- /** `$.<number field>` of the seed row, or `_agg.<name>` of a number-valued frame aggregate. */
4805
- function deriveOperand(o, path, scope, h) {
4806
- const m = typeof o === "string" ? /^(\$|_agg)\.(.+)$/.exec(o) : null;
4807
- let kind;
4808
- if (m !== null) {
4809
- const [, src, name] = m;
4810
- if (src === "_agg") kind = scope.aggs?.get(name);
4811
- else {
4812
- const def = h.lookup(scope.fields, name);
4813
- kind = def === void 0 ? void 0 : h.kindOf(def);
6280
+ if (p.groupBy !== void 0) {
6281
+ if (!isObj$1(p.groupBy) || Object.keys(p.groupBy).length === 0) fail("group_invalid", "groupBy maps names to expressions, and needs at least one", ["groupBy"]);
6282
+ for (const [n, expr] of Object.entries(p.groupBy)) {
6283
+ const at = ["groupBy", n];
6284
+ if (!IDENT.test(n)) fail("group_invalid", `groupBy name '${n}' must be an identifier`, at);
6285
+ if (outputs.has(n)) fail("group_invalid", `groupBy name '${n}' is also an aggregate name`, at);
6286
+ outputs.set(n, checkFrameExpr(expr, scope, false, at));
6287
+ }
6288
+ }
6289
+ if (p.having !== void 0) {
6290
+ const named = {
6291
+ ...scope,
6292
+ outputsOnly: true,
6293
+ fields: Object.fromEntries([...outputs].map(([n, t]) => [n, {
6294
+ kind: "scalar",
6295
+ type: t
6296
+ }]))
6297
+ };
6298
+ const t = checkFrameExpr(p.having, named, false, ["having"]);
6299
+ if (t !== "boolean") fail("expr_invalid", `having must be boolean, got ${t}`, ["having"]);
6300
+ }
6301
+ if (p.offset !== void 0 && (!Number.isSafeInteger(p.offset) || p.offset < 0)) fail("type_mismatch", "offset takes a non-negative integer", ["offset"]);
6302
+ if (p.groupBy !== void 0 && Array.isArray(p.orderBy)) p.orderBy.forEach((c, i) => {
6303
+ const k = isObj$1(c) ? Object.keys(c)[0] : void 0;
6304
+ if (k !== void 0 && !outputs.has(k)) fail("agg_invalid", `orderBy '${k}' names no groupBy or aggregate output`, [
6305
+ "orderBy",
6306
+ String(i),
6307
+ k
6308
+ ]);
6309
+ });
6310
+ const selected = /* @__PURE__ */ new Set();
6311
+ if (p.select !== void 0) {
6312
+ if (!isObj$1(p.select)) fail("select_invalid", "select maps names to expressions", ["select"]);
6313
+ for (const [n, expr] of Object.entries(p.select)) {
6314
+ const at = ["select", n];
6315
+ if (!IDENT.test(n)) fail("select_invalid", `select name '${n}' must be an identifier`, at);
6316
+ const nested = p.fields?.[n];
6317
+ if (h.lookup(scope.fields, n) !== void 0 || RESERVED_ROW_KEYS.has(n) || isObj$1(nested) && "_walk" in nested) fail("select_invalid", `select name '${n}' collides with a field, a row key or a nested selection of the type`, at);
6318
+ checkFrameExpr(expr, scope, true, at);
6319
+ selected.add(n);
4814
6320
  }
4815
6321
  }
4816
- if (kind !== "scalar.number") fail("derive_invalid", `derive operand '${String(o)}' must be a number field '$.<field>' or a number-valued '_agg.<name>' in this frame's fields`, path);
6322
+ return { selected: /* @__PURE__ */ new Set([...selected, ...outputs.keys()]) };
6323
+ }
6324
+ const FRAME_AGG_FNS = [
6325
+ "count",
6326
+ "countDistinct",
6327
+ "avg",
6328
+ "sum",
6329
+ "min",
6330
+ "max"
6331
+ ];
6332
+ /** A frame aggregate: one function over an expression (`count: true` counts rows). Returns its value type. */
6333
+ function frameAggType(agg, scope, path) {
6334
+ for (const k of Object.keys(agg)) {
6335
+ if (k === "latest") fail("agg_invalid", "latest picks one row per seed row; a frame aggregate takes count, countDistinct, avg, sum, min or max", [...path, k]);
6336
+ if (!FRAME_AGG_FNS.includes(k)) fail("agg_invalid", `unknown aggregate key '${k}'`, [...path, k]);
6337
+ }
6338
+ if (Object.keys(agg).length !== 1) fail("agg_invalid", "an aggregate names exactly one of count, countDistinct, avg, sum, min or max", path);
6339
+ const [fn] = Object.keys(agg);
6340
+ const at = [...path, fn];
6341
+ if (fn === "count" && agg.count === true) return "number";
6342
+ const arg = agg[fn];
6343
+ if (fn === "count" && (arg === null || typeof arg === "number" || typeof arg === "boolean" || isObj$1(arg) && ("lit" in arg || "int64" in arg))) fail("agg_invalid", "count takes true (rows) or an expression, not another literal", at);
6344
+ const t = checkFrameExpr(arg, scope, false, at);
6345
+ const ok = {
6346
+ avg: ["number", "int64"],
6347
+ sum: ["number", "int64"],
6348
+ min: [
6349
+ "number",
6350
+ "int64",
6351
+ "string",
6352
+ "date"
6353
+ ],
6354
+ max: [
6355
+ "number",
6356
+ "int64",
6357
+ "string",
6358
+ "date"
6359
+ ]
6360
+ };
6361
+ if (ok[fn] !== void 0 && !ok[fn].includes(t)) fail("agg_invalid", `${fn} needs ${ok[fn].join(", ")}; the argument is ${t}`, at);
6362
+ return fn === "count" || fn === "countDistinct" || fn === "avg" ? "number" : t;
4817
6363
  }
4818
6364
 
4819
6365
  //#endregion
@@ -5417,7 +6963,8 @@ function runFilterGuard(deps, input) {
5417
6963
  if (entry.fields !== void 0) {
5418
6964
  const typeSchema = deps.schemaFor(ns).types[name];
5419
6965
  if (typeSchema) {
5420
- const unknown = Object.keys(entry.fields).filter((f) => !(f in typeSchema.fields) && !PROJECTION_VIRTUAL_KEYS.has(f) && computedFieldOwner(f) === void 0 && !isWalkSelection(f, entry.fields[f]));
6966
+ const selectNames = entry.params?.select ?? {};
6967
+ const unknown = Object.keys(entry.fields).filter((f) => !(f in typeSchema.fields) && !PROJECTION_VIRTUAL_KEYS.has(f) && computedFieldOwner(f) === void 0 && !isWalkSelection(f, entry.fields[f]) && !Object.hasOwn(selectNames, f));
5421
6968
  if (unknown.length > 0) {
5422
6969
  envelope._diagnostics ??= {};
5423
6970
  envelope._diagnostics[key] = { unknownProjectionFields: unknown };
@@ -5429,11 +6976,12 @@ function runFilterGuard(deps, input) {
5429
6976
  }
5430
6977
  }
5431
6978
  const walks = usesWalkGrammar(entry);
5432
- if (where === void 0 && orderBy === void 0 && !walks) return true;
6979
+ const selects = entry.params?.select !== void 0;
6980
+ if (where === void 0 && orderBy === void 0 && !walks && !selects) return true;
5433
6981
  return validateAgainst(deps, envelope, key, ns, name, dataset, {
5434
6982
  ...where !== void 0 ? { where } : {},
5435
6983
  ...orderBy !== void 0 ? { orderBy } : {},
5436
- ...walks ? walkInput(entry) : {}
6984
+ ...walks || selects ? walkInput(entry) : {}
5437
6985
  });
5438
6986
  }
5439
6987
  /**
@@ -5489,12 +7037,14 @@ function isWalkSelection(name, sel) {
5489
7037
  }
5490
7038
  /** The walk-grammar params and field selection `validateFilter` checks. */
5491
7039
  function walkInput(entry) {
5492
- const { count, aggregate, bucket, derive, cursor } = entry.params ?? {};
7040
+ const { count, aggregate, groupBy, having, offset, select, cursor } = entry.params ?? {};
5493
7041
  return {
5494
7042
  count,
5495
7043
  aggregate,
5496
- bucket,
5497
- derive,
7044
+ groupBy,
7045
+ having,
7046
+ offset,
7047
+ select,
5498
7048
  cursor,
5499
7049
  ...entry.fields !== void 0 ? { fields: entry.fields } : {}
5500
7050
  };
@@ -5659,6 +7209,15 @@ function partitionMutateByTxScope(singleFrameKeys, parsedByKey, datasets) {
5659
7209
  * short-form numeric ids legitimately miss and are excluded.
5660
7210
  */
5661
7211
  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
7212
+ /**
7213
+ * Whether row-filter obligations are already settled for `entry`'s result. A
7214
+ * by-filter mutation's resolver filters the rows it writes, and a delete
7215
+ * returns `{ id, deleted }`, which carries no row values to filter: running a
7216
+ * row predicate on it drops a committed delete to null.
7217
+ */
7218
+ function resolverFiltered(entry) {
7219
+ return entry.filterTarget !== void 0 || entry.verb === "delete";
7220
+ }
5662
7221
  function shapeResult(input) {
5663
7222
  const { envelope, key, entry, ctx, result, metric } = input;
5664
7223
  const decision = input.resolverFiltered === true ? {
@@ -6287,6 +7846,7 @@ const KNOWN_SUBSCRIBE_PARAMS = /* @__PURE__ */ new Set([
6287
7846
  "orderBy",
6288
7847
  "_allowTableScan"
6289
7848
  ]);
7849
+ const NO_FIELDS = () => void 0;
6290
7850
  var SubscribeSubsystem = class {
6291
7851
  #namespaces;
6292
7852
  #datasets;
@@ -6295,6 +7855,8 @@ var SubscribeSubsystem = class {
6295
7855
  #subscriptionQueueLimit;
6296
7856
  #snapshotLimit;
6297
7857
  #schemaFor;
7858
+ /** One field lookup per type's field map, so the evaluator's per-node type cache holds across events. */
7859
+ #fieldDefs = /* @__PURE__ */ new WeakMap();
6298
7860
  #isTombstoned;
6299
7861
  /**
6300
7862
  * Live subscription bus (§5.4). Keyed by `"<ns>/<type>"` so the mutate
@@ -6871,6 +8433,15 @@ var SubscribeSubsystem = class {
6871
8433
  }
6872
8434
  idSet.add(entry);
6873
8435
  }
8436
+ #fieldDefOf(fields) {
8437
+ if (fields === void 0) return NO_FIELDS;
8438
+ let f = this.#fieldDefs.get(fields);
8439
+ if (f === void 0) {
8440
+ f = (name) => Object.hasOwn(fields, name) ? fields[name] : void 0;
8441
+ this.#fieldDefs.set(fields, f);
8442
+ }
8443
+ return f;
8444
+ }
6874
8445
  /**
6875
8446
  * Remove an entry from the bus + per-call index (mirrors the drain teardown).
6876
8447
  * Used when a post-registration step bails before the snapshot ships.
@@ -6928,7 +8499,7 @@ var SubscribeSubsystem = class {
6928
8499
  let whereMatches;
6929
8500
  try {
6930
8501
  const fields = this.#schemaFor(entry.ns).types[entry.type]?.fields;
6931
- whereMatches = entry.where === void 0 ? true : evaluateWhere(row, entry.where, (f) => fields?.[f]);
8502
+ whereMatches = entry.where === void 0 ? true : evaluateWhere(row, entry.where, this.#fieldDefOf(fields));
6932
8503
  } catch (err) {
6933
8504
  const code = isResolverFrameError(err) ? err.code : "resolver_error";
6934
8505
  this.#enqueueFrame(entry, {
@@ -7779,7 +9350,7 @@ var Engine = class {
7779
9350
  return null;
7780
9351
  }
7781
9352
  if (limit > limits.maxLimit) {
7782
- addError(envelope, [key, "limit"], `limit ${limit} exceeds the maximum page of ${limits.maxLimit}; page with the returned cursor`, "limit_exceeds_max", { max: limits.maxLimit });
9353
+ addError(envelope, [key, "limit"], `limit ${limit} exceeds the maximum page of ${limits.maxLimit}; ${entry.params?.aggregate !== void 0 ? "page with offset" : "page with the returned cursor"}`, "limit_exceeds_max", { max: limits.maxLimit });
7783
9354
  return null;
7784
9355
  }
7785
9356
  return entry;
@@ -8219,7 +9790,7 @@ var Engine = class {
8219
9790
  decision,
8220
9791
  result,
8221
9792
  metric: this.#metric,
8222
- resolverFiltered: registryEntry.filterTarget !== void 0
9793
+ resolverFiltered: resolverFiltered(registryEntry)
8223
9794
  });
8224
9795
  return false;
8225
9796
  }
@@ -8586,7 +10157,7 @@ var Engine = class {
8586
10157
  decision: p.decision,
8587
10158
  result: rows[j] ?? null,
8588
10159
  metric: this.#metric,
8589
- resolverFiltered: p.registryEntry.filterTarget !== void 0
10160
+ resolverFiltered: resolverFiltered(p.registryEntry)
8590
10161
  });
8591
10162
  const shaped = slotResultOf(scratch, key);
8592
10163
  results[i] = shaped;
@@ -9567,6 +11138,15 @@ function rejectUnknownParams(resolverName, typeName, params, allowed) {
9567
11138
  });
9568
11139
  }
9569
11140
  /**
11141
+ * Refuse a caller-supplied value for a `readonly` field, on create and update
11142
+ * alike. shortId is the main case: the engine allocates it.
11143
+ *
11144
+ * @throws ResolverFrameError `readonly_field` naming the first such field
11145
+ */
11146
+ function assertNoReadonlyFields(params, fieldDefs) {
11147
+ for (const [name, def] of Object.entries(fieldDefs)) if (def.kind === "scalar" && def.readonly === true && name in params) throw new ResolverFrameError("readonly_field", `Cannot set read-only field '${name}' (engine-allocated)`, { field: name });
11148
+ }
11149
+ /**
9570
11150
  * Assert that the caller has not supplied any server-controlled fields.
9571
11151
  *
9572
11152
  * Tier-0: `_metadata` is rejected explicitly — the resolver's spread ordering
@@ -9727,11 +11307,13 @@ function assertScalarTypes(params, fieldDefs, phase) {
9727
11307
  if (def.kind !== "scalar" || !Object.hasOwn(params, name)) continue;
9728
11308
  const v = params[name];
9729
11309
  if (v === null) continue;
9730
- if (!(def.type === "number" ? typeof v === "number" && Number.isFinite(v) : def.type === "boolean" ? typeof v === "boolean" : def.type === "date" ? typeof v === "string" ? isIsoTimestamp(v) : v instanceof Date && Number.isFinite(v.getTime()) : true)) throw new ResolverFrameError("invalid_field_type", `Cannot ${phase} '${name}' with ${JSON.stringify(v)}: expected a ${def.type === "date" ? "date (ISO 8601 string)" : def.type}.`, {
9731
- field: name,
9732
- expected: def.type,
9733
- phase
9734
- });
11310
+ if (def.type === "int64") {
11311
+ const n = parseInt64(v);
11312
+ if (n !== void 0) params[name] = n;
11313
+ else throwInvalidScalar(name, v, def.type, phase);
11314
+ continue;
11315
+ }
11316
+ if (!(def.type === "number" ? typeof v === "number" && Number.isFinite(v) : def.type === "int16" ? isInt16(v) : def.type === "int32" ? isInt32(v) : def.type === "boolean" ? typeof v === "boolean" : def.type === "date" ? typeof v === "string" ? isIsoTimestamp(v) : v instanceof Date && Number.isFinite(v.getTime()) : true)) throwInvalidScalar(name, v, def.type, phase);
9735
11317
  }
9736
11318
  }
9737
11319
  /**
@@ -9827,6 +11409,13 @@ function assertServerSetFieldsFillable(typeName, fieldDefs) {
9827
11409
  const names = unfillable.map((n) => `'${n}'`).join(", ");
9828
11410
  throw new Error(`type '${typeName}': serverSet field(s) ${names} are non-nullable with no default, but clients may not supply them on create and autoCRUD does not stamp serverSet fields, so autoCRUD create could never fill them. Declare them \`nullable: true\` and stamp them from server-side code, or give them a \`default\`.`);
9829
11411
  }
11412
+ function throwInvalidScalar(name, v, type, phase) {
11413
+ throw new ResolverFrameError("invalid_field_type", `Cannot ${phase} '${name}' with ${JSON.stringify(typeof v === "bigint" ? String(v) : v)}: expected a ${type === "date" ? "date (ISO 8601 string)" : type}.`, {
11414
+ field: name,
11415
+ expected: type,
11416
+ phase
11417
+ });
11418
+ }
9830
11419
 
9831
11420
  //#endregion
9832
11421
  //#region ../../packages/substrate-sdk/src/autocrud/autocrud-get.ts
@@ -9860,8 +11449,10 @@ const KNOWN_LIST_PARAMS = /* @__PURE__ */ new Set([
9860
11449
  "_allowTableScan",
9861
11450
  "count",
9862
11451
  "aggregate",
9863
- "bucket",
9864
- "derive"
11452
+ "groupBy",
11453
+ "having",
11454
+ "offset",
11455
+ "select"
9865
11456
  ]);
9866
11457
  function extractLimit(params) {
9867
11458
  if (!params) return void 0;
@@ -9890,8 +11481,10 @@ function listResolver(typeName, dataset, options = {}) {
9890
11481
  const p = args.params ?? {};
9891
11482
  if (p.count !== void 0) readParams.count = p.count;
9892
11483
  if (p.aggregate !== void 0) readParams.aggregate = p.aggregate;
9893
- if (p.bucket !== void 0) readParams.bucket = p.bucket;
9894
- if (p.derive !== void 0) readParams.derive = p.derive;
11484
+ if (p.groupBy !== void 0) readParams.groupBy = p.groupBy;
11485
+ if (p.having !== void 0) readParams.having = p.having;
11486
+ if (typeof p.offset === "number") readParams.offset = p.offset;
11487
+ if (p.select !== void 0) readParams.select = p.select;
9895
11488
  const fields = args.fields;
9896
11489
  if (fields !== void 0) {
9897
11490
  const entries = Object.entries(fields);
@@ -9907,58 +11500,6 @@ function listResolver(typeName, dataset, options = {}) {
9907
11500
  };
9908
11501
  }
9909
11502
 
9910
- //#endregion
9911
- //#region ../../packages/substrate-sdk/src/autocrud/autocrud-purge.ts
9912
- /**
9913
- * autoCRUD `purge<T>` resolver. Spec: §5.1 (`purge<T>({ id })` — optional
9914
- * admin-only hard-delete), §4.5 (`purge` on nonexistent row returns
9915
- * `{ deleted: 0 }` without error).
9916
- *
9917
- * Purge is hard-delete: it bypasses the `_deletedAt` tombstone lifecycle and
9918
- * removes the row outright. Downstream edges observe the row as MISSING on
9919
- * subsequent reads; the sweep's non-bridged MISSING branch treats this as
9920
- * deleted and fans policy per §6.3.
9921
- *
9922
- * Admin gate: this resolver does NOT embed a capability check. The gate is a
9923
- * `Policy` composed at install time — see `installAutoCrud(..., { purgeable: true })`
9924
- * which attaches `requireCapability(adminCapability)` by default. Callers can
9925
- * override with any policy.
9926
- *
9927
- * Kill switch: assertHardDeleteAllowed() is the first thing — refusal
9928
- * short-circuits before any state read.
9929
- */
9930
- const KNOWN_PURGE_PARAMS = /* @__PURE__ */ new Set(["id"]);
9931
- function purgeResolver(typeName, dataset) {
9932
- return async (_ctx, args) => {
9933
- rejectUnknownParams("purge", typeName, args.params, KNOWN_PURGE_PARAMS);
9934
- assertHardDeleteAllowed();
9935
- const ds = args.dataset ?? dataset;
9936
- const id = coerceId(args.params?.id);
9937
- if (id === void 0) throw new ResolverFrameError("missing_id", `purgeResolver('${typeName}'): params.id is required`, { field: "id" });
9938
- const { rows: existing } = await ds.read(typeName, {
9939
- id,
9940
- includeDeleted: true
9941
- });
9942
- const preRow = existing[0];
9943
- const { deleted } = await ds.purge(typeName, [id]);
9944
- const purged = deleted > 0;
9945
- if (purged && args.onWrite !== void 0) {
9946
- const event = {
9947
- ns: ds.namespace,
9948
- type: typeName,
9949
- id,
9950
- operation: "delete",
9951
- ...preRow !== void 0 ? { row: preRow } : {}
9952
- };
9953
- args.onWrite(event);
9954
- }
9955
- return {
9956
- id,
9957
- purged
9958
- };
9959
- };
9960
- }
9961
-
9962
11503
  //#endregion
9963
11504
  //#region ../../packages/substrate-sdk/src/delete.ts
9964
11505
  async function deleteRow(args) {
@@ -10027,7 +11568,7 @@ function prepareCreateRow(rawParams, fields) {
10027
11568
  const params = dropUndefinedParams(rawParams ?? {});
10028
11569
  if (fields) {
10029
11570
  assertNoClientServerFields(params, fields, "create");
10030
- for (const [fieldName, def] of Object.entries(fields)) if (def.kind === "scalar" && def.readonly === true && fieldName in params) throw new ResolverFrameError("readonly_field", `Cannot set read-only field '${fieldName}' (engine-allocated)`, { field: fieldName });
11571
+ assertNoReadonlyFields(params, fields);
10031
11572
  Object.assign(params, normaliseVocabValues(params, fields));
10032
11573
  assertEnumValues(params, fields);
10033
11574
  assertNoUnknownFields(params, fields, "create");
@@ -10107,6 +11648,7 @@ function prepareUpdate(typeName, rawParams, fields) {
10107
11648
  function preparePatch(rawParams, fields) {
10108
11649
  if (fields) assertNoClientServerFields(rawParams ?? {}, fields, "update");
10109
11650
  const sent = dropUndefinedParams(rawParams ?? {});
11651
+ if (fields) assertNoReadonlyFields(sent, fields);
10110
11652
  const params = fields !== void 0 ? normaliseVocabValues(sent, fields) : sent;
10111
11653
  if ("_deletedAt" in params) throw new ReservedField("_deletedAt");
10112
11654
  if (fields) {
@@ -10712,8 +12254,65 @@ function updateResolver(typeName, dataset, edges, options = {}) {
10712
12254
  return singleFrame(updateBatchResolver(typeName, dataset, edges, options));
10713
12255
  }
10714
12256
  /** `delete<T>`: the batch resolver with one element. */
10715
- function deleteResolver(typeName, dataset, edges) {
10716
- return singleFrame(deleteBatchResolver(typeName, dataset, edges));
12257
+ function deleteResolver(typeName, dataset, edges, options = {}) {
12258
+ return singleFrame(deleteBatchResolver(typeName, dataset, edges, options));
12259
+ }
12260
+
12261
+ //#endregion
12262
+ //#region ../../packages/substrate-sdk/src/autocrud/autocrud-purge.ts
12263
+ /**
12264
+ * autoCRUD `purge<T>` resolver. Spec: §5.1 (`purge<T>({ id })` — optional
12265
+ * admin-only hard-delete), §4.5 (`purge` on nonexistent row returns
12266
+ * `{ deleted: 0 }` without error).
12267
+ *
12268
+ * Purge is hard-delete: it bypasses the `_deletedAt` tombstone lifecycle and
12269
+ * removes the row outright. Downstream edges observe the row as MISSING on
12270
+ * subsequent reads; the sweep's non-bridged MISSING branch treats this as
12271
+ * deleted and fans policy per §6.3.
12272
+ *
12273
+ * Admin gate: this resolver does NOT embed a capability check. The gate is a
12274
+ * `Policy` composed at install time — see `installAutoCrud(..., { purgeable: true })`
12275
+ * which attaches `requireCapability(adminCapability)` by default. Callers can
12276
+ * override with any policy.
12277
+ *
12278
+ * Kill switch: assertHardDeleteAllowed() is the first thing — refusal
12279
+ * short-circuits before any state read.
12280
+ */
12281
+ const KNOWN_PURGE_PARAMS = /* @__PURE__ */ new Set(["id"]);
12282
+ /** With `policy`, a row its row filters hide is left in place and answers `purged: false`. */
12283
+ function purgeResolver(typeName, dataset, policy) {
12284
+ return async (ctx, args) => {
12285
+ rejectUnknownParams("purge", typeName, args.params, KNOWN_PURGE_PARAMS);
12286
+ assertHardDeleteAllowed();
12287
+ const ds = args.dataset ?? dataset;
12288
+ const id = coerceId(args.params?.id);
12289
+ if (id === void 0) throw new ResolverFrameError("missing_id", `purgeResolver('${typeName}'): params.id is required`, { field: "id" });
12290
+ const { rows: existing } = await ds.read(typeName, {
12291
+ id,
12292
+ includeDeleted: true
12293
+ });
12294
+ const preRow = existing[0];
12295
+ if (guardRowWrites(ctx, policy, [args], [preRow ?? null])[0]) return {
12296
+ id,
12297
+ purged: false
12298
+ };
12299
+ const { deleted } = await ds.purge(typeName, [id]);
12300
+ const purged = deleted > 0;
12301
+ if (purged && args.onWrite !== void 0) {
12302
+ const event = {
12303
+ ns: ds.namespace,
12304
+ type: typeName,
12305
+ id,
12306
+ operation: "delete",
12307
+ ...preRow !== void 0 ? { row: preRow } : {}
12308
+ };
12309
+ args.onWrite(event);
12310
+ }
12311
+ return {
12312
+ id,
12313
+ purged
12314
+ };
12315
+ };
10717
12316
  }
10718
12317
 
10719
12318
  //#endregion
@@ -11080,7 +12679,7 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
11080
12679
  const create = singleFrame(createBatch);
11081
12680
  const update = singleFrame(updateBatch);
11082
12681
  const del = singleFrame(deleteBatch);
11083
- const purge = purgeResolver(typeName, dataset);
12682
+ const purge = purgeResolver(typeName, dataset, policy);
11084
12683
  const cap = capOf(typeName);
11085
12684
  const stillOwn = (key, own) => () => {
11086
12685
  const get = registry.get?.bind(registry);
@@ -11201,6 +12800,25 @@ const field = {
11201
12800
  number(opts) {
11202
12801
  return makeScalar("number", opts);
11203
12802
  },
12803
+ /**
12804
+ * Integers: pick the narrowest kind whose range holds every value the field
12805
+ * will EVER take, because a kind cannot change once rows exist (moving means
12806
+ * a new field and a backfill). All three filter, sort and sum as exact
12807
+ * integers; they differ in storage width.
12808
+ * int16 -32768 to 32767, 2 bytes: small codes, flags, ages, percentages.
12809
+ * int32 about ±2.1 billion, 4 bytes: counts, durations, ids within one source.
12810
+ * int64 about ±9.2e18, 8 bytes, a decimal string on the wire past 2^53: totals, epoch-ms, external ids.
12811
+ * Use `number` for fractional values. When unsure, take the next width up.
12812
+ */
12813
+ int16(opts) {
12814
+ return makeScalar("int16", opts);
12815
+ },
12816
+ int32(opts) {
12817
+ return makeScalar("int32", opts);
12818
+ },
12819
+ int64(opts) {
12820
+ return makeScalar("int64", opts);
12821
+ },
11204
12822
  boolean(opts) {
11205
12823
  return makeScalar("boolean", opts);
11206
12824
  },
@@ -11305,6 +12923,22 @@ const RESERVED_AUTOCRUD_FIELDS = { shortId: reserved(field.number({
11305
12923
  function isReservedAutoCrudField(def) {
11306
12924
  return def[RESERVED] === true;
11307
12925
  }
12926
+ /** The server metadata names a body field may not take: expressions, where and orderBy read them as metadata. */
12927
+ const RESERVED_METADATA_FIELD_NAMES = [
12928
+ "createdAt",
12929
+ "updatedAt",
12930
+ "seq",
12931
+ "createdBy",
12932
+ "updatedBy",
12933
+ "createdById",
12934
+ "createdByKind",
12935
+ "updatedById",
12936
+ "updatedByKind"
12937
+ ];
12938
+ /** Why a field of this name cannot be declared, or undefined when it can. */
12939
+ function reservedMetadataFieldMessage(name) {
12940
+ return RESERVED_METADATA_FIELD_NAMES.includes(name) ? `\`${name}\` is a reserved field name: it is reserved for server metadata` : void 0;
12941
+ }
11308
12942
  /** Reserved field names — useful for validation loops. */
11309
12943
  const RESERVED_AUTOCRUD_FIELD_NAMES = Object.keys(RESERVED_AUTOCRUD_FIELDS);
11310
12944
 
@@ -11471,6 +13105,10 @@ const NAMESPACE_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
11471
13105
  function defineNamespace(namespace, types, opts = {}) {
11472
13106
  if (!NAMESPACE_NAME_PATTERN.test(namespace)) throw new Error(`invalid namespace name '${namespace}': expected ${NAMESPACE_NAME_PATTERN.source}. A namespace must not contain '/' (it would truncate every qualified frame key) or ':' (it would be ambiguous with the per-namespace grant form, e.g. --ns notes:read).`);
11473
13107
  for (const [typeName, typeInput] of Object.entries(types)) {
13108
+ for (const name of Object.keys(typeInput.fields)) {
13109
+ const why = reservedMetadataFieldMessage(name);
13110
+ if (why !== void 0) throw new Error(`${why} (type: ${typeName})`);
13111
+ }
11474
13112
  if (typeInput.autoCrud === false) continue;
11475
13113
  for (const reserved of RESERVED_AUTOCRUD_FIELD_NAMES) if (Object.hasOwn(typeInput.fields, reserved)) throw new Error(`\`${reserved}\` is a reserved field name, auto-injected by the engine (type: ${typeName})`);
11476
13114
  assertServerSetFieldsFillable(typeName, typeInput.fields);
@@ -11564,9 +13202,9 @@ function assertOrderedBy(typeName, def) {
11564
13202
  }
11565
13203
  const field = def.fields[name];
11566
13204
  if (field === void 0) throw new Error(`${where}: unknown field '${name}'`);
11567
- if (!(field.kind === "scalar" && (field.type === "date" || field.type === "number"))) {
13205
+ if (!(field.kind === "scalar" && (field.type === "date" || field.type === "number" || field.type === "int16" || field.type === "int32" || field.type === "int64"))) {
11568
13206
  const kind = field.kind === "scalar" ? field.type : field.kind;
11569
- throw new Error(`${where}: field '${name}' is ${kind}; only date and number fields, or ${[...ORDERED_BY_METADATA_COLUMNS].join(", ")}, can be a natural order`);
13207
+ throw new Error(`${where}: field '${name}' is ${kind}; only date, number, int16, int32 and int64 fields, or ${[...ORDERED_BY_METADATA_COLUMNS].join(", ")}, can be a natural order`);
11570
13208
  }
11571
13209
  }
11572
13210
  function composePolicyLayers(pluginLevel, namespaceLevel, typeLevel) {
@@ -14542,39 +16180,88 @@ var MemoryDataset = class MemoryDataset {
14542
16180
  hasMore: false,
14543
16181
  count: pool.length
14544
16182
  };
14545
- if (params.aggregate !== void 0) return aggregateGroups(pool, params.aggregate, params.bucket, limit, fieldDefOf);
16183
+ if (params.aggregate !== void 0) {
16184
+ const { groups, truncated } = groupRows(pool, {
16185
+ ...params,
16186
+ aggregate: params.aggregate
16187
+ }, fieldTypeLookup(fieldDefOf), limit);
16188
+ return {
16189
+ rows: [],
16190
+ hasMore: false,
16191
+ groups,
16192
+ ...truncated ? { truncated: true } : {}
16193
+ };
16194
+ }
14546
16195
  const original = /* @__PURE__ */ new Map();
14547
- const derive = params.derive;
14548
- if (derive !== void 0) pool = pool.map((row) => {
14549
- const ctx = ctxFor(row);
14550
- const operand = (ref) => {
14551
- const v = ref.startsWith("_agg.") ? ctx.aggValue?.(ref.slice(5)) : getFieldValue(row, ref.slice(2));
14552
- return typeof v === "number" ? v : null;
16196
+ const selected = /* @__PURE__ */ new Map();
16197
+ const dateNames = /* @__PURE__ */ new Set();
16198
+ const sortDefOf = (f) => dateNames.has(f) ? {
16199
+ kind: "scalar",
16200
+ type: "date"
16201
+ } : fieldDefOf(f);
16202
+ let restSelect;
16203
+ const select = params.select;
16204
+ if (select !== void 0) {
16205
+ const entries = Object.entries(select);
16206
+ const fieldType = fieldTypeLookup(fieldDefOf);
16207
+ const typeOf = (name) => {
16208
+ if (!name.startsWith("_agg.")) return fieldType(name);
16209
+ const spec = frameAggs?.[name.slice(5)];
16210
+ return spec === void 0 ? void 0 : walkAggExprType(spec, type, (t, f) => lookup?.(t, f));
14553
16211
  };
14554
- const values = Object.entries(derive).map(([name, spec]) => {
14555
- if ("value" in spec) return [`$${name}`, operand(spec.value)];
14556
- const [op, [a, b]] = Object.entries(spec)[0];
14557
- const x = operand(a);
14558
- const y = operand(b);
14559
- if (x === null || y === null || op === "ratio" && y === 0) return [`$${name}`, null];
14560
- const v = op === "diff" ? x - y : x / y;
14561
- const exactZero = op === "diff" ? x === y : x === 0;
14562
- const m = Math.abs(v);
14563
- return [`$${name}`, m <= 1e300 && (m >= 1e-300 || exactZero) ? v : null];
14564
- });
14565
- const copy = {
14566
- ...row,
14567
- ...Object.fromEntries(values)
16212
+ for (const [name, expr] of entries) {
16213
+ const checked = checkExpr(expr, { field: typeOf }, []);
16214
+ if (checked.ok && checked.type === "date") dateNames.add(name);
16215
+ }
16216
+ const text = JSON.stringify(select);
16217
+ const aggRefs = Object.keys(frameAggs ?? {}).filter((n) => text.includes(`"_agg.${n}"`));
16218
+ const orderKeys = new Set((params.orderBy ?? []).flatMap((c) => Object.keys(c)).filter((k) => Object.hasOwn(select, k)));
16219
+ const valuesOf = (row, names) => {
16220
+ const ctx = ctxFor(row);
16221
+ const output = {};
16222
+ for (const name of aggRefs) output[`_agg.${name}`] = ctx.aggValue?.(name);
16223
+ const values = {};
16224
+ for (const [name, expr] of names) values[name] = evalExpr(expr, row, {
16225
+ output,
16226
+ fieldType: typeOf
16227
+ }) ?? null;
16228
+ return values;
14568
16229
  };
14569
- original.set(copy, row);
14570
- return copy;
14571
- });
16230
+ const printed = (values) => {
16231
+ for (const name of dateNames) if (name in values) values[name] = isoMicros(values[name]);
16232
+ return values;
16233
+ };
16234
+ const ordering = entries.filter(([n]) => orderKeys.has(n));
16235
+ const rest = entries.filter(([n]) => !orderKeys.has(n));
16236
+ try {
16237
+ if (ordering.length > 0) pool = pool.map((row) => {
16238
+ const values = valuesOf(row, ordering);
16239
+ const copy = {
16240
+ ...row,
16241
+ ...values
16242
+ };
16243
+ original.set(copy, row);
16244
+ selected.set(copy, printed({ ...values }));
16245
+ return copy;
16246
+ });
16247
+ } catch (err) {
16248
+ outOfRange(err);
16249
+ }
16250
+ restSelect = (row) => {
16251
+ try {
16252
+ return printed(valuesOf(original.get(row) ?? row, rest));
16253
+ } catch (err) {
16254
+ return outOfRange(err);
16255
+ }
16256
+ };
16257
+ if (rest.length === 0) restSelect = void 0;
16258
+ }
14572
16259
  const orderBy = normalizeOrderBy(params.orderBy);
14573
- pool.sort((a, b2) => compareByClauses(a, b2, orderBy, fieldDefOf));
16260
+ pool.sort((a, b2) => compareByClauses(a, b2, orderBy, sortDefOf));
14574
16261
  let startIdx = 0;
14575
16262
  if (params.cursor !== void 0 && params.cursor !== "") {
14576
16263
  const cursor = decodeCursor(params.cursor, orderBy);
14577
- startIdx = findCursorStart(pool, orderBy, cursor.orderByValues, cursor.id, fieldDefOf);
16264
+ startIdx = findCursorStart(pool, orderBy, cursor.orderByValues, cursor.id, sortDefOf);
14578
16265
  }
14579
16266
  let hasMore = false;
14580
16267
  let slice;
@@ -14593,11 +16280,15 @@ var MemoryDataset = class MemoryDataset {
14593
16280
  const columns = this.columnFieldNames(type);
14594
16281
  const page = (rows) => {
14595
16282
  const base = original.size === 0 ? rows : rows.map((r) => original.get(r) ?? r);
14596
- if (params.agg === void 0 && params.nested === void 0) return base.map((r) => withoutNullColumns(columns, r));
14597
- return base.map((r) => withoutNullColumns(columns, {
16283
+ const out = params.agg === void 0 && params.nested === void 0 ? base.map((r) => withoutNullColumns(columns, r)) : base.map((r) => withoutNullColumns(columns, {
14598
16284
  ...r,
14599
16285
  ...walkProjection(r, params.agg, params.nested ?? {}, ctxFor(r), true)
14600
16286
  }));
16287
+ return selected.size === 0 && restSelect === void 0 ? out : out.map((r, i) => ({
16288
+ ...r,
16289
+ ...selected.get(rows[i]),
16290
+ ...restSelect?.(rows[i])
16291
+ }));
14601
16292
  };
14602
16293
  const last = slice[slice.length - 1];
14603
16294
  if (hasMore && last !== void 0) out.nextCursor = encodeCursor({
@@ -15015,40 +16706,6 @@ function conditionalMatchEq(actual, expected) {
15015
16706
  return actual === expected;
15016
16707
  }
15017
16708
  /**
15018
- * A whole-result aggregate: one group, or one per UTC day/hour bucket in
15019
- * ascending order. A row whose bucket field is null or not a date is in no
15020
- * bucket. Groups beyond `limit` are cut and say `truncated`.
15021
- */
15022
- function aggregateGroups(pool, aggregate, bucket, limit, fieldDefOf) {
15023
- const values = (rows) => Object.fromEntries(Object.entries(aggregate).map(([name, fn]) => [name, applyAgg(rows, fn, fieldDefOf)]));
15024
- if (bucket === void 0) return {
15025
- rows: [],
15026
- hasMore: false,
15027
- groups: [values(pool)]
15028
- };
15029
- const byKey = /* @__PURE__ */ new Map();
15030
- for (const row of pool) {
15031
- const micros = storedMicros(getFieldValue(row, bucket.field));
15032
- if (micros === void 0) continue;
15033
- const ms = Number((micros - (micros % 1000n + 1000n) % 1000n) / 1000n);
15034
- const key = new Date(ms).toISOString().slice(0, bucket.by === "day" ? 10 : 13);
15035
- const list = byKey.get(key);
15036
- if (list === void 0) byKey.set(key, [row]);
15037
- else list.push(row);
15038
- }
15039
- const keys = [...byKey.keys()].sort();
15040
- const truncated = limit !== void 0 && keys.length > limit;
15041
- return {
15042
- rows: [],
15043
- hasMore: false,
15044
- groups: (truncated ? keys.slice(0, limit) : keys).map((key) => ({
15045
- bucket: key,
15046
- ...values(byKey.get(key) ?? [])
15047
- })),
15048
- ...truncated ? { truncated: true } : {}
15049
- };
15050
- }
15051
- /**
15052
16709
  * A row's walk selections: `_agg` values and nested lists, each list
15053
16710
  * filtered, ordered (id ascending last) and cut to its limit, with
15054
16711
  * `_truncated` naming the lists that were cut. Nested rows carry `id`, their
@@ -15086,6 +16743,14 @@ function walkProjection(row, aggs, nested, ctx, top = false) {
15086
16743
  if (truncated.length > 0) out.push(["_truncated", Object.fromEntries(truncated)]);
15087
16744
  return Object.fromEntries(out);
15088
16745
  }
16746
+ /** A date value as UTC text to the microsecond, the form pg's row projection prints; null when it is not a date. */
16747
+ function isoMicros(v) {
16748
+ const micros = storedMicros(v);
16749
+ if (micros === void 0) return null;
16750
+ const sub = (micros % 1000n + 1000n) % 1000n;
16751
+ const ms = Number((micros - sub) / 1000n);
16752
+ return new Date(ms).toISOString().replace("Z", `${sub.toString().padStart(3, "0")}Z`);
16753
+ }
15089
16754
  function compareByClauses(a, b, orderBy, fieldDefOf) {
15090
16755
  for (const [field, dir] of orderBy) {
15091
16756
  const av = asSortValue(field, getFieldValue(a, field), fieldDefOf);
@@ -15971,7 +17636,8 @@ function healthRoute(deps) {
15971
17636
  warnings: await deps.warnings(),
15972
17637
  version: deps.version,
15973
17638
  walks: true,
15974
- uptimeSeconds: Math.floor((Date.now() - deps.startedAt) / 1e3)
17639
+ uptimeSeconds: Math.floor((Date.now() - deps.startedAt) / 1e3),
17640
+ ...deps.pool !== void 0 ? { pool: deps.pool() } : {}
15975
17641
  });
15976
17642
  }
15977
17643
 
@@ -15985,6 +17651,9 @@ function healthRoute(deps) {
15985
17651
  * by the registry. The route pulls each mutation's registry entry via
15986
17652
  * `engine.registryFor(ns)` and threads the declared `returns` FieldDef into
15987
17653
  * the substrate-pack encoder (§5.2).
17654
+ *
17655
+ * On the JSON wire, a create or update that names no `fields` answers with
17656
+ * `{ id, shortId }` rather than the whole written row.
15988
17657
  */
15989
17658
  function mutateRoute(engine, trustedProxies, authEnabled) {
15990
17659
  return async (req) => {
@@ -15999,7 +17668,8 @@ function mutateRoute(engine, trustedProxies, authEnabled) {
15999
17668
  });
16000
17669
  const returnsByKey = {};
16001
17670
  const currentNsByKey = {};
16002
- for (const key of Object.keys(frame)) {
17671
+ const projectBy = { ...frame };
17672
+ for (const [key, frameEntry] of Object.entries(frame)) {
16003
17673
  const parsed = parseQualifiedKey(key);
16004
17674
  if (parsed === null) continue;
16005
17675
  const { ns, name } = parsed;
@@ -16008,13 +17678,29 @@ function mutateRoute(engine, trustedProxies, authEnabled) {
16008
17678
  returnsByKey[key] = entry.returns;
16009
17679
  currentNsByKey[key] = ns;
16010
17680
  }
17681
+ if (entry !== void 0 && writesRows(entry)) projectBy[key] = Array.isArray(frameEntry) ? frameEntry.map(withAckFields) : withAckFields(frameEntry);
16011
17682
  }
16012
- return serializeEnvelope(req, envelope, engine, frame, {
17683
+ return serializeEnvelope(req, envelope, engine, projectBy, {
16013
17684
  returnsByKey,
16014
17685
  currentNsByKey
16015
17686
  });
16016
17687
  };
16017
17688
  }
17689
+ /** What a row-writing mutation answers when the frame names no `fields`. */
17690
+ const ACK_FIELDS = {
17691
+ id: true,
17692
+ shortId: true
17693
+ };
17694
+ /** A create or update that returns rows of a declared type, not a struct of its own (delete's `{ id, deleted }`). */
17695
+ function writesRows(entry) {
17696
+ return (entry.verb === "create" || entry.verb === "update") && entry.returns !== void 0 && entry.fields !== void 0 && Object.keys(entry.fields).length > 0;
17697
+ }
17698
+ function withAckFields(frameEntry) {
17699
+ return frameEntry.fields === void 0 ? {
17700
+ ...frameEntry,
17701
+ fields: ACK_FIELDS
17702
+ } : frameEntry;
17703
+ }
16018
17704
 
16019
17705
  //#endregion
16020
17706
  //#region ../../packages/substrate-compose/src/routes/onboard.ts
@@ -16407,6 +18093,13 @@ function operatorContract(engine, ns) {
16407
18093
  metadataAuthorFields: METADATA_AUTHOR_FIELDS
16408
18094
  };
16409
18095
  }
18096
+ /** The expression catalogue: what `select`, `where.$expr`, `groupBy`, `having` and aggregates accept. */
18097
+ const EXPRESSIONS = {
18098
+ functions: EXPR_FUNCTIONS,
18099
+ aggregates: EXPR_AGGREGATES,
18100
+ limits: EXPR_LIMITS,
18101
+ dateUnits: DATE_UNITS
18102
+ };
16410
18103
  /**
16411
18104
  * GET /substrate/v1/schema — the `defaultNamespace`'s schema, a pre-federation
16412
18105
  * compatibility surface.
@@ -16430,7 +18123,8 @@ function schemaRoute(engine, defaultNamespace) {
16430
18123
  try {
16431
18124
  return jsonResponse(200, {
16432
18125
  ...engine.schemaFor(defaultNamespace),
16433
- ...operatorContract(engine, defaultNamespace)
18126
+ ...operatorContract(engine, defaultNamespace),
18127
+ expressions: EXPRESSIONS
16434
18128
  });
16435
18129
  } catch {
16436
18130
  return jsonResponse(404, {
@@ -16542,6 +18236,14 @@ function mutationTargetsType(name, def, type, fields) {
16542
18236
 
16543
18237
  //#endregion
16544
18238
  //#region ../../packages/substrate-compose/src/routes/sse-frame.ts
18239
+ /**
18240
+ * SSE wire framing. Spec §5. Pure — no I/O, so every wire-format decision is
18241
+ * unit-testable without a server.
18242
+ *
18243
+ * Encoding is `json` ONLY. SSE `data:` is a text field; base64-ing msgpack
18244
+ * would cost ~33% to ship the format that is supposed to be the compact one.
18245
+ * The §7.4 pack codec stays reserved for a future binary transport.
18246
+ */
16545
18247
  const SSE_HEADERS = {
16546
18248
  "content-type": "text/event-stream",
16547
18249
  "cache-control": "no-store",
@@ -16561,7 +18263,7 @@ function sseRetry(ms) {
16561
18263
  * §4). `sequence` travels inside `data` for client-side ordering instead.
16562
18264
  */
16563
18265
  function sseEvent(frame, fieldsByKey) {
16564
- return `event: ${frame.kind}\ndata: ${JSON.stringify(payloadFor(frame, fieldsByKey))}\n\n`;
18266
+ return `event: ${frame.kind}\ndata: ${stringifyJson(payloadFor(frame, fieldsByKey))}\n\n`;
16565
18267
  }
16566
18268
  function payloadFor(frame, fieldsByKey) {
16567
18269
  if (frame.kind === "end") return { reason: frame.reason ?? (frame._meta?.cancelled === true ? "cancelled" : "complete") };
@@ -17166,7 +18868,7 @@ function parseRequestFrame(buf, mode) {
17166
18868
  }
17167
18869
  }
17168
18870
  function serializeFrame(frame, mode, fieldsByKey, engine) {
17169
- if (mode === "json") return JSON.stringify(projectWsFrame(frame, fieldsByKey));
18871
+ if (mode === "json") return stringifyJson(projectWsFrame(frame, fieldsByKey));
17170
18872
  const encoded = encodeDataForPack(frame, fieldsByKey, engine);
17171
18873
  const wire = encodeWsFrame(encoded, mode);
17172
18874
  return typeof wire === "string" ? wire : Buffer.from(wire);
@@ -17482,11 +19184,12 @@ function registerWsRoute(server, engine, trustedProxies, metric, auth, systemIde
17482
19184
  //#endregion
17483
19185
  //#region ../../packages/substrate-compose/src/compose/routes.ts
17484
19186
  async function registerCoreRoutes(args) {
17485
- const { server, engine, gate, trustedProxies, auth, streamTicketSecret, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport, storageReport, promoteFields, fieldWarnings } = args;
19187
+ const { server, engine, gate, trustedProxies, auth, streamTicketSecret, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport, storageReport, promoteFields, fieldWarnings, poolStats } = args;
17486
19188
  server.route("GET", "/health", healthRoute({
17487
19189
  version: version ?? "0.0.0",
17488
19190
  startedAt: Date.now(),
17489
- warnings: async () => [...engine.postWriteWarnings(), ...await fieldWarnings?.().catch(() => []) ?? []]
19191
+ warnings: async () => [...engine.postWriteWarnings(), ...await fieldWarnings?.().catch(() => []) ?? []],
19192
+ ...poolStats !== void 0 ? { pool: poolStats } : {}
17490
19193
  }));
17491
19194
  server.route("GET", "/substrate/v1/schema", gate(schemaRoute(engine, "default"), "read"));
17492
19195
  server.route("GET", "/substrate/v1/schema/:namespace", gate(schemaForNamespaceRoute(engine), "read"));
@@ -17947,7 +19650,8 @@ async function composeInner(opts, cleanup) {
17947
19650
  ...opts.configReport !== void 0 ? { configReport: opts.configReport } : {},
17948
19651
  ...opts.storageReport !== void 0 ? { storageReport: opts.storageReport } : {},
17949
19652
  promoteFields: promoteRunner.run,
17950
- ...opts.dataset.fieldWarnings !== void 0 ? { fieldWarnings: opts.dataset.fieldWarnings.bind(opts.dataset) } : {}
19653
+ ...opts.dataset.fieldWarnings !== void 0 ? { fieldWarnings: opts.dataset.fieldWarnings.bind(opts.dataset) } : {},
19654
+ ...opts.dataset.poolStats !== void 0 ? { poolStats: opts.dataset.poolStats.bind(opts.dataset) } : {}
17951
19655
  });
17952
19656
  let scheduler = null;
17953
19657
  if (scheduleEntries.length > 0) {
@@ -18234,4 +19938,4 @@ function kernelMigrationTracking(sql) {
18234
19938
  }
18235
19939
 
18236
19940
  //#endregion
18237
- export { applyObligations as $, BatchElementError as $t, field as A, parseJsonBody as At, applyUpdatePatch as B, vocabImplication as Bt, makeCtx as C, assertNoRepeatedIds as Cn, applyExtensionResultMeta as Ct, RESERVED_AUTOCRUD_FIELDS as D, buildContext as Dt, selectAll as E, defineBootstrap as En, JSON_HEADERS as Et, deleteManyResolver as F, WS_REASON_SUBSCRIPTION_OVERLOADED as Ft, UnattributedWriteError as G, normaliseMetadataWhere as Gt, purgeResolver as H, METADATA_AUTHOR_FIELDS as Ht, updateManyResolver as I, canonicalVocabValue as It, resolveEntityRow as J, isImpossibleIsoTimestamp as Jt, resolveIdentity as K, normaliseWalkNode as Kt, createResolver as L, normaliseVocabValues as Lt, autoCrudOptionsOf as M, signHs256 as Mt, createResolverWithEdges as N, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as Nt, RESERVED_AUTOCRUD_FIELD_NAMES as O, error400 as Ot, installAutoCrud as P, WS_REASON_SERVER_RESTART as Pt, effectiveFilterOperators as Q, validateHardDeleteEnv as Qt, deleteResolver as R, normaliseVocabWhere as Rt, EngineQueryError as S, ROW_METADATA_FIELDS as Sn, fullBuiltinOperators as St, queryOne as T, BootstrapConfigError as Tn, HttpBridgeClient as Tt, listResolver as U, METADATA_FILTER_FIELDS as Ut, deleteRow as V, RegistryBase as Vt, getResolver as W, normaliseMetadataOrderBy as Wt, loadPlugins as X, normalizeIsoTimestamp as Xt, MemoryEdgesStore as Y, isIsoTimestamp as Yt, publishSchema as Z, assertHardDeleteAllowed as Zt, AUDIT_EVENT_TYPE as _, isAuthCause as _n, unregisterExtensionOperator as _t, composeFromManifests as a, ROW_POLICY_BLOCKS_WALK as an, windowGroupBy as at, assertOrderedBy as b, isRestrictViolation as bn, encodeCursor as bt, MemoryDataset as c, RestrictViolation as cn, groupConjuncts as ct, uuidFromName as d, WALKS_IN_SUBSCRIPTION as dn, preResolveExtensionOperatorsDetailed as dt, BridgeUnreachableError as en, loadSweepState as et, emitFieldEvents as f, WALKS_NEED_PARTITIONED as fn, assertJsonPathPredicate as ft, buildAuditRow as g, filterTooBroad as gn, registerExtensionOperator as gt, SYSTEM_TYPE_DEFS as h, WALK_UNSUPPORTED_REF as hn, listExtensionOperators as ht, PluginLoadError as i, QUERY_TIMEOUT as in, sharedPicks as it, AutoCrudNameCollisionError as j, parseAuthConfig as jt, isReservedAutoCrudField as k, jsonResponse as kt, planServesShape as l, UnsupportedFilterError as ln, isRefOperand as lt, runInviteSweep as m, WALK_BUDGET_EXCEEDED as mn, getExtensionOperator as mt, kernelMigrationTracking as n, MissingReferentError as nn, saveSweepState as nt, DEFAULT_NAMESPACE as o, ReservedField as on, isDateField as ot, migrateFieldValues as p, WALKS_UNSUPPORTED_STORE as pn, isJsonPathPredicate as pt, resolveEntityId as q, createKeyedMutex as qt, mountKernelRoute as r, NamespaceMismatch as rn, forEachWalkHop as rt, compose as s, ResolverFrameError as sn, bindingWalks as st, composeKernelPlugins as t, FILTER_TOO_BROAD as tn, runSweep as tt, isStoreProfileName as u, WALKS_IN_MUTATION as un, refNames as ut, INVITE_TYPE as v, isBatchElementError as vn, CursorDecodeError as vt, queryAll as w, canonicalize as wn, fieldRequested as wt, defineNamespace as x, CLIENT_SUPPLIED_SERVER_FIELD as xn, normalizeOrderBy as xt, assertIndexDecl as y, isResolverFrameError as yn, decodeCursor as yt, updateResolver as z, storedVocabSpellings as zt };
19941
+ export { publishSchema as $, METADATA_FILTER_FIELDS as $t, isReservedAutoCrudField as A, isAuthCause as An, encodeCursor as At, createResolver as B, parseJsonBody as Bt, makeCtx as C, WALKS_IN_MUTATION as Cn, walkAggExprType as Ct, RESERVED_AUTOCRUD_FIELDS as D, WALK_BUDGET_EXCEEDED as Dn, endsWithEscape as Dt, selectAll as E, WALKS_UNSUPPORTED_STORE as En, LIKE_TRAILING_ESCAPE as Et, createResolverWithEdges as F, ROW_METADATA_FIELDS as Fn, HttpBridgeClient as Ft, listResolver as G, WS_REASON_SUBSCRIPTION_OVERLOADED as Gt, updateResolver as H, signHs256 as Ht, installAutoCrud as I, assertNoRepeatedIds as In, JSON_HEADERS as It, resolveIdentity as J, normaliseVocabWhere as Jt, getResolver as K, canonicalVocabValue as Kt, deleteManyResolver as L, canonicalize as Ln, buildContext as Lt, field as M, isResolverFrameError as Mn, fullBuiltinOperators as Mt, AutoCrudNameCollisionError as N, isRestrictViolation as Nn, applyExtensionResultMeta as Nt, RESERVED_AUTOCRUD_FIELD_NAMES as O, WALK_UNSUPPORTED_REF as On, CursorDecodeError as Ot, autoCrudOptionsOf as P, CLIENT_SUPPLIED_SERVER_FIELD as Pn, fieldRequested as Pt, loadPlugins as Q, METADATA_AUTHOR_FIELDS as Qt, updateManyResolver as R, BootstrapConfigError as Rn, error400 as Rt, EngineQueryError as S, VALUE_OUT_OF_RANGE as Sn, metadataExprType as St, queryOne as T, WALKS_NEED_PARTITIONED as Tn, isJsonPathPredicate as Tt, applyUpdatePatch as U, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as Ut, deleteResolver as V, parseAuthConfig as Vt, deleteRow as W, WS_REASON_SERVER_RESTART as Wt, resolveEntityRow as X, vocabImplication as Xt, resolveEntityId as Y, storedVocabSpellings as Yt, MemoryEdgesStore as Z, RegistryBase as Zt, AUDIT_EVENT_TYPE as _, ReservedField as _n, getExtensionOperator as _t, composeFromManifests as a, isIsoTimestamp as an, forEachWalkHop as at, assertOrderedBy as b, STORE_BUSY as bn, unregisterExtensionOperator as bt, MemoryDataset as c, validateHardDeleteEnv as cn, preResolveExtensionOperatorsDetailed as ct, uuidFromName as d, FILTER_TOO_BROAD as dn, canRaise as dt, normaliseMetadataOrderBy as en, effectiveFilterOperators as et, emitFieldEvents as f, MissingReferentError as fn, isDateField as ft, buildAuditRow as g, ROW_POLICY_BLOCKS_WALK as gn, refNames as gt, SYSTEM_TYPE_DEFS as h, REGEX_BUDGET_EXCEEDED as hn, isRefOperand as ht, PluginLoadError as i, isImpossibleIsoTimestamp as in, saveSweepState as it, reservedMetadataFieldMessage as j, isBatchElementError as jn, normalizeOrderBy as jt, RESERVED_METADATA_FIELD_NAMES as k, filterTooBroad as kn, decodeCursor as kt, planServesShape as l, BatchElementError as ln, aggParts as lt, runInviteSweep as m, QUERY_TIMEOUT as mn, groupConjuncts as mt, kernelMigrationTracking as n, normaliseWalkNode as nn, loadSweepState as nt, DEFAULT_NAMESPACE as o, normalizeIsoTimestamp as on, sharedPicks as ot, migrateFieldValues as p, NamespaceMismatch as pn, bindingWalks as pt, UnattributedWriteError as q, normaliseVocabValues as qt, mountKernelRoute as r, createKeyedMutex as rn, runSweep as rt, compose as s, assertHardDeleteAllowed as sn, windowGroupBy as st, composeKernelPlugins as t, normaliseMetadataWhere as tn, applyObligations as tt, isStoreProfileName as u, BridgeUnreachableError as un, aggType as ut, INVITE_TYPE as v, ResolverFrameError as vn, listExtensionOperators as vt, queryAll as w, WALKS_IN_SUBSCRIPTION as wn, assertJsonPathPredicate as wt, defineNamespace as x, UnsupportedFilterError as xn, exprTypeOfField as xt, assertIndexDecl as y, RestrictViolation as yn, registerExtensionOperator as yt, purgeResolver as z, defineBootstrap as zn, jsonResponse as zt };