@mnmal-ai/substrate 1.0.0-alpha.0 → 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 +51 -9
  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-j1jt1l3n.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-D91yij6C.js → src-5SJ5GEIM.js} +1557 -327
  33. package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
  34. package/dist/{src-CrEgiMJQ.js → src-Bi849yhn.js} +39 -15
  35. package/dist/{src-D88LvCX8.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 -5471
  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-BXkus75W.js +0 -1527
  46. package/dist/env-utils-B7SGmoeJ.js +0 -21
  47. package/dist/src-CzxvmhFn.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") : [];
@@ -962,7 +1020,9 @@ function authenticateBearer(token, cfg) {
962
1020
  }
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
- return reason === "lifetime_exceeds_max" ? "the token expires further ahead than this server accepts; mint a shorter-lived token or raise SUBSTRATE_JWT_MAX_TTL_SECONDS" : void 0;
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)";
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";
966
1026
  }
967
1027
  /**
968
1028
  * The parts of a Key row a verification relied on. A string, so it survives
@@ -1017,7 +1077,7 @@ function watchCredential(identity, cfg, onLapse) {
1017
1077
  }
1018
1078
  function extractBearer(authorization) {
1019
1079
  if (authorization === void 0) return null;
1020
- const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
1080
+ const match = /^Bearer\s+(\S.*)$/i.exec(authorization.trim());
1021
1081
  if (match === null) return null;
1022
1082
  const token = match[1]?.trim();
1023
1083
  if (token === void 0 || token.length === 0) return null;
@@ -1361,6 +1421,328 @@ function whoamiRoute(auth) {
1361
1421
  };
1362
1422
  }
1363
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
+
1364
1746
  //#endregion
1365
1747
  //#region ../../packages/substrate-core/src/engine/cursor-seal.ts
1366
1748
  /**
@@ -1513,17 +1895,26 @@ function fullBuiltinOperators() {
1513
1895
  //#endregion
1514
1896
  //#region ../../packages/substrate-filter/src/cursor.ts
1515
1897
  /**
1516
- * @internal — thrown by `decodeCursor` on malformed input. Re-exported so
1517
- * 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.
1518
1901
  */
1519
- var CursorDecodeError = class extends Error {
1902
+ var CursorDecodeError = class extends ResolverFrameError {
1520
1903
  name = "CursorDecodeError";
1904
+ constructor(message, details = {}) {
1905
+ super("invalid_cursor", message, {
1906
+ field: "cursor",
1907
+ ...details
1908
+ });
1909
+ }
1521
1910
  };
1522
1911
  function encodeCursor(input) {
1523
1912
  const json = JSON.stringify(input);
1524
1913
  return Buffer.from(json, "utf8").toString("base64url");
1525
1914
  }
1526
- 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) {
1527
1918
  let json;
1528
1919
  try {
1529
1920
  json = Buffer.from(cursor, "base64url").toString("utf8");
@@ -1549,9 +1940,17 @@ function decodeCursor(cursor) {
1549
1940
  "number",
1550
1941
  "boolean"
1551
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
+ });
1552
1950
  return {
1553
1951
  orderByValues: values,
1554
- id
1952
+ id,
1953
+ order: issued
1555
1954
  };
1556
1955
  }
1557
1956
 
