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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +48 -6
  2. package/dist/boot-store-BVqfFxh1.js +4060 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-Cp4PaIYO.d.ts} +2 -87
  4. package/dist/cli-hSCBywhE.js +3126 -0
  5. package/dist/client.d.ts +130 -8
  6. package/dist/client.js +6 -5
  7. package/dist/{plugin-t2g2wX0b.d.ts → dataset-CejF-Fr_.d.ts} +1640 -1320
  8. package/dist/{agent-token-BIboWOU0.js → env-utils-CGNazUNt.js} +31 -2
  9. package/dist/{errors-D4vKuwz8.d.ts → errors-7mycvNGq.d.ts} +1 -1
  10. package/dist/{index-D7mSOFlM.d.ts → index-DgSfwx7M.d.ts} +1 -1
  11. package/dist/node-version-C5FSmwJX.js +26 -0
  12. package/dist/pack.d.ts +2 -2
  13. package/dist/pack.js +1 -1
  14. package/dist/pg-edges-store-Lxsl5ZnK.js +381 -0
  15. package/dist/{plugin-BuQQEzL-.js → plugin-CtwOINCM.js} +171 -18
  16. package/dist/proposals-bootstrap.js +6 -4
  17. package/dist/proposals.config.schema.json +5 -0
  18. package/dist/proposals.d.ts +15 -4
  19. package/dist/proposals.default-config.json +2 -1
  20. package/dist/proposals.js +2 -2
  21. package/dist/recall-bootstrap.js +13 -4
  22. package/dist/recall.config.schema.json +12 -0
  23. package/dist/recall.d.ts +54 -9
  24. package/dist/recall.js +2 -2
  25. package/dist/{repl-C52wyfMs.js → repl-DqfHelK7.js} +62 -29
  26. package/dist/{row-ByLFE2Wx.d.ts → row-BKKCXIG6.d.ts} +5 -3
  27. package/dist/run-B5dTbZ3g.js +1997 -0
  28. package/dist/{schema-g4FQLr0V.d.ts → schema-DoSc-4ig.d.ts} +44 -7
  29. package/dist/script-C6DSa_Na.js +134 -0
  30. package/dist/sdk.d.ts +90 -12
  31. package/dist/sdk.js +5 -110
  32. package/dist/{src-YXlv_RyL.js → src-5SJ5GEIM.js} +1555 -326
  33. package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
  34. package/dist/{src-zcyUofMJ.js → src-Bi849yhn.js} +39 -15
  35. package/dist/{src-5hVbeiAu.js → src-CqT-QWZ_.js} +697 -57
  36. package/dist/src-CyvV7dCK.js +4333 -0
  37. package/dist/{row-DK7lPZVe.js → src-Da0t6si5.js} +11 -11
  38. package/dist/{src-C4DzaIQZ.js → src-hZb8wfvg.js} +12 -1
  39. package/dist/substrate-admin.js +17 -781
  40. package/dist/substrate.js +4 -5476
  41. package/dist/testing.d.ts +557 -8
  42. package/dist/testing.js +39 -3
  43. package/dist/{ws-C72iVS5T.d.ts → ws-ByZyHk7m.d.ts} +3 -3
  44. package/package.json +21 -20
  45. package/dist/dataset-DOXGRz50.js +0 -1535
  46. package/dist/env-utils-B7SGmoeJ.js +0 -21
  47. package/dist/src-CjEwiKXw.js +0 -2327
@@ -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, p as grantOf, r as allowAll, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer } from "./row-DK7lPZVe.js";
3
- import { S as assertNever, c as isPlainRequestData, f as encodeEnvelope, o as decodeWsEnvelope, p as encodePositional, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, x as parseQualifiedKey } from "./src-C4DzaIQZ.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-Da0t6si5.js";
3
+ import { C as parseQualifiedKey, S as formatQualifiedKey, c as isPlainRequestData, f as encodeEnvelope, o as decodeWsEnvelope, p as encodePositional, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, w as assertNever, x as naturalOrderOf } from "./src-hZb8wfvg.js";
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";
@@ -65,6 +65,19 @@ function canonicalize(value) {
65
65
 
66
66
  //#endregion
67
67
  //#region ../../packages/substrate-types/src/core.ts
68
+ /**
69
+ * Refuse an upsert batch that names one id twice: the datasets would
70
+ * otherwise disagree (pg cannot update a row twice in one statement).
71
+ */
72
+ function assertNoRepeatedIds(type, rows) {
73
+ const seen = /* @__PURE__ */ new Set();
74
+ for (const { id } of rows) {
75
+ if (id == null) continue;
76
+ const key = String(id);
77
+ if (seen.has(key)) throw new Error(`write: id '${key}' appears twice in one batch (type='${type}')`);
78
+ seen.add(key);
79
+ }
80
+ }
68
81
  const CLIENT_SUPPLIED_SERVER_FIELD = "client_supplied_server_field";
69
82
  const ROW_METADATA_FIELDS = [
70
83
  "createdAt",
@@ -257,6 +270,44 @@ function validateHardDeleteEnv() {
257
270
  if (v !== void 0 && v !== VALUE_ALLOW && v !== VALUE_REFUSE) throw new Error(`${ENV_VAR} must be '${VALUE_ALLOW}' or '${VALUE_REFUSE}' (got '${v}'). Unset = ${VALUE_ALLOW}.`);
258
271
  }
259
272
 
273
+ //#endregion
274
+ //#region ../../packages/substrate-types/src/iso-timestamp.ts
275
+ /**
276
+ * The one ISO 8601 date and date-time grammar a `date` field accepts. The
277
+ * write validator, the memory evaluator and pg's `substrate_ts` (0003, which
278
+ * carries the same pattern as SQL) all read it to the same instant.
279
+ *
280
+ * Groups: date, `HH:MM`, seconds, the first 6 fraction digits (pg keeps
281
+ * microseconds; more digits are truncated), the offset. Anchored and free of
282
+ * nested quantifiers, so no backtracking blow-up. pg caps an offset at ±15:59.
283
+ */
284
+ const ISO_TIMESTAMP = /^(\d{4}-\d{2}-\d{2})(?:[T ]((?:[01]\d|2[0-3]):[0-5]\d)(?::([0-5]\d)(?:\.(\d{1,6})\d{0,3})?)?)?(Z|[+-](?:0\d|1[0-5])(?::?[0-5]\d)?)?$/;
285
+ /**
286
+ * `v` as `YYYY-MM-DDTHH:MM:SS[.ffffff](Z|±HH:MM)`, or `undefined` when it is
287
+ * outside the grammar or names a day that does not exist (Feb 30, year 0000).
288
+ * No offset is read as UTC, and a date alone as its midnight UTC.
289
+ */
290
+ function normalizeIsoTimestamp(v) {
291
+ const m = ISO_TIMESTAMP.exec(v);
292
+ if (m === null) return void 0;
293
+ const [, date = "", hm, sec, frac, offset] = m;
294
+ const [y, mo, d] = date.split("-").map(Number);
295
+ if (y < 1 || mo < 1 || mo > 12 || d < 1) return void 0;
296
+ const probe = /* @__PURE__ */ new Date(0);
297
+ probe.setUTCFullYear(y, mo - 1, d);
298
+ if (probe.getUTCDate() !== d) return void 0;
299
+ const zone = offset === void 0 || offset === "Z" ? "Z" : `${offset.slice(0, 3)}:${offset.slice(3).replace(":", "") || "00"}`;
300
+ return `${date}T${hm ?? "00:00"}:${sec ?? "00"}${frac === void 0 ? "" : `.${frac}`}${zone}`;
301
+ }
302
+ /** Is `v` a timestamp every dataset reads to the same instant? */
303
+ function isIsoTimestamp(v) {
304
+ return normalizeIsoTimestamp(v) !== void 0;
305
+ }
306
+ /** Does `v` have the grammar's shape but name a day that does not exist (Feb 30, month 13, year 0000)? */
307
+ function isImpossibleIsoTimestamp(v) {
308
+ return ISO_TIMESTAMP.test(v) && normalizeIsoTimestamp(v) === void 0;
309
+ }
310
+
260
311
  //#endregion
261
312
  //#region ../../packages/substrate-types/src/keyed-mutex.ts
262
313
  /**
@@ -323,6 +374,12 @@ const METADATA_FILTER_FIELDS = {
323
374
  kind: "scalar",
324
375
  type: "string",
325
376
  indexed: true
377
+ },
378
+ /** Commit order on an `ordering: 'visible'` type; null on every other type. */
379
+ seq: {
380
+ kind: "scalar",
381
+ type: "number",
382
+ indexed: true
326
383
  }
327
384
  };
328
385
  /**
@@ -703,7 +760,7 @@ function parseAuthConfig(env) {
703
760
  }
704
761
  /** True for a postgres `SUBSTRATE_DATABASE_URL`, which is what makes the DB key registry available. */
705
762
  function isPostgresStore(store) {
706
- return store?.startsWith("postgres://") ?? false;
763
+ return (store?.startsWith("postgres://") || store?.startsWith("postgresql://")) ?? false;
707
764
  }
708
765
  /** Mode defaults to `required` — the safe end — when unset. */
709
766
  function applyMode(cfg, mode) {
@@ -794,7 +851,7 @@ function base64UrlDecode(segment) {
794
851
  return Buffer.from(b64, "base64");
795
852
  }
796
853
  function base64UrlEncode(buf) {
797
- return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
854
+ return buf.toString("base64url");
798
855
  }
799
856
  function parseSegments(token) {
800
857
  const parts = token.split(".");
@@ -924,7 +981,8 @@ function authenticateBearer(token, cfg) {
924
981
  if (maxLifetime > 0 && payload.exp > nowSeconds + maxLifetime + leeway) return reject("lifetime_exceeds_max");
925
982
  }
926
983
  if (typeof payload.nbf === "number" && payload.nbf > nowSeconds + leeway) return reject("not_yet_valid");
927
- if (cfg.audiences !== void 0 && payload.aud !== void 0) {
984
+ if (cfg.audiences !== void 0) {
985
+ if (payload.aud === void 0) return reject("missing_audience");
928
986
  if (!(Array.isArray(payload.aud) ? payload.aud : [payload.aud]).some((a) => cfg.audiences?.includes(a))) return reject("wrong_audience");
929
987
  }
930
988
  const claimedCapabilities = Array.isArray(payload.capabilities) ? payload.capabilities.filter((c) => typeof c === "string") : [];
@@ -963,6 +1021,7 @@ function authenticateBearer(token, cfg) {
963
1021
  /** What a 401 should add for a reason whose fix is a server knob, not the token. */
964
1022
  function rejectionDetail(reason) {
965
1023
  if (reason === "lifetime_exceeds_max") return "the token expires further ahead than this server accepts; mint a shorter-lived token or raise SUBSTRATE_JWT_MAX_TTL_SECONDS";
1024
+ if (reason === "missing_audience") return "the token has no aud; mint it with aud set to this server's origin (e.g. https://host:3100)";
966
1025
  if (reason === "wrong_audience") return "the token's aud is not one of this server's origins; connect through an origin listed in SUBSTRATE_PUBLIC_ORIGIN, or add this one there";
967
1026
  }
968
1027
  /**
@@ -1018,7 +1077,7 @@ function watchCredential(identity, cfg, onLapse) {
1018
1077
  }
1019
1078
  function extractBearer(authorization) {
1020
1079
  if (authorization === void 0) return null;
1021
- const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
1080
+ const match = /^Bearer\s+(\S.*)$/i.exec(authorization.trim());
1022
1081
  if (match === null) return null;
1023
1082
  const token = match[1]?.trim();
1024
1083
  if (token === void 0 || token.length === 0) return null;
@@ -1362,6 +1421,328 @@ function whoamiRoute(auth) {
1362
1421
  };
1363
1422
  }
1364
1423
 
1424
+ //#endregion
1425
+ //#region ../../packages/substrate-bridge-http/src/http-bridge-client.ts
1426
+ const DEFAULT_HEALTH_INTERVAL_MS = 1e4;
1427
+ const DEFAULT_TIMEOUT_MS = 1e4;
1428
+ const DEFAULT_MAX_RESPONSE_BYTES = 67108864;
1429
+ var HttpBridgeClient = class {
1430
+ name;
1431
+ baseUrl;
1432
+ #fetch;
1433
+ #intervalMs;
1434
+ #auth;
1435
+ #timeoutMs;
1436
+ #maxResponseBytes;
1437
+ #reachable;
1438
+ #timer;
1439
+ #disposed = false;
1440
+ constructor(opts) {
1441
+ this.name = opts.name;
1442
+ this.baseUrl = opts.baseUrl.endsWith("/") ? opts.baseUrl.slice(0, -1) : opts.baseUrl;
1443
+ this.#fetch = opts.fetch ?? fetch;
1444
+ this.#intervalMs = opts.healthCheckIntervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
1445
+ this.#auth = opts.auth;
1446
+ this.#timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
1447
+ this.#maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
1448
+ this.#reachable = opts.initialReachable ?? true;
1449
+ this.#startHealthProbe();
1450
+ }
1451
+ isReachable() {
1452
+ return this.#reachable;
1453
+ }
1454
+ async federatedSchema() {
1455
+ return this.#getJson("/substrate/v1/federated-schema");
1456
+ }
1457
+ query(frame) {
1458
+ return this.#postJson("/substrate/v1/query", frame);
1459
+ }
1460
+ mutate(frame) {
1461
+ return this.#postJson("/substrate/v1/mutate", frame);
1462
+ }
1463
+ async readRow(ref) {
1464
+ const key = `${ref.ns}/${ref.type}`;
1465
+ const frame = { [key]: {
1466
+ params: {
1467
+ id: ref.id,
1468
+ includeDeleted: true
1469
+ },
1470
+ fields: {
1471
+ id: true,
1472
+ _deletedAt: true
1473
+ }
1474
+ } };
1475
+ const envelope = await this.query(frame);
1476
+ const data = envelope.data?.[key];
1477
+ if (data === void 0) {
1478
+ const code = envelope.errors?.[0]?.code ?? "no_data";
1479
+ throw new BridgeUnreachableError(this.name, this.baseUrl, `refused (${code})`);
1480
+ }
1481
+ if (data === null) return null;
1482
+ if (Array.isArray(data)) {
1483
+ const first = data[0];
1484
+ return first === void 0 || first === null ? null : first;
1485
+ }
1486
+ return data;
1487
+ }
1488
+ dispose() {
1489
+ if (this.#disposed) return;
1490
+ this.#disposed = true;
1491
+ if (this.#timer !== void 0) {
1492
+ clearInterval(this.#timer);
1493
+ this.#timer = void 0;
1494
+ }
1495
+ }
1496
+ #headers(base) {
1497
+ const headers = { ...base };
1498
+ if (this.#auth !== void 0) headers.authorization = this.#auth();
1499
+ return headers;
1500
+ }
1501
+ #startHealthProbe() {
1502
+ const timer = setInterval(() => {
1503
+ this.#probeOnce();
1504
+ }, this.#intervalMs);
1505
+ const unref = timer.unref;
1506
+ if (typeof unref === "function") unref.call(timer);
1507
+ this.#timer = timer;
1508
+ }
1509
+ async #probeOnce() {
1510
+ try {
1511
+ const res = await this.#fetch(`${this.baseUrl}/substrate/v1/federated-schema`, {
1512
+ method: "GET",
1513
+ headers: this.#headers(),
1514
+ redirect: "error",
1515
+ signal: AbortSignal.timeout(this.#timeoutMs)
1516
+ });
1517
+ this.#reachable = res.ok;
1518
+ await res.body?.cancel();
1519
+ } catch {
1520
+ this.#reachable = false;
1521
+ }
1522
+ }
1523
+ #getJson(path) {
1524
+ return this.#request(path, {
1525
+ method: "GET",
1526
+ headers: this.#headers()
1527
+ });
1528
+ }
1529
+ /**
1530
+ * Non-2xx handling for both verbs. 5xx and auth failures throw
1531
+ * `BridgeUnreachableError`; anything else throws a plain `Error`.
1532
+ *
1533
+ * Only 401 and 5xx flip coordinator-wide reachability. A 403 refuses THIS
1534
+ * operation only — flipping the shared flag would make every read against
1535
+ * a healthy peer short-circuit as unreachable after one refused mutate. A
1536
+ * credential that cannot read is still caught by `#probeOnce`.
1537
+ */
1538
+ #throwForStatus(status, path) {
1539
+ if (status >= 500) {
1540
+ this.#reachable = false;
1541
+ throw new BridgeUnreachableError(this.name, this.baseUrl, `HTTP ${status}`);
1542
+ }
1543
+ if (status === 401 || status === 403) {
1544
+ if (status === 401) this.#reachable = false;
1545
+ throw new BridgeUnreachableError(this.name, this.baseUrl, `HTTP ${status} (auth)`);
1546
+ }
1547
+ throw new Error(`bridge '${this.name}' ${path} returned HTTP ${status}`);
1548
+ }
1549
+ #postJson(path, body) {
1550
+ return this.#request(path, {
1551
+ method: "POST",
1552
+ headers: this.#headers({ "content-type": "application/json" }),
1553
+ body: JSON.stringify(body)
1554
+ });
1555
+ }
1556
+ /** The body as text, refusing once it passes `maxResponseBytes`. */
1557
+ async #readCapped(res, path) {
1558
+ const tooLarge = () => /* @__PURE__ */ new Error(`bridge '${this.name}' ${path} response exceeds ${this.#maxResponseBytes} bytes`);
1559
+ if (Number(res.headers.get("content-length")) > this.#maxResponseBytes) {
1560
+ await res.body?.cancel();
1561
+ throw tooLarge();
1562
+ }
1563
+ if (res.body === null) return "";
1564
+ const chunks = [];
1565
+ let total = 0;
1566
+ for await (const chunk of res.body) {
1567
+ total += chunk.byteLength;
1568
+ if (total > this.#maxResponseBytes) throw tooLarge();
1569
+ chunks.push(chunk);
1570
+ }
1571
+ return Buffer.concat(chunks).toString("utf8");
1572
+ }
1573
+ async #request(path, init) {
1574
+ const signal = AbortSignal.timeout(this.#timeoutMs);
1575
+ let res;
1576
+ try {
1577
+ res = await this.#fetch(`${this.baseUrl}${path}`, {
1578
+ ...init,
1579
+ redirect: "error",
1580
+ signal
1581
+ });
1582
+ } catch (err) {
1583
+ this.#reachable = false;
1584
+ throw new BridgeUnreachableError(this.name, this.baseUrl, err);
1585
+ }
1586
+ if (!res.ok) this.#throwForStatus(res.status, path);
1587
+ try {
1588
+ const parsed = JSON.parse(await this.#readCapped(res, path));
1589
+ this.#reachable = true;
1590
+ return parsed;
1591
+ } catch (err) {
1592
+ if (!signal.aborted) throw err;
1593
+ this.#reachable = false;
1594
+ throw new BridgeUnreachableError(this.name, this.baseUrl, err);
1595
+ }
1596
+ }
1597
+ };
1598
+
1599
+ //#endregion
1600
+ //#region ../../packages/substrate-core/src/metrics/histogram.ts
1601
+ /** Upper bounds in ms: powers of √2 from 0.1 ms; the last bucket catches everything larger. */
1602
+ const BOUNDS = [];
1603
+ for (let b = .1; b < 6e4; b *= Math.SQRT2) BOUNDS.push(b);
1604
+ BOUNDS.push(Number.POSITIVE_INFINITY);
1605
+ /** O(1) observe; percentiles read off bucket upper bounds (clamped to the observed max). */
1606
+ var LogHistogram = class {
1607
+ #counts = new Array(BOUNDS.length).fill(0);
1608
+ count = 0;
1609
+ max = 0;
1610
+ observe(ms) {
1611
+ if (!Number.isFinite(ms) || ms < 0) return;
1612
+ let i = 0;
1613
+ while (ms > BOUNDS[i]) i++;
1614
+ this.#counts[i] = this.#counts[i] + 1;
1615
+ this.count++;
1616
+ if (ms > this.max) this.max = ms;
1617
+ }
1618
+ /** Lower bound of the bucket holding the p-th percentile; 0 when empty. */
1619
+ percentileLowerBound(p) {
1620
+ if (this.count === 0) return 0;
1621
+ const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
1622
+ let seen = 0;
1623
+ for (let i = 0; i < BOUNDS.length; i++) {
1624
+ seen += this.#counts[i];
1625
+ if (seen >= rank) return i === 0 ? 0 : BOUNDS[i - 1];
1626
+ }
1627
+ return this.max;
1628
+ }
1629
+ percentile(p) {
1630
+ if (this.count === 0) return 0;
1631
+ const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
1632
+ let seen = 0;
1633
+ for (let i = 0; i < BOUNDS.length; i++) {
1634
+ seen += this.#counts[i];
1635
+ if (seen >= rank) return Math.min(BOUNDS[i], this.max);
1636
+ }
1637
+ return this.max;
1638
+ }
1639
+ };
1640
+
1641
+ //#endregion
1642
+ //#region ../../packages/substrate-core/src/advisor/shape-recorder.ts
1643
+ /** Stable across filter order and operand values: field names and operators only. */
1644
+ function shapeKey(s) {
1645
+ const filters = [...new Set(s.filters.map((f) => `${f.field} ${f.op}`))].sort();
1646
+ const key = [
1647
+ s.namespace,
1648
+ s.type,
1649
+ filters,
1650
+ s.orderBy
1651
+ ];
1652
+ const literals = Object.entries(s.literals ?? {}).sort(([a], [b]) => a.localeCompare(b));
1653
+ if (s.disjunctive === true || literals.length > 0) key.push(s.disjunctive === true, literals);
1654
+ return JSON.stringify(key);
1655
+ }
1656
+ const COMBINATORS = /* @__PURE__ */ new Set([
1657
+ "AND",
1658
+ "OR",
1659
+ "NOT"
1660
+ ]);
1661
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
1662
+ /**
1663
+ * The shape of a read: every field `where` names, at any depth (through
1664
+ * AND/OR/NOT, and into struct fields as `a.b`), with each operator on it, and
1665
+ * the order it reads in. Takes the canonical `where` and `orderBy` as given.
1666
+ */
1667
+ function readShapeOf(namespace, type, fields, where, orderBy) {
1668
+ const filters = [];
1669
+ const literals = {};
1670
+ let disjunctive = false;
1671
+ const walk = (w, defs, prefix, conjunct) => {
1672
+ if (!isObject(w)) return;
1673
+ for (const [k, v] of Object.entries(w)) {
1674
+ if (COMBINATORS.has(k)) {
1675
+ const under = conjunct && k === "AND";
1676
+ if (!under) disjunctive = true;
1677
+ for (const sub of Array.isArray(v) ? v : [v]) walk(sub, defs, prefix, under);
1678
+ continue;
1679
+ }
1680
+ const def = defs !== void 0 && Object.hasOwn(defs, k) ? defs[k] : void 0;
1681
+ if (def?.kind === "struct") walk(v, def.fields, `${prefix}${k}.`, conjunct);
1682
+ else if (isObject(v)) {
1683
+ for (const op of Object.keys(v)) if (op !== "path") filters.push({
1684
+ field: `${prefix}${k}`,
1685
+ op
1686
+ });
1687
+ const operand = v.eq;
1688
+ if (conjunct && (operand === null || typeof operand === "boolean")) literals[`${prefix}${k}`] = operand;
1689
+ }
1690
+ }
1691
+ };
1692
+ walk(where, fields, "", true);
1693
+ const order = [];
1694
+ for (const clause of Array.isArray(orderBy) ? orderBy : []) {
1695
+ if (!isObject(clause)) continue;
1696
+ for (const [f, dir] of Object.entries(clause)) order.push([f, dir === "desc" ? "desc" : "asc"]);
1697
+ }
1698
+ return {
1699
+ namespace,
1700
+ type,
1701
+ filters,
1702
+ orderBy: order,
1703
+ ...disjunctive ? { disjunctive: true } : {},
1704
+ ...Object.keys(literals).length > 0 ? { literals } : {}
1705
+ };
1706
+ }
1707
+ /** Distinct shapes held between drains; past it the least recently seen is dropped. */
1708
+ const MAX_SHAPES = 1024;
1709
+ var ShapeRecorder = class {
1710
+ #shapes = /* @__PURE__ */ new Map();
1711
+ #now;
1712
+ /** When this recorder was created or last drained: the start of what `drain` returns. */
1713
+ since;
1714
+ constructor(now = Date.now) {
1715
+ this.#now = now;
1716
+ this.since = now();
1717
+ }
1718
+ observe(shape, durationMs) {
1719
+ const key = shapeKey(shape);
1720
+ const held = this.#shapes.get(key);
1721
+ const entry = held ?? {
1722
+ shape,
1723
+ hist: new LogHistogram()
1724
+ };
1725
+ if (held !== void 0) this.#shapes.delete(key);
1726
+ entry.hist.observe(durationMs);
1727
+ this.#shapes.set(key, entry);
1728
+ if (this.#shapes.size > MAX_SHAPES) {
1729
+ const oldest = this.#shapes.keys().next().value;
1730
+ this.#shapes.delete(oldest);
1731
+ }
1732
+ }
1733
+ /** Every shape seen since the last drain, with its count and p95; then forgets them. */
1734
+ drain() {
1735
+ const out = [...this.#shapes.values()].map(({ shape, hist }) => ({
1736
+ shape,
1737
+ count: hist.count,
1738
+ p95Ms: hist.percentile(.95)
1739
+ }));
1740
+ this.#shapes.clear();
1741
+ this.since = this.#now();
1742
+ return out;
1743
+ }
1744
+ };
1745
+
1365
1746
  //#endregion