@@ -1652,6 +2051,13 @@ function getExtensionOperator(name) {
1652
2051
  function listExtensionOperators() {
1653
2052
  return Array.from(extensionOperators.keys()).sort();
1654
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
+ }
1655
2061
  /**
1656
2062
  * True when any key in the where-tree (root, nested under AND/OR/NOT, or
1657
2063
  * inside a struct-field sub-clause) is a registered extension operator.
@@ -1724,12 +2130,6 @@ function whereContainsOperator(where, opName) {
1724
2130
  const JSON_PATH_MAX_DEPTH = 16;
1725
2131
  /** Most `in` / `nin` members both substrates accept (pg binds two per member). */
1726
2132
  const JSON_PATH_MAX_IN = 1e4;
1727
- /**
1728
- * Most `in` members still treated as index-served. jsonb `@>` has no planner
1729
- * statistics, so each OR'd containment adds a default-selectivity guess, and
1730
- * past a few dozen the planner scans the partition regardless of the GIN.
1731
- */
1732
- const JSON_PATH_INDEXED_IN_MAX = 32;
1733
2133
  const OPS = new Set(JSON_PATH_OPS$1);
1734
2134
  const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
1735
2135
  function isJsonPathPredicate(p) {
@@ -1769,18 +2169,6 @@ function jsonPathOperandProblem(op, operand) {
1769
2169
  default: return isScalar(operand) ? null : "requires a string, number or boolean";
1770
2170
  }
1771
2171
  }
1772
- /**
1773
- * Whether `op` scans the (namespace, type) partition on pg even when the field
1774
- * is `field.json({ indexed: true })`. Only containment is served by the derived
1775
- * `(body -> field)` GIN; a null operand needs an IS NULL test containment
1776
- * cannot express, and a long `in` is scanned by the planner anyway.
1777
- */
1778
- function jsonPathNeedsScan(op, operand) {
1779
- if (op === "has") return false;
1780
- if (op === "eq") return operand === null;
1781
- if (op === "in") return Array.isArray(operand) && (operand.length > 32 || operand.some((e) => e === null));
1782
- return true;
1783
- }
1784
2172
  /** The value at `path`, walking plain objects only. `undefined` means absent. */
1785
2173
  function resolveJsonPath(value, path) {
1786
2174
  let cur = value;
@@ -1998,7 +2386,8 @@ const METADATA_COLUMN_PROJECTIONS = {
1998
2386
  createdById: (row) => row._metadata?.createdBy?.id ?? null,
1999
2387
  createdByKind: (row) => row._metadata?.createdBy?.kind ?? null,
2000
2388
  updatedById: (row) => row._metadata?.updatedBy?.id ?? null,
2001
- updatedByKind: (row) => row._metadata?.updatedBy?.kind ?? null
2389
+ updatedByKind: (row) => row._metadata?.updatedBy?.kind ?? null,
2390
+ seq: (row) => row._metadata?.seq ?? null
2002
2391
  };
2003
2392
  /**
2004
2393
  * Resolve the effective filter value for `name` on `row`.
@@ -2012,6 +2401,14 @@ function getFieldValue(row, name) {
2012
2401
  if (projector !== void 0) return projector(row);
2013
2402
  return row[name];
2014
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
+ }
2015
2412
  const KNOWN_OPS = /* @__PURE__ */ new Set([
2016
2413
  "eq",
2017
2414
  "neq",
@@ -2086,27 +2483,35 @@ function assertFieldPredicateHonourable(field, predicate) {
2086
2483
  case "endsWith": if (typeof operand !== "string") throw new UnsupportedFilterError(field, op, "requires a string value");
2087
2484
  }
2088
2485
  }
2089
- 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) {
2090
2492
  if (where === null || typeof where !== "object" || Array.isArray(where)) return true;
2091
2493
  for (const [k, child] of Object.entries(where)) if (k === "AND") {
2092
2494
  if (Array.isArray(child)) {
2093
- for (const sub of child) if (!evaluateWhere(row, sub)) return false;
2495
+ for (const sub of child) if (!evaluateWhere(row, sub, fieldDefOf)) return false;
2094
2496
  }
2095
2497
  } else if (k === "OR") {
2096
2498
  if (Array.isArray(child)) {
2097
2499
  let any = false;
2098
- for (const sub of child) if (evaluateWhere(row, sub)) {
2500
+ for (const sub of child) if (evaluateWhere(row, sub, fieldDefOf)) {
2099
2501
  any = true;
2100
2502
  break;
2101
2503
  }
2102
2504
  if (!any) return false;
2103
2505
  }
2104
2506
  } else if (k === "NOT") {
2105
- if (evaluateWhere(row, child)) return false;
2106
- } 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
+ }
2107
2512
  return true;
2108
2513
  }
2109
- function evaluateFieldPredicate(field, value, predicate) {
2514
+ function evaluateFieldPredicate(field, value, predicate, asDate = false) {
2110
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}`);
2111
2516
  if (isJsonPathPredicate(predicate)) return evaluateJsonPathPredicate(field, value, predicate);
2112
2517
  const p = predicate;
@@ -2118,34 +2523,25 @@ function evaluateFieldPredicate(field, value, predicate) {
2118
2523
  }
2119
2524
  for (const op of keys) {
2120
2525
  const operand = p[op];
2121
- if (!applyOp(field, op, value, operand)) return false;
2526
+ if (!applyOp(field, op, value, operand, asDate)) return false;
2122
2527
  }
2123
2528
  return true;
2124
2529
  }
2125
- function applyOp(field, op, value, operand) {
2530
+ function applyOp(field, op, value, operand, asDate) {
2126
2531
  switch (op) {
2127
- case "eq": return equals(value, operand);
2128
- case "neq": return !equals(value, operand);
2129
- case "gt":
2130
- if (value == null) return false;
2131
- return compare$1(value, operand) > 0;
2132
- case "gte":
2133
- if (value == null) return false;
2134
- return compare$1(value, operand) >= 0;
2135
- case "lt":
2136
- if (value == null) return false;
2137
- return compare$1(value, operand) < 0;
2138
- case "lte":
2139
- if (value == null) return false;
2140
- 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;
2141
2538
  case "between":
2142
2539
  if (!Array.isArray(operand) || operand.length !== 2) throw new UnsupportedFilterError(field, op, "requires a two-element [low, high] array");
2143
- if (value == null) return false;
2144
- 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;
2145
2541
  case "in":
2146
2542
  case "nin": {
2147
2543
  if (!Array.isArray(operand)) throw new UnsupportedFilterError(field, op, "requires an array value");
2148
- const member = operand.some((e) => equals(value, e));
2544
+ const member = operand.some((e) => equals(value, e, asDate));
2149
2545
  return op === "in" ? member : !member;
2150
2546
  }
2151
2547
  case "contains":
@@ -2163,26 +2559,86 @@ function applyOp(field, op, value, operand) {
2163
2559
  default: throw new UnsupportedFilterError(field, op, "is not a recognised filter operator");
2164
2560
  }
2165
2561
  }
2166
- function equals(a, b) {
2562
+ function equals(a, b, asDate = false) {
2167
2563
  if (a == null && b == null) return true;
2168
- if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
2169
- if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
2170
- 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
+ }
2171
2569
  return a === b;
2172
2570
  }
2173
- 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) {
2174
2588
  if (a == null && b == null) return 0;
2175
2589
  if (a == null) return 1;
2176
2590
  if (b == null) return -1;
2177
- if (a instanceof Date || b instanceof Date) {
2178
- const at = a instanceof Date ? a.getTime() : typeof a === "string" ? Date.parse(a) : Number(a);
2179
- const bt = b instanceof Date ? b.getTime() : typeof b === "string" ? Date.parse(b) : Number(b);
2180
- 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;
2181
2595
  }
2182
2596
  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
2183
- const as = String(a);
2184
- const bs = String(b);
2185
- 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));
2186
2642
  }
2187
2643
 
2188
2644
  //#endregion
@@ -2192,6 +2648,7 @@ const SWEEP_ACTOR = {
2192
2648
  kind: "system",
2193
2649
  id: "sweep"
2194
2650
  };
2651
+ /** `UNKNOWN`: the bridge could not answer (down, or refused), so nothing may be applied. */
2195
2652
  async function resolveTarget(ref, deps) {
2196
2653
  const ds = deps.datasets.get(ref.ns);
2197
2654
  if (ds) {
@@ -2209,7 +2666,7 @@ async function resolveTarget(ref, deps) {
2209
2666
  if (row === null) return "MISSING";
2210
2667
  return row._deletedAt != null ? "DELETED" : "EXISTS";
2211
2668
  } catch (err) {
2212
- if (err instanceof BridgeUnreachableError) return "MISSING";
2669
+ if (err instanceof BridgeUnreachableError) return "UNKNOWN";
2213
2670
  throw err;
2214
2671
  }
2215
2672
  return "MISSING";
@@ -2313,6 +2770,7 @@ async function sweepBatch(base, deps) {
2313
2770
  id: edge.id,
2314
2771
  lastSweptAt: deps.now()
2315
2772
  });
2773
+ else if (target === "UNKNOWN") deps.metric("bridge_unreachable", edge.to.ns);
2316
2774
  else if (target === "DELETED") await applyPolicy(edge, cascadeQueue, deps);
2317
2775
  else if (edge.to.bridged === true && deps.bridges.isUnreachable(edge.to.ns)) deps.metric("bridge_unreachable", edge.to.ns);
2318
2776
  else await applyPolicy(edge, cascadeQueue, deps);
@@ -2326,7 +2784,7 @@ async function sweepBatch(base, deps) {
2326
2784
  return worklist.length;
2327
2785
  }
2328
2786
  const SWEEP_CURSOR_TYPE = "SweepCursor";
2329
- const SWEEP_CURSOR_ID = "edges";
2787
+ const SWEEP_CURSOR_ID = "5ee9c0a5-0000-4000-8000-000000000001";
2330
2788
  /** Reads the sweep cursor persisted by `saveSweepState`, or the scan head. */
2331
2789
  async function loadSweepState(ds) {
2332
2790
  const { rows } = await ds.read(SWEEP_CURSOR_TYPE, {
@@ -2468,6 +2926,9 @@ var Registry = class extends RegistryBase {
2468
2926
  params: input.params ?? {}
2469
2927
  };
2470
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;
2471
2932
  if (input.verb !== void 0) entry.verb = input.verb;
2472
2933
  this.entries.set(name, entry);
2473
2934
  }
@@ -2488,6 +2949,9 @@ var Registry = class extends RegistryBase {
2488
2949
  params: input.params ?? {}
2489
2950
  };
2490
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;
2491
2955
  if (input.verb !== void 0) entry.verb = input.verb;
2492
2956
  this.entries.set(name, entry);
2493
2957
  }
@@ -2591,7 +3055,7 @@ function checkIdentityGrant(identity, ns, operation) {
2591
3055
  required
2592
3056
  };
2593
3057
  }
2594
- function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx) {
3058
+ function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset, afterTx, txEntries) {
2595
3059
  const args = { edges };
2596
3060
  if (dataset !== void 0) args.dataset = dataset;
2597
3061
  if (entry.params !== void 0) args.params = entry.params;
@@ -2600,9 +3064,26 @@ function toResolverArgs(entry, dataset, edges, onWrite, signal, resolveDataset,
2600
3064
  if (signal !== void 0) args.signal = signal;
2601
3065
  if (resolveDataset !== void 0) args.resolveDataset = resolveDataset;
2602
3066
  if (afterTx !== void 0) args.afterTx = afterTx;
3067
+ if (txEntries !== void 0) args.txEntries = txEntries;
2603
3068
  return args;
2604
3069
  }
2605
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
+ /**
2606
3087
  * The frame with its `where` / `orderBy` metadata spellings rewritten onto the
2607
3088
  * canonical columns (`createdBy` -> `createdById`, …). Returns the same frame
2608
3089
  * when it carries neither.
@@ -2733,12 +3214,30 @@ function toBridgeFrame(bucket) {
2733
3214
  return out;
2734
3215
  }
2735
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
+ /**
2736
3231
  * Snapshot obligation gate. Mirrors `applyRowFilters` from the SDK but on a
2737
3232
  * single row — we can't wrap every live push in an allocation when the vast
2738
3233
  * majority of rows pass the filter.
2739
3234
  */
2740
3235
  function obligationsPermitRow(obligations, ctx, row) {
2741
- 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
+ }
2742
3241
  return true;
2743
3242
  }
2744
3243
  function normaliseToRows(result) {
@@ -2965,7 +3464,7 @@ function lookupField(fields, name) {
2965
3464
  */
2966
3465
  function metadataHint(fieldName) {
2967
3466
  if (!/^(_metadata|createdBy|updatedBy)(\.|$)/.test(fieldName)) return "";
2968
- 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";
2969
3468
  }
2970
3469
  const LOGICAL_KEYS = /* @__PURE__ */ new Set([
2971
3470
  "AND",
@@ -3074,19 +3573,22 @@ function validatePrimitiveKind(fieldKind, value, path, op) {
3074
3573
  case "scalar.boolean":
3075
3574
  if (typeof value !== "boolean") throw new FilterValidationError("type_mismatch", `operator '${op}' expected boolean, got ${typeof value}`, path);
3076
3575
  return;
3077
- case "scalar.date":
3576
+ case "scalar.date": {
3078
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);
3079
3580
  return;
3581
+ }
3080
3582
  case "crossRef":
3081
3583
  if (typeof value !== "string" && typeof value !== "number") throw new FilterValidationError("type_mismatch", `crossRef '${op}' expected id (string or number), got ${typeof value}`, path);
3082
3584
  return;
3083
3585
  }
3084
3586
  }
3085
- function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedCheck) {
3587
+ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, ctx) {
3086
3588
  if (fieldDef.kind === "struct") {
3087
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);
3088
3590
  validateWhereAgainstFields(leaf, fieldDef.fields, path, capabilities, {
3089
- ...indexedCheck,
3591
+ ...ctx,
3090
3592
  insideStruct: true
3091
3593
  });
3092
3594
  return;
@@ -3095,7 +3597,6 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3095
3597
  const listDef = fieldDef;
3096
3598
  const elementKind = fieldKindOf(listDef.of);
3097
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);
3098
- 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);
3099
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);
3100
3601
  const datasetCapOps = new Set(capabilities.operators.list ?? []);
3101
3602
  const elemNullable = listDef.of.kind === "scalar" && listDef.of.nullable === true;
@@ -3112,11 +3613,10 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3112
3613
  }
3113
3614
  const kind = fieldKindOf(fieldDef);
3114
3615
  if (kind === "scalar.json") {
3115
- 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"]);
3116
- 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);
3117
3618
  return;
3118
3619
  }
3119
- if (!isIndexed(fieldDef) && !indexedCheck.allowTableScan) throw new FilterValidationError("unindexed_field", `field '${fieldName}' is not indexed — set params._allowTableScan to override`, path);
3120
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);
3121
3621
  const allowedOps = opsAllowedFor(kind);
3122
3622
  const datasetCapOps = new Set(capabilities.operators[kind] ?? []);
@@ -3135,13 +3635,12 @@ function validateLeaf(fieldName, fieldDef, leaf, path, capabilities, indexedChec
3135
3635
  }
3136
3636
  const JSON_PATH_HINT = "address inside it with { path: [...], <op>: ... }";
3137
3637
  /**
3138
- * A json field is filterable only through a path predicate. The
3139
- * index gate is per operator AND per field: `eq`/`in`/`has` compile to
3140
- * containment, which the GIN derived for `field.json({ indexed: true })`
3141
- * serves; every other operator, and every operator on an unindexed json
3142
- * 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.
3143
3642
  */
3144
- function validateJsonPathLeaf(fieldName, fieldIndexed, leaf, path, capabilities, indexedCheck) {
3643
+ function validateJsonPathLeaf(fieldName, leaf, path, capabilities) {
3145
3644
  const obj = leaf !== null && typeof leaf === "object" && !Array.isArray(leaf) ? leaf : null;
3146
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"]);
3147
3646
  if (!isJsonPathPredicate(leaf)) {
@@ -3160,15 +3659,9 @@ function validateJsonPathLeaf(fieldName, fieldIndexed, leaf, path, capabilities,
3160
3659
  if (!datasetCapOps.has(op)) throw new FilterValidationError("capability_unsupported", `dataset does not support operator '${op}' on field kind 'scalar.json'`, [...path, op]);
3161
3660
  const problem = jsonPathOperandProblem(op, operand);
3162
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]);
3163
- 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]);
3164
3662
  }
3165
3663
  }
3166
- function isIndexed(def) {
3167
- if (def.kind === "scalar") return def.indexed === true;
3168
- if (def.kind === "crossRef") return true;
3169
- return false;
3170
- }
3171
- function validateWhereAgainstFields(where, fields, path, capabilities, indexedCheck) {
3664
+ function validateWhereAgainstFields(where, fields, path, capabilities, ctx) {
3172
3665
  if (where === null || typeof where !== "object" || Array.isArray(where)) throw new FilterValidationError("type_mismatch", "where must be an object", path);
3173
3666
  const keys = Object.keys(where);
3174
3667
  const hasLogical = keys.some((k) => LOGICAL_KEYS.has(k));
@@ -3184,11 +3677,11 @@ function validateWhereAgainstFields(where, fields, path, capabilities, indexedCh
3184
3677
  ...path,
3185
3678
  k,
3186
3679
  String(i)
3187
- ], capabilities, indexedCheck);
3680
+ ], capabilities, ctx);
3188
3681
  });
3189
3682
  } else if (k === "NOT") {
3190
3683
  if (child === null || typeof child !== "object" || Array.isArray(child)) throw new FilterValidationError("invalid_logical", `'NOT' expects a single WhereClause`, [...path, k]);
3191
- validateWhereAgainstFields(child, fields, [...path, k], capabilities, indexedCheck);
3684
+ validateWhereAgainstFields(child, fields, [...path, k], capabilities, ctx);
3192
3685
  }
3193
3686
  }
3194
3687
  return;
@@ -3204,9 +3697,14 @@ function validateWhereAgainstFields(where, fields, path, capabilities, indexedCh
3204
3697
  }
3205
3698
  throw new FilterValidationError("unknown_field", `unknown field '${fieldName}'${metadataHint(fieldName)}`, [...path, fieldName]);
3206
3699
  }
3207
- 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]);
3208
3702
  }
3209
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
+ }
3210
3708
  function validateOrderBy(orderBy, fields, capabilities) {
3211
3709
  if (!capabilities.orderBy) throw new FilterValidationError("capability_unsupported", "dataset does not support orderBy", ["orderBy"]);
3212
3710
  if (!Array.isArray(orderBy)) throw new FilterValidationError("type_mismatch", "orderBy must be an array of { field: \"asc\" | \"desc\" } entries", ["orderBy"]);
@@ -3240,8 +3738,7 @@ function validateOrderBy(orderBy, fields, capabilities) {
3240
3738
  });
3241
3739
  }
3242
3740
  function validateFilter(input) {
3243
- const allowTableScan = input.allowTableScan === true;
3244
- 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, {});
3245
3742
  if (input.orderBy !== void 0) validateOrderBy(input.orderBy, input.typeSchema.fields, input.capabilities);
3246
3743
  }
3247
3744
 
@@ -3268,7 +3765,6 @@ function runFilterGuard(deps, input) {
3268
3765
  const params = entry.params;
3269
3766
  const where = params?.where;
3270
3767
  const orderBy = params?.orderBy;
3271
- const allowTableScan = params?._allowTableScan === true;
3272
3768
  const requested = hasComputedFields() && entry.fields !== void 0 ? Object.keys(entry.fields) : [];
3273
3769
  for (const f of requested) {
3274
3770
  const owner = computedFieldOwner(f);
@@ -3315,7 +3811,6 @@ function runFilterGuard(deps, input) {
3315
3811
  } else validateFilter({
3316
3812
  ...where !== void 0 ? { where } : {},
3317
3813
  ...orderBy !== void 0 ? { orderBy } : {},
3318
- allowTableScan,
3319
3814
  typeSchema,
3320
3815
  capabilities: dataset.capabilities
3321
3816
  });
@@ -3574,7 +4069,10 @@ function publishSchema(registry) {
3574
4069
  params: entry.params,
3575
4070
  returns: entry.returns ?? UNKNOWN_RETURNS
3576
4071
  };
3577
- 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 };
3578
4076
  return {
3579
4077
  schemaVersion: hashContent(types, mutations),
3580
4078
  types,
@@ -3789,7 +4287,23 @@ var StreamSubsystem = class {
3789
4287
  if (input.signal.aborted) controller.abort();
3790
4288
  else input.signal.addEventListener("abort", () => controller.abort(), { once: true });
3791
4289
  }
3792
- 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
+ });
3793
4307
  return {
3794
4308
  id: input.id,
3795
4309
  cancel: () => {
@@ -3909,14 +4423,12 @@ var StreamSubsystem = class {
3909
4423
  const params = frame.params;
3910
4424
  const where = params?.where;
3911
4425
  const orderBy = params?.orderBy;
3912
- const allowTableScan = params?._allowTableScan === true;
3913
4426
  if (where !== void 0 || orderBy !== void 0) {
3914
4427
  const typeSchema = this.#schemaFor(ns).types[name];
3915
4428
  if (typeSchema) try {
3916
4429
  validateFilter({
3917
4430
  ...where !== void 0 ? { where } : {},
3918
4431
  ...orderBy !== void 0 ? { orderBy } : {},
3919
- allowTableScan,
3920
4432
  typeSchema,
3921
4433
  capabilities: dataset.capabilities
3922
4434
  });
@@ -3934,6 +4446,8 @@ var StreamSubsystem = class {
3934
4446
  }
3935
4447
  }
3936
4448
  }
4449
+ const ordered = withNaturalOrder(args.params, registryEntry, dataset);
4450
+ if (ordered !== void 0) args.params = ordered;
3937
4451
  let result;
3938
4452
  try {
3939
4453
  result = await registryEntry.resolver(ctx, args);
@@ -4447,14 +4961,12 @@ var SubscribeSubsystem = class {
4447
4961
  const rawWhere = params?.where;
4448
4962
  const where = rawWhere !== void 0 && typeFields !== void 0 ? normaliseVocabWhere(rawWhere, typeFields) : rawWhere;
4449
4963
  const orderBy = params?.orderBy;
4450
- const allowTableScan = params?._allowTableScan === true;
4451
4964
  if (where !== void 0 || orderBy !== void 0) {
4452
4965
  const typeSchema = this.#schemaFor(ns).types[name];
4453
4966
  if (typeSchema) try {
4454
4967
  validateFilter({
4455
4968
  ...where !== void 0 ? { where } : {},
4456
4969
  ...orderBy !== void 0 ? { orderBy } : {},
4457
- allowTableScan,
4458
4970
  typeSchema,
4459
4971
  capabilities: dataset.capabilities
4460
4972
  });
@@ -4497,6 +5009,8 @@ var SubscribeSubsystem = class {
4497
5009
  pendingEvents: []
4498
5010
  };
4499
5011
  this.#registerEntry(subscriptionEntry);
5012
+ const ordered = withNaturalOrder(args.params, registryEntry, dataset);
5013
+ if (ordered !== void 0) args.params = ordered;
4500
5014
  const snapshotLimit = registryEntry.kind === "type" ? this.#snapshotLimit : void 0;
4501
5015
  if (snapshotLimit !== void 0) args.params = {
4502
5016
  ...args.params,
@@ -4670,7 +5184,8 @@ var SubscribeSubsystem = class {
4670
5184
  const obligationsAllow = obligationsPermitRow(entry.obligations, entry.ctx, row);
4671
5185
  let whereMatches;
4672
5186
  try {
4673
- 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]);
4674
5189
  } catch (err) {
4675
5190
  const code = isResolverFrameError(err) ? err.code : "resolver_error";
4676
5191
  this.#enqueueFrame(entry, {
@@ -4874,6 +5389,7 @@ var Engine = class {
4874
5389
  #edges;
4875
5390
  #metric;
4876
5391
  #onResolve;
5392
+ #shapeRecorder;
4877
5393
  #idempotency;
4878
5394
  /**
4879
5395
  * Mutates under a dedup key that are still running. The store only sees a
@@ -4909,6 +5425,7 @@ var Engine = class {
4909
5425
  this.#edges = opts.edges;
4910
5426
  this.#metric = opts.metric ?? (() => {});
4911
5427
  this.#onResolve = opts.onResolve;
5428
+ this.#shapeRecorder = opts.shapeRecorder;
4912
5429
  this.#idempotency = opts.idempotency !== void 0 ? {
4913
5430
  store: opts.idempotency.store,
4914
5431
  defaultTtlMs: opts.idempotency.defaultTtlMs ?? 864e5
@@ -5338,7 +5855,7 @@ var Engine = class {
5338
5855
  const ctx = this.#buildContext(input.ctx, "mutate");
5339
5856
  const signal = input.signal;
5340
5857
  const bridgePromises = [];
5341
- 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));
5342
5859
  const writeBatch = [];
5343
5860
  const onWrite = (event) => {
5344
5861
  writeBatch.push(event);
@@ -5388,7 +5905,8 @@ var Engine = class {
5388
5905
  const entry = frame[key];
5389
5906
  if (entry === void 0) continue;
5390
5907
  const parsed = parsedByKey.get(key) ?? null;
5391
- 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)) {
5392
5910
  refusedKey = key;
5393
5911
  throw new SharedTxRefusal();
5394
5912
  }
@@ -5415,9 +5933,9 @@ var Engine = class {
5415
5933
  } catch (err) {
5416
5934
  if (!(err instanceof SharedTxRefusal)) throw err;
5417
5935
  for (const key of singleFrameKeys) {
5418
- if (!(key in envelope.data)) continue;
5419
5936
  const ns = parsedByKey.get(key)?.ns;
5420
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;
5421
5939
  delete envelope.data[key];
5422
5940
  delete envelope.shapes[key];
5423
5941
  addError(envelope, [key], `mutate rolled back: '${refusedKey}' refused`, "frame_rolled_back");
@@ -5471,7 +5989,7 @@ var Engine = class {
5471
5989
  * `mutate` so both honour the dedup contract.
5472
5990
  */
5473
5991
  async #finaliseMutateEnvelope(envelope, keys, resolution, callerKey) {
5474
- 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)) {
5475
5993
  const dedupKey = makeDedupKey(keys, resolution.value, callerKey);
5476
5994
  try {
5477
5995
  await this.#idempotency.store.put(dedupKey, envelope, this.#idempotency.defaultTtlMs);
@@ -5605,7 +6123,7 @@ var Engine = class {
5605
6123
  });
5606
6124
  return refused;
5607
6125
  }
5608
- 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) {
5609
6127
  if (!parsed) {
5610
6128
  addError(envelope, [key], `unqualified frame key '${key}' — expected '<ns>/<name>'`, "unqualified_key");
5611
6129
  this.#metric("engine_unqualified_key", key);
@@ -5651,7 +6169,7 @@ var Engine = class {
5651
6169
  entry: name,
5652
6170
  ...registryEntry.verb !== void 0 ? { verb: registryEntry.verb } : {}
5653
6171
  };
5654
- 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);
5655
6173
  const decision = evaluatePolicy(registryEntry.policy, ctx, args);
5656
6174
  if (!decision.allow) {
5657
6175
  addError(envelope, [key], decision.reason ?? "policy denied", "policy_denied");
@@ -5677,6 +6195,10 @@ var Engine = class {
5677
6195
  isVirtual,
5678
6196
  dataset
5679
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
+ }
5680
6202
  const cursor = args.params?.cursor;
5681
6203
  if (typeof cursor === "string") {
5682
6204
  const opened = (decision.obligations?.length ?? 0) > 0 && !isSealedCursor(cursor) ? null : openCursor(cursor);
@@ -5690,6 +6212,7 @@ var Engine = class {
5690
6212
  };
5691
6213
  }
5692
6214
  let result;
6215
+ const t0 = performance.now();
5693
6216
  try {
5694
6217
  result = await registryEntry.resolver(ctx, args);
5695
6218
  } catch (err) {
@@ -5710,6 +6233,8 @@ var Engine = class {
5710
6233
  return true;
5711
6234
  }
5712
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);
5713
6238
  }
5714
6239
  shapeResult({
5715
6240
  envelope,
@@ -5871,7 +6396,7 @@ var Engine = class {
5871
6396
  shapes: {}
5872
6397
  };
5873
6398
  failedIndex = i;
5874
- 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);
5875
6400
  failedIndex = void 0;
5876
6401
  const entry = {};
5877
6402
  if (key in scratch.data) entry.data = scratch.data[key];
@@ -6386,48 +6911,6 @@ function farEndAllowed(edge, fromMatch, toMatch, allowed) {
6386
6911
  return fromMatch && allowed.has(edge.to.ns) || toMatch && allowed.has(edge.from.ns);
6387
6912
  }
6388
6913
 
6389
- //#endregion
6390
- //#region ../../packages/substrate-core/src/metrics/histogram.ts
6391
- /** Upper bounds in ms: powers of √2 from 0.1 ms; the last bucket catches everything larger. */
6392
- const BOUNDS = [];
6393
- for (let b = .1; b < 6e4; b *= Math.SQRT2) BOUNDS.push(b);
6394
- BOUNDS.push(Number.POSITIVE_INFINITY);
6395
- /** O(1) observe; percentiles read off bucket upper bounds (clamped to the observed max). */
6396
- var LogHistogram = class {
6397
- #counts = new Array(BOUNDS.length).fill(0);
6398
- count = 0;
6399
- max = 0;
6400
- observe(ms) {
6401
- if (!Number.isFinite(ms) || ms < 0) return;
6402
- let i = 0;
6403
- while (ms > BOUNDS[i]) i++;
6404
- this.#counts[i] = this.#counts[i] + 1;
6405
- this.count++;
6406
- if (ms > this.max) this.max = ms;
6407
- }
6408
- /** Lower bound of the bucket holding the p-th percentile; 0 when empty. */
6409
- percentileLowerBound(p) {
6410
- if (this.count === 0) return 0;
6411
- const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
6412
- let seen = 0;
6413
- for (let i = 0; i < BOUNDS.length; i++) {
6414
- seen += this.#counts[i];
6415
- if (seen >= rank) return i === 0 ? 0 : BOUNDS[i - 1];
6416
- }
6417
- return this.max;
6418
- }
6419
- percentile(p) {
6420
- if (this.count === 0) return 0;
6421
- const rank = Math.ceil(Math.min(1, Math.max(0, p)) * this.count);
6422
- let seen = 0;
6423
- for (let i = 0; i < BOUNDS.length; i++) {
6424
- seen += this.#counts[i];
6425
- if (seen >= rank) return Math.min(BOUNDS[i], this.max);
6426
- }
6427
- return this.max;
6428
- }
6429
- };
6430
-
6431
6914
  //#endregion
6432
6915
  //#region ../../packages/substrate-core/src/metrics/resolver-table.ts
6433
6916
  const round = (ms) => Math.round(ms * 100) / 100;
@@ -6944,6 +7427,26 @@ function assertNoNullOnNonNullable(params, fieldDefs, phase) {
6944
7427
  });
6945
7428
  }
6946
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
+ /**
6947
7450
  * Fill `create` defaults: for every declared scalar field with a `default` that
6948
7451
  * the caller omitted, set it on `params`. Mutates the supplied bag in place
6949
7452
  * (the create resolver passes a fresh `{ ...args.params }`). A caller-supplied
@@ -7034,20 +7537,6 @@ function assertServerSetFieldsFillable(typeName, fieldDefs) {
7034
7537
 
7035
7538
  //#endregion
7036
7539
  //#region ../../packages/substrate-sdk/src/autocrud/autocrud-create.ts
7037
- /**
7038
- * autoCRUD `create<T>` resolver. Spec: §5.1.
7039
- *
7040
- * Accepts the entity body via `params`. Generates a UUID id when absent.
7041
- * `_deletedAt` is stripped at the dataset layer — no sanitation needed here.
7042
- *
7043
- * Design call: id generation is `crypto.randomUUID()` rather than monotonic
7044
- * counters so two engines pointed at the same dataset (future) don't collide.
7045
- *
7046
- * When `options.fields` is supplied, any field with `readonly: true` is
7047
- * rejected if the caller includes it in params — shortId is the primary use
7048
- * case. The engine allocates shortId post-write and binds
7049
- * it in the same transaction via `ds.allocateShortId` / `ds.bindShortId`.
7050
- */
7051
7540
  function createResolver(typeName, dataset, options = {}) {
7052
7541
  return async (ctx, args) => {
7053
7542
  const ds = args.dataset ?? dataset;
@@ -7063,10 +7552,12 @@ function createResolver(typeName, dataset, options = {}) {
7063
7552
  if (options.fields) assertNoUnknownFields(params, options.fields, "create");
7064
7553
  if (options.fields) {
7065
7554
  assertNoNullOnNonNullable(params, options.fields, "create");
7555
+ assertScalarTypes(params, options.fields, "create");
7066
7556
  applyScalarDefaults(params, options.fields);
7067
7557
  assertRequiredFields(params, options.fields);
7068
7558
  }
7069
- const id = coerceId(params.id) ?? randomUUID();
7559
+ const { id: rawId, ...body } = params;
7560
+ const id = coerceId(rawId);
7070
7561
  const at = ctx.now.toISOString();
7071
7562
  const actor = resolveIdentity(ctx);
7072
7563
  const _metadata = {
@@ -7075,8 +7566,11 @@ function createResolver(typeName, dataset, options = {}) {
7075
7566
  createdBy: actor,
7076
7567
  updatedBy: actor
7077
7568
  };
7078
- const row = {
7079
- ...params,
7569
+ const row = id === void 0 ? {
7570
+ ...body,
7571
+ _metadata
7572
+ } : {
7573
+ ...body,
7080
7574
  id,
7081
7575
  _metadata
7082
7576
  };
@@ -7213,14 +7707,12 @@ function listResolver(typeName, dataset, options = {}) {
7213
7707
  const where = args.params?.where;
7214
7708
  const orderBy = args.params?.orderBy;
7215
7709
  const cursor = args.params?.cursor;
7216
- const allowTableScan = args.params?._allowTableScan;
7217
7710
  const includeDeleted = args.params?.includeDeleted;
7218
7711
  if (id !== void 0) readParams.id = id;
7219
7712
  if (ids !== void 0) readParams.ids = ids;
7220
7713
  if (where !== void 0) readParams.where = options.fields !== void 0 ? normaliseVocabWhere(where, options.fields) : where;
7221
7714
  if (orderBy !== void 0) readParams.orderBy = orderBy;
7222
7715
  if (typeof cursor === "string") readParams.cursor = cursor;
7223
- if (allowTableScan === true) readParams._allowTableScan = true;
7224
7716
  if (includeDeleted === true) readParams.includeDeleted = true;
7225
7717
  const fields = args.fields;
7226
7718
  if (fields !== void 0) readParams.fields = fields;
@@ -7410,6 +7902,7 @@ function updateResolver(typeName, dataset, edges, options = {}) {
7410
7902
  if (options.fields) {
7411
7903
  assertNoUnknownFields(inParams, options.fields, "update");
7412
7904
  assertNoNullOnNonNullable(inParams, options.fields, "update");
7905
+ assertScalarTypes(inParams, options.fields, "update");
7413
7906
  }
7414
7907
  const rowId = await resolveEntityId(ds, typeName, id);
7415
7908
  if (rowId === null) throw new ResolverFrameError("not_found", `updateResolver('${typeName}'): no row with id '${String(id)}'`, { field: "id" });
@@ -7638,7 +8131,10 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
7638
8131
  resolver: list,
7639
8132
  kind: "type",
7640
8133
  ...policy !== void 0 ? { policy } : {},
7641
- ...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 } : {}
7642
8138
  });
7643
8139
  const cap = typeName.charAt(0).toUpperCase() + typeName.slice(1);
7644
8140
  registry.register(`get${cap}`, {
@@ -7699,9 +8195,9 @@ function installAutoCrud(registry, typeName, dataset, edges, options = {}) {
7699
8195
  function makeScalar(type, opts) {
7700
8196
  const def = {
7701
8197
  kind: "scalar",
7702
- type,
7703
- indexed: opts?.indexed ?? true
8198
+ type
7704
8199
  };
8200
+ if (opts?.indexed !== void 0) def.indexed = opts.indexed;
7705
8201
  if (opts?.nullable !== void 0) def.nullable = opts.nullable;
7706
8202
  if (opts?.readonly !== void 0) def.readonly = opts.readonly;
7707
8203
  if (opts?.default !== void 0) def.default = opts.default;
@@ -7789,8 +8285,7 @@ const field = {
7789
8285
  * JSON body. Value round-trips unchanged. Filter a value INSIDE it with a
7790
8286
  * path predicate — `{ values: { path: ['year'], gt: 1990 } }` — which is
7791
8287
  * type-strict. `eq` / `in` / `has` are index-served only with
7792
- * `{ indexed: true }`; everything else scans the type's rows and needs
7793
- * `_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,
7794
8289
  * `field.struct` is still the better fit: declared, indexed, orderable.
7795
8290
  */
7796
8291
  json(opts) {
@@ -7807,13 +8302,125 @@ const field = {
7807
8302
 
7808
8303
  //#endregion
7809
8304
  //#region ../../packages/substrate-sdk/src/autocrud/reserved.ts
7810
- 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({
7811
8310
  indexed: true,
7812
8311
  readonly: true
7813
- }) };
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
+ }
7814
8317
  /** Reserved field names — useful for validation loops. */
7815
8318
  const RESERVED_AUTOCRUD_FIELD_NAMES = Object.keys(RESERVED_AUTOCRUD_FIELDS);
7816
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
+
7817
8424
  //#endregion
7818
8425
  //#region ../../packages/substrate-sdk/src/namespace.ts
7819
8426
  /**
@@ -7877,6 +8484,14 @@ function defineNamespace(namespace, types, opts = {}) {
7877
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})`);
7878
8485
  assertServerSetFieldsFillable(typeName, typeInput.fields);
7879
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
+ }
7880
8495
  if (opts.annotations !== void 0) assertJsonValue(opts.annotations, "annotations");
7881
8496
  const globalPolicy = opts.policy;
7882
8497
  return {
@@ -7893,6 +8508,7 @@ function defineNamespace(namespace, types, opts = {}) {
7893
8508
  };
7894
8509
  const combined = composePolicyLayers(ctx.pluginPolicy, globalPolicy, typeInput.policy);
7895
8510
  const installOpts = { fields: augmentedFields };
8511
+ if (typeInput.orderedBy !== void 0) installOpts.orderedBy = typeInput.orderedBy;
7896
8512
  if (combined !== void 0) installOpts.policy = combined;
7897
8513
  if (typeInput.purgeable === true) installOpts.purgeable = true;
7898
8514
  if (typeInput.adminCapability !== void 0) installOpts.adminCapability = typeInput.adminCapability;
@@ -7906,6 +8522,61 @@ function defineNamespace(namespace, types, opts = {}) {
7906
8522
  }
7907
8523
  };
7908
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
+ }
7909
8580
  function composePolicyLayers(pluginLevel, namespaceLevel, typeLevel) {
7910
8581
  const layers = [
7911
8582
  pluginLevel,
@@ -7989,6 +8660,8 @@ const INVITE_FIELDS = {
7989
8660
  * - `field_backfilled` : `backfillFieldRoute` wrote per-row values of one field, metadata preserved
7990
8661
  * - `type_dropped` : `dropTypeRoute` dropped every row in a single type
7991
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
7992
8665
  *
7993
8666
  * `details` is an opaque JSON body — `field.json()` round-trips the value
7994
8667
  * unchanged through encoder/decoder, no JSON.stringify boundary needed.
@@ -8038,27 +8711,69 @@ const ENUM_VERDICT_FIELDS = {
8038
8711
  /** `namespace/type/field` — the upsert key the writer derives. Indexed for the lookup. */
8039
8712
  verdictKey: field.string()
8040
8713
  };
8041
- const AUDIT_EVENT_TYPE = "AuditEvent";
8714
+ const STORE_PROFILE_TYPE = "StoreProfile";
8715
+ const INDEX_RECOMMENDATION_TYPE = "IndexRecommendation";
8042
8716
  /**
8043
- * Public-policy projection of `Key`. Returns only verification material.
8044
- * Named `SigningKey` to follow the `_system` namespace convention (every
8045
- * type in `_system` carries the `Substrate` prefix as identity, independent of
8046
- * policy posture). Policy posture is documented per-resolver: this one accepts
8047
- * `identity: null` and gates only on namespace presence. See `./signing-key.ts`
8048
- * 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.
8049
8719
  */
8050
- const SIGNING_KEY_TYPE = "SigningKey";
8720
+ const STORE_PROFILE_ID = "5703e000-0000-4000-8000-000000000001";
8051
8721
  /**
8052
- * Field surface for `_system/SigningKey`. Mirrors the subset of `Key`
8053
- * that a JWT verifier needs: `id` (the kid, auto-included by the schema
8054
- * publisher for every type) plus `publicKey` and `algorithm`. Capabilities,
8055
- * namespaces, and `revokedAt` are NOT exposed — they're admin-only on the
8056
- * 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.
8057
8725
  */
8058
- const SIGNING_KEY_FIELDS = {
8059
- publicKey: field.string({ indexed: false }),
8060
- 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 })
8061
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";
8062
8777
  const KEY_ALGORITHMS = /* @__PURE__ */ new Set([
8063
8778
  "EdDSA",
8064
8779
  "RS256",
@@ -8127,6 +8842,7 @@ function createKeyRegistry(opts) {
8127
8842
  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
8128
8843
  const warn = opts.onWarn ?? (() => void 0);
8129
8844
  let cache = /* @__PURE__ */ new Map();
8845
+ let generation = 0;
8130
8846
  function isLive(record) {
8131
8847
  if (record.revokedAt === null) return true;
8132
8848
  return record.revokedAt.getTime() > now().getTime();
@@ -8160,6 +8876,7 @@ function createKeyRegistry(opts) {
8160
8876
  function installRow(row) {
8161
8877
  const projected = projectRow(row);
8162
8878
  if (projected === null) return false;
8879
+ generation++;
8163
8880
  cache.set(projected.kid, projected);
8164
8881
  return true;
8165
8882
  }
@@ -8167,8 +8884,9 @@ function createKeyRegistry(opts) {
8167
8884
  const reprimeIntervalMs = opts.reprimeIntervalMs;
8168
8885
  if (reprimeIntervalMs !== void 0 && Number.isFinite(reprimeIntervalMs) && reprimeIntervalMs > 0) {
8169
8886
  timer = setInterval(() => {
8887
+ const started = generation;
8170
8888
  loadAll().then((next) => {
8171
- cache = next;
8889
+ if (generation === started) cache = next;
8172
8890
  }).catch((err) => {
8173
8891
  warn("substrate_key_registry_reprime_failed", { error: err instanceof Error ? err.message : String(err) });
8174
8892
  });
@@ -8190,11 +8908,13 @@ function createKeyRegistry(opts) {
8190
8908
  }) ?? void 0;
8191
8909
  if (row === void 0) {
8192
8910
  warn("substrate_key_registry_no_live_row", { kid });
8911
+ generation++;
8193
8912
  cache.delete(kid);
8194
8913
  return;
8195
8914
  }
8196
8915
  if (!installRow(row)) {
8197
8916
  warn("substrate_key_registry_malformed_row", { kid });
8917
+ generation++;
8198
8918
  cache.delete(kid);
8199
8919
  }
8200
8920
  },
@@ -8202,6 +8922,7 @@ function createKeyRegistry(opts) {
8202
8922
  return installRow(row);
8203
8923
  },
8204
8924
  evict(kid) {
8925
+ generation++;
8205
8926
  cache.delete(kid);
8206
8927
  },
8207
8928
  async primeFromDataset() {
@@ -8216,67 +8937,14 @@ function createKeyRegistry(opts) {
8216
8937
  };
8217
8938
  }
8218
8939
 
8219
- //#endregion
8220
- //#region ../../packages/substrate-compose/src/_system/signing-key.ts
8221
- /**
8222
- * Extract the `kid` string from a `where` clause that has exactly the shape
8223
- * `{ id: { eq: <non-empty string> } }`. Any other shape is rejected:
8224
- *
8225
- * - Compound predicates (AND / OR / NOT discriminators) are unsupported and
8226
- * emit `engine_signing_key_unsupported_where` with `reason: 'compound'`.
8227
- * - Extra top-level keys alongside `id` are unsupported and emit the metric
8228
- * with `reason: 'extra_fields'`. Callers who add defence-in-depth filters
8229
- * (e.g. `revokedAt: { eq: null }`) believe they are filtering, but this
8230
- * resolver cannot honour them — surfacing the mismatch explicitly is safer
8231
- * than silently ignoring it.
8232
- * - Everything else (wrong operator, wrong type, missing where) returns null
8233
- * without a metric because those are expected call shapes (e.g. "no filter
8234
- * supplied").
8235
- */
8236
- function extractKid(where, metric) {
8237
- if (where === void 0 || where === null) return null;
8238
- if (typeof where !== "object") return null;
8239
- if ("AND" in where || "OR" in where || "NOT" in where) {
8240
- metric?.("engine_signing_key_unsupported_where", { reason: "compound" });
8241
- return null;
8242
- }
8243
- const keys = Object.keys(where);
8244
- if (keys.length !== 1 || keys[0] !== "id") {
8245
- metric?.("engine_signing_key_unsupported_where", {
8246
- reason: "extra_fields",
8247
- keys
8248
- });
8249
- return null;
8250
- }
8251
- const id = where.id;
8252
- if (id === null || typeof id !== "object") return null;
8253
- const eq = id.eq;
8254
- return typeof eq === "string" && eq.length > 0 ? eq : null;
8255
- }
8256
- function createSigningKeyResolver(registry, opts) {
8257
- const metric = opts?.onMetric;
8258
- return async (_ctx, args) => {
8259
- const kid = extractKid(args.params?.where, metric);
8260
- if (kid === null) return [];
8261
- const record = registry.lookup(kid);
8262
- if (record === null) return [];
8263
- return [{
8264
- id: record.kid,
8265
- publicKey: record.publicKey,
8266
- algorithm: record.algorithm
8267
- }];
8268
- };
8269
- }
8270
-
8271
8940
  //#endregion
8272
8941
  //#region ../../packages/substrate-compose/src/_system/install.ts
8273
8942
  /**
8274
8943
  * `_system` namespace wire-up. Spec §5.12.
8275
8944
  *
8276
- * Registers `Key`, `Invite`, `AuditEvent` and the enum-verdict
8277
- * type with admin-gated autoCRUD, plus the public `SigningKey`
8278
- * projection. Returns a live `KeyRegistry` whose cache is synchronously
8279
- * 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.
8280
8948
  *
8281
8949
  * Invalidation strategy: we wrap the `Registry` surface that
8282
8950
  * `installAutoCrud` writes into. The `Key` mutations get their resolver
@@ -8301,6 +8969,10 @@ function createSigningKeyResolver(registry, opts) {
8301
8969
  * (algorithm is a param on the frame, not a property of the identity) and
8302
8970
  * the client deserves a dedicated code to branch on.
8303
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";
8304
8976
  /**
8305
8977
  * Wrap a `Registry` so `register` AND `replace` calls for the configured
8306
8978
  * mutation names route their resolver through `wrap(resolver, mutationName)`.
@@ -8398,11 +9070,10 @@ function resolveActorKid(ctx) {
8398
9070
  /**
8399
9071
  * Build the AuditEvent row. Shared between the interceptor emits (which
8400
9072
  * write via `args.dataset` to stay in-tx) and the route emits (which write via
8401
- * the ambient dataset post-tx). `id` is a random UUID.
9073
+ * the ambient dataset post-tx). The dataset assigns the `id`.
8402
9074
  */
8403
9075
  function buildAuditRow(input) {
8404
9076
  return {
8405
- id: randomUUID(),
8406
9077
  ts: input.now.toISOString(),
8407
9078
  actorKid: input.actorKid,
8408
9079
  kind: input.kind,
@@ -8524,9 +9195,29 @@ async function installSystemNamespace(opts) {
8524
9195
  if (opts.onWarn !== void 0) keyRegistryOpts.onWarn = opts.onWarn;
8525
9196
  if (opts.reprimeIntervalMs !== void 0) keyRegistryOpts.reprimeIntervalMs = opts.reprimeIntervalMs;
8526
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;
8527
9215
  const wrappedForSubstrateKey = wrapRegistryMutations(opts.registry, {
8528
- createKey: (base) => async (ctx, args) => {
9216
+ createKey: (base) => lockedKeyWrite(async (ctx, args) => {
8529
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`);
8530
9221
  const result = await base(ctx, args);
8531
9222
  const kid = extractKidForInvalidation(result);
8532
9223
  if (kid !== null) {
@@ -8546,13 +9237,25 @@ async function installSystemNamespace(opts) {
8546
9237
  installFromResult(keyRegistry, result, kid, opts.onWarn);
8547
9238
  }
8548
9239
  return result;
8549
- },
8550
- updateKey: (base) => async (ctx, args) => {
9240
+ }),
9241
+ updateKey: (base) => lockedKeyWrite(async (ctx, args) => {
8551
9242
  if (args.params?.kid !== void 0) throw new Error("Key.kid is immutable; rotate or re-register instead of changing kid");
8552
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);
8553
9256
  const result = await base(ctx, args);
8554
9257
  const kid = extractKidForInvalidation(result);
8555
- if (kid !== null) {
9258
+ if (kid !== null && wasLive) {
8556
9259
  const revokedAt = args.params?.revokedAt;
8557
9260
  if (revokedAt !== void 0 && revokedAt !== null && revokedAt !== "") await emitAuditInTx(ctx, args, {
8558
9261
  actorKid: resolveActorKid(ctx),
@@ -8565,19 +9268,21 @@ async function installSystemNamespace(opts) {
8565
9268
  installFromResult(keyRegistry, result, kid, opts.onWarn);
8566
9269
  }
8567
9270
  return result;
8568
- },
8569
- deleteKey: (base) => async (ctx, args) => {
9271
+ }),
9272
+ deleteKey: (base) => lockedKeyWrite(async (ctx, args) => {
8570
9273
  const targetId = typeof args.params?.id === "string" ? args.params.id : void 0;
8571
9274
  let kidToEvict = null;
8572
9275
  if (targetId !== void 0) {
8573
- const { rows } = await (args.dataset ?? opts.dataset).read("Key", { id: targetId });
8574
- 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);
8575
9280
  }
8576
9281
  const result = await base(ctx, args);
8577
9282
  if (kidToEvict !== null) keyRegistry.evict(kidToEvict);
8578
9283
  return result;
8579
- },
8580
- purgeKey: (base) => async (ctx, args) => {
9284
+ }),
9285
+ purgeKey: (base) => lockedKeyWrite(async (ctx, args) => {
8581
9286
  const targetId = typeof args.params?.id === "string" ? args.params.id : void 0;
8582
9287
  let kidToEvict = null;
8583
9288
  if (targetId !== void 0) {
@@ -8585,7 +9290,8 @@ async function installSystemNamespace(opts) {
8585
9290
  id: targetId,
8586
9291
  includeDeleted: true
8587
9292
  });
8588
- kidToEvict = extractKidForInvalidation(rows[0]);
9293
+ assertAdminSurvives(await keysFor(args), targetId, null);
9294
+ if (isLive(rows[0])) kidToEvict = extractKidForInvalidation(rows[0]);
8589
9295
  }
8590
9296
  try {
8591
9297
  const result = await base(ctx, args);
@@ -8598,7 +9304,7 @@ async function installSystemNamespace(opts) {
8598
9304
  }
8599
9305
  throw err;
8600
9306
  }
8601
- }
9307
+ })
8602
9308
  });
8603
9309
  installAutoCrud(wrappedForSubstrateKey, "Key", opts.dataset, opts.edges, {
8604
9310
  fields: mergeIdField(KEY_FIELDS),
@@ -8668,11 +9374,37 @@ async function installSystemNamespace(opts) {
8668
9374
  purgeable: true,
8669
9375
  adminCapability
8670
9376
  });
8671
- opts.registry.register(SIGNING_KEY_TYPE, {
8672
- resolver: createSigningKeyResolver(keyRegistry, opts.onMetric !== void 0 ? { onMetric: opts.onMetric } : void 0),
8673
- kind: "type",
8674
- policy: allowAll(),
8675
- 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
+ }
8676
9408
  });
8677
9409
  await backfillBootstrapAuditIfNeeded(opts.dataset);
8678
9410
  return { keyRegistry };
@@ -9669,7 +10401,6 @@ function keysRoute(engine, opts) {
9669
10401
  const dirFrameKey = dirPlan === null ? null : `${dirPlan.ns}/create${dirPlan.type}`;
9670
10402
  const frame = { [keyFrameKey]: {
9671
10403
  params: {
9672
- id: randomUUID(),
9673
10404
  kid: b.kid,
9674
10405
  name: b.name,
9675
10406
  algorithm: b.algorithm,
@@ -9696,7 +10427,7 @@ function keysRoute(engine, opts) {
9696
10427
  const keyErr = errorFor(keyFrameKey);
9697
10428
  if (keyErr !== void 0) {
9698
10429
  const code = keyErr.code ?? "internal_error";
9699
- return jsonResponse(code === "policy_denied" ? 403 : 500, {
10430
+ return jsonResponse(code === "policy_denied" ? 403 : code === "kid_already_live" ? 409 : 500, {
9700
10431
  code,
9701
10432
  message: keyErr.message ?? "key registration failed"
9702
10433
  });
@@ -9889,7 +10620,6 @@ function registerRoute(dataset, registry, rateLimiter, opts) {
9889
10620
  message: "invite has expired"
9890
10621
  });
9891
10622
  const kid = base64Url(randomBytes(16));
9892
- const rowId = randomUUID();
9893
10623
  const createdAt = now();
9894
10624
  const inviteNamespacesRaw = invite.namespaces;
9895
10625
  const inviteCapabilitiesRaw = invite.capabilities;
@@ -9905,7 +10635,6 @@ function registerRoute(dataset, registry, rateLimiter, opts) {
9905
10635
  id: kid
9906
10636
  })).matched) throw new RegisterRaceError();
9907
10637
  await tx.write("Key", [{
9908
- id: rowId,
9909
10638
  kid,
9910
10639
  name: body.keyName,
9911
10640
  algorithm: body.algorithm,
@@ -9960,6 +10689,366 @@ var RegisterRaceError = class extends Error {
9960
10689
  }
9961
10690
  };
9962
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
+
9963
11052
  //#endregion
9964
11053
  //#region ../../packages/substrate-dataset-memory/src/memory-short-id-store.ts
9965
11054
  const EMPTY_BY_ROW = /* @__PURE__ */ new Map();
@@ -10094,6 +11183,38 @@ var MemoryShortIdStore = class {
10094
11183
  }
10095
11184
  };
10096
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
+
10097
11218
  //#endregion
10098
11219
  //#region ../../packages/substrate-dataset-memory/src/memory-dataset.ts
10099
11220
  /**
@@ -10109,8 +11230,7 @@ var MemoryShortIdStore = class {
10109
11230
  *
10110
11231
  * Filter contract (§5.2): `read()` honours `where` + `orderBy` + `cursor` in
10111
11232
  * addition to the id/ids/includeDeleted/limit short-circuit. Filter evaluation
10112
- * is in-memory; there's no indexing, so the validator (upstream, in the
10113
- * engine) is what gates unindexed-field scans.
11233
+ * is in-memory; there's no indexing, so every filter is a scan.
10114
11234
  */
10115
11235
  const RESERVED_DELETED_AT = "_deletedAt";
10116
11236
  /**
@@ -10120,17 +11240,27 @@ const RESERVED_DELETED_AT = "_deletedAt";
10120
11240
  * existing when incoming is null.
10121
11241
  */
10122
11242
  function mergeRowMetadata(existing, incoming) {
10123
- if (existing === void 0) return incoming;
11243
+ if (existing === void 0) return withoutSeq(incoming);
10124
11244
  return {
10125
11245
  createdAt: existing.createdAt ?? incoming.createdAt,
10126
11246
  updatedAt: incoming.updatedAt ?? existing.updatedAt,
10127
11247
  createdBy: existing.createdBy ?? incoming.createdBy,
10128
- updatedBy: incoming.updatedBy ?? existing.updatedBy
11248
+ updatedBy: incoming.updatedBy ?? existing.updatedBy,
11249
+ ...existing.seq !== void 0 ? { seq: existing.seq } : {}
10129
11250
  };
10130
11251
  }
11252
+ function withoutSeq(meta) {
11253
+ if (meta.seq === void 0) return meta;
11254
+ const { seq: _seq, ...rest } = meta;
11255
+ return rest;
11256
+ }
10131
11257
  var MemoryDataset = class MemoryDataset {
10132
11258
  namespace;
10133
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();
10134
11264
  capabilities = {
10135
11265
  operators: fullBuiltinOperators(),
10136
11266
  orderBy: true,
@@ -10149,6 +11279,8 @@ var MemoryDataset = class MemoryDataset {
10149
11279
  constructor(options) {
10150
11280
  this.namespace = options.namespace;
10151
11281
  this.txScopeId = options.txScopeId ?? `mem:${randomUUID()}`;
11282
+ this.#fieldDefLookup = options.fieldDefLookup;
11283
+ this.typeDefLookup = options.typeDefLookup;
10152
11284
  }
10153
11285
  bucket(type) {
10154
11286
  let b = this.store.get(type);
@@ -10166,6 +11298,8 @@ var MemoryDataset = class MemoryDataset {
10166
11298
  hasMore: false
10167
11299
  };
10168
11300
  const includeDeleted = params.includeDeleted === true;
11301
+ const lookup = this.#fieldDefLookup;
11302
+ const fieldDefOf = (field) => lookup?.(type, field);
10169
11303
  const idFilter = /* @__PURE__ */ new Set();
10170
11304
  let hasIdFilter = false;
10171
11305
  if (params.id !== void 0) {
@@ -10198,15 +11332,15 @@ var MemoryDataset = class MemoryDataset {
10198
11332
  })() : b.values();
10199
11333
  for (const row of candidates) {
10200
11334
  if (!includeDeleted && row._deletedAt != null) continue;
10201
- if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere)) continue;
11335
+ if (resolvedWhere !== void 0 && !evaluateWhere(row, resolvedWhere, fieldDefOf)) continue;
10202
11336
  pool.push(row);
10203
11337
  }
10204
11338
  const orderBy = normalizeOrderBy(params.orderBy);
10205
- pool.sort((a, b2) => compareByClauses(a, b2, orderBy));
11339
+ pool.sort((a, b2) => compareByClauses(a, b2, orderBy, fieldDefOf));
10206
11340
  let startIdx = 0;
10207
11341
  if (params.cursor !== void 0 && params.cursor !== "") {
10208
- const cursor = decodeCursor(params.cursor);
10209
- 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);
10210
11344
  }
10211
11345
  let hasMore = false;
10212
11346
  let slice;
@@ -10225,7 +11359,8 @@ var MemoryDataset = class MemoryDataset {
10225
11359
  const last = slice[slice.length - 1];
10226
11360
  if (hasMore && last !== void 0) out.nextCursor = encodeCursor({
10227
11361
  orderByValues: orderBy.map(([field]) => getFieldValue(last, field)),
10228
- id: last.id
11362
+ id: last.id,
11363
+ order: orderBy
10229
11364
  });
10230
11365
  if (extMeta !== null) out.rows = applyExtensionResultMeta(out.rows, extMeta, {
10231
11366
  hasExplicitOrderBy: params.orderBy !== void 0 && params.orderBy.length > 0,
@@ -10234,13 +11369,18 @@ var MemoryDataset = class MemoryDataset {
10234
11369
  return out;
10235
11370
  }
10236
11371
  async write(type, rows, options) {
11372
+ if (options?.insertOnly !== true) assertNoRepeatedIds(type, rows);
10237
11373
  const b = this.bucket(type);
10238
11374
  const ids = [];
10239
11375
  const merged = [];
10240
11376
  const fallbackNow = (options?.now ?? /* @__PURE__ */ new Date()).toISOString();
10241
11377
  const fallbackActor = options?.identity ?? null;
10242
- for (const row of rows) {
10243
- 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
+ };
10244
11384
  let rowToWrite = row;
10245
11385
  if (row._metadata === void 0) {
10246
11386
  const autoMeta = {
@@ -10277,6 +11417,16 @@ var MemoryDataset = class MemoryDataset {
10277
11417
  b.set(rowToWrite.id, landed);
10278
11418
  } else {
10279
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
+ }
10280
11430
  b.set(rowToWrite.id, landed);
10281
11431
  }
10282
11432
  ids.push(row.id);
@@ -10387,7 +11537,8 @@ var MemoryDataset = class MemoryDataset {
10387
11537
  createdAt: prior?.createdAt ?? null,
10388
11538
  createdBy: prior?.createdBy ?? null,
10389
11539
  updatedAt: (now ?? /* @__PURE__ */ new Date()).toISOString(),
10390
- updatedBy
11540
+ updatedBy,
11541
+ ...prior?.seq !== void 0 ? { seq: prior.seq } : {}
10391
11542
  };
10392
11543
  return {
10393
11544
  matched: true,
@@ -10401,7 +11552,20 @@ var MemoryDataset = class MemoryDataset {
10401
11552
  if (!b) return;
10402
11553
  const row = b.get(ref.id);
10403
11554
  if (!row) return;
11555
+ const seq = row._metadata?.seq;
10404
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
+ }
10405
11569
  }
10406
11570
  /**
10407
11571
  * Snapshot-and-restore atomicity. Spec §5.3 / G1.
@@ -10423,6 +11587,7 @@ var MemoryDataset = class MemoryDataset {
10423
11587
  for (const [id, r] of bucket.entries()) cloned.set(id, { ...r });
10424
11588
  snapshot.set(type, cloned);
10425
11589
  }
11590
+ const seqSnapshot = new Map(this.seqs);
10426
11591
  const undoLog = [];
10427
11592
  const dropUndoLog = [];
10428
11593
  this.#inTx = true;
@@ -10432,6 +11597,7 @@ var MemoryDataset = class MemoryDataset {
10432
11597
  return await fn(this);
10433
11598
  } catch (err) {
10434
11599
  this.store = snapshot;
11600
+ this.seqs = seqSnapshot;
10435
11601
  for (let i = dropUndoLog.length - 1; i >= 0; i--) {
10436
11602
  const entry = dropUndoLog[i];
10437
11603
  if (entry !== void 0) this.shortIds._restoreBucket(this.namespace, entry.type, entry.snapshot);
@@ -10467,7 +11633,11 @@ var MemoryDataset = class MemoryDataset {
10467
11633
  return this.shortIds.getShortIdForRow(this.namespace, type, rowId);
10468
11634
  }
10469
11635
  forNamespace(namespace) {
10470
- 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
+ });
10471
11641
  }
10472
11642
  };
10473
11643
  /**
@@ -10485,20 +11655,6 @@ function conditionalMatchEq(actual, expected) {
10485
11655
  }
10486
11656
  return actual === expected;
10487
11657
  }
10488
- function compare(a, b) {
10489
- if (a == null && b == null) return 0;
10490
- if (a == null) return 1;
10491
- if (b == null) return -1;
10492
- if (a instanceof Date || b instanceof Date) {
10493
- const at = a instanceof Date ? a.getTime() : typeof a === "string" ? Date.parse(a) : Number(a);
10494
- const bt = b instanceof Date ? b.getTime() : typeof b === "string" ? Date.parse(b) : Number(b);
10495
- return at < bt ? -1 : at > bt ? 1 : 0;
10496
- }
10497
- if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
10498
- const as = String(a);
10499
- const bs = String(b);
10500
- return as < bs ? -1 : as > bs ? 1 : 0;
10501
- }
10502
11658
  function normalizeOrderBy(orderBy) {
10503
11659
  const out = [];
10504
11660
  let hasIdTail = false;
@@ -10512,19 +11668,19 @@ function normalizeOrderBy(orderBy) {
10512
11668
  if (!hasIdTail) out.push(["id", "asc"]);
10513
11669
  return out;
10514
11670
  }
10515
- function compareByClauses(a, b, orderBy) {
11671
+ function compareByClauses(a, b, orderBy, fieldDefOf) {
10516
11672
  for (const [field, dir] of orderBy) {
10517
- const av = getFieldValue(a, field);
10518
- const bv = getFieldValue(b, field);
11673
+ const av = asSortValue(field, getFieldValue(a, field), fieldDefOf);
11674
+ const bv = asSortValue(field, getFieldValue(b, field), fieldDefOf);
10519
11675
  if (av == null && bv == null) continue;
10520
11676
  if (av == null) return 1;
10521
11677
  if (bv == null) return -1;
10522
- const cmp = compare(av, bv);
11678
+ const cmp = compareFilterValues(av, bv, isDateField(field, fieldDefOf));
10523
11679
  if (cmp !== 0) return dir === "asc" ? cmp : -cmp;
10524
11680
  }
10525
11681
  return 0;
10526
11682
  }
10527
- function findCursorStart(pool, orderBy, cursorValues, cursorId) {
11683
+ function findCursorStart(pool, orderBy, cursorValues, cursorId, fieldDefOf) {
10528
11684
  const cursorRow = { id: cursorId };
10529
11685
  const meta = {};
10530
11686
  const createdBy = {};
@@ -10532,7 +11688,7 @@ function findCursorStart(pool, orderBy, cursorValues, cursorId) {
10532
11688
  orderBy.forEach(([field], i) => {
10533
11689
  const v = cursorValues[i];
10534
11690
  if (field === "id") return;
10535
- if (field === "createdAt" || field === "updatedAt") meta[field] = v;
11691
+ if (field === "createdAt" || field === "updatedAt" || field === "seq") meta[field] = v;
10536
11692
  else if (field === "createdById") createdBy.id = v;
10537
11693
  else if (field === "createdByKind") createdBy.kind = v;
10538
11694
  else if (field === "updatedById") updatedBy.id = v;
@@ -10545,7 +11701,7 @@ function findCursorStart(pool, orderBy, cursorValues, cursorId) {
10545
11701
  for (let i = 0; i < pool.length; i++) {
10546
11702
  const row = pool[i];
10547
11703
  if (row === void 0) continue;
10548
- if (compareByClauses(row, cursorRow, orderBy) > 0) return i;
11704
+ if (compareByClauses(row, cursorRow, orderBy, fieldDefOf) > 0) return i;
10549
11705
  }
10550
11706
  return pool.length;
10551
11707
  }
@@ -10884,7 +12040,10 @@ function resolveBootGuards(opts) {
10884
12040
  *
10885
12041
  * Scope is data-only: substrate rows, short-ids and (optionally) edges.
10886
12042
  * Schema declarations are not affected — a type still declared in
10887
- * 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.
10888
12047
  */
10889
12048
  const SAMPLE_EDGE_LIMIT = 5;
10890
12049
  const DANGLING_COUNT_CAP = 1e4;
@@ -11166,7 +12325,15 @@ function dropNamespaceRoute(deps) {
11166
12325
  } catch (err) {
11167
12326
  warnings.push(`drop participant for ${participant.namespaces.join(", ")} failed after the drop committed: ${err instanceof Error ? err.message : String(err)}`);
11168
12327
  }
11169
- 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
+ }
11170
12337
  return jsonResponse(200, {
11171
12338
  namespace,
11172
12339
  dryRun,
@@ -11279,9 +12446,17 @@ function handleConfigRequest(report) {
11279
12446
  * Route handler factory. Pass to `gate(configRouteHandler(report), 'admin')`
11280
12447
  * in compose so it inherits the same treatment as `/substrate/v1/_system/invites`.
11281
12448
  */
11282
- function configRouteHandler(report) {
11283
- 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
+ });
11284
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
+ });
11285
12460
 
11286
12461
  //#endregion
11287
12462
  //#region ../../packages/substrate-compose/src/routes/connection-limit.ts
@@ -11518,7 +12693,7 @@ const WS_INSTRUCTIONS = {
11518
12693
  notes: [
11519
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\" }] }",
11520
12695
  "server replies { id, kind:\"snapshot\", data:{ \"<ns>/<TypeName>\": rows }, shapes } immediately, then pushes kind:\"add\" | \"update\" | \"remove\" (a remove carries `removedId`, no `data`)",
11521
- "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",
11522
12697
  "multi-key subscribe IS supported (unlike stream); one socket multiplexes many sessions, keyed by your `id`",
11523
12698
  "cancel with { id, op:\"cancel\" } — the server acknowledges a cancelled SUBSCRIBE with { id, kind:\"end\", final:true }",
11524
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",
@@ -11564,6 +12739,18 @@ const WS_INSTRUCTIONS = {
11564
12739
  ]
11565
12740
  }
11566
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
+ };
11567
12754
  const AUTH_INSTRUCTIONS = {
11568
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`.",
11569
12756
  modes: {
@@ -11607,8 +12794,8 @@ function buildFrameGrammar(coordinators) {
11607
12794
  return {
11608
12795
  queryKey: "<ns>/<TypeName>",
11609
12796
  mutationKey: "<ns>/<mutationName>",
11610
- 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.",
11611
- 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} }] }`
11612
12799
  };
11613
12800
  }
11614
12801
  function buildPluginContributions(plugins) {
@@ -11651,6 +12838,7 @@ function buildOnboardBody(deps) {
11651
12838
  stream: WS_INSTRUCTIONS.stream,
11652
12839
  substratePack: WS_INSTRUCTIONS.substratePack,
11653
12840
  sse: WS_INSTRUCTIONS.sse,
12841
+ codeMode: CODE_MODE_INSTRUCTIONS,
11654
12842
  plugins: buildPluginContributions(deps.coordinators),
11655
12843
  pluginRoutes: buildPluginRoutes(deps.coordinators)
11656
12844
  };
@@ -11895,11 +13083,16 @@ function schemaForTypeRoute(engine) {
11895
13083
  fields: typeSchema.fields,
11896
13084
  ...operatorContract(engine, ns)
11897
13085
  };
11898
- return jsonResponse(200, shape === "fields" ? {
13086
+ const storage = await engine.datasetFor(ns)?.describeStorage?.(type).catch(() => void 0);
13087
+ const withStorage = storage === void 0 ? base : {
11899
13088
  ...base,
13089
+ storage
13090
+ };
13091
+ return jsonResponse(200, shape === "fields" ? {
13092
+ ...withStorage,
11900
13093
  mutationNames: Object.keys(mutations).sort()
11901
13094
  } : {
11902
- ...base,
13095
+ ...withStorage,
11903
13096
  mutations
11904
13097
  });
11905
13098
  };
@@ -12278,6 +13471,8 @@ const STREAM_CAPABILITY = "read";
12278
13471
  *
12279
13472
  * The values must be checked here: `StreamSession` reads `entry.fields` off
12280
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.
12281
13476
  *
12282
13477
  * Unlike `validateFrame` in `helpers.ts`, array values (the §5.13
12283
13478
  * batched-mutate shape) are rejected: streams cannot carry them, so this
@@ -12533,6 +13728,7 @@ function parseRequestFrame(buf, mode) {
12533
13728
  const v = value;
12534
13729
  if (typeof v.id !== "string") return null;
12535
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;
12536
13732
  return value;
12537
13733
  } catch {
12538
13734
  return null;
@@ -12855,7 +14051,7 @@ function registerWsRoute(server, engine, trustedProxies, metric, auth, systemIde
12855
14051
  //#endregion
12856
14052
  //#region ../../packages/substrate-compose/src/compose/routes.ts
12857
14053
  async function registerCoreRoutes(args) {
12858
- 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;
12859
14055
  server.route("GET", "/health", healthRoute({
12860
14056
  version: version ?? "0.0.0",
12861
14057
  startedAt: Date.now()
@@ -12883,7 +14079,7 @@ async function registerCoreRoutes(args) {
12883
14079
  authOff: auth === void 0,
12884
14080
  ...adminCapability !== void 0 ? { adminCapability } : {}
12885
14081
  }), "admin"));
12886
- 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"));
12887
14083
  const rateLimiter = registerRateLimiter ?? createRateLimiter({
12888
14084
  maxRequests: 10,
12889
14085
  windowMs: 6e4
@@ -12939,6 +14135,7 @@ async function registerCoreRoutes(args) {
12939
14135
  now: () => /* @__PURE__ */ new Date(),
12940
14136
  trustedProxies,
12941
14137
  engine,
14138
+ declaredInCode: (ns) => coordinatorPlugins.some((p) => p.namespaces.some((n) => n.namespace === ns)),
12942
14139
  ...dropGrants
12943
14140
  })), "admin"));
12944
14141
  server.route("POST", "/substrate/v1/_system/drop-type", gate(adminInTarget(dropTypeRoute({
@@ -13188,11 +14385,11 @@ async function composeInner(opts, cleanup) {
13188
14385
  const installSubstrateOpts = {
13189
14386
  registry: substrateRegistry,
13190
14387
  dataset: substrateDataset,
13191
- edges,
13192
- onMetric: routeMetric
14388
+ edges
13193
14389
  };
13194
14390
  if (opts.auth?.adminCapability !== void 0) installSubstrateOpts.adminCapability = opts.auth.adminCapability;
13195
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;
13196
14393
  const { keyRegistry: substrateKeyRegistry } = await installSystemNamespace(installSubstrateOpts);
13197
14394
  datasets.set(SYSTEM_NAMESPACE, substrateDataset);
13198
14395
  namespaces.set(SYSTEM_NAMESPACE, { registry: substrateRegistry });
@@ -13251,6 +14448,9 @@ async function composeInner(opts, cleanup) {
13251
14448
  ...opts.subscriptions,
13252
14449
  snapshotLimit: opts.subscriptions?.snapshotLimit ?? (opts.pageLimits ?? DEFAULT_PAGE_LIMITS).maxLimit
13253
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;
13254
14454
  const engine = new Engine(engineOpts);
13255
14455
  engineForStats = engine;
13256
14456
  let auth;
@@ -13289,7 +14489,8 @@ async function composeInner(opts, cleanup) {
13289
14489
  ...opts.registerRateLimiter !== void 0 ? { registerRateLimiter: opts.registerRateLimiter } : {},
13290
14490
  ...opts.auth?.identityDirectory !== void 0 ? { identityDirectory: opts.auth.identityDirectory } : {},
13291
14491
  ...opts.auth?.adminCapability !== void 0 ? { adminCapability: opts.auth.adminCapability } : {},
13292
- ...opts.configReport !== void 0 ? { configReport: opts.configReport } : {}
14492
+ ...opts.configReport !== void 0 ? { configReport: opts.configReport } : {},
14493
+ ...opts.storageReport !== void 0 ? { storageReport: opts.storageReport } : {}
13293
14494
  });
13294
14495
  let scheduler = null;
13295
14496
  if (scheduleEntries.length > 0) {
@@ -13301,6 +14502,30 @@ async function composeInner(opts, cleanup) {
13301
14502
  }
13302
14503
  if (opts.bridges !== void 0) await engine.refreshBridgeSchemas();
13303
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
+ }
13304
14529
  return {
13305
14530
  engine,
13306
14531
  keyRegistry: opts.auth === void 0 ? null : substrateKeyRegistry,
@@ -13309,10 +14534,13 @@ async function composeInner(opts, cleanup) {
13309
14534
  edges,
13310
14535
  sweepDeps,
13311
14536
  runSweepNow: () => runSweep(sweepDeps, { lastSweptCursor: null }),
14537
+ runAdvisorNow,
13312
14538
  scheduler,
13313
14539
  stats,
13314
14540
  stop: async (stopOpts) => {
13315
14541
  sampler.stop();
14542
+ clearInterval(advisorTimer);
14543
+ await advisorPass;
13316
14544
  if (scheduler !== null) await scheduler.stop();
13317
14545
  if (runCoordinatorOnStop !== null) await runCoordinatorOnStop(engine);
13318
14546
  if (ownsRateLimiter) rateLimiter.dispose();
@@ -13472,6 +14700,7 @@ async function composeKernelPlugins(plugins, ctx) {
13472
14700
  }
13473
14701
  await migration.apply({
13474
14702
  sql: ctx.sql,
14703
+ layout: ctx.layout,
13475
14704
  metric: ctx.metric
13476
14705
  });
13477
14706
  await ctx.applyMigration(plugin.name, migration.id);
@@ -13487,6 +14716,7 @@ async function composeKernelPlugins(plugins, ctx) {
13487
14716
  sql: ctx.sql,
13488
14717
  coordinatorNamespaces: ctx.coordinatorNamespaces ?? [],
13489
14718
  ...ctx.coordinatorNamespacesByPlugin !== void 0 ? { coordinatorNamespacesByPlugin: ctx.coordinatorNamespacesByPlugin } : {},
14719
+ background: ctx.background ?? true,
13490
14720
  metric: ctx.metric
13491
14721
  };
13492
14722
  await plugin.onKernelReady(lifecycleCtx);
@@ -13520,4 +14750,4 @@ function kernelMigrationTracking(sql) {
13520
14750
  }
13521
14751
 
13522
14752
  //#endregion
13523
- 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 };