1366
1747
  //#region ../../packages/substrate-core/src/engine/cursor-seal.ts
1367
1748
  /**
@@ -1514,17 +1895,26 @@ function fullBuiltinOperators() {
1514
1895
  //#endregion
1515
1896
  //#region ../../packages/substrate-filter/src/cursor.ts
1516
1897
  /**
1517
- * @internal — thrown by `decodeCursor` on malformed input. Re-exported so
1518
- * consumers can catch it by class, but treated as package-private.
1898
+ * Thrown by `decodeCursor` on a malformed, unsigned (pre-order-signing) or
1899
+ * mismatched cursor. A `ResolverFrameError` coded `invalid_cursor`, so the
1900
+ * engine reports it as a per-frame refusal rather than failing the request.
1519
1901
  */
1520
- var CursorDecodeError = class extends Error {
1902
+ var CursorDecodeError = class extends ResolverFrameError {
1521
1903
  name = "CursorDecodeError";
1904
+ constructor(message, details = {}) {
1905
+ super("invalid_cursor", message, {
1906
+ field: "cursor",
1907
+ ...details
1908
+ });
1909
+ }
1522
1910
  };
1523
1911
  function encodeCursor(input) {
1524
1912
  const json = JSON.stringify(input);
1525
1913
  return Buffer.from(json, "utf8").toString("base64url");
1526
1914
  }
1527
- function decodeCursor(cursor) {
1915
+ const orderText = (order) => order.map(([f, d]) => `${f} ${d}`).join(", ");
1916
+ /** Decodes a cursor and checks it was issued for `expected`, the read's normalized order. */
1917
+ function decodeCursor(cursor, expected) {
1528
1918
  let json;
1529
1919
  try {
1530
1920
  json = Buffer.from(cursor, "base64url").toString("utf8");
@@ -1550,9 +1940,17 @@ function decodeCursor(cursor) {
1550
1940
  "number",
1551
1941
  "boolean"
1552
1942
  ].includes(typeof v))) throw new CursorDecodeError("cursor 'orderByValues' must hold only scalar values");
1943
+ const order = obj.order;
1944
+ if (!Array.isArray(order) || !order.every((p) => Array.isArray(p) && p.length === 2 && typeof p[0] === "string" && (p[1] === "asc" || p[1] === "desc"))) throw new CursorDecodeError("cursor carries no 'order' (issued before cursors recorded their order); restart paging without a cursor");
1945
+ const issued = order;
1946
+ if (orderText(issued) !== orderText(expected)) throw new CursorDecodeError(`cursor was issued for orderBy '${orderText(issued)}' but this read orders by '${orderText(expected)}'; restart paging without a cursor`, {
1947
+ issuedFor: orderText(issued),
1948
+ readOrder: orderText(expected)
1949
+ });
1553
1950
  return {
1554
1951
  orderByValues: values,
1555
- id
1952
+ id,
1953
+ order: issued
1556
1954
  };
1557
1955
  }
1558
1956
 
@@ -1653,6 +2051,13 @@ function getExtensionOperator(name) {
1653
2051
  function listExtensionOperators() {
1654
2052
  return Array.from(extensionOperators.keys()).sort();
1655
2053
  }
2054
+ /** Remove `name` and the computed fields it owns. A no-op when `name` is not registered. */
2055
+ function unregisterExtensionOperator(name) {
2056
+ const op = extensionOperators.get(name);
2057
+ if (op === void 0) return;
2058
+ extensionOperators.delete(name);
2059
+ for (const cf of op.computedFields ?? []) if (computedFieldOwners.get(cf) === name) computedFieldOwners.delete(cf);
2060
+ }
1656
2061
  /**
1657
2062
  * True when any key in the where-tree (root, nested under AND/OR/NOT, or
1658
2063
  * inside a struct-field sub-clause) is a registered extension operator.
@@ -1725,12 +2130,6 @@ function whereContainsOperator(where, opName) {
1725
2130
  const JSON_PATH_MAX_DEPTH = 16;
1726
2131
  /** Most `in` / `nin` members both substrates accept (pg binds two per member). */
1727
2132
  const JSON_PATH_MAX_IN = 1e4;
1728
- /**
1729
- * Most `in` members still treated as index-served. jsonb `@>` has no planner
1730
- * statistics, so each OR'd containment adds a default-selectivity guess, and
1731
- * past a few dozen the planner scans the partition regardless of the GIN.
1732
- */
1733
- const JSON_PATH_INDEXED_IN_MAX = 32;
1734
2133
  const OPS = new Set(JSON_PATH_OPS$1);
1735
2134
  const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
1736
2135
  function isJsonPathPredicate(p) {
@@ -1770,18 +2169,6 @@ function jsonPathOperandProblem(op, operand) {
1770
2169
  default: return isScalar(operand) ? null : "requires a string, number or boolean";
1771
2170
  }
1772
2171
  }
1773
- /**
1774
- * Whether `op` scans the (namespace, type) partition on pg even when the field
1775
- * is `field.json({ indexed: true })`. Only containment is served by the derived
1776
- * `(body -> field)` GIN; a null operand needs an IS NULL test containment
1777
- * cannot express, and a long `in` is scanned by the planner anyway.
1778
- */
1779
- function jsonPathNeedsScan(op, operand) {
1780
- if (op === "has") return false;
1781
- if (op === "eq") return operand === null;
1782
- if (op === "in") return Array.isArray(operand) && (operand.length > 32 || operand.some((e) => e === null));
1783
- return true;
1784
- }
1785
2172
  /** The value at `path`, walking plain objects only. `undefined` means absent. */
1786
2173
  function resolveJsonPath(value, path) {
1787
2174
  let cur = value;
@@ -1999,7 +2386,8 @@ const METADATA_COLUMN_PROJECTIONS = {
1999
2386
  createdById: (row) => row._metadata?.createdBy?.id ?? null,
2000
2387
  createdByKind: (row) => row._metadata?.createdBy?.kind ?? null,
2001
2388
  updatedById: (row) => row._metadata?.updatedBy?.id ?? null,
2002
- updatedByKind: (row) => row._metadata?.updatedBy?.kind ?? null
2389
+ updatedByKind: (row) => row._metadata?.updatedBy?.kind ?? null,
2390
+ seq: (row) => row._metadata?.seq ?? null
2003
2391
  };
2004
2392
  /**
2005
2393
  * Resolve the effective filter value for `name` on `row`.
@@ -2013,6 +2401,14 @@ function getFieldValue(row, name) {
2013
2401
  if (projector !== void 0) return projector(row);
2014
2402
  return row[name];
2015
2403
  }
2404
+ /**
2405
+ * Whether `field` holds a date: the `createdAt`/`updatedAt` columns always do,
2406
+ * a body field when its declaration says so. Date fields compare as instants.
2407
+ */
2408
+ function isDateField(field, fieldDefOf) {
2409
+ const def = METADATA_FILTER_FIELDS[field] ?? fieldDefOf?.(field);
2410
+ return def?.kind === "scalar" && def.type === "date";
2411
+ }
2016
2412
  const KNOWN_OPS = /* @__PURE__ */ new Set([
2017
2413
  "eq",
2018
2414
  "neq",
@@ -2087,27 +2483,35 @@ function assertFieldPredicateHonourable(field, predicate) {
2087
2483
  case "endsWith": if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
2088
2484
  }
2089
2485
  }
2090
- function evaluateWhere(row, where) {
2486
+ /**
2487
+ * `fieldDefOf` names the row type's declared fields, so `date` fields compare
2488
+ * as instants (as pg's timestamptz does). Without it, only `createdAt` and
2489
+ * `updatedAt` do; nested struct fields always compare as written.
2490
+ */
2491
+ function evaluateWhere(row, where, fieldDefOf) {
2091
2492
  if (where === null || typeof where !== "object" || Array.isArray(where)) return true;
2092
2493
  for (const [k, child] of Object.entries(where)) if (k === "AND") {
2093
2494
  if (Array.isArray(child)) {
2094
- for (const sub of child) if (!evaluateWhere(row, sub)) return false;
2495
+ for (const sub of child) if (!evaluateWhere(row, sub, fieldDefOf)) return false;
2095
2496
  }
2096
2497
  } else if (k === "OR") {
2097
2498
  if (Array.isArray(child)) {
2098
2499
  let any = false;
2099
- for (const sub of child) if (evaluateWhere(row, sub)) {
2500
+ for (const sub of child) if (evaluateWhere(row, sub, fieldDefOf)) {
2100
2501
  any = true;
2101
2502
  break;
2102
2503
  }
2103
2504
  if (!any) return false;
2104
2505
  }
2105
2506
  } else if (k === "NOT") {
2106
- if (evaluateWhere(row, child)) return false;
2107
- } else if (!evaluateFieldPredicate(k, getFieldValue(row, k), child)) return false;
2507
+ if (evaluateWhere(row, child, fieldDefOf)) return false;
2508
+ } else {
2509
+ const asDate = isDateField(k, fieldDefOf);
2510
+ if (!evaluateFieldPredicate(k, getFieldValue(row, k), child, asDate)) return false;
2511
+ }
2108
2512
  return true;
2109
2513
  }
2110
- function evaluateFieldPredicate(field, value, predicate) {
2514
+ function evaluateFieldPredicate(field, value, predicate, asDate = false) {
2111
2515
  if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) throw new UnsupportedFilterError(field, "<none>", `expected a predicate object such as { eq: ... }, got ${Array.isArray(predicate) ? "an array" : typeof predicate}`);
2112
2516
  if (isJsonPathPredicate(predicate)) return evaluateJsonPathPredicate(field, value, predicate);
2113
2517
  const p = predicate;
@@ -2119,34 +2523,25 @@ function evaluateFieldPredicate(field, value, predicate) {
2119
2523
  }
2120
2524
  for (const op of keys) {
2121
2525
  const operand = p[op];
2122
- if (!applyOp(field, op, value, operand)) return false;
2526
+ if (!applyOp(field, op, value, operand, asDate)) return false;
2123
2527
  }
2124
2528
  return true;
2125
2529
  }
2126
- function applyOp(field, op, value, operand) {
2530
+ function applyOp(field, op, value, operand, asDate) {
2127
2531
  switch (op) {
2128
- case "eq": return equals(value, operand);
2129
- case "neq": return !equals(value, operand);
2130
- case "gt":
2131
- if (value == null) return false;
2132
- return compare$1(value, operand) > 0;
2133
- case "gte":
2134
- if (value == null) return false;
2135
- return compare$1(value, operand) >= 0;
2136
- case "lt":
2137
- if (value == null) return false;
2138
- return compare$1(value, operand) < 0;
2139
- case "lte":
2140
- if (value == null) return false;
2141
- return compare$1(value, operand) <= 0;
2532
+ case "eq": return equals(value, operand, asDate);
2533
+ case "neq": return !equals(value, operand, asDate);
2534
+ case "gt": return rangeCmp(value, operand, asDate) > 0;
2535
+ case "gte": return rangeCmp(value, operand, asDate) >= 0;
2536
+ case "lt": return rangeCmp(value, operand, asDate) < 0;
2537
+ case "lte": return rangeCmp(value, operand, asDate) <= 0;
2142
2538
  case "between":
2143
2539
  if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2144
- if (value == null) return false;
2145
- return compare$1(value, operand[0]) >= 0 && compare$1(value, operand[1]) <= 0;
2540
+ return rangeCmp(value, operand[0], asDate) >= 0 && rangeCmp(value, operand[1], asDate) <= 0;
2146
2541
  case "in":
2147
2542
  case "nin": {
2148
2543
  if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
2149
- const member = operand.some((e) => equals(value, e));
2544
+ const member = operand.some((e) => equals(value, e, asDate));
2150
2545
  return op === "in" ? member : !member;
2151
2546
  }
2152
2547
  case "contains":
@@ -2164,26 +2559,86 @@ function applyOp(field, op, value, operand) {
2164
2559
  default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2165
2560
  }
2166
2561
  }
2167
- function equals(a, b) {
2562
+ function equals(a, b, asDate = false) {
2168
2563
  if (a == null && b == null) return true;
2169
- if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
2170
- if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
2171
- if (b instanceof Date && typeof a === "string") return b.toISOString() === a;
2564
+ if (asDate || a instanceof Date || b instanceof Date) {
2565
+ const at = storedMicros(a);
2566
+ const bt = toMicros(b);
2567
+ return at !== void 0 && bt !== void 0 && at === bt;
2568
+ }
2172
2569
  return a === b;
2173
2570
  }
2174
- function compare$1(a, b) {
2571
+ /**
2572
+ * {@link compareFilterValues} for a range operator, or NaN, which fails every
2573
+ * ordered test, where pg's compare is NULL: a null value, a non-number value
2574
+ * against a number operand (substrate_num), or either side not an instant in
2575
+ * date mode (substrate_ts).
2576
+ */
2577
+ function rangeCmp(value, operand, asDate) {
2578
+ if (value == null) return NaN;
2579
+ if (typeof operand === "number" && typeof value !== "number") return NaN;
2580
+ if ((asDate || value instanceof Date || operand instanceof Date) && (storedMicros(value) === void 0 || toMicros(operand) === void 0)) return NaN;
2581
+ return compareFilterValues(value, operand, asDate);
2582
+ }
2583
+ /**
2584
+ * Orders two filter values: nullish last, dates (when `asDate`, or either side
2585
+ * is a `Date`) by instant, numbers numerically, anything else as text by code point.
2586
+ */
2587
+ function compareFilterValues(a, b, asDate = false) {
2175
2588
  if (a == null && b == null) return 0;
2176
2589
  if (a == null) return 1;
2177
2590
  if (b == null) return -1;
2178
- if (a instanceof Date || b instanceof Date) {
2179
- const at = a instanceof Date ? a.getTime() : typeof a === "string" ? Date.parse(a) : Number(a);
2180
- const bt = b instanceof Date ? b.getTime() : typeof b === "string" ? Date.parse(b) : Number(b);
2181
- return at < bt ? -1 : at > bt ? 1 : 0;
2591
+ if (asDate || a instanceof Date || b instanceof Date) {
2592
+ const at = toMicros(a);
2593
+ const bt = toMicros(b);
2594
+ if (at !== void 0 && bt !== void 0) return at < bt ? -1 : at > bt ? 1 : 0;
2182
2595
  }
2183
2596
  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
2184
- const as = String(a);
2185
- const bs = String(b);
2186
- return as < bs ? -1 : as > bs ? 1 : 0;
2597
+ return compareCodePoints(String(a), String(b));
2598
+ }
2599
+ /**
2600
+ * {@link toMicros} for a stored value: `undefined` wherever `substrate_ts` is
2601
+ * NULL, a number included. Only the shared ISO grammar is read; operands are
2602
+ * cast leniently, as pg's `tsParam` casts them.
2603
+ */
2604
+ function storedMicros(v) {
2605
+ if (v instanceof Date) return toMicros(v);
2606
+ if (typeof v !== "string" || normalizeIsoTimestamp(v) === void 0) return void 0;
2607
+ return toMicros(v);
2608
+ }
2609
+ /**
2610
+ * A row value as pg sorts it: a date-field value `substrate_ts` cannot read, or
2611
+ * a number-field value that is not a number, becomes null and sorts last.
2612
+ */
2613
+ function asSortValue(field, value, fieldDefOf) {
2614
+ if (value == null) return value;
2615
+ if (isDateField(field, fieldDefOf)) return storedMicros(value) === void 0 ? null : value;
2616
+ const def = METADATA_FILTER_FIELDS[field] ?? fieldDefOf?.(field);
2617
+ if (def?.kind === "scalar" && def.type === "number" && typeof value !== "number") return null;
2618
+ return value;
2619
+ }
2620
+ /**
2621
+ * Microseconds since the epoch, pg's timestamptz precision, as a bigint: a
2622
+ * double is exact only to 2^53 µs (about 1685-2255), and the grammar spans
2623
+ * years 0001-9999. `Date.parse` keeps only milliseconds, so the 4th-6th
2624
+ * fraction digits are added back. A number is read as epoch milliseconds;
2625
+ * anything unparseable is `undefined`.
2626
+ */
2627
+ function toMicros(v) {
2628
+ if (v instanceof Date) return msToMicros(v.getTime());
2629
+ if (typeof v === "number") return msToMicros(v);
2630
+ if (typeof v !== "string") return void 0;
2631
+ const iso = normalizeIsoTimestamp(v) ?? v;
2632
+ const micros = msToMicros(Date.parse(iso));
2633
+ if (micros === void 0) return void 0;
2634
+ const frac = /[T ][\d:]+\.(\d+)/.exec(iso)?.[1] ?? "";
2635
+ return micros + BigInt(frac.padEnd(6, "0").slice(3, 6));
2636
+ }
2637
+ /** Epoch milliseconds as microseconds, exact: `ms * 1000` as a double is not, past 2^53. */
2638
+ function msToMicros(ms) {
2639
+ if (!Number.isFinite(ms)) return void 0;
2640
+ const whole = Math.floor(ms);
2641
+ return BigInt(whole) * 1000n + BigInt(Math.round((ms - whole) * 1e3));
2187
2642
  }
2188
2643
 
2189
2644
  //#endregion
@@ -2193,6 +2648,7 @@ const SWEEP_ACTOR = {
2193
2648
  kind: "system",
2194
2649
  id: "sweep"
2195
2650
  };
2651
+ /** `UNKNOWN`: the bridge could not answer (down, or refused), so nothing may be applied. */
2196
2652
  async function resolveTarget(ref, deps) {
2197
2653
  const ds = deps.datasets.get(ref.ns);
2198
2654
  if (ds) {
@@ -2210,7 +2666,7 @@ async function resolveTarget(ref, deps) {
2210
2666
  if (row === null) return "MISSING";
2211
2667
  return row._deletedAt != null ? "DELETED" : "EXISTS";
2212
2668
  } catch (err) {
2213
- if (err instanceof BridgeUnreachableError) return "MISSING";
2669
+ if (err instanceof BridgeUnreachableError) return "UNKNOWN";
2214
2670
  throw err;
2215
2671
  }
2216
2672
  return "MISSING";
@@ -2314,6 +2770,7 @@ async function sweepBatch(base, deps) {
2314
2770
  id: edge.id,
2315
2771
  lastSweptAt: deps.now()
2316
2772
  });
2773
+ else if (target === "UNKNOWN") deps.metric("bridge_unreachable", edge.to.ns);
2317
2774
  else if (target === "DELETED") await applyPolicy(edge, cascadeQueue, deps);
2318
2775
  else if (edge.to.bridged === true && deps.bridges.isUnreachable(edge.to.ns)) deps.metric("bridge_unreachable", edge.to.ns);
2319
2776
  else await applyPolicy(edge, cascadeQueue, deps);
@@ -2327,7 +2784,7 @@ async function sweepBatch(base, deps) {
2327
2784
  return worklist.length;
2328
2785
  }
2329
2786
  const SWEEP_CURSOR_TYPE = "SweepCursor";
2330
- const SWEEP_CURSOR_ID = "edges";
2787
+ const SWEEP_CURSOR_ID = "5ee9c0a5-0000-4000-8000-000000000001";
2331
2788
  /** Reads the sweep cursor persisted by `saveSweepState`, or the scan head. */
2332
2789
  async function loadSweepState(ds) {
2333
2790
  const { rows } = await ds.read(SWEEP_CURSOR_TYPE, {
@@ -2469,6 +2926,9 @@ var Registry = class extends RegistryBase {
2469
2926
  params: input.params ?? {}
2470
2927
  };
2471
2928
  if (input.returns !== void 0) entry.returns = input.returns;
2929
+ if (input.orderedBy !== void 0) entry.orderedBy = input.orderedBy;
2930
+ if (input.indexes !== void 0) entry.indexes = input.indexes;
2931
+ if (input.expectedSize !== void 0) entry.expectedSize = input.expectedSize;
2472
2932
  if (input.verb !== void 0) entry.verb = input.verb;
2473
2933
  this.entries.set(name, entry);
2474
2934
  }
@@ -2489,6 +2949,9 @@ var Registry = class extends RegistryBase {
2489
2949
  params: input.params ?? {}
2490
2950
  };
2491
2951
  if (input.returns !== void 0) entry.returns = input.returns;
2952
+ if (input.orderedBy !== void 0) entry.orderedBy = input.orderedBy;
2953
+ if (input.indexes !== void 0) entry.indexes = input.indexes;
2954
+ if (input.expectedSize !== void 0) entry.expectedSize = input.expectedSize;
2492
2955
  if (input.verb !== void 0) entry.verb = input.verb;
2493
2956
  this.entries.set(name, entry);
2494
2957
  }
@@ -2592,7 +3055,7 @@ function checkIdentityGrant(identity, ns, operation) {
2592
3055
  required
2593
3056
  };
2594
3057
  }
2595
- function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx) {
3058
+ function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx, txEntries) {
2596
3059
  const args = { edges };
2597
3060
  if (dataset !== void 0) args.dataset = dataset;
2598
3061
  if (entry.params !== void 0) args.params = entry.params;
@@ -2601,9 +3064,26 @@ function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset,
2601
3064
  if (signal !== void 0) args.signal = signal;
2602
3065
  if (resolveDataset !== void 0) args.resolveDataset = resolveDataset;
2603
3066
  if (afterTx !== void 0) args.afterTx = afterTx;
3067
+ if (txEntries !== void 0) args.txEntries = txEntries;
2604
3068
  return args;
2605
3069
  }
2606
3070
  /**
3071
+ * `params` with the type's natural order as `orderBy` when it names none: the
3072
+ * default read order of a query, a subscription's snapshot and a stream. A
3073
+ * single-row `id` read has no order, and get-shaped resolvers refuse one. An
3074
+ * extension operator (semantic, …) in `where` keeps its relevance order.
3075
+ * Returns `params` itself when nothing is added.
3076
+ */
3077
+ function withNaturalOrder(params, entry, dataset) {
3078
+ if (entry.kind !== "type" || dataset?.capabilities.orderBy !== true || params?.id !== void 0 || listExtensionOperators().some((op) => whereContainsOperator(params?.where, op))) return params;
3079
+ const orderBy = params?.orderBy;
3080
+ if (Array.isArray(orderBy) && orderBy.length > 0) return params;
3081
+ return {
3082
+ ...params,
3083
+ orderBy: [{ ...naturalOrderOf(entry) }]
3084
+ };
3085
+ }
3086
+ /**
2607
3087
  * The frame with its `where` / `orderBy` metadata spellings rewritten onto the
2608
3088
  * canonical columns (`createdBy` -> `createdById`, …). Returns the same frame
2609
3089
  * when it carries neither.
@@ -2734,12 +3214,30 @@ function toBridgeFrame(bucket) {
2734
3214
  return out;
2735
3215
  }
2736
3216
  /**
3217
+ * Scope each forwarded `idempotencyKey` to the local caller. The peer sees
3218
+ * every forwarded write under the bridge's one credential, so a key passed
3219
+ * verbatim lets two callers who pick the same key share one cached reply
3220
+ * there. The same caller retrying still forwards the same key.
3221
+ */
3222
+ function scopeBridgeIdempotency(bucket, caller) {
3223
+ const out = {};
3224
+ for (const [key, entry] of Object.entries(bucket)) out[key] = !Array.isArray(entry) && typeof entry.idempotencyKey === "string" ? {
3225
+ ...entry,
3226
+ idempotencyKey: createHash("sha256").update(JSON.stringify([caller, entry.idempotencyKey])).digest("hex")
3227
+ } : entry;
3228
+ return out;
3229
+ }
3230
+ /**
2737
3231
  * Snapshot obligation gate. Mirrors `applyRowFilters` from the SDK but on a
2738
3232
  * single row — we can't wrap every live push in an allocation when the vast
2739
3233
  * majority of rows pass the filter.
2740
3234
  */
2741
3235
  function obligationsPermitRow(obligations, ctx, row) {
2742
- for (const ob of obligations) if (!ob.predicate(ctx, row)) return false;
3236
+ for (const ob of obligations) try {
3237
+ if (!ob.predicate(ctx, row)) return false;
3238
+ } catch {
3239
+ return false;
3240
+ }
2743
3241
  return true;
2744
3242
  }
2745
3243
  function normaliseToRows(result) {
@@ -2966,7 +3464,7 @@ function lookupField(fields, name) {
2966
3464
  */
2967
3465
  function metadataHint(fieldName) {
2968
3466
  if (!/^(_metadata|createdBy|updatedBy)(\.|$)/.test(fieldName)) return "";
2969
- return " — row metadata is filterable as createdAt, updatedAt, createdBy / updatedBy (an identity id, or { kind, id }), or createdById, createdByKind, updatedById, updatedByKind";
3467
+ return " — row metadata is filterable as createdAt, updatedAt, createdBy / updatedBy (an identity id, or { kind, id }), or createdById, createdByKind, updatedById, updatedByKind, and seq on a visible-order type";
2970
3468
  }
2971
3469
  const LOGICAL_KEYS = /* @__PURE__ */ new Set([
2972
3470
  "AND",
@@ -3075,19 +3573,22 @@ function validatePrimitiveKind(fieldKind, value, path, op) {
3075
3573
  case "scalar.boolean":
3076
3574
  if (typeof value !== "boolean") throw new FilterValidationError("type_mismatch", `operator '${op}' expected boolean, got ${typeof value}`, path);
3077
3575
  return;
3078
- case "scalar.date":
3576
+ case "scalar.date": {
3079
3577
  if (!(value instanceof Date) && typeof value !== "string") throw new FilterValidationError("type_mismatch", `operator '${op}' expected Date or ISO string, got ${typeof value}`, path);
3578
+ const field = path.slice(path[0] === "where" ? 1 : 0, -1).join(".");
3579
+ if (value instanceof Date && Number.isNaN(value.getTime()) || typeof value === "string" && isImpossibleIsoTimestamp(value)) throw new FilterValidationError("type_mismatch", `operator '${op}' on '${field}': ${String(value)} is not a real date`, path);
3080
3580
  return;
3581
+ }
3081
3582
  case "crossRef":
3082
3583
  if (typeof value !== "string" && typeof value !== "number") throw new FilterValidationError("type_mismatch", `crossRef '${op}' expected id (string or number), got ${typeof value}`, path);
3083
3584
  return;
3084
3585
  }
3085
3586
  }
3086
- function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedCheck) {
3587
+ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, ctx) {
3087
3588
  if (fieldDef.kind === "struct") {
3088
3589
  if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' is a struct — expected a nested where clause object`, path);
3089
3590
  validateWhereAgainstFields(leaf, fieldDef.fields, path, capabilities, {
3090
- ...indexedCheck,
3591
+ ...ctx,
3091
3592
  insideStruct: true
3092
3593
  });
3093
3594
  return;
@@ -3096,7 +3597,6 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3096
3597
  const listDef = fieldDef;
3097
3598
  const elementKind = fieldKindOf(listDef.of);
3098
3599
  if (elementKind === "struct" || elementKind === "list" || elementKind === "scalar.json") throw new FilterValidationError("unknown_operator", `field '${fieldName}' is a list of ${elementKind} — only lists of scalars / refs support 'has'`, path);
3099
- if (listDef.indexed !== true && !indexedCheck.allowTableScan) throw new FilterValidationError("unindexed_field", `field '${fieldName}' is an unindexed list — set { indexed: true } on the field or params._allowTableScan to override`, path);
3100
3600
  if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3101
3601
  const datasetCapOps = new Set(capabilities.operators.list ?? []);
3102
3602
  const elemNullable = listDef.of.kind === "scalar" && listDef.of.nullable === true;
@@ -3113,11 +3613,10 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3113
3613
  }
3114
3614
  const kind = fieldKindOf(fieldDef);
3115
3615
  if (kind === "scalar.json") {
3116
- if (indexedCheck.insideStruct === true && isJsonPathPredicate(leaf)) throw new FilterValidationError("unknown_operator", `json path filters apply to top-level json fields only — '${fieldName}' is inside a struct (kind=scalar.json)`, [...path, "path"]);
3117
- validateJsonPathLeaf(fieldName, isIndexed(fieldDef), leaf, path, capabilities, indexedCheck);
3616
+ if (ctx.insideStruct === true && isJsonPathPredicate(leaf)) throw new FilterValidationError("unknown_operator", `json path filters apply to top-level json fields only — '${fieldName}' is inside a struct (kind=scalar.json)`, [...path, "path"]);
3617
+ validateJsonPathLeaf(fieldName, leaf, path, capabilities);
3118
3618
  return;
3119
3619
  }
3120
- if (!isIndexed(fieldDef) && !indexedCheck.allowTableScan) throw new FilterValidationError("unindexed_field", `field '${fieldName}' is not indexed — set params._allowTableScan to override`, path);
3121
3620
  if (leaf === null || typeof leaf !== "object" || Array.isArray(leaf)) throw new FilterValidationError("type_mismatch", `field '${fieldName}' expected a predicate object, got ${typeof leaf}`, path);
3122
3621
  const allowedOps = opsAllowedFor(kind);
3123
3622
  const datasetCapOps = new Set(capabilities.operators[kind] ?? []);
@@ -3136,13 +3635,12 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3136
3635
  }
3137
3636
  const JSON_PATH_HINT = "address inside it with { path: [...], <op>: ... }";
3138
3637
  /**
3139
- * A json field is filterable only through a path predicate. The
3140
- * index gate is per operator AND per field: `eq`/`in`/`has` compile to
3141
- * containment, which the GIN derived for `field.json({ indexed: true })`
3142
- * serves; every other operator, and every operator on an unindexed json
3143
- * field, scans the (namespace, type) partition.
3638
+ * A json field is filterable only through a path predicate. `eq`/`in`/`has`
3639
+ * compile to containment, which the GIN derived for
3640
+ * `field.json({ indexed: true })` serves; anything else scans the
3641
+ * (namespace, type) partition. Either way it is accepted.
3144
3642
  */
3145
- function validateJsonPathLeaf(fieldName, fieldIndexed, leaf, path, capabilities, indexedCheck) {
3643
+ function validateJsonPathLeaf(fieldName, leaf, path, capabilities) {
3146
3644
  const obj = leaf !== null && typeof leaf === "object" && !Array.isArray(leaf) ? leaf : null;
3147
3645
  if (obj !== null && "path" in obj && !isJsonPathPredicate(obj)) throw new FilterValidationError("type_mismatch", `field '${fieldName}': path must be an array of keys (kind=scalar.json)`, [...path, "path"]);
3148
3646
  if (!isJsonPathPredicate(leaf)) {
@@ -3161,15 +3659,9 @@ function validateJsonPathLeaf(fieldName, fieldIndexed, leaf, path, capabilities,
3161
3659
  if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'scalar.json'`, [...path, op]);
3162
3660
  const problem = jsonPathOperandProblem(op, operand);
3163
3661
  if (problem !== null) throw new FilterValidationError(op === "between" ? "invalid_between" : "type_mismatch", `operator '${op}' on a json path of field '${fieldName}' ${problem}`, [...path, op]);
3164
- if ((!fieldIndexed || jsonPathNeedsScan(op, operand)) && !indexedCheck.allowTableScan) throw new FilterValidationError("unindexed_field", `operator '${op}' on json field '${fieldName}' scans the type's rows — set params._allowTableScan to override (eq, in and has are index-served on a field declared field.json({ indexed: true }))`, [...path, op]);
3165
3662
  }
3166
3663
  }
3167
- function isIndexed(def) {
3168
- if (def.kind === "scalar") return def.indexed === true;
3169
- if (def.kind === "crossRef") return true;
3170
- return false;
3171
- }
3172
- function validateWhereAgainstFields(where, fields, path, capabilities, indexedCheck) {
3664
+ function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
3173
3665
  if (where === null || typeof where !== "object" || Array.isArray(where)) throw new FilterValidationError("type_mismatch", "where must be an object", path);
3174
3666
  const keys = Object.keys(where);
3175
3667
  const hasLogical = keys.some((k) => LOGICAL_KEYS.has(k));
@@ -3185,11 +3677,11 @@ function validateWhereAgainstFields(where, fields, path, capabilities, indexedCh
3185
3677
  ...path,
3186
3678
  k,
3187
3679
  String(i)
3188
- ], capabilities, indexedCheck);
3680
+ ], capabilities, ctx);
3189
3681
  });
3190
3682
  } else if (k === "NOT") {
3191
3683
  if (child === null || typeof child !== "object" || Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'NOT' expects a single WhereClause`, [...path, k]);
3192
- validateWhereAgainstFields(child, fields, [...path, k], capabilities, indexedCheck);
3684
+ validateWhereAgainstFields(child, fields, [...path, k], capabilities, ctx);
3193
3685
  }
3194
3686
  }
3195
3687
  return;
@@ -3205,9 +3697,14 @@ function validateWhereAgainstFields(where, fields, path, capabilities, indexedCh
3205
3697
  }
3206
3698
  throw new FilterValidationError("unknown_field", `unknown field '${fieldName}'${metadataHint(fieldName)}`, [...path, fieldName]);
3207
3699
  }
3208
- validateLeaf(fieldName, def, where[fieldName], [...path, fieldName], capabilities, indexedCheck);
3700
+ validateLeaf(fieldName, def, where[fieldName], [...path, fieldName], capabilities, ctx);
3701
+ if (def === METADATA_VIRTUAL_FIELDS.seq) assertSeqIntegers(where[fieldName], [...path, fieldName]);
3209
3702
  }
3210
3703
  }
3704
+ /** `seq` is a bigint column: every numeric operand must be a safe integer. */
3705
+ function assertSeqIntegers(leaf, path) {
3706
+ for (const [op, operand] of Object.entries(leaf)) for (const v of Array.isArray(operand) ? operand : [operand]) if (typeof v === "number" && !Number.isSafeInteger(v)) throw new FilterValidationError("type_mismatch", `operator '${op}' expected an integer for 'seq', got ${v}`, [...path, op]);
3707
+ }
3211
3708
  function validateOrderBy(orderBy, fields, capabilities) {
3212
3709
  if (!capabilities.orderBy) throw new FilterValidationError("capability_unsupported", "dataset does not support orderBy", ["orderBy"]);
3213
3710
  if (!Array.isArray(orderBy)) throw new FilterValidationError("type_mismatch", "orderBy must be an array of { field: \"asc\" | \"desc\" } entries", ["orderBy"]);
@@ -3241,8 +3738,7 @@ function validateOrderBy(orderBy, fields, capabilities) {
3241
3738
  });
3242
3739
  }
3243
3740
  function validateFilter(input) {
3244
- const allowTableScan = input.allowTableScan === true;
3245
- if (input.where !== void 0) validateWhereAgainstFields(input.where, input.typeSchema.fields, ["where"], input.capabilities, { allowTableScan });
3741
+ if (input.where !== void 0) validateWhereAgainstFields(input.where, input.typeSchema.fields, ["where"], input.capabilities, {});
3246
3742
  if (input.orderBy !== void 0) validateOrderBy(input.orderBy, input.typeSchema.fields, input.capabilities);
3247
3743
  }
3248
3744
 
@@ -3269,7 +3765,6 @@ function runFilterGuard(deps, input) {
3269
3765
  const params = entry.params;
3270
3766
  const where = params?.where;
3271
3767
  const orderBy = params?.orderBy;
3272
- const allowTableScan = params?._allowTableScan === true;
3273
3768
  const requested = hasComputedFields() && entry.fields !== void 0 ? Object.keys(entry.fields) : [];
3274
3769
  for (const f of requested) {
3275
3770
  const owner = computedFieldOwner(f);
@@ -3316,7 +3811,6 @@ function runFilterGuard(deps, input) {
3316
3811
  } else validateFilter({
3317
3812
  ...where !== void 0 ? { where } : {},
3318
3813
  ...orderBy !== void 0 ? { orderBy } : {},
3319
- allowTableScan,
3320
3814
  typeSchema,
3321
3815
  capabilities: dataset.capabilities
3322
3816
  });
@@ -3575,7 +4069,10 @@ function publishSchema(registry) {
3575
4069
  params: entry.params,
3576
4070
  returns: entry.returns ?? UNKNOWN_RETURNS
3577
4071
  };
3578
- else types[name] = { fields: entry.fields };
4072
+ else types[name] = entry.orderedBy !== void 0 ? {
4073
+ fields: entry.fields,
4074
+ orderedBy: entry.orderedBy
4075
+ } : { fields: entry.fields };
3579
4076
  return {
3580
4077
  schemaVersion: hashContent(types, mutations),
3581
4078
  types,
@@ -3790,7 +4287,23 @@ var StreamSubsystem = class {
3790
4287
  if (input.signal.aborted) controller.abort();
3791
4288
  else input.signal.addEventListener("abort", () => controller.abort(), { once: true });
3792
4289
  }
3793
- this.#runStream(input, keys[0], controller);
4290
+ this.#runStream(input, keys[0], controller).catch((err) => {
4291
+ const key = keys[0];
4292
+ deliverFrame(input.onFrame, {
4293
+ id: input.id,
4294
+ kind: "error",
4295
+ errors: [{
4296
+ message: clientErrorMessage(err, this.#metric, key),
4297
+ code: "resolver_error",
4298
+ path: [key]
4299
+ }]
4300
+ }, this.#metric);
4301
+ deliverFrame(input.onFrame, {
4302
+ id: input.id,
4303
+ kind: "end",
4304
+ final: true
4305
+ }, this.#metric);
4306
+ });
3794
4307
  return {
3795
4308
  id: input.id,
3796
4309
  cancel: () => {
@@ -3910,14 +4423,12 @@ var StreamSubsystem = class {
3910
4423
  const params = frame.params;
3911
4424
  const where = params?.where;
3912
4425
  const orderBy = params?.orderBy;
3913
- const allowTableScan = params?._allowTableScan === true;
3914
4426
  if (where !== void 0 || orderBy !== void 0) {
3915
4427
  const typeSchema = this.#schemaFor(ns).types[name];
3916
4428
  if (typeSchema) try {
3917
4429
  validateFilter({
3918
4430
  ...where !== void 0 ? { where } : {},
3919
4431
  ...orderBy !== void 0 ? { orderBy } : {},
3920
- allowTableScan,
3921
4432
  typeSchema,
3922
4433
  capabilities: dataset.capabilities
3923
4434
  });
@@ -3935,6 +4446,8 @@ var StreamSubsystem = class {
3935
4446
  }
3936
4447
  }
3937
4448
  }
4449
+ const ordered = withNaturalOrder(args.params, registryEntry, dataset);
4450
+ if (ordered !== void 0) args.params = ordered;
3938
4451
  let result;
3939
4452
  try {
3940
4453
  result = await registryEntry.resolver(ctx, args);
@@ -4448,14 +4961,12 @@ var SubscribeSubsystem = class {
4448
4961
  const rawWhere = params?.where;
4449
4962
  const where = rawWhere !== void 0 && typeFields !== void 0 ? normaliseVocabWhere(rawWhere, typeFields) : rawWhere;
4450
4963
  const orderBy = params?.orderBy;
4451
- const allowTableScan = params?._allowTableScan === true;
4452
4964
  if (where !== void 0 || orderBy !== void 0) {
4453
4965
  const typeSchema = this.#schemaFor(ns).types[name];
4454
4966
  if (typeSchema) try {
4455
4967
  validateFilter({
4456
4968
  ...where !== void 0 ? { where } : {},
4457
4969
  ...orderBy !== void 0 ? { orderBy } : {},
4458
- allowTableScan,
4459
4970
  typeSchema,
4460
4971
  capabilities: dataset.capabilities
4461
4972
  });
@@ -4498,6 +5009,8 @@ var SubscribeSubsystem = class {
4498
5009
  pendingEvents: []
4499
5010
  };
4500
5011
  this.#registerEntry(subscriptionEntry);
5012
+ const ordered = withNaturalOrder(args.params, registryEntry, dataset);
5013
+ if (ordered !== void 0) args.params = ordered;
4501
5014
  const snapshotLimit = registryEntry.kind === "type" ? this.#snapshotLimit : void 0;
4502
5015
  if (snapshotLimit !== void 0) args.params = {
4503
5016
  ...args.params,
@@ -4671,7 +5184,8 @@ var SubscribeSubsystem = class {
4671
5184
  const obligationsAllow = obligationsPermitRow(entry.obligations, entry.ctx, row);
4672
5185
  let whereMatches;
4673
5186
  try {
4674
- whereMatches = entry.where === void 0 ? true : evaluateWhere(row, entry.where);
5187
+ const fields = this.#schemaFor(entry.ns).types[entry.type]?.fields;
5188
+ whereMatches = entry.where === void 0 ? true : evaluateWhere(row, entry.where, (f) => fields?.[f]);
4675
5189
  } catch (err) {
4676
5190
  const code = isResolverFrameError(err) ? err.code : "resolver_error";
4677
5191
  this.#enqueueFrame(entry, {
@@ -4875,6 +5389,7 @@ var Engine = class {
4875
5389
  #edges;
4876
5390
  #metric;
4877
5391
  #onResolve;
5392
+ #shapeRecorder;
4878
5393
  #idempotency;
4879
5394
  /**
4880
5395
  * Mutates under a dedup key that are still running. The store only sees a
@@ -4910,6 +5425,7 @@ var Engine = class {
4910
5425
  this.#edges = opts.edges;
4911
5426
  this.#metric = opts.metric ?? (() => {});
4912
5427
  this.#onResolve = opts.onResolve;
5428
+ this.#shapeRecorder = opts.shapeRecorder;
4913
5429
  this.#idempotency = opts.idempotency !== void 0 ? {
4914
5430
  store: opts.idempotency.store,
4915
5431
  defaultTtlMs: opts.idempotency.defaultTtlMs ?? 864e5
@@ -5339,7 +5855,7 @@ var Engine = class {
5339
5855
  const ctx = this.#buildContext(input.ctx, "mutate");
5340
5856
  const signal = input.signal;
5341
5857
  const bridgePromises = [];
5342
- for (const [ns, bucket] of bridgeBuckets) bridgePromises.push(this.#bridgeProxy.runMutate(ns, bucket, envelope));
5858
+ for (const [ns, bucket] of bridgeBuckets) bridgePromises.push(this.#bridgeProxy.runMutate(ns, scopeBridgeIdempotency(bucket, callerKey), envelope));
5343
5859
  const writeBatch = [];
5344
5860
  const onWrite = (event) => {
5345
5861
  writeBatch.push(event);
@@ -5389,7 +5905,8 @@ var Engine = class {
5389
5905
  const entry = frame[key];
5390
5906
  if (entry === void 0) continue;
5391
5907
  const parsed = parsedByKey.get(key) ?? null;
5392
- if (await this.#runEntry(envelope, key, entry, ctx, "mutate", parsed === null ? null : txFor(parsed.ns), txEdges, parsed, (event) => pending.push(event), signal, (fn) => settled.push(fn))) {
5908
+ const errorsBefore = envelope.errors?.length ?? 0;
5909
+ if (await this.#runEntry(envelope, key, entry, ctx, "mutate", parsed === null ? null : txFor(parsed.ns), txEdges, parsed, (event) => pending.push(event), signal, (fn) => settled.push(fn), singleFrameKeys.length) || (envelope.errors ?? []).slice(errorsBefore).some((e) => e.path?.[0] === key)) {
5393
5910
  refusedKey = key;
5394
5911
  throw new SharedTxRefusal();
5395
5912
  }
@@ -5416,9 +5933,9 @@ var Engine = class {
5416
5933
  } catch (err) {
5417
5934
  if (!(err instanceof SharedTxRefusal)) throw err;
5418
5935
  for (const key of singleFrameKeys) {
5419
- if (!(key in envelope.data)) continue;
5420
5936
  const ns = parsedByKey.get(key)?.ns;
5421
5937
  if (ns !== void 0 && this.#namespaces.get(ns)?.virtual === true) continue;
5938
+ if (!(key in envelope.data) && envelope.errors?.some((e) => e.path?.[0] === key)) continue;
5422
5939
  delete envelope.data[key];
5423
5940
  delete envelope.shapes[key];
5424
5941
  addError(envelope, [key], `mutate rolled back: '${refusedKey}' refused`, "frame_rolled_back");
@@ -5472,7 +5989,7 @@ var Engine = class {
5472
5989
  * `mutate` so both honour the dedup contract.
5473
5990
  */
5474
5991
  async #finaliseMutateEnvelope(envelope, keys, resolution, callerKey) {
5475
- if (resolution.kind === "present" && this.#idempotency !== void 0 && (envelope.errors === void 0 || envelope.errors.length === 0)) {
5992
+ if (resolution.kind === "present" && this.#idempotency !== void 0 && keys.some((key) => key in envelope.data)) {
5476
5993
  const dedupKey = makeDedupKey(keys, resolution.value, callerKey);
5477
5994
  try {
5478
5995
  await this.#idempotency.store.put(dedupKey, envelope, this.#idempotency.defaultTtlMs);
@@ -5606,7 +6123,7 @@ var Engine = class {
5606
6123
  });
5607
6124
  return refused;
5608
6125
  }
5609
- async #runEntryInner(envelope, key, entry, ctxBase, operation, tx, txEdges, parsed, onWrite, signal, afterTx) {
6126
+ async #runEntryInner(envelope, key, entry, ctxBase, operation, tx, txEdges, parsed, onWrite, signal, afterTx, txEntries) {
5610
6127
  if (!parsed) {
5611
6128
  addError(envelope, [key], `unqualified frame key '${key}' — expected '<ns>/<name>'`, "unqualified_key");
5612
6129
  this.#metric("engine_unqualified_key", key);
@@ -5652,7 +6169,7 @@ var Engine = class {
5652
6169
  entry: name,
5653
6170
  ...registryEntry.verb !== void 0 ? { verb: registryEntry.verb } : {}
5654
6171
  };
5655
- const args = toResolverArgs(frame, dataset, txEdges ?? this.#edges, onWrite, signal, (ns) => this.#datasets.get(ns), afterTx);
6172
+ const args = toResolverArgs(frame, dataset, txEdges ?? this.#edges, onWrite, signal, (ns) => this.#datasets.get(ns), afterTx, txEntries);
5656
6173
  const decision = evaluatePolicy(registryEntry.policy, ctx, args);
5657
6174
  if (!decision.allow) {
5658
6175
  addError(envelope, [key], decision.reason ?? "policy denied", "policy_denied");
@@ -5678,6 +6195,10 @@ var Engine = class {
5678
6195
  isVirtual,
5679
6196
  dataset
5680
6197
  })) return false;
6198
+ if (operation === "query" && !isVirtual) {
6199
+ const params = withNaturalOrder(args.params, registryEntry, dataset);
6200
+ if (params !== void 0) args.params = params;
6201
+ }
5681
6202
  const cursor = args.params?.cursor;
5682
6203
  if (typeof cursor === "string") {
5683
6204
  const opened = (decision.obligations?.length ?? 0) > 0 && !isSealedCursor(cursor) ? null : openCursor(cursor);
@@ -5691,6 +6212,7 @@ var Engine = class {
5691
6212
  };
5692
6213
  }
5693
6214
  let result;
6215
+ const t0 = performance.now();
5694
6216
  try {
5695
6217
  result = await registryEntry.resolver(ctx, args);
5696
6218
  } catch (err) {
@@ -5711,6 +6233,8 @@ var Engine = class {
5711
6233
  return true;
5712
6234
  }
5713
6235
  throw err;
6236
+ } finally {
6237
+ if (operation === "query" && registryEntry.kind === "type" && !isVirtual && args.params?.id === void 0) this.#shapeRecorder?.observe(readShapeOf(ns, name, registryEntry.fields, args.params?.where, args.params?.orderBy), performance.now() - t0);
5714
6238
  }
5715
6239
  shapeResult({
5716
6240
  envelope,
@@ -5872,7 +6396,7 @@ var Engine = class {
5872
6396
  shapes: {}
5873
6397
  };
5874
6398
  failedIndex = i;
5875
- await this.#runEntry(scratch, key, frame, ctxBase, "mutate", txDs, txEdges, parsed, arrayOnWrite, signal, (fn) => settled.push(fn));
6399
+ await this.#runEntry(scratch, key, frame, ctxBase, "mutate", txDs, txEdges, parsed, arrayOnWrite, signal, (fn) => settled.push(fn), frames.length);
5876
6400
  failedIndex = void 0;
5877
6401
  const entry = {};
5878
6402
  if (key in scratch.data) entry.data = scratch.data[key];
@@ -6387,48 +6911,6 @@ function farEndAllowed(edge, fromMatch, toMatch, allowed) {
6387
6911
  return fromMatch && allowed.has(edge.to.ns) || toMatch && allowed.has(edge.from.ns);
6388
6912
  }
6389
6913
 
6390
- //#endregion
6391
- //#region ../../packages/substrate-core/src/metrics/histogram.ts
6392
- /** Upper bounds in ms: powers of √2 from 0.1 ms; the last bucket catches everything larger. */
6393
- const BOUNDS = [];
6394
- for (let b = .1; b < 6e4; b *= Math.SQRT2) BOUNDS.push(b);
6395
- BOUNDS.push(Number.POSITIVE_INFINITY);
6396
- /** O(1) observe; percentiles read off bucket upper bounds (clamped to the observed max). */
6397
- var LogHistogram = class {
6398
- #counts = new Array(BOUNDS.length).fill(0);
6399
- count = 0;
6400
- max = 0;
6401
- observe(ms) {
6402
- if (!Number.isFinite(ms) || ms < 0) return;
6403
- let i = 0;
6404
- while (ms > BOUNDS[i]) i++;
6405
- this.#counts[i] = this.#counts[i] + 1;
6406
- this.count++;
6407
- if (ms > this.max) this.max = ms;
6408
- }
6409
- /** Lower bound of the bucket holding the p-th percentile; 0 when empty. */
6410
- percentileLowerBound(p) {
6411
- if (this.count === 0) return 0;
6412
- const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
6413
- let seen = 0;
6414
- for (let i = 0; i < BOUNDS.length; i++) {
6415
- seen += this.#counts[i];
6416
- if (seen >= rank) return i === 0 ? 0 : BOUNDS[i - 1];
6417
- }
6418
- return this.max;
6419
- }
6420
- percentile(p) {
6421
- if (this.count === 0) return 0;
6422
- const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
6423
- let seen = 0;
6424
- for (let i = 0; i < BOUNDS.length; i++) {
6425
- seen += this.#counts[i];
6426
- if (seen >= rank) return Math.min(BOUNDS[i], this.max);
6427
- }
6428
- return this.max;
6429
- }
6430
- };
6431
-
6432
6914
  //#endregion
6433
6915
  //#region ../../packages/substrate-core/src/metrics/resolver-table.ts
6434
6916
  const round = (ms) => Math.round(ms * 100) / 100;
@@ -6945,6 +7427,26 @@ function assertNoNullOnNonNullable(params, fieldDefs, phase) {
6945
7427
  });
6946
7428
  }
6947
7429
  /**
7430
+ * Refuse a supplied value whose JS type does not match a `number`, `boolean`
7431
+ * or `date` scalar. pg sorts and date-filters these by casting
7432
+ * `body->>field` to numeric, boolean or timestamptz, so one stored
7433
+ * `dueAt: "next week"` fails every such read of the type, for every caller.
7434
+ * `string` and `json` fields are left alone: nothing casts them. `null` is
7435
+ * the null guard's business, not this one's.
7436
+ */
7437
+ function assertScalarTypes(params, fieldDefs, phase) {
7438
+ for (const [name, def] of Object.entries(fieldDefs)) {
7439
+ if (def.kind !== "scalar" || !Object.hasOwn(params, name)) continue;
7440
+ const v = params[name];
7441
+ if (v === null) continue;
7442
+ 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}.`, {
7443
+ field: name,
7444
+ expected: def.type,
7445
+ phase
7446
+ });
7447
+ }
7448
+ }
7449
+ /**
6948
7450
  * Fill `create` defaults: for every declared scalar field with a `default` that
6949
7451
  * the caller omitted, set it on `params`. Mutates the supplied bag in place
6950
7452
  * (the create resolver passes a fresh `{ ...args.params }`). A caller-supplied
@@ -7035,20 +7537,6 @@ function assertServerSetFieldsFillable(typeName, fieldDefs) {
7035
7537
 
7036
7538
  //#endregion
7037
7539
  //#region ../../packages/substrate-sdk/src/autocrud/autocrud-create.ts
7038
- /**
7039
- * autoCRUD `create<T>` resolver. Spec: §5.1.
7040
- *
7041
- * Accepts the entity body via `params`. Generates a UUID id when absent.
7042
- * `_deletedAt` is stripped at the dataset layer — no sanitation needed here.
7043
- *
7044
- * Design call: id generation is `crypto.randomUUID()` rather than monotonic
7045
- * counters so two engines pointed at the same dataset (future) don't collide.
7046
- *
7047
- * When `options.fields` is supplied, any field with `readonly: true` is
7048
- * rejected if the caller includes it in params — shortId is the primary use
7049
- * case. The engine allocates shortId post-write and binds
7050
- * it in the same transaction via `ds.allocateShortId` / `ds.bindShortId`.
7051
- */
7052
7540
  function createResolver(typeName, dataset, options = {}) {
7053
7541
  return async (ctx, args) => {
7054
7542
  const ds = args.dataset ?? dataset;
@@ -7064,10 +7552,12 @@ function createResolver(typeName, dataset, options = {}) {
7064
7552
  if (options.fields) assertNoUnknownFields(params, options.fields, "create");
7065
7553
  if (options.fields) {
7066
7554
  assertNoNullOnNonNullable(params, options.fields, "create");
7555
+ assertScalarTypes(params, options.fields, "create");
7067
7556
  applyScalarDefaults(params, options.fields);
7068
7557
  assertRequiredFields(params, options.fields);
7069
7558
  }
7070
- const id = coerceId(params.id) ?? randomUUID();
7559
+ const { id: rawId, ...body } = params;
7560
+ const id = coerceId(rawId);
7071
7561
  const at = ctx.now.toISOString();
7072
7562
  const actor = resolveIdentity(ctx);
7073
7563
  const _metadata = {
@@ -7076,8 +7566,11 @@ function createResolver(typeName, dataset, options = {}) {
7076
7566
  createdBy: actor,
7077
7567
  updatedBy: actor
7078
7568
  };
7079
- const row = {
7080
- ...params,
7569
+ const row = id === void 0 ? {
7570
+ ...body,
7571
+ _metadata
7572
+ } : {
7573
+ ...body,
7081
7574
  id,
7082
7575
  _metadata
7083
7576
  };
@@ -7214,14 +7707,12 @@ function listResolver(typeName, dataset, options = {}) {
7214
7707
  const where = args.params?.where;
7215
7708
  const orderBy = args.params?.orderBy;
7216
7709
  const cursor = args.params?.cursor;
7217
- const allowTableScan = args.params?._allowTableScan;
7218
7710
  const includeDeleted = args.params?.includeDeleted;
7219
7711
  if (id !== void 0) readParams.id = id;
7220
7712
  if (ids !== void 0) readParams.ids = ids;
7221
7713
  if (where !== void 0) readParams.where = options.fields !== void 0 ? normaliseVocabWhere(where, options.fields) : where;
7222
7714
  if (orderBy !== void 0) readParams.orderBy = orderBy;
7223
7715
  if (typeof cursor === "string") readParams.cursor = cursor;
7224
- if (allowTableScan === true) readParams._allowTableScan = true;
7225
7716
  if (includeDeleted === true) readParams.includeDeleted = true;
7226
7717
  const fields = args.fields;
7227
7718
  if (fields !== void 0) readParams.fields = fields;
@@ -7411,6 +7902,7 @@ function updateResolver(typeName, dataset, edges, options = {}) {
7411
7902
  if (options.fields) {
7412
7903
  assertNoUnknownFields(inParams, options.fields, "update");
7413
7904
  assertNoNullOnNonNullable(inParams, options.fields, "update");
7905
+ assertScalarTypes(inParams, options.fields, "update");
7414
7906
  }
7415
7907
  const rowId = await resolveEntityId(ds, typeName, id);
7416
7908
  if (rowId === null) throw new ResolverFrameError("not_found", `updateResolver('${typeName}'): no row with id '${String(id)}'`, { field: "id" });
@@ -7639,7 +8131,10 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
7639
8131
  resolver: list,
7640
8132
  kind: "type",
7641
8133
  ...policy !== void 0 ? { policy } : {},
7642
- ...fields !== void 0 ? { fields } : {}
8134
+ ...fields !== void 0 ? { fields } : {},
8135
+ ...options.orderedBy !== void 0 ? { orderedBy: options.orderedBy } : {},
8136
+ ...options.indexes !== void 0 ? { indexes: options.indexes } : {},
8137
+ ...options.expectedSize !== void 0 ? { expectedSize: options.expectedSize } : {}
7643
8138
  });
7644
8139
  const cap = typeName.charAt(0).toUpperCase() + typeName.slice(1);
7645
8140
  registry.register(`get${cap}`, {
@@ -7700,9 +8195,9 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
7700
8195
  function makeScalar(type, opts) {
7701
8196
  const def = {
7702
8197
  kind: "scalar",
7703
- type,
7704
- indexed: opts?.indexed ?? true
8198
+ type
7705
8199
  };
8200
+ if (opts?.indexed !== void 0) def.indexed = opts.indexed;
7706
8201
  if (opts?.nullable !== void 0) def.nullable = opts.nullable;
7707
8202
  if (opts?.readonly !== void 0) def.readonly = opts.readonly;
7708
8203
  if (opts?.default !== void 0) def.default = opts.default;
@@ -7790,8 +8285,7 @@ const field = {
7790
8285
  * JSON body. Value round-trips unchanged. Filter a value INSIDE it with a
7791
8286
  * path predicate — `{ values: { path: ['year'], gt: 1990 } }` — which is
7792
8287
  * type-strict. `eq` / `in` / `has` are index-served only with
7793
- * `{ indexed: true }`; everything else scans the type's rows and needs
7794
- * `_allowTableScan`. No ordering. When inner keys are known at schema time,
8288
+ * `{ indexed: true }`; everything else scans the type's rows. No ordering. When inner keys are known at schema time,
7795
8289
  * `field.struct` is still the better fit: declared, indexed, orderable.
7796
8290
  */
7797
8291
  json(opts) {
@@ -7808,13 +8302,125 @@ const field = {
7808
8302
 
7809
8303
  //#endregion
7810
8304
  //#region ../../packages/substrate-sdk/src/autocrud/reserved.ts
7811
- const RESERVED_AUTOCRUD_FIELDS = { shortId: field.number({
8305
+ /** A registered symbol, so a second copy of this SDK in one process marks the same way. */
8306
+ const RESERVED = Symbol.for("@mnmal-ai/substrate-sdk:autocrud-reserved");
8307
+ /** `def`, marked as autoCRUD's own. Non-enumerable, so equality and JSON ignore it. */
8308
+ const reserved = (def) => Object.defineProperty(def, RESERVED, { value: true });
8309
+ const RESERVED_AUTOCRUD_FIELDS = { shortId: reserved(field.number({
7812
8310
  indexed: true,
7813
8311
  readonly: true
7814
- }) };
8312
+ })) };
8313
+ /** Is `def` a descriptor autoCRUD injected, rather than a body field of the same name? */
8314
+ function isReservedAutoCrudField(def) {
8315
+ return def[RESERVED] === true;
8316
+ }
7815
8317
  /** Reserved field names — useful for validation loops. */
7816
8318
  const RESERVED_AUTOCRUD_FIELD_NAMES = Object.keys(RESERVED_AUTOCRUD_FIELDS);
7817
8319
 
8320
+ //#endregion
8321
+ //#region ../../packages/substrate-sdk/src/engine-helpers.ts
8322
+ /**
8323
+ * Engine-call helpers for coordinator/plugin authors.
8324
+ *
8325
+ * Run an internal engine query or build a request context from inside a
8326
+ * plugin route or scheduled task, so coordinators share one implementation.
8327
+ *
8328
+ * Depends only on `@mnmal-ai/substrate-types`; this package must not take a
8329
+ * runtime dependency on `substrate-core`.
8330
+ */
8331
+ /**
8332
+ * Build a minimal `Partial<RequestContext>` for a plugin's engine call.
8333
+ *
8334
+ * PASS THE CALLER'S IDENTITY WHENEVER THERE IS ONE. Omitting it yields the
8335
+ * SYSTEM ACTOR (`identity: null`), which the engine's per-frame namespace gate
8336
+ * waves through unconditionally — correct for genuinely system-initiated work
8337
+ * (a scheduled sweep, a liveness probe), and a privilege escalation for
8338
+ * anything a caller asked for. A plugin route that omits it lets a caller reach
8339
+ * namespaces their grant does not cover, because the route gate checks a
8340
+ * capability without a namespace and the engine gate then checks a namespace
8341
+ * without an identity.
8342
+ *
8343
+ * The distinction is WHO ASKED, not which plugin.
8344
+ */
8345
+ function makeCtx(namespace, operation, identity = null) {
8346
+ return {
8347
+ identity,
8348
+ namespace,
8349
+ operation,
8350
+ now: /* @__PURE__ */ new Date(),
8351
+ headers: {},
8352
+ meta: {}
8353
+ };
8354
+ }
8355
+ /**
8356
+ * A frame the engine REFUSED, surfaced as a throw rather than as an empty result.
8357
+ *
8358
+ * Substrate returns a partial-success envelope: a rejected frame comes back with its
8359
+ * key ABSENT from `data` and the reason in `errors`. Without this, `queryOne` /
8360
+ * `queryAll` would render a refusal as `null` / `[]`, indistinguishable from a
8361
+ * query that matched nothing.
8362
+ */
8363
+ var EngineQueryError = class extends Error {
8364
+ name = "EngineQueryError";
8365
+ code;
8366
+ constructor(code, message) {
8367
+ super(message);
8368
+ this.code = code;
8369
+ }
8370
+ };
8371
+ /** Throw when the envelope carries an error, so a refusal cannot read as absence. */
8372
+ function assertNoFrameError(env, key) {
8373
+ const err = env.errors?.[0];
8374
+ if (err !== void 0) throw new EngineQueryError(err.code ?? "query_failed", err.message ?? `${key} was refused`);
8375
+ }
8376
+ /** Expand a list of field names into the `{ field: true }` selection map. */
8377
+ function selectAll(fields) {
8378
+ const out = {};
8379
+ for (const f of fields) out[f] = true;
8380
+ return out;
8381
+ }
8382
+ /** Accept either a field-name list or an already-built selection map. */
8383
+ function toSelection(fields) {
8384
+ return Array.isArray(fields) ? selectAll(fields) : fields;
8385
+ }
8386
+ /**
8387
+ * Run an internal engine query and return the row list (empty when the frame
8388
+ * resolves to nothing). `fields` may be a name list or a prebuilt selection map.
8389
+ */
8390
+ async function queryAll(engine, namespace, typeName, params, fields, identity = null) {
8391
+ const key = formatQualifiedKey(namespace, typeName);
8392
+ const env = await engine.query({
8393
+ frame: { [key]: {
8394
+ params,
8395
+ fields: toSelection(fields)
8396
+ } },
8397
+ ctx: makeCtx(namespace, "query", identity)
8398
+ });
8399
+ assertNoFrameError(env, key);
8400
+ const rows = env.data[key];
8401
+ if (rows === void 0 || rows === null) return [];
8402
+ return rows;
8403
+ }
8404
+ /**
8405
+ * Run an internal engine query expecting at most one row; returns the first
8406
+ * row or null. `fields` may be a name list or a prebuilt selection map.
8407
+ */
8408
+ async function queryOne(engine, namespace, typeName, params, fields, identity = null) {
8409
+ const key = formatQualifiedKey(namespace, typeName);
8410
+ const env = await engine.query({
8411
+ frame: { [key]: {
8412
+ params,
8413
+ fields: toSelection(fields)
8414
+ } },
8415
+ ctx: makeCtx(namespace, "query", identity)
8416
+ });
8417
+ assertNoFrameError(env, key);
8418
+ const rows = env.data[key];
8419
+ if (rows === void 0 || rows === null) return null;
8420
+ if (Array.isArray(rows)) return rows[0] ?? null;
8421
+ return rows;
8422
+ }
8423
+
7818
8424
  //#endregion
7819
8425
  //#region ../../packages/substrate-sdk/src/namespace.ts
7820
8426
  /**
@@ -7878,6 +8484,14 @@ function defineNamespace(namespace, types, opts = {}) {
7878
8484
  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})`);
7879
8485
  assertServerSetFieldsFillable(typeName, typeInput.fields);
7880
8486
  }
8487
+ for (const [typeName, typeInput] of Object.entries(types)) {
8488
+ for (const decl of typeInput.indexes ?? []) assertIndexDecl(typeName, typeInput.fields, decl);
8489
+ const ordering = typeInput.ordering;
8490
+ if (ordering !== void 0 && ordering !== "visible") throw new Error(`ordering on ${typeName} must be 'visible', got '${String(ordering)}'`);
8491
+ if (typeInput.orderedBy !== void 0) assertOrderedBy(typeName, typeInput);
8492
+ const size = typeInput.expectedSize;
8493
+ if (size !== void 0 && size !== "small" && size !== "large") throw new Error(`expectedSize on ${typeName} must be 'small' or 'large', got '${String(size)}'`);
8494
+ }
7881
8495
  if (opts.annotations !== void 0) assertJsonValue(opts.annotations, "annotations");
7882
8496
  const globalPolicy = opts.policy;
7883
8497
  return {
@@ -7894,6 +8508,7 @@ function defineNamespace(namespace, types, opts = {}) {
7894
8508
  };
7895
8509
  const combined = composePolicyLayers(ctx.pluginPolicy, globalPolicy, typeInput.policy);
7896
8510
  const installOpts = { fields: augmentedFields };
8511
+ if (typeInput.orderedBy !== void 0) installOpts.orderedBy = typeInput.orderedBy;
7897
8512
  if (combined !== void 0) installOpts.policy = combined;
7898
8513
  if (typeInput.purgeable === true) installOpts.purgeable = true;
7899
8514
  if (typeInput.adminCapability !== void 0) installOpts.adminCapability = typeInput.adminCapability;
@@ -7907,6 +8522,61 @@ function defineNamespace(namespace, types, opts = {}) {
7907
8522
  }
7908
8523
  };
7909
8524
  }
8525
+ /** Lower-snake, within pg's 63-byte identifier limit. */
8526
+ const INDEX_NAME_PATTERN = /^[a-z_][a-z0-9_]{0,62}$/;
8527
+ /** Throws unless every key is a btree-indexable declared field or `createdAt`/`updatedAt`, and every predicate field a declared one. */
8528
+ function assertIndexDecl(typeName, fields, decl) {
8529
+ const where = `index on ${typeName}`;
8530
+ const assertField = (name) => {
8531
+ const def = fields[name];
8532
+ if (def === void 0) throw new Error(`${where}: unknown field '${name}'`);
8533
+ if (!(def.kind === "crossRef" || def.kind === "scalar" && def.type !== "json")) throw new Error(`${where}: field '${name}' is ${def.kind}; only scalar and crossRef fields index`);
8534
+ };
8535
+ if (!Array.isArray(decl.fields) || decl.fields.length === 0) throw new Error(`${where}: fields must be a non-empty array`);
8536
+ const assertKey = (name) => {
8537
+ if (name !== "createdAt" && name !== "updatedAt") assertField(name);
8538
+ };
8539
+ for (const f of decl.fields) {
8540
+ if (typeof f === "string") {
8541
+ assertKey(f);
8542
+ continue;
8543
+ }
8544
+ assertKey(f.field);
8545
+ if (f.dir !== "asc" && f.dir !== "desc") throw new Error(`${where}: dir of '${f.field}' must be 'asc' or 'desc', got '${String(f.dir)}'`);
8546
+ }
8547
+ if (decl.where !== void 0 && decl.where !== "live") for (const [name, value] of Object.entries(decl.where)) {
8548
+ assertField(name);
8549
+ if (value !== null && typeof value !== "boolean") throw new Error(`${where}: where.${name} must be a boolean or null`);
8550
+ const def = fields[name];
8551
+ if (value !== null && !(def?.kind === "scalar" && def.type === "boolean")) throw new Error(`${where}: where.${name} compares a boolean, but '${name}' is not a boolean field`);
8552
+ }
8553
+ if (decl.name?.endsWith("__swap") === true) throw new Error(`${where}: name '${decl.name}' must not end in '__swap', the reconciler's temporary suffix`);
8554
+ if (decl.name !== void 0 && !INDEX_NAME_PATTERN.test(decl.name)) throw new Error(`${where}: name '${decl.name}' must match ${INDEX_NAME_PATTERN.source}`);
8555
+ }
8556
+ /** Metadata columns a type may take as its natural order. */
8557
+ const ORDERED_BY_METADATA_COLUMNS = /* @__PURE__ */ new Set(["createdAt", "updatedAt"]);
8558
+ /**
8559
+ * Throws unless `orderedBy` is one key, on a date or number field or a metadata
8560
+ * column; `seq` only on a type declared `ordering: 'visible'`.
8561
+ */
8562
+ function assertOrderedBy(typeName, def) {
8563
+ const where = `orderedBy on ${typeName}`;
8564
+ const entries = Object.entries(def.orderedBy ?? {});
8565
+ if (entries.length !== 1) throw new Error(`${where}: must name exactly one field, got ${entries.length}`);
8566
+ const [name, dir] = entries[0];
8567
+ if (dir !== "asc" && dir !== "desc") throw new Error(`${where}: dir of '${name}' must be 'asc' or 'desc', got '${String(dir)}'`);
8568
+ if (ORDERED_BY_METADATA_COLUMNS.has(name)) return;
8569
+ if (name === "seq") {
8570
+ if (def.ordering === "visible") return;
8571
+ throw new Error(`${where}: 'seq' needs the type to declare ordering: 'visible'`);
8572
+ }
8573
+ const field = def.fields[name];
8574
+ if (field === void 0) throw new Error(`${where}: unknown field '${name}'`);
8575
+ if (!(field.kind === "scalar" && (field.type === "date" || field.type === "number"))) {
8576
+ const kind = field.kind === "scalar" ? field.type : field.kind;
8577
+ throw new Error(`${where}: field '${name}' is ${kind}; only date and number fields, or ${[...ORDERED_BY_METADATA_COLUMNS].join(", ")}, can be a natural order`);
8578
+ }
8579
+ }
7910
8580
  function composePolicyLayers(pluginLevel, namespaceLevel, typeLevel) {
7911
8581
  const layers = [
7912
8582
  pluginLevel,
@@ -7990,6 +8660,8 @@ const INVITE_FIELDS = {
7990
8660
  * - `field_backfilled` : `backfillFieldRoute` wrote per-row values of one field, metadata preserved
7991
8661
  * - `type_dropped` : `dropTypeRoute` dropped every row in a single type
7992
8662
  * - `destructive_op_refused` : kill switch refused a hard-destructive operation
8663
+ * - `index_proposed` : `propose_index` added, removed or reordered an index, or
8664
+ * dismissed a recommendation; `details` names the action
7993
8665
  *
7994
8666
  * `details` is an opaque JSON body — `field.json()` round-trips the value
7995
8667
  * unchanged through encoder/decoder, no JSON.stringify boundary needed.
@@ -8039,27 +8711,69 @@ const ENUM_VERDICT_FIELDS = {
8039
8711
  /** `namespace/type/field` — the upsert key the writer derives. Indexed for the lookup. */
8040
8712
  verdictKey: field.string()
8041
8713
  };
8042
- const AUDIT_EVENT_TYPE = "AuditEvent";
8714
+ const STORE_PROFILE_TYPE = "StoreProfile";
8715
+ const INDEX_RECOMMENDATION_TYPE = "IndexRecommendation";
8043
8716
  /**
8044
- * Public-policy projection of `Key`. Returns only verification material.
8045
- * Named `SigningKey` to follow the `_system` namespace convention (every
8046
- * type in `_system` carries the `Substrate` prefix as identity, independent of
8047
- * policy posture). Policy posture is documented per-resolver: this one accepts
8048
- * `identity: null` and gates only on namespace presence. See `./signing-key.ts`
8049
- * for the resolver implementation.
8717
+ * The one `StoreProfile` row's id. A fixed UUID, not a name, so the row passes
8718
+ * the `rows_id_uuid_format` CHECK that `SUBSTRATE_ENFORCE_UUID_CHECK` installs.
8050
8719
  */
8051
- const SIGNING_KEY_TYPE = "SigningKey";
8720
+ const STORE_PROFILE_ID = "5703e000-0000-4000-8000-000000000001";
8052
8721
  /**
8053
- * Field surface for `_system/SigningKey`. Mirrors the subset of `Key`
8054
- * that a JWT verifier needs: `id` (the kid, auto-included by the schema
8055
- * publisher for every type) plus `publicKey` and `algorithm`. Capabilities,
8056
- * namespaces, and `revokedAt` are NOT exposed — they're admin-only on the
8057
- * parent type.
8722
+ * `StoreProfile` — one row, id `STORE_PROFILE_ID`: the sizing profile the index advisor
8723
+ * reads its thresholds from on each pass. Seeded once from
8724
+ * `SUBSTRATE_STORE_PROFILE` (else `personal`), then changed live.
8058
8725
  */
8059
- const SIGNING_KEY_FIELDS = {
8060
- publicKey: field.string({ indexed: false }),
8061
- algorithm: field.string()
8726
+ const STORE_PROFILE_FIELDS = {
8727
+ profile: field.enum([
8728
+ "personal",
8729
+ "growth",
8730
+ "scale"
8731
+ ]),
8732
+ updatedReason: field.string({ indexed: false })
8062
8733
  };
8734
+ const ADVISOR_STATE_TYPE = "AdvisorState";
8735
+ /** The one `AdvisorState` row's id: a fixed UUID, for the same CHECK. */
8736
+ const ADVISOR_STATE_ID = "5703e000-0000-4000-8000-000000000002";
8737
+ /**
8738
+ * `AdvisorState` — one row, id `ADVISOR_STATE_ID`: the index advisor's persisted
8739
+ * baseline (`{ epoch, types, indexes }`, see `AdvisorState` in the advisor).
8740
+ * Written only by the advisor through the dataset; admins may read it, and
8741
+ * no caller may write it.
8742
+ */
8743
+ const ADVISOR_STATE_FIELDS = { stateJson: field.string({ indexed: false }) };
8744
+ /**
8745
+ * `IndexRecommendation` — one index the advisor recommends adding or removing,
8746
+ * with its evidence. The row id is a version-8 UUID derived from `recKey`, so
8747
+ * every advisor process on a store converges on one row per (action, shape) or (action, index), refreshed
8748
+ * while `open` and never reopened once `accepted` or `dismissed`.
8749
+ */
8750
+ const INDEX_RECOMMENDATION_FIELDS = {
8751
+ /** sha256 of the action and the shape key (or the index name, for `remove`); the row id derives from it. */
8752
+ recKey: field.string(),
8753
+ namespace: field.string(),
8754
+ type: field.string(),
8755
+ action: field.enum(["add", "remove"]),
8756
+ /** The read shape's key (`add`); empty for `remove`. */
8757
+ shape: field.string(),
8758
+ /** The `indexes` entry to add, or `{ drop: <indexName> }`. */
8759
+ declarationJson: field.string({ indexed: false }),
8760
+ /** count, p95Ms, liveRows, writeRatePerMin, window. */
8761
+ evidenceJson: field.string({ indexed: false }),
8762
+ estimatedWriteCost: field.enum([
8763
+ "low",
8764
+ "medium",
8765
+ "high"
8766
+ ]),
8767
+ state: field.enum([
8768
+ "open",
8769
+ "accepted",
8770
+ "dismissed",
8771
+ "superseded"
8772
+ ]),
8773
+ /** The index to drop, for `remove`. */
8774
+ indexName: field.string({ nullable: true })
8775
+ };
8776
+ const AUDIT_EVENT_TYPE = "AuditEvent";
8063
8777
  const KEY_ALGORITHMS = /* @__PURE__ */ new Set([
8064
8778
  "EdDSA",
8065
8779
  "RS256",
@@ -8128,6 +8842,7 @@ function createKeyRegistry(opts) {
8128
8842
  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
8129
8843
  const warn = opts.onWarn ?? (() => void 0);
8130
8844
  let cache = /* @__PURE__ */ new Map();
8845
+ let generation = 0;
8131
8846
  function isLive(record) {
8132
8847
  if (record.revokedAt === null) return true;
8133
8848
  return record.revokedAt.getTime() > now().getTime();
@@ -8161,6 +8876,7 @@ function createKeyRegistry(opts) {
8161
8876
  function installRow(row) {
8162
8877
  const projected = projectRow(row);
8163
8878
  if (projected === null) return false;
8879
+ generation++;
8164
8880
  cache.set(projected.kid, projected);
8165
8881
  return true;
8166
8882
  }
@@ -8168,8 +8884,9 @@ function createKeyRegistry(opts) {
8168
8884
  const reprimeIntervalMs = opts.reprimeIntervalMs;
8169
8885
  if (reprimeIntervalMs !== void 0 && Number.isFinite(reprimeIntervalMs) && reprimeIntervalMs > 0) {
8170
8886
  timer = setInterval(() => {
8887
+ const started = generation;
8171
8888
  loadAll().then((next) => {
8172
- cache = next;
8889
+ if (generation === started) cache = next;
8173
8890
  }).catch((err) => {
8174
8891
  warn("substrate_key_registry_reprime_failed", { error: err instanceof Error ? err.message : String(err) });
8175
8892
  });
@@ -8191,11 +8908,13 @@ function createKeyRegistry(opts) {
8191
8908
  }) ?? void 0;
8192
8909
  if (row === void 0) {
8193
8910
  warn("substrate_key_registry_no_live_row", { kid });
8911
+ generation++;
8194
8912
  cache.delete(kid);
8195
8913
  return;
8196
8914
  }
8197
8915
  if (!installRow(row)) {
8198
8916
  warn("substrate_key_registry_malformed_row", { kid });
8917
+ generation++;
8199
8918
  cache.delete(kid);
8200
8919
  }
8201
8920
  },
@@ -8203,6 +8922,7 @@ function createKeyRegistry(opts) {
8203
8922
  return installRow(row);
8204
8923
  },
8205
8924
  evict(kid) {
8925
+ generation++;
8206
8926
  cache.delete(kid);
8207
8927
  },
8208
8928
  async primeFromDataset() {
@@ -8217,67 +8937,14 @@ function createKeyRegistry(opts) {
8217
8937
  };
8218
8938
  }
8219
8939
 
8220
- //#endregion
8221
- //#region ../../packages/substrate-compose/src/_system/signing-key.ts
8222
- /**
8223
- * Extract the `kid` string from a `where` clause that has exactly the shape
8224
- * `{ id: { eq: <non-empty string> } }`. Any other shape is rejected:
8225
- *
8226
- * - Compound predicates (AND / OR / NOT discriminators) are unsupported and
8227
- * emit `engine_signing_key_unsupported_where` with `reason: 'compound'`.
8228
- * - Extra top-level keys alongside `id` are unsupported and emit the metric
8229
- * with `reason: 'extra_fields'`. Callers who add defence-in-depth filters
8230
- * (e.g. `revokedAt: { eq: null }`) believe they are filtering, but this
8231
- * resolver cannot honour them — surfacing the mismatch explicitly is safer
8232
- * than silently ignoring it.
8233
- * - Everything else (wrong operator, wrong type, missing where) returns null
8234
- * without a metric because those are expected call shapes (e.g. "no filter
8235
- * supplied").
8236
- */
8237
- function extractKid(where, metric) {
8238
- if (where === void 0 || where === null) return null;
8239
- if (typeof where !== "object") return null;
8240
- if ("AND" in where || "OR" in where || "NOT" in where) {
8241
- metric?.("engine_signing_key_unsupported_where", { reason: "compound" });
8242
- return null;
8243
- }
8244
- const keys = Object.keys(where);
8245
- if (keys.length !== 1 || keys[0] !== "id") {
8246
- metric?.("engine_signing_key_unsupported_where", {
8247
- reason: "extra_fields",
8248
- keys
8249
- });
8250
- return null;
8251
- }
8252
- const id = where.id;
8253
- if (id === null || typeof id !== "object") return null;
8254
- const eq = id.eq;
8255
- return typeof eq === "string" && eq.length > 0 ? eq : null;
8256
- }
8257
- function createSigningKeyResolver(registry, opts) {
8258
- const metric = opts?.onMetric;
8259
- return async (_ctx, args) => {
8260
- const kid = extractKid(args.params?.where, metric);
8261
- if (kid === null) return [];
8262
- const record = registry.lookup(kid);
8263
- if (record === null) return [];
8264
- return [{
8265
- id: record.kid,
8266
- publicKey: record.publicKey,
8267
- algorithm: record.algorithm
8268
- }];
8269
- };
8270
- }
8271
-
8272
8940
  //#endregion
8273
8941
  //#region ../../packages/substrate-compose/src/_system/install.ts
8274
8942
  /**
8275
8943
  * `_system` namespace wire-up. Spec §5.12.
8276
8944
  *
8277
- * Registers `Key`, `Invite`, `AuditEvent` and the enum-verdict
8278
- * type with admin-gated autoCRUD, plus the public `SigningKey`
8279
- * projection. Returns a live `KeyRegistry` whose cache is synchronously
8280
- * updated by `Key` create/update/delete/purge.
8945
+ * Registers `Key`, `Invite`, `AuditEvent` and the enum-verdict type with
8946
+ * admin-gated autoCRUD. Returns a live `KeyRegistry` whose cache is
8947
+ * synchronously updated by `Key` create/update/delete/purge.
8281
8948
  *
8282
8949
  * Invalidation strategy: we wrap the `Registry` surface that
8283
8950
  * `installAutoCrud` writes into. The `Key` mutations get their resolver
@@ -8302,6 +8969,10 @@ function createSigningKeyResolver(registry, opts) {
8302
8969
  * (algorithm is a param on the frame, not a property of the identity) and
8303
8970
  * the client deserves a dedicated code to branch on.
8304
8971
  */
8972
+ /** The capability that changes indexes: the store profile and index recommendations. */
8973
+ const INDEX_CAPABILITY = "substrate.index";
8974
+ /** Advisory-lock key held by key writes that can remove an admin. */
8975
+ const KEY_WRITE_LOCK = "substrate-system:key-write";
8305
8976
  /**
8306
8977
  * Wrap a `Registry` so `register` AND `replace` calls for the configured
8307
8978
  * mutation names route their resolver through `wrap(resolver, mutationName)`.
@@ -8399,11 +9070,10 @@ function resolveActorKid(ctx) {
8399
9070
  /**
8400
9071
  * Build the AuditEvent row. Shared between the interceptor emits (which
8401
9072
  * write via `args.dataset` to stay in-tx) and the route emits (which write via
8402
- * the ambient dataset post-tx). `id` is a random UUID.
9073
+ * the ambient dataset post-tx). The dataset assigns the `id`.
8403
9074
  */
8404
9075
  function buildAuditRow(input) {
8405
9076
  return {
8406
- id: randomUUID(),
8407
9077
  ts: input.now.toISOString(),
8408
9078
  actorKid: input.actorKid,
8409
9079
  kind: input.kind,
@@ -8525,9 +9195,29 @@ async function installSystemNamespace(opts) {
8525
9195
  if (opts.onWarn !== void 0) keyRegistryOpts.onWarn = opts.onWarn;
8526
9196
  if (opts.reprimeIntervalMs !== void 0) keyRegistryOpts.reprimeIntervalMs = opts.reprimeIntervalMs;
8527
9197
  const keyRegistry = createKeyRegistry(keyRegistryOpts);
9198
+ const keysFor = async (args) => (await (args.dataset ?? opts.dataset).read("Key", {})).rows;
9199
+ const assertGrantParses = (row) => {
9200
+ const err = grantEntryError(decodeList(row.namespaces), decodeList(row.capabilities));
9201
+ if (err !== null) throw new ResolverFrameError("invalid_grant_entry", `${err} — each entry is '<namespace>' or '<namespace>:<cap>[+<cap>...]'.`);
9202
+ };
9203
+ const assertAdminSurvives = (rows, targetId, next) => {
9204
+ const isAdmin = (r) => isActiveAdminKeyRow(r, adminCapability);
9205
+ const after = [...rows.filter((r) => r.id !== targetId), ...next === null ? [] : [next]];
9206
+ if (rows.some(isAdmin) && !after.some(isAdmin)) throw new ResolverFrameError("last_active_admin", "refusing a key write that would leave no active admin key — rotate instead via `substrate-admin rotate`.");
9207
+ };
9208
+ const localKeyLock = createKeyedMutex();
9209
+ const lockedKeyWrite = (fn) => (ctx, args) => {
9210
+ const ds = args.dataset ?? opts.dataset;
9211
+ const run = () => fn(ctx, args);
9212
+ return ds.withAdvisoryLock !== void 0 ? ds.withAdvisoryLock(KEY_WRITE_LOCK, run) : localKeyLock(KEY_WRITE_LOCK, run);
9213
+ };
9214
+ const isLive = (row) => row !== void 0 && row.revokedAt == null && row._deletedAt == null;
8528
9215
  const wrappedForSubstrateKey = wrapRegistryMutations(opts.registry, {
8529
- createKey: (base) => async (ctx, args) => {
9216
+ createKey: (base) => lockedKeyWrite(async (ctx, args) => {
8530
9217
  assertAllowedAlgorithm(args.params);
9218
+ assertGrantParses(args.params ?? {});
9219
+ const newKid = args.params?.kid;
9220
+ if (isLive(args.params) && (await keysFor(args)).some((r) => r.kid === newKid && isLive(r))) throw new ResolverFrameError("kid_already_live", `kid '${String(newKid)}' is already registered and live — rotate or revoke it before re-registering`);
8531
9221
  const result = await base(ctx, args);
8532
9222
  const kid = extractKidForInvalidation(result);
8533
9223
  if (kid !== null) {
@@ -8547,13 +9237,25 @@ async function installSystemNamespace(opts) {
8547
9237
  installFromResult(keyRegistry, result, kid, opts.onWarn);
8548
9238
  }
8549
9239
  return result;
8550
- },
8551
- updateKey: (base) => async (ctx, args) => {
9240
+ }),
9241
+ updateKey: (base) => lockedKeyWrite(async (ctx, args) => {
8552
9242
  if (args.params?.kid !== void 0) throw new Error("Key.kid is immutable; rotate or re-register instead of changing kid");
8553
9243
  if (args.params?.algorithm !== void 0) assertAllowedAlgorithm(args.params);
9244
+ const params = args.params ?? {};
9245
+ const rows = await keysFor(args);
9246
+ const target = rows.find((r) => r.id === params.id);
9247
+ if (target !== void 0) {
9248
+ const next = {
9249
+ ...target,
9250
+ ...params
9251
+ };
9252
+ if (params.namespaces !== void 0 || params.capabilities !== void 0) assertGrantParses(next);
9253
+ assertAdminSurvives(rows, target.id, next);
9254
+ }
9255
+ const wasLive = isLive(target);
8554
9256
  const result = await base(ctx, args);
8555
9257
  const kid = extractKidForInvalidation(result);
8556
- if (kid !== null) {
9258
+ if (kid !== null && wasLive) {
8557
9259
  const revokedAt = args.params?.revokedAt;
8558
9260
  if (revokedAt !== void 0 && revokedAt !== null && revokedAt !== "") await emitAuditInTx(ctx, args, {
8559
9261
  actorKid: resolveActorKid(ctx),
@@ -8566,19 +9268,21 @@ async function installSystemNamespace(opts) {
8566
9268
  installFromResult(keyRegistry, result, kid, opts.onWarn);
8567
9269
  }
8568
9270
  return result;
8569
- },
8570
- deleteKey: (base) => async (ctx, args) => {
9271
+ }),
9272
+ deleteKey: (base) => lockedKeyWrite(async (ctx, args) => {
8571
9273
  const targetId = typeof args.params?.id === "string" ? args.params.id : void 0;
8572
9274
  let kidToEvict = null;
8573
9275
  if (targetId !== void 0) {
8574
- const { rows } = await (args.dataset ?? opts.dataset).read("Key", { id: targetId });
8575
- kidToEvict = extractKidForInvalidation(rows[0]);
9276
+ const rows = await keysFor(args);
9277
+ const target = rows.find((r) => r.id === targetId);
9278
+ assertAdminSurvives(rows, targetId, null);
9279
+ if (isLive(target)) kidToEvict = extractKidForInvalidation(target);
8576
9280
  }
8577
9281
  const result = await base(ctx, args);
8578
9282
  if (kidToEvict !== null) keyRegistry.evict(kidToEvict);
8579
9283
  return result;
8580
- },
8581
- purgeKey: (base) => async (ctx, args) => {
9284
+ }),
9285
+ purgeKey: (base) => lockedKeyWrite(async (ctx, args) => {
8582
9286
  const targetId = typeof args.params?.id === "string" ? args.params.id : void 0;
8583
9287
  let kidToEvict = null;
8584
9288
  if (targetId !== void 0) {
@@ -8586,7 +9290,8 @@ async function installSystemNamespace(opts) {
8586
9290
  id: targetId,
8587
9291
  includeDeleted: true
8588
9292
  });
8589
- kidToEvict = extractKidForInvalidation(rows[0]);
9293
+ assertAdminSurvives(await keysFor(args), targetId, null);
9294
+ if (isLive(rows[0])) kidToEvict = extractKidForInvalidation(rows[0]);
8590
9295
  }
8591
9296
  try {
8592
9297
  const result = await base(ctx, args);
@@ -8599,7 +9304,7 @@ async function installSystemNamespace(opts) {
8599
9304
  }
8600
9305
  throw err;
8601
9306
  }
8602
- }
9307
+ })
8603
9308
  });
8604
9309
  installAutoCrud(wrappedForSubstrateKey, "Key", opts.dataset, opts.edges, {
8605
9310
  fields: mergeIdField(KEY_FIELDS),
@@ -8669,11 +9374,37 @@ async function installSystemNamespace(opts) {
8669
9374
  purgeable: true,
8670
9375
  adminCapability
8671
9376
  });
8672
- opts.registry.register(SIGNING_KEY_TYPE, {
8673
- resolver: createSigningKeyResolver(keyRegistry, opts.onMetric !== void 0 ? { onMetric: opts.onMetric } : void 0),
8674
- kind: "type",
8675
- policy: allowAll(),
8676
- fields: SIGNING_KEY_FIELDS
9377
+ const indexGate = or(adminGate, and(requireCapability(INDEX_CAPABILITY), requireNamespace(SYSTEM_NAMESPACE)));
9378
+ installAutoCrud(opts.registry, STORE_PROFILE_TYPE, opts.dataset, opts.edges, {
9379
+ fields: mergeIdField(STORE_PROFILE_FIELDS),
9380
+ policy: indexGate,
9381
+ adminCapability
9382
+ });
9383
+ installAutoCrud(opts.registry, INDEX_RECOMMENDATION_TYPE, opts.dataset, opts.edges, {
9384
+ fields: mergeIdField(INDEX_RECOMMENDATION_FIELDS),
9385
+ policy: indexGate,
9386
+ purgeable: true,
9387
+ adminCapability
9388
+ });
9389
+ installAutoCrud(opts.registry, ADVISOR_STATE_TYPE, opts.dataset, opts.edges, {
9390
+ fields: mergeIdField(ADVISOR_STATE_FIELDS),
9391
+ policy: and(adminGate, denyVerbs([
9392
+ "create",
9393
+ "update",
9394
+ "delete"
9395
+ ], "AdvisorState is written by the index advisor only")),
9396
+ adminCapability
9397
+ });
9398
+ await opts.dataset.write(STORE_PROFILE_TYPE, [{
9399
+ id: STORE_PROFILE_ID,
9400
+ profile: opts.storeProfile ?? "personal",
9401
+ updatedReason: opts.storeProfile === void 0 ? "default" : "seeded from SUBSTRATE_STORE_PROFILE"
9402
+ }], {
9403
+ insertOnly: true,
9404
+ identity: {
9405
+ kind: "system",
9406
+ id: "bootstrap"
9407
+ }
8677
9408
  });
8678
9409
  await backfillBootstrapAuditIfNeeded(opts.dataset);
8679
9410
  return { keyRegistry };
@@ -9670,7 +10401,6 @@ function keysRoute(engine, opts) {
9670
10401
  const dirFrameKey = dirPlan === null ? null : `${dirPlan.ns}/create${dirPlan.type}`;
9671
10402
  const frame = { [keyFrameKey]: {
9672
10403
  params: {
9673
- id: randomUUID(),
9674
10404
  kid: b.kid,
9675
10405
  name: b.name,
9676
10406
  algorithm: b.algorithm,
@@ -9697,7 +10427,7 @@ function keysRoute(engine, opts) {
9697
10427
  const keyErr = errorFor(keyFrameKey);
9698
10428
  if (keyErr !== void 0) {
9699
10429
  const code = keyErr.code ?? "internal_error";
9700
- return jsonResponse(code === "policy_denied" ? 403 : 500, {
10430
+ return jsonResponse(code === "policy_denied" ? 403 : code === "kid_already_live" ? 409 : 500, {
9701
10431
  code,
9702
10432
  message: keyErr.message ?? "key registration failed"
9703
10433
  });
@@ -9890,7 +10620,6 @@ function registerRoute(dataset, registry, rateLimiter, opts) {
9890
10620
  message: "invite has expired"
9891
10621
  });
9892
10622
  const kid = base64Url(randomBytes(16));
9893
- const rowId = randomUUID();
9894
10623
  const createdAt = now();
9895
10624
  const inviteNamespacesRaw = invite.namespaces;
9896
10625
  const inviteCapabilitiesRaw = invite.capabilities;
@@ -9906,7 +10635,6 @@ function registerRoute(dataset, registry, rateLimiter, opts) {
9906
10635
  id: kid
9907
10636
  })).matched) throw new RegisterRaceError();
9908
10637
  await tx.write("Key", [{
9909
- id: rowId,
9910
10638
  kid,
9911
10639
  name: body.keyName,
9912
10640
  algorithm: body.algorithm,
@@ -9961,6 +10689,366 @@ var RegisterRaceError = class extends Error {
9961
10689
  }
9962
10690
  };
9963
10691
 
10692
+ //#endregion
10693
+ //#region ../../packages/substrate-compose/src/name-uuid.ts
10694
+ /**
10695
+ * A deterministic row id for `name`: an RFC 9562 version-8 UUID whose custom
10696
+ * bits are the first 122 bits of sha256(name). The same name always yields the
10697
+ * same id, and the id passes the `rows_id_uuid_format` CHECK that
10698
+ * `SUBSTRATE_ENFORCE_UUID_CHECK` installs.
10699
+ */
10700
+ function uuidFromName(name) {
10701
+ const b = createHash("sha256").update(name).digest().subarray(0, 16);
10702
+ b[6] = (b[6] ?? 0) & 15 | 128;
10703
+ b[8] = (b[8] ?? 0) & 63 | 128;
10704
+ const h = b.toString("hex");
10705
+ return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
10706
+ }
10707
+
10708
+ //#endregion
10709
+ //#region ../../packages/substrate-compose/src/advisor/profiles.ts
10710
+ const DAY = 864e5;
10711
+ const PROFILES = {
10712
+ personal: {
10713
+ slowP95Ms: 250,
10714
+ minRows: 1e5,
10715
+ minRowsLargeHint: 1e4,
10716
+ unusedWindowMs: 7 * DAY,
10717
+ minWriteRatePerMin: 100,
10718
+ minReads: 50
10719
+ },
10720
+ growth: {
10721
+ slowP95Ms: 100,
10722
+ minRows: 5e4,
10723
+ minRowsLargeHint: 5e3,
10724
+ unusedWindowMs: 3 * DAY,
10725
+ minWriteRatePerMin: 50,
10726
+ minReads: 30
10727
+ },
10728
+ scale: {
10729
+ slowP95Ms: 50,
10730
+ minRows: 2e4,
10731
+ minRowsLargeHint: 1e3,
10732
+ unusedWindowMs: DAY,
10733
+ minWriteRatePerMin: 20,
10734
+ minReads: 20
10735
+ }
10736
+ };
10737
+ const isStoreProfileName = (v) => typeof v === "string" && Object.hasOwn(PROFILES, v);
10738
+
10739
+ //#endregion
10740
+ //#region ../../packages/substrate-compose/src/advisor/advisor.ts
10741
+ /**
10742
+ * The index advisor's pass: from the read shapes the engine recorded and the
10743
+ * store's own statistics, write `_system/IndexRecommendation` rows. It builds
10744
+ * and drops nothing; a recommendation is applied only by a signed approval.
10745
+ *
10746
+ * - `add`: a conjunctive shape read often enough (`minReads`) is slow (p95 ≥
10747
+ * `slowP95Ms`) on a type with enough live rows, and no index that serves
10748
+ * the type's reads serves it.
10749
+ * - `remove`: an engine-owned, non-unique index the engine no longer wants
10750
+ * (an old default, a retracted declaration) has had no scans for the
10751
+ * profile's window on a type with real write volume. Never a `_base` or
10752
+ * unique index, never one still wanted, so remove and reconcile cannot flap.
10753
+ *
10754
+ * A type `typeStats` does not report is unknown, never empty: no
10755
+ * recommendation is made for it.
10756
+ */
10757
+ const ADVISOR = {
10758
+ kind: "system",
10759
+ id: "index-advisor"
10760
+ };
10761
+ const typeKey = (namespace, type) => JSON.stringify([namespace, type]);
10762
+ const sha256 = (s) => createHash("sha256").update(s).digest("hex");
10763
+ /** A recommendation's identity: `recKey`, and the UUID row id derived from it. */
10764
+ const recIdentity = (name) => ({
10765
+ id: uuidFromName(name),
10766
+ recKey: sha256(name)
10767
+ });
10768
+ function needOf(shape) {
10769
+ const eq = [...new Set(shape.filters.filter((f) => f.op === "eq").map((f) => f.field))];
10770
+ const order = shape.orderBy.filter(([f], i, all) => !(f === "id" && i === all.length - 1));
10771
+ return {
10772
+ eq,
10773
+ literals: shape.literals ?? {},
10774
+ order
10775
+ };
10776
+ }
10777
+ /**
10778
+ * Whether `index` serves `need`: a partial index only when the read `eq`s
10779
+ * each predicate field to its value; then its keys lead with the remaining
10780
+ * equality fields (any order), followed by the order in direction.
10781
+ */
10782
+ function serves(index, need) {
10783
+ const only = Object.entries(index.only ?? {});
10784
+ if (only.some(([f, v]) => !Object.hasOwn(need.literals, f) || need.literals[f] !== v)) return false;
10785
+ const fixed = new Set(only.map(([f]) => f));
10786
+ const eq = need.eq.filter((f) => !fixed.has(f));
10787
+ const head = new Set(index.keys.slice(0, eq.length).map(([f]) => f));
10788
+ if (head.size !== eq.length || eq.some((f) => !head.has(f))) return false;
10789
+ return need.order.every(([f, d], i) => {
10790
+ const k = index.keys[eq.length + i];
10791
+ return k !== void 0 && k[0] === f && k[1] === d;
10792
+ });
10793
+ }
10794
+ /**
10795
+ * Whether `plan` already serves the read shape `key` names (an `add`
10796
+ * recommendation's `shape`), as the advisor's supersede pass decides.
10797
+ * Undefined when the key does not parse.
10798
+ */
10799
+ function planServesShape(plan, key) {
10800
+ const shape = shapeOf(key);
10801
+ if (shape === void 0) return void 0;
10802
+ const need = needOf(shape);
10803
+ return plan.indexes.some((i) => serves(i, need));
10804
+ }
10805
+ /** What an `indexes` entry may key on: a declared scalar or crossRef, or a metadata column. */
10806
+ const declarable = (field, def) => field === "createdAt" || field === "updatedAt" || def?.kind === "crossRef" || def?.kind === "scalar" && def.type !== "json";
10807
+ /** The shape a `shapeKey` names, or undefined when it does not parse. */
10808
+ function shapeOf(key) {
10809
+ try {
10810
+ const [namespace, type, filters, orderBy, disjunctive, literals] = JSON.parse(key);
10811
+ return {
10812
+ namespace,
10813
+ type,
10814
+ filters: filters.map((f) => {
10815
+ const at = f.lastIndexOf(" ");
10816
+ return {
10817
+ field: f.slice(0, at),
10818
+ op: f.slice(at + 1)
10819
+ };
10820
+ }),
10821
+ orderBy,
10822
+ ...disjunctive === true ? { disjunctive: true } : {},
10823
+ ...literals !== void 0 && literals.length > 0 ? { literals: Object.fromEntries(literals) } : {}
10824
+ };
10825
+ } catch {
10826
+ return;
10827
+ }
10828
+ }
10829
+ function writeCost(rate, t) {
10830
+ if (rate === void 0 || rate < t.minWriteRatePerMin) return "low";
10831
+ return rate < 10 * t.minWriteRatePerMin ? "medium" : "high";
10832
+ }
10833
+ async function readState(system) {
10834
+ const { rows } = await system.read(ADVISOR_STATE_TYPE, { id: ADVISOR_STATE_ID });
10835
+ try {
10836
+ return JSON.parse(String(rows[0]?.stateJson ?? "null")) ?? void 0;
10837
+ } catch {
10838
+ return;
10839
+ }
10840
+ }
10841
+ /**
10842
+ * One row per `recKey`, whose UUID is its id: inserted `open`; or, when it
10843
+ * exists, its evidence refreshed while `open`, or reopened when `superseded`
10844
+ * (the evidence is back). Each step is atomic, so advisors on one store
10845
+ * converge on one row and never reopen an accepted or dismissed one.
10846
+ */
10847
+ async function upsert(system, row, at) {
10848
+ if ((await system.write("IndexRecommendation", [{
10849
+ ...row,
10850
+ state: "open"
10851
+ }], {
10852
+ insertOnly: true,
10853
+ identity: ADVISOR,
10854
+ now: at
10855
+ })).ids.length > 0) return true;
10856
+ const { id, ...refresh } = row;
10857
+ if ((await system.conditionalUpdate("IndexRecommendation", id, { state: "open" }, refresh, ADVISOR, at)).matched) return true;
10858
+ return (await system.conditionalUpdate(INDEX_RECOMMENDATION_TYPE, id, { state: "superseded" }, {
10859
+ ...refresh,
10860
+ state: "open"
10861
+ }, ADVISOR, at)).matched;
10862
+ }
10863
+ async function runAdvisorPass(deps) {
10864
+ const { dataset, system, recorder } = deps;
10865
+ const now = deps.now();
10866
+ const at = new Date(now);
10867
+ const windowMs = now - recorder.since;
10868
+ const shapes = recorder.drain();
10869
+ if (dataset.typeStats === void 0 || dataset.indexPlan === void 0) return { upserted: 0 };
10870
+ const { rows: profiles } = await system.read(STORE_PROFILE_TYPE, { id: STORE_PROFILE_ID });
10871
+ const profile = profiles[0]?.profile;
10872
+ const base = PROFILES[isStoreProfileName(profile) ? profile : "personal"];
10873
+ const t = deps.writeHeavy ? {
10874
+ ...base,
10875
+ minWriteRatePerMin: base.minWriteRatePerMin / 2
10876
+ } : base;
10877
+ const prior = await readState(system);
10878
+ const state = {
10879
+ epoch: prior?.epoch ?? now,
10880
+ types: {},
10881
+ indexes: {}
10882
+ };
10883
+ const stats = /* @__PURE__ */ new Map();
10884
+ for (const s of await dataset.typeStats()) stats.set(typeKey(s.namespace, s.type), s);
10885
+ const plans = /* @__PURE__ */ new Map();
10886
+ const planOf = (namespace, type) => {
10887
+ const key = typeKey(namespace, type);
10888
+ let plan = plans.get(key);
10889
+ if (plan === void 0) {
10890
+ plan = dataset.indexPlan.call(dataset, type, namespace);
10891
+ plans.set(key, plan);
10892
+ }
10893
+ return plan;
10894
+ };
10895
+ const rates = /* @__PURE__ */ new Map();
10896
+ for (const [key, s] of stats) {
10897
+ const cur = {
10898
+ ins: s.insertsTotal,
10899
+ upd: s.updatesTotal,
10900
+ del: s.deletesTotal,
10901
+ at: now
10902
+ };
10903
+ const base = prior?.types[key];
10904
+ const seenOf = (name) => prior?.indexes[`${key}\0${name}`];
10905
+ const restarted = base !== void 0 && (cur.ins < base.ins || cur.upd < base.upd || cur.del < base.del || s.indexes.some((i) => {
10906
+ const seen = seenOf(i.name);
10907
+ return seen !== void 0 && (i.scans < seen.scans || seen.scanned && i.lastScanAt === null);
10908
+ }));
10909
+ if (base === void 0 || restarted) state.types[key] = cur;
10910
+ else {
10911
+ state.types[key] = base;
10912
+ if (now > base.at) {
10913
+ const writes = cur.ins - base.ins + (cur.upd - base.upd) + (cur.del - base.del);
10914
+ rates.set(key, writes * 6e4 / (now - base.at));
10915
+ }
10916
+ }
10917
+ for (const i of s.indexes) {
10918
+ if (!i.engineOwned) continue;
10919
+ const seen = seenOf(i.name);
10920
+ state.indexes[`${key}\0${i.name}`] = {
10921
+ seen: seen === void 0 || restarted ? now : seen.seen,
10922
+ scans: i.scans,
10923
+ scanned: i.lastScanAt !== null
10924
+ };
10925
+ }
10926
+ }
10927
+ for (const [key, base] of Object.entries(prior?.types ?? {})) {
10928
+ if (stats.has(key)) continue;
10929
+ const [namespace, type] = JSON.parse(key);
10930
+ if (await planOf(namespace, type) === void 0) continue;
10931
+ state.types[key] = base;
10932
+ for (const [k, seen] of Object.entries(prior?.indexes ?? {})) if (k.startsWith(`${key}\0`)) state.indexes[k] = seen;
10933
+ }
10934
+ let upserted = 0;
10935
+ for (const { shape, count, p95Ms } of shapes) {
10936
+ const rec = await addFor(shape, count, p95Ms);
10937
+ if (rec !== void 0 && await upsert(system, rec, at)) upserted++;
10938
+ }
10939
+ for (const [key, s] of stats) {
10940
+ const plan = await planOf(s.namespace, s.type);
10941
+ if (plan === void 0) continue;
10942
+ const desired = new Set(plan.indexes.map((i) => i.name));
10943
+ const rate = rates.get(key);
10944
+ for (const i of s.indexes) {
10945
+ if (!i.engineOwned || i.unique || desired.has(i.name) || i.name.endsWith("_base")) continue;
10946
+ const since = state.indexes[`${key}\0${i.name}`]?.seen ?? now;
10947
+ const lastScan = i.lastScanAt === null ? void 0 : Date.parse(i.lastScanAt);
10948
+ if (lastScan !== void 0 && now - lastScan < t.unusedWindowMs) continue;
10949
+ if (now - since < t.unusedWindowMs) continue;
10950
+ if (rate === void 0 || rate < t.minWriteRatePerMin) continue;
10951
+ if (await upsert(system, {
10952
+ ...recIdentity(`remove${i.name}`),
10953
+ namespace: s.namespace,
10954
+ type: s.type,
10955
+ action: "remove",
10956
+ shape: "",
10957
+ indexName: i.name,
10958
+ declarationJson: JSON.stringify({ drop: i.name }),
10959
+ evidenceJson: JSON.stringify({
10960
+ scans: i.scans,
10961
+ lastScanAt: i.lastScanAt,
10962
+ sizeBytes: i.sizeBytes,
10963
+ liveRows: s.liveRows,
10964
+ writeRatePerMin: rate,
10965
+ window: t.unusedWindowMs
10966
+ }),
10967
+ estimatedWriteCost: writeCost(rate, t)
10968
+ }, at)) upserted++;
10969
+ }
10970
+ }
10971
+ await supersede();
10972
+ await system.write(ADVISOR_STATE_TYPE, [{
10973
+ id: ADVISOR_STATE_ID,
10974
+ stateJson: JSON.stringify(state)
10975
+ }], {
10976
+ identity: ADVISOR,
10977
+ now: at
10978
+ });
10979
+ return { upserted };
10980
+ /** Open recommendations the store no longer needs: a shape now served, an index gone or wanted again. */
10981
+ async function supersede() {
10982
+ const { rows } = await system.read(INDEX_RECOMMENDATION_TYPE, { where: { state: { eq: "open" } } });
10983
+ for (const row of rows) {
10984
+ const namespace = String(row.namespace);
10985
+ const type = String(row.type);
10986
+ const s = stats.get(typeKey(namespace, type));
10987
+ const plan = s === void 0 ? void 0 : await planOf(namespace, type);
10988
+ if (s === void 0 || plan === void 0) continue;
10989
+ let done = false;
10990
+ if (row.action === "add") {
10991
+ const served = planServesShape(plan, String(row.shape));
10992
+ if (served === void 0) continue;
10993
+ done = served;
10994
+ } else if (row.action === "remove") {
10995
+ const name = String(row.indexName);
10996
+ done = !s.indexes.some((i) => i.name === name) || plan.indexes.some((i) => i.name === name);
10997
+ }
10998
+ if (done) await system.conditionalUpdate(INDEX_RECOMMENDATION_TYPE, row.id, { state: "open" }, { state: "superseded" }, ADVISOR, at);
10999
+ }
11000
+ }
11001
+ async function addFor(shape, count, p95Ms) {
11002
+ if (count < t.minReads || p95Ms < t.slowP95Ms) return void 0;
11003
+ if (shape.disjunctive === true) return void 0;
11004
+ if (shape.filters.some((f) => getExtensionOperator(f.op) !== void 0)) return void 0;
11005
+ const key = typeKey(shape.namespace, shape.type);
11006
+ const s = stats.get(key);
11007
+ if (s === void 0) return void 0;
11008
+ const plan = await planOf(shape.namespace, shape.type);
11009
+ if (plan === void 0) return void 0;
11010
+ const min = plan.expectedSize === "large" ? t.minRowsLargeHint : t.minRows;
11011
+ if (s.liveRows < min) return void 0;
11012
+ const need = needOf(shape);
11013
+ if (plan.indexes.some((i) => serves(i, need))) return void 0;
11014
+ const entry = deps.registry(shape.namespace)?.get(shape.type);
11015
+ const fields = entry?.kind === "type" ? entry.fields : {};
11016
+ const declEq = need.eq.filter((f) => declarable(f, fields[f]));
11017
+ const stop = need.order.findIndex(([f]) => !declarable(f, fields[f]));
11018
+ const declOrder = stop === -1 ? need.order : need.order.slice(0, stop);
11019
+ if (declEq.length + declOrder.length === 0) return void 0;
11020
+ const declNeed = {
11021
+ eq: declEq,
11022
+ literals: need.literals,
11023
+ order: declOrder
11024
+ };
11025
+ if (plan.indexes.some((i) => serves(i, declNeed))) return void 0;
11026
+ const declaration = { fields: [...declEq, ...declOrder.map(([field, dir]) => ({
11027
+ field,
11028
+ dir
11029
+ }))] };
11030
+ const rate = rates.get(key);
11031
+ const sk = shapeKey(shape);
11032
+ return {
11033
+ ...recIdentity(`add${sk}`),
11034
+ namespace: shape.namespace,
11035
+ type: shape.type,
11036
+ action: "add",
11037
+ shape: sk,
11038
+ indexName: null,
11039
+ declarationJson: JSON.stringify(declaration),
11040
+ evidenceJson: JSON.stringify({
11041
+ count,
11042
+ p95Ms,
11043
+ liveRows: s.liveRows,
11044
+ writeRatePerMin: rate ?? null,
11045
+ window: windowMs
11046
+ }),
11047
+ estimatedWriteCost: writeCost(rate, t)
11048
+ };
11049
+ }
11050
+ }
11051
+
9964
11052
  //#endregion
9965
11053
  //#region ../../packages/substrate-dataset-memory/src/memory-short-id-store.ts
9966
11054
  const EMPTY_BY_ROW = /* @__PURE__ */ new Map();
@@ -10095,6 +11183,38 @@ var MemoryShortIdStore = class {
10095
11183
  }
10096
11184
  };
10097
11185
 
11186
+ //#endregion
11187
+ //#region ../../packages/substrate-dataset-memory/src/uuidv7.ts
11188
+ let lastMs = -1;
11189
+ let counter = 0;
11190
+ /**
11191
+ * An RFC 9562 version-7 UUID: 48-bit unix milliseconds, then a 12-bit counter
11192
+ * in `rand_a`, then 62 random bits. Ids from one process sort in creation
11193
+ * order: the counter steps within a millisecond, and on overflow or a clock
11194
+ * step backwards the timestamp advances past the last one issued.
11195
+ *
11196
+ * Limits: the order holds only within this process, so it is never a
11197
+ * happened-before signal across writers; the id reveals its creation time; and
11198
+ * deciding who won uses a transaction time or a per-row version, never the id.
11199
+ */
11200
+ function uuidv7() {
11201
+ const now = Date.now();
11202
+ if (now > lastMs) {
11203
+ lastMs = now;
11204
+ counter = randomBytes(2).readUInt16BE(0) & 2047;
11205
+ } else if (++counter > 4095) {
11206
+ lastMs++;
11207
+ counter = 0;
11208
+ }
11209
+ const b = randomBytes(16);
11210
+ b.writeUIntBE(lastMs, 0, 6);
11211
+ b[6] = 112 | counter >> 8;
11212
+ b[7] = counter & 255;
11213
+ b[8] = b.readUInt8(8) & 63 | 128;
11214
+ const h = b.toString("hex");
11215
+ return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
11216
+ }
11217
+
10098
11218
  //#endregion
10099
11219
  //#region ../../packages/substrate-dataset-memory/src/memory-dataset.ts
10100
11220
  /**
@@ -10110,8 +11230,7 @@ var MemoryShortIdStore = class {
10110
11230
  *
10111
11231
  * Filter contract (§5.2): `read()` honours `where` + `orderBy` + `cursor` in
10112
11232
  * addition to the id/ids/includeDeleted/limit short-circuit. Filter evaluation
10113
- * is in-memory; there's no indexing, so the validator (upstream, in the
10114
- * engine) is what gates unindexed-field scans.
11233
+ * is in-memory; there's no indexing, so every filter is a scan.
10115
11234
  */
10116
11235
  const RESERVED_DELETED_AT = "_deletedAt";
10117
11236
  /**
@@ -10121,17 +11240,27 @@ const RESERVED_DELETED_AT = "_deletedAt";
10121
11240
  * existing when incoming is null.
10122
11241
  */
10123
11242
  function mergeRowMetadata(existing, incoming) {
10124
- if (existing === void 0) return incoming;
11243
+ if (existing === void 0) return withoutSeq(incoming);
10125
11244
  return {
10126
11245
  createdAt: existing.createdAt ?? incoming.createdAt,
10127
11246
  updatedAt: incoming.updatedAt ?? existing.updatedAt,
10128
11247
  createdBy: existing.createdBy ?? incoming.createdBy,
10129
- updatedBy: incoming.updatedBy ?? existing.updatedBy
11248
+ updatedBy: incoming.updatedBy ?? existing.updatedBy,
11249
+ ...existing.seq !== void 0 ? { seq: existing.seq } : {}
10130
11250
  };
10131
11251
  }
11252
+ function withoutSeq(meta) {
11253
+ if (meta.seq === void 0) return meta;
11254
+ const { seq: _seq, ...rest } = meta;
11255
+ return rest;
11256
+ }
10132
11257
  var MemoryDataset = class MemoryDataset {
10133
11258
  namespace;
10134
11259
  txScopeId;
11260
+ #fieldDefLookup;
11261
+ typeDefLookup;
11262
+ /** Last seq assigned per visible-order type; never decreases, as pg's `visible_seqs`. */
11263
+ seqs = /* @__PURE__ */ new Map();
10135
11264
  capabilities = {
10136
11265
  operators: fullBuiltinOperators(),
10137
11266
  orderBy: true,
@@ -10150,6 +11279,8 @@ var MemoryDataset = class MemoryDataset {
10150
11279
  constructor(options) {
10151
11280
  this.namespace = options.namespace;
10152
11281
  this.txScopeId = options.txScopeId ?? `mem:${randomUUID()}`;
11282
+ this.#fieldDefLookup = options.fieldDefLookup;
11283
+ this.typeDefLookup = options.typeDefLookup;
10153
11284
  }
10154
11285
  bucket(type) {
10155
11286
  let b = this.store.get(type);
@@ -10167,6 +11298,8 @@ var MemoryDataset = class MemoryDataset {
10167
11298
  hasMore: false
10168
11299
  };
10169
11300
  const includeDeleted = params.includeDeleted === true;
11301
+ const lookup = this.#fieldDefLookup;
11302
+ const fieldDefOf = (field) => lookup?.(type, field);
10170
11303
  const idFilter = /* @__PURE__ */ new Set();
10171
11304
  let hasIdFilter = false;
10172
11305
  if (params.id !== void 0) {
@@ -10199,15 +11332,15 @@ var MemoryDataset = class MemoryDataset {
10199
11332
  })() : b.values();
10200
11333
  for (const row of candidates) {
10201
11334
  if (!includeDeleted && row._deletedAt != null) continue;
10202
- if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere)) continue;
11335
+ if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere, fieldDefOf)) continue;
10203
11336
  pool.push(row);
10204
11337
  }
10205
11338
  const orderBy = normalizeOrderBy(params.orderBy);
10206
- pool.sort((a, b2) => compareByClauses(a, b2, orderBy));
11339
+ pool.sort((a, b2) => compareByClauses(a, b2, orderBy, fieldDefOf));
10207
11340
  let startIdx = 0;
10208
11341
  if (params.cursor !== void 0 && params.cursor !== "") {
10209
- const cursor = decodeCursor(params.cursor);
10210
- startIdx = findCursorStart(pool, orderBy, cursor.orderByValues, cursor.id);
11342
+ const cursor = decodeCursor(params.cursor, orderBy);
11343
+ startIdx = findCursorStart(pool, orderBy, cursor.orderByValues, cursor.id, fieldDefOf);
10211
11344
  }
10212
11345
  let hasMore = false;
10213
11346
  let slice;
@@ -10226,7 +11359,8 @@ var MemoryDataset = class MemoryDataset {
10226
11359
  const last = slice[slice.length - 1];
10227
11360
  if (hasMore && last !== void 0) out.nextCursor = encodeCursor({
10228
11361
  orderByValues: orderBy.map(([field]) => getFieldValue(last, field)),
10229
- id: last.id
11362
+ id: last.id,
11363
+ order: orderBy
10230
11364
  });
10231
11365
  if (extMeta !== null) out.rows = applyExtensionResultMeta(out.rows, extMeta, {
10232
11366
  hasExplicitOrderBy: params.orderBy !== void 0 && params.orderBy.length > 0,
@@ -10235,13 +11369,18 @@ var MemoryDataset = class MemoryDataset {
10235
11369
  return out;
10236
11370
  }
10237
11371
  async write(type, rows, options) {
11372
+ if (options?.insertOnly !== true) assertNoRepeatedIds(type, rows);
10238
11373
  const b = this.bucket(type);
10239
11374
  const ids = [];
10240
11375
  const merged = [];
10241
11376
  const fallbackNow = (options?.now ?? /* @__PURE__ */ new Date()).toISOString();
10242
11377
  const fallbackActor = options?.identity ?? null;
10243
- for (const row of rows) {
10244
- if (row.id === void 0 || row.id === null) throw new Error(`write: row.id is required (type='${type}')`);
11378
+ const visible = this.typeDefLookup?.(type, this.namespace)?.ordering === "visible";
11379
+ for (const input of rows) {
11380
+ const row = {
11381
+ ...input,
11382
+ id: input.id ?? uuidv7()
11383
+ };
10245
11384
  let rowToWrite = row;
10246
11385
  if (row._metadata === void 0) {
10247
11386
  const autoMeta = {
@@ -10278,6 +11417,16 @@ var MemoryDataset = class MemoryDataset {
10278
11417
  b.set(rowToWrite.id, landed);
10279
11418
  } else {
10280
11419
  landed = sanitised;
11420
+ const meta = landed._metadata;
11421
+ if (meta !== void 0) landed._metadata = withoutSeq(meta);
11422
+ if (visible) {
11423
+ const seq = (this.seqs.get(type) ?? 0) + 1;
11424
+ this.seqs.set(type, seq);
11425
+ landed._metadata = {
11426
+ ...landed._metadata,
11427
+ seq
11428
+ };
11429
+ }
10281
11430
  b.set(rowToWrite.id, landed);
10282
11431
  }
10283
11432
  ids.push(row.id);
@@ -10388,7 +11537,8 @@ var MemoryDataset = class MemoryDataset {
10388
11537
  createdAt: prior?.createdAt ?? null,
10389
11538
  createdBy: prior?.createdBy ?? null,
10390
11539
  updatedAt: (now ?? /* @__PURE__ */ new Date()).toISOString(),
10391
- updatedBy
11540
+ updatedBy,
11541
+ ...prior?.seq !== void 0 ? { seq: prior.seq } : {}
10392
11542
  };
10393
11543
  return {
10394
11544
  matched: true,
@@ -10402,7 +11552,20 @@ var MemoryDataset = class MemoryDataset {
10402
11552
  if (!b) return;
10403
11553
  const row = b.get(ref.id);
10404
11554
  if (!row) return;
11555
+ const seq = row._metadata?.seq;
10405
11556
  row[fieldName] = value;
11557
+ if (fieldName === "_metadata" && (value != null || seq !== void 0)) {
11558
+ const meta = withoutSeq(value ?? {
11559
+ createdAt: null,
11560
+ updatedAt: null,
11561
+ createdBy: null,
11562
+ updatedBy: null
11563
+ });
11564
+ row._metadata = seq !== void 0 ? {
11565
+ ...meta,
11566
+ seq
11567
+ } : meta;
11568
+ }
10406
11569
  }
10407
11570
  /**
10408
11571
  * Snapshot-and-restore atomicity. Spec §5.3 / G1.
@@ -10424,6 +11587,7 @@ var MemoryDataset = class MemoryDataset {
10424
11587
  for (const [id, r] of bucket.entries()) cloned.set(id, { ...r });
10425
11588
  snapshot.set(type, cloned);
10426
11589
  }
11590
+ const seqSnapshot = new Map(this.seqs);
10427
11591
  const undoLog = [];
10428
11592
  const dropUndoLog = [];
10429
11593
  this.#inTx = true;
@@ -10433,6 +11597,7 @@ var MemoryDataset = class MemoryDataset {
10433
11597
  return await fn(this);
10434
11598
  } catch (err) {
10435
11599
  this.store = snapshot;
11600
+ this.seqs = seqSnapshot;
10436
11601
  for (let i = dropUndoLog.length - 1; i >= 0; i--) {
10437
11602
  const entry = dropUndoLog[i];
10438
11603
  if (entry !== void 0) this.shortIds._restoreBucket(this.namespace, entry.type, entry.snapshot);
@@ -10468,7 +11633,11 @@ var MemoryDataset = class MemoryDataset {
10468
11633
  return this.shortIds.getShortIdForRow(this.namespace, type, rowId);
10469
11634
  }
10470
11635
  forNamespace(namespace) {
10471
- return new MemoryDataset({ namespace });
11636
+ return new MemoryDataset({
11637
+ namespace,
11638
+ ...this.#fieldDefLookup !== void 0 ? { fieldDefLookup: this.#fieldDefLookup } : {},
11639
+ ...this.typeDefLookup !== void 0 ? { typeDefLookup: this.typeDefLookup } : {}
11640
+ });
10472
11641
  }
10473
11642
  };
10474
11643
  /**
@@ -10486,20 +11655,6 @@ function conditionalMatchEq(actual, expected) {
10486
11655
  }
10487
11656
  return actual === expected;
10488
11657
  }
10489
- function compare(a, b) {
10490
- if (a == null && b == null) return 0;
10491
- if (a == null) return 1;
10492
- if (b == null) return -1;
10493
- if (a instanceof Date || b instanceof Date) {
10494
- const at = a instanceof Date ? a.getTime() : typeof a === "string" ? Date.parse(a) : Number(a);
10495
- const bt = b instanceof Date ? b.getTime() : typeof b === "string" ? Date.parse(b) : Number(b);
10496
- return at < bt ? -1 : at > bt ? 1 : 0;
10497
- }
10498
- if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
10499
- const as = String(a);
10500
- const bs = String(b);
10501
- return as < bs ? -1 : as > bs ? 1 : 0;
10502
- }
10503
11658
  function normalizeOrderBy(orderBy) {
10504
11659
  const out = [];
10505
11660
  let hasIdTail = false;
@@ -10513,19 +11668,19 @@ function normalizeOrderBy(orderBy) {
10513
11668
  if (!hasIdTail) out.push(["id", "asc"]);
10514
11669
  return out;
10515
11670
  }
10516
- function compareByClauses(a, b, orderBy) {
11671
+ function compareByClauses(a, b, orderBy, fieldDefOf) {
10517
11672
  for (const [field, dir] of orderBy) {
10518
- const av = getFieldValue(a, field);
10519
- const bv = getFieldValue(b, field);
11673
+ const av = asSortValue(field, getFieldValue(a, field), fieldDefOf);
11674
+ const bv = asSortValue(field, getFieldValue(b, field), fieldDefOf);
10520
11675
  if (av == null && bv == null) continue;
10521
11676
  if (av == null) return 1;
10522
11677
  if (bv == null) return -1;
10523
- const cmp = compare(av, bv);
11678
+ const cmp = compareFilterValues(av, bv, isDateField(field, fieldDefOf));
10524
11679
  if (cmp !== 0) return dir === "asc" ? cmp : -cmp;
10525
11680
  }
10526
11681
  return 0;
10527
11682
  }
10528
- function findCursorStart(pool, orderBy, cursorValues, cursorId) {
11683
+ function findCursorStart(pool, orderBy, cursorValues, cursorId, fieldDefOf) {
10529
11684
  const cursorRow = { id: cursorId };
10530
11685
  const meta = {};
10531
11686
  const createdBy = {};
@@ -10533,7 +11688,7 @@ function findCursorStart(pool, orderBy, cursorValues, cursorId) {
10533
11688
  orderBy.forEach(([field], i) => {
10534
11689
  const v = cursorValues[i];
10535
11690
  if (field === "id") return;
10536
- if (field === "createdAt" || field === "updatedAt") meta[field] = v;
11691
+ if (field === "createdAt" || field === "updatedAt" || field === "seq") meta[field] = v;
10537
11692
  else if (field === "createdById") createdBy.id = v;
10538
11693
  else if (field === "createdByKind") createdBy.kind = v;
10539
11694
  else if (field === "updatedById") updatedBy.id = v;
@@ -10546,7 +11701,7 @@ function findCursorStart(pool, orderBy, cursorValues, cursorId) {
10546
11701
  for (let i = 0; i < pool.length; i++) {
10547
11702
  const row = pool[i];
10548
11703
  if (row === void 0) continue;
10549
- if (compareByClauses(row, cursorRow, orderBy) > 0) return i;
11704
+ if (compareByClauses(row, cursorRow, orderBy, fieldDefOf) > 0) return i;
10550
11705
  }
10551
11706
  return pool.length;
10552
11707
  }
@@ -10885,7 +12040,10 @@ function resolveBootGuards(opts) {
10885
12040
  *
10886
12041
  * Scope is data-only: substrate rows, short-ids and (optionally) edges.
10887
12042
  * Schema declarations are not affected — a type still declared in
10888
- * code/proposals reappears on next compose boot.
12043
+ * code/proposals reappears on next compose boot. A committed namespace drop
12044
+ * also drops the namespace's non-unique engine indexes, and its unique ones
12045
+ * when the namespace is declared nowhere (`Dataset.dropNamespaceIndexes`); a
12046
+ * type drop keeps its type's, since the type stays registered.
10889
12047
  */
10890
12048
  const SAMPLE_EDGE_LIMIT = 5;
10891
12049
  const DANGLING_COUNT_CAP = 1e4;
@@ -11167,7 +12325,15 @@ function dropNamespaceRoute(deps) {
11167
12325
  } catch (err) {
11168
12326
  warnings.push(`drop participant for ${participant.namespaces.join(", ")} failed after the drop committed: ${err instanceof Error ? err.message : String(err)}`);
11169
12327
  }
11170
- if (!dryRun) deps.engine.tombstoneNamespace(namespace);
12328
+ if (!dryRun) {
12329
+ deps.engine.tombstoneNamespace(namespace);
12330
+ const declared = deps.declaredInCode?.(namespace) !== false || warnings.length > 0;
12331
+ try {
12332
+ await dataset.dropNamespaceIndexes?.({ unique: !declared });
12333
+ } catch (err) {
12334
+ warnings.push(`indexes of '${namespace}' were not all dropped after the drop committed: ${err instanceof Error ? err.message : String(err)}; storage doctor lists the rest as orphaned`);
12335
+ }
12336
+ }
11171
12337
  return jsonResponse(200, {
11172
12338
  namespace,
11173
12339
  dryRun,
@@ -11280,9 +12446,17 @@ function handleConfigRequest(report) {
11280
12446
  * Route handler factory. Pass to `gate(configRouteHandler(report), 'admin')`
11281
12447
  * in compose so it inherits the same treatment as `/substrate/v1/_system/invites`.
11282
12448
  */
11283
- function configRouteHandler(report) {
11284
- return (_req) => jsonResponse(200, handleConfigRequest(report));
12449
+ function configRouteHandler(report, storage) {
12450
+ return async (_req) => jsonResponse(200, {
12451
+ ...handleConfigRequest(report),
12452
+ ...storage !== void 0 ? { storage: await storage().catch(failed) } : {}
12453
+ });
11285
12454
  }
12455
+ /** A catalog error costs the storage section, never the knobs beside it. */
12456
+ const failed = (err) => ({
12457
+ layout: "unknown",
12458
+ warnings: [`storage report failed: ${err instanceof Error ? err.message : String(err)}`]
12459
+ });
11286
12460
 
11287
12461
  //#endregion
11288
12462
  //#region ../../packages/substrate-compose/src/routes/connection-limit.ts
@@ -11519,7 +12693,7 @@ const WS_INSTRUCTIONS = {
11519
12693
  notes: [
11520
12694
  "ops are `subscribe` | `stream` | `cancel` | `whoami` — any other `op`, and any frame missing a string `id`, is refused with { id:\"\", kind:\"error\", errors:[{ code:\"invalid_frame\" }] }",
11521
12695
  "server replies { id, kind:\"snapshot\", data:{ \"<ns>/<TypeName>\": rows }, shapes } immediately, then pushes kind:\"add\" | \"update\" | \"remove\" (a remove carries `removedId`, no `data`)",
11522
- "PARAMS ARE NARROWER THAN QUERY: subscribe accepts only `where`, `orderBy` and `_allowTableScan`. `limit` is a POST /substrate/v1/query param and is refused here with code `unknown_param` — the allowlist is in the message",
12696
+ "PARAMS ARE NARROWER THAN QUERY: subscribe accepts only `where` and `orderBy`. `limit` is a POST /substrate/v1/query param and is refused here with code `unknown_param` — the allowlist is in the message",
11523
12697
  "multi-key subscribe IS supported (unlike stream); one socket multiplexes many sessions, keyed by your `id`",
11524
12698
  "cancel with { id, op:\"cancel\" } — the server acknowledges a cancelled SUBSCRIBE with { id, kind:\"end\", final:true }",
11525
12699
  "`{ id, op:\"whoami\" }` answers { id, kind:\"whoami\", data:{ authEnabled, identity } } without opening a session — ask it on the socket rather than over HTTP when the socket is what you are asking about",
@@ -11565,6 +12739,18 @@ const WS_INSTRUCTIONS = {
11565
12739
  ]
11566
12740
  }
11567
12741
  };
12742
+ const CODE_MODE_INSTRUCTIONS = {
12743
+ command: "substrate run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]",
12744
+ summary: "For an agent with a shell: run a TypeScript script whose default export receives a signed client, so many reads and writes cost one call and return one small JSON report. It composes the operations above; it adds none, and every call meets the same grants and policy.",
12745
+ when: "a count or census over many rows, a join across types, recall followed by fetching the bodies of the hits worth reading, or a batch of writes chosen by what a read found. One lookup or one write is simpler as a direct query or mutate",
12746
+ context: "the default export gets `s` with `args`, `query(frame)`, `queryAll(key, { params, fields })`, `recall({ query, namespace, type, ... })`, `mutate(payload)` and `log(...)`; return a reduced result (counts, ids, a verdict), not whole rows",
12747
+ notes: [
12748
+ "signs from SUBSTRATE_URL, SUBSTRATE_AGENT_KEY_ID and SUBSTRATE_AGENT_KEY_PATH, and refuses to run unsigned",
12749
+ "read-only by default: `mutate` throws unless `--dry-run` (records each payload and sends nothing) or `--write` (sends up to `--max-writes` frames, default 50). Dry-run first, read the recorded mutations, then write",
12750
+ "a frame the server rejected fails the run with its error rather than reading as empty; a truncated `query` is reported in `warnings`, and `queryAll` pages to the end",
12751
+ "stdout is one report `{ ok, kid, mode, args, result, error?, mutations, warnings, stats }`; `mutations` lists every payload with `applied`, including those sent before a failure. Exit codes: 0 ok, 1 the script failed, 2 usage or configuration"
12752
+ ]
12753
+ };
11568
12754
  const AUTH_INSTRUCTIONS = {
11569
12755
  summary: "Bearer-JWT auth (§5.12). Present `Authorization: Bearer <jwt>` on every request, onboard included. Only /health, /substrate/v1/whoami and /substrate/v1/_system/register answer without one. Two paths to a token: (a) the invite→register exchange for a namespace-scoped JWT, or (b) a pre-registered per-principal key you sign with directly (the agent-identity path — see `identity`). How a MISSING token is treated depends on `mode`.",
11570
12756
  modes: {
@@ -11608,8 +12794,8 @@ function buildFrameGrammar(coordinators) {
11608
12794
  return {
11609
12795
  queryKey: "<ns>/<TypeName>",
11610
12796
  mutationKey: "<ns>/<mutationName>",
11611
- batched: "A mutate op-key MAY carry an Array<FrameEntry>. All frames under one op-key run serially inside the same transaction (all-or-nothing per op-key). Cross-op-key atomicity is not a goal — each op-key commits independently. Query/subscribe/stream op-keys reject array values.",
11612
- example: `{ "${exampleNs}/Todo": { "params": {"status": "open"}, "fields": {"id": true, "title": true} }, "${exampleNs}/createTodo": [{ "params": {"title": "first"}, "fields": {"id": true} }, { "params": {"title": "second"}, "fields": {"id": true} }] }`
12797
+ batched: "A mutate op-key MAY carry an Array<FrameEntry>. All frames under one array op-key run serially inside the same transaction (all-or-nothing per op-key), and each array op-key commits independently of every other op-key. The single-frame op-keys of one call share their own transaction: if any of them is refused, all of them roll back with `frame_rolled_back`. Query/subscribe/stream op-keys reject array values.",
12798
+ example: `{ "${exampleNs}/Todo": { "params": {"where": {"status": {"eq": "open"}}}, "fields": {"id": true, "title": true} }, "${exampleNs}/createTodo": [{ "params": {"title": "first"}, "fields": {"id": true} }, { "params": {"title": "second"}, "fields": {"id": true} }] }`
11613
12799
  };
11614
12800
  }
11615
12801
  function buildPluginContributions(plugins) {
@@ -11652,6 +12838,7 @@ function buildOnboardBody(deps) {
11652
12838
  stream: WS_INSTRUCTIONS.stream,
11653
12839
  substratePack: WS_INSTRUCTIONS.substratePack,
11654
12840
  sse: WS_INSTRUCTIONS.sse,
12841
+ codeMode: CODE_MODE_INSTRUCTIONS,
11655
12842
  plugins: buildPluginContributions(deps.coordinators),
11656
12843
  pluginRoutes: buildPluginRoutes(deps.coordinators)
11657
12844
  };
@@ -11896,11 +13083,16 @@ function schemaForTypeRoute(engine) {
11896
13083
  fields: typeSchema.fields,
11897
13084
  ...operatorContract(engine, ns)
11898
13085
  };
11899
- return jsonResponse(200, shape === "fields" ? {
13086
+ const storage = await engine.datasetFor(ns)?.describeStorage?.(type).catch(() => void 0);
13087
+ const withStorage = storage === void 0 ? base : {
11900
13088
  ...base,
13089
+ storage
13090
+ };
13091
+ return jsonResponse(200, shape === "fields" ? {
13092
+ ...withStorage,
11901
13093
  mutationNames: Object.keys(mutations).sort()
11902
13094
  } : {
11903
- ...base,
13095
+ ...withStorage,
11904
13096
  mutations
11905
13097
  });
11906
13098
  };
@@ -12279,6 +13471,8 @@ const STREAM_CAPABILITY = "read";
12279
13471
  *
12280
13472
  * The values must be checked here: `StreamSession` reads `entry.fields` off
12281
13473
  * each one, and a throw after the transport opens leaks its heartbeat timer.
13474
+ * The WS route uses it too, where that throw would escape the message
13475
+ * listener and exit the process.
12282
13476
  *
12283
13477
  * Unlike `validateFrame` in `helpers.ts`, array values (the §5.13
12284
13478
  * batched-mutate shape) are rejected: streams cannot carry them, so this
@@ -12534,6 +13728,7 @@ function parseRequestFrame(buf, mode) {
12534
13728
  const v = value;
12535
13729
  if (typeof v.id !== "string") return null;
12536
13730
  if (v.op !== "subscribe" && v.op !== "stream" && v.op !== "cancel" && v.op !== "whoami") return null;
13731
+ if (v.frame !== void 0 && !isFrameRecord(v.frame)) return null;
12537
13732
  return value;
12538
13733
  } catch {
12539
13734
  return null;
@@ -12856,7 +14051,7 @@ function registerWsRoute(server, engine, trustedProxies, metric, auth, systemIde
12856
14051
  //#endregion
12857
14052
  //#region ../../packages/substrate-compose/src/compose/routes.ts
12858
14053
  async function registerCoreRoutes(args) {
12859
- const { server, engine, gate, trustedProxies, auth, streamTicketSecret, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport } = args;
14054
+ const { server, engine, gate, trustedProxies, auth, streamTicketSecret, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport, storageReport } = args;
12860
14055
  server.route("GET", "/health", healthRoute({
12861
14056
  version: version ?? "0.0.0",
12862
14057
  startedAt: Date.now()
@@ -12884,7 +14079,7 @@ async function registerCoreRoutes(args) {
12884
14079
  authOff: auth === void 0,
12885
14080
  ...adminCapability !== void 0 ? { adminCapability } : {}
12886
14081
  }), "admin"));
12887
- if (configReport !== void 0) server.route("GET", "/substrate/v1/config", gate(configRouteHandler(configReport), "admin"));
14082
+ if (configReport !== void 0) server.route("GET", "/substrate/v1/config", gate(configRouteHandler(configReport, storageReport), "admin"));
12888
14083
  const rateLimiter = registerRateLimiter ?? createRateLimiter({
12889
14084
  maxRequests: 10,
12890
14085
  windowMs: 6e4
@@ -12940,6 +14135,7 @@ async function registerCoreRoutes(args) {
12940
14135
  now: () => /* @__PURE__ */ new Date(),
12941
14136
  trustedProxies,
12942
14137
  engine,
14138
+ declaredInCode: (ns) => coordinatorPlugins.some((p) => p.namespaces.some((n) => n.namespace === ns)),
12943
14139
  ...dropGrants
12944
14140
  })), "admin"));
12945
14141
  server.route("POST", "/substrate/v1/_system/drop-type", gate(adminInTarget(dropTypeRoute({
@@ -13189,11 +14385,11 @@ async function composeInner(opts, cleanup) {
13189
14385
  const installSubstrateOpts = {
13190
14386
  registry: substrateRegistry,
13191
14387
  dataset: substrateDataset,
13192
- edges,
13193
- onMetric: routeMetric
14388
+ edges
13194
14389
  };
13195
14390
  if (opts.auth?.adminCapability !== void 0) installSubstrateOpts.adminCapability = opts.auth.adminCapability;
13196
14391
  if (opts.auth !== void 0 && opts.keyReprimeIntervalMs !== void 0) installSubstrateOpts.reprimeIntervalMs = opts.keyReprimeIntervalMs;
14392
+ if (opts.advisor?.storeProfile !== void 0) installSubstrateOpts.storeProfile = opts.advisor.storeProfile;
13197
14393
  const { keyRegistry: substrateKeyRegistry } = await installSystemNamespace(installSubstrateOpts);
13198
14394
  datasets.set(SYSTEM_NAMESPACE, substrateDataset);
13199
14395
  namespaces.set(SYSTEM_NAMESPACE, { registry: substrateRegistry });
@@ -13252,6 +14448,9 @@ async function composeInner(opts, cleanup) {
13252
14448
  ...opts.subscriptions,
13253
14449
  snapshotLimit: opts.subscriptions?.snapshotLimit ?? (opts.pageLimits ?? DEFAULT_PAGE_LIMITS).maxLimit
13254
14450
  };
14451
+ const advisorIntervalMs = opts.advisor?.intervalMs ?? 0;
14452
+ const shapeRecorder = advisorIntervalMs > 0 ? new ShapeRecorder() : void 0;
14453
+ if (shapeRecorder !== void 0) engineOpts.shapeRecorder = shapeRecorder;
13255
14454
  const engine = new Engine(engineOpts);
13256
14455
  engineForStats = engine;
13257
14456
  let auth;
@@ -13290,7 +14489,8 @@ async function composeInner(opts, cleanup) {
13290
14489
  ...opts.registerRateLimiter !== void 0 ? { registerRateLimiter: opts.registerRateLimiter } : {},
13291
14490
  ...opts.auth?.identityDirectory !== void 0 ? { identityDirectory: opts.auth.identityDirectory } : {},
13292
14491
  ...opts.auth?.adminCapability !== void 0 ? { adminCapability: opts.auth.adminCapability } : {},
13293
- ...opts.configReport !== void 0 ? { configReport: opts.configReport } : {}
14492
+ ...opts.configReport !== void 0 ? { configReport: opts.configReport } : {},
14493
+ ...opts.storageReport !== void 0 ? { storageReport: opts.storageReport } : {}
13294
14494
  });
13295
14495
  let scheduler = null;
13296
14496
  if (scheduleEntries.length > 0) {
@@ -13302,6 +14502,30 @@ async function composeInner(opts, cleanup) {
13302
14502
  }
13303
14503
  if (opts.bridges !== void 0) await engine.refreshBridgeSchemas();
13304
14504
  if (runCoordinatorOnStart !== null) await runCoordinatorOnStart(engine);
14505
+ let advisorPass = null;
14506
+ let advisorTimer;
14507
+ let runAdvisorNow = null;
14508
+ if (shapeRecorder !== void 0) {
14509
+ const deps = {
14510
+ dataset: opts.dataset,
14511
+ system: substrateDataset,
14512
+ recorder: shapeRecorder,
14513
+ registry: (ns) => namespaces.get(ns)?.registry,
14514
+ now: Date.now,
14515
+ writeHeavy: opts.advisor?.writeHeavy === true
14516
+ };
14517
+ const pass = () => runAdvisorPass(deps);
14518
+ runAdvisorNow = pass;
14519
+ advisorTimer = setInterval(() => {
14520
+ if (advisorPass !== null) return;
14521
+ advisorPass = pass().then(() => void 0).catch((err) => {
14522
+ process.stderr.write(`[substrate] index advisor pass failed and will run again: ${err instanceof Error ? err.message : String(err)}\n`);
14523
+ }).finally(() => {
14524
+ advisorPass = null;
14525
+ });
14526
+ }, advisorIntervalMs);
14527
+ advisorTimer.unref?.();
14528
+ }
13305
14529
  return {
13306
14530
  engine,
13307
14531
  keyRegistry: opts.auth === void 0 ? null : substrateKeyRegistry,
@@ -13310,10 +14534,13 @@ async function composeInner(opts, cleanup) {
13310
14534
  edges,
13311
14535
  sweepDeps,
13312
14536
  runSweepNow: () => runSweep(sweepDeps, { lastSweptCursor: null }),
14537
+ runAdvisorNow,
13313
14538
  scheduler,
13314
14539
  stats,
13315
14540
  stop: async (stopOpts) => {
13316
14541
  sampler.stop();
14542
+ clearInterval(advisorTimer);
14543
+ await advisorPass;
13317
14544
  if (scheduler !== null) await scheduler.stop();
13318
14545
  if (runCoordinatorOnStop !== null) await runCoordinatorOnStop(engine);
13319
14546
  if (ownsRateLimiter) rateLimiter.dispose();
@@ -13473,6 +14700,7 @@ async function composeKernelPlugins(plugins, ctx) {
13473
14700
  }
13474
14701
  await migration.apply({
13475
14702
  sql: ctx.sql,
14703
+ layout: ctx.layout,
13476
14704
  metric: ctx.metric
13477
14705
  });
13478
14706
  await ctx.applyMigration(plugin.name, migration.id);
@@ -13488,6 +14716,7 @@ async function composeKernelPlugins(plugins, ctx) {
13488
14716
  sql: ctx.sql,
13489
14717
  coordinatorNamespaces: ctx.coordinatorNamespaces ?? [],
13490
14718
  ...ctx.coordinatorNamespacesByPlugin !== void 0 ? { coordinatorNamespacesByPlugin: ctx.coordinatorNamespacesByPlugin } : {},
14719
+ background: ctx.background ?? true,
13491
14720
  metric: ctx.metric
13492
14721
  };
13493
14722
  await plugin.onKernelReady(lifecycleCtx);
@@ -13521,4 +14750,4 @@ function kernelMigrationTracking(sql) {
13521
14750
  }
13522
14751
 
13523
14752
  //#endregion
13524
- export { error400 as $, resolveIdentity as A, CLIENT_SUPPLIED_SERVER_FIELD as At, saveSweepState as B, purgeResolver as C, ReservedField as Ct, deleteRow as D, isAuthCause as Dt, deleteResolver as E, UnsupportedFilterError as Et, publishSchema as F, registerExtensionOperator as G, assertJsonPathPredicate as H, effectiveFilterOperators as I, fullBuiltinOperators as J, decodeCursor as K, applyObligations as L, resolveEntityRow as M, canonicalize as Mt, MemoryEdgesStore as N, BootstrapConfigError as Nt, createResolver as O, isResolverFrameError as Ot, loadPlugins as P, defineBootstrap as Pt, buildContext as Q, loadSweepState as R, updateResolver as S, NamespaceMismatch as St, getResolver as T, RestrictViolation as Tt, isJsonPathPredicate as U, preResolveExtensionOperatorsDetailed as V, getExtensionOperator as W, fieldRequested as X, applyExtensionResultMeta as Y, JSON_HEADERS as Z, field as _, createKeyedMutex as _t, composeFromManifests as a, WS_REASON_SERVER_RESTART as at, installAutoCrud as b, BridgeUnreachableError as bt, MemoryDataset as c, normaliseVocabValues as ct, buildAuditRow as d, vocabImplication as dt, jsonResponse as et, AUDIT_EVENT_TYPE as f, RegistryBase as ft, RESERVED_AUTOCRUD_FIELD_NAMES as g, normaliseMetadataWhere as gt, RESERVED_AUTOCRUD_FIELDS as h, normaliseMetadataOrderBy as ht, PluginLoadError as i, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as it, resolveEntityId as j, ROW_METADATA_FIELDS as jt, UnattributedWriteError as k, isRestrictViolation as kt, migrateFieldValues as l, normaliseVocabWhere as lt, defineNamespace as m, METADATA_FILTER_FIELDS as mt, kernelMigrationTracking as n, parseAuthConfig as nt, DEFAULT_NAMESPACE as o, WS_REASON_SUBSCRIPTION_OVERLOADED as ot, INVITE_TYPE as p, METADATA_AUTHOR_FIELDS as pt, encodeCursor as q, mountKernelRoute as r, signHs256 as rt, compose as s, canonicalVocabValue as st, composeKernelPlugins as t, parseJsonBody as tt, runInviteSweep as u, storedVocabSpellings as ut, autoCrudOptionsOf as v, assertHardDeleteAllowed as vt, listResolver as w, ResolverFrameError as wt, applyUpdatePatch as x, MissingReferentError as xt, createResolverWithEdges as y, validateHardDeleteEnv as yt, runSweep as z };
14753
+ export { assertJsonPathPredicate as $, createResolverWithEdges as A, normaliseMetadataWhere as At, UnattributedWriteError as B, ReservedField as Bt, queryOne as C, normaliseVocabWhere as Ct, isReservedAutoCrudField as D, METADATA_AUTHOR_FIELDS as Dt, RESERVED_AUTOCRUD_FIELD_NAMES as E, RegistryBase as Et, listResolver as F, assertHardDeleteAllowed as Ft, loadPlugins as G, isResolverFrameError as Gt, resolveEntityId as H, RestrictViolation as Ht, getResolver as I, validateHardDeleteEnv as It, applyObligations as J, ROW_METADATA_FIELDS as Jt, publishSchema as K, isRestrictViolation as Kt, deleteResolver as L, BridgeUnreachableError as Lt, applyUpdatePatch as M, isImpossibleIsoTimestamp as Mt, updateResolver as N, isIsoTimestamp as Nt, field as O, METADATA_FILTER_FIELDS as Ot, purgeResolver as P, normalizeIsoTimestamp as Pt, preResolveExtensionOperatorsDetailed as Q, defineBootstrap as Qt, deleteRow as R, MissingReferentError as Rt, queryAll as S, normaliseVocabValues as St, RESERVED_AUTOCRUD_FIELDS as T, vocabImplication as Tt, resolveEntityRow as U, UnsupportedFilterError as Ut, resolveIdentity as V, ResolverFrameError as Vt, MemoryEdgesStore as W, isAuthCause as Wt, runSweep as X, canonicalize as Xt, loadSweepState as Y, assertNoRepeatedIds as Yt, saveSweepState as Z, BootstrapConfigError as Zt, assertIndexDecl as _, signHs256 as _t, composeFromManifests as a, decodeCursor as at, EngineQueryError as b, WS_REASON_SUBSCRIPTION_OVERLOADED as bt, MemoryDataset as c, applyExtensionResultMeta as ct, uuidFromName as d, JSON_HEADERS as dt, isJsonPathPredicate as et, migrateFieldValues as f, buildContext as ft, INVITE_TYPE as g, parseAuthConfig as gt, AUDIT_EVENT_TYPE as h, parseJsonBody as ht, PluginLoadError as i, unregisterExtensionOperator as it, installAutoCrud as j, createKeyedMutex as jt, autoCrudOptionsOf as k, normaliseMetadataOrderBy as kt, planServesShape as l, fieldRequested as lt, buildAuditRow as m, jsonResponse as mt, kernelMigrationTracking as n, listExtensionOperators as nt, DEFAULT_NAMESPACE as o, encodeCursor as ot, runInviteSweep as p, error400 as pt, effectiveFilterOperators as q, CLIENT_SUPPLIED_SERVER_FIELD as qt, mountKernelRoute as r, registerExtensionOperator as rt, compose as s, fullBuiltinOperators as st, composeKernelPlugins as t, getExtensionOperator as tt, isStoreProfileName as u, HttpBridgeClient as ut, assertOrderedBy as v, WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME as vt, selectAll as w, storedVocabSpellings as wt, makeCtx as x, canonicalVocabValue as xt, defineNamespace as y, WS_REASON_SERVER_RESTART as yt, createResolver as z, NamespaceMismatch as zt };