@mnmal-ai/substrate 1.0.0-alpha.9 → 1.0.0-beta.1

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 (52) hide show
  1. package/README.md +31 -13
  2. package/dist/boot-store-BMQUbHKv.js +4086 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
  4. package/dist/cli-DModIbnN.js +3390 -0
  5. package/dist/client.browser.js +2507 -0
  6. package/dist/client.d.ts +222 -171
  7. package/dist/client.js +6 -7
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-Cmkp1qxf.d.ts} +44 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/{plugin-DpncES1p.js → plugin-CEOhrEme.js} +78 -8
  19. package/dist/proposals-bootstrap.js +6 -5
  20. package/dist/proposals.config.schema.json +5 -0
  21. package/dist/proposals.d.ts +17 -5
  22. package/dist/proposals.default-config.json +2 -1
  23. package/dist/proposals.js +2 -3
  24. package/dist/recall-bootstrap.js +3 -4
  25. package/dist/recall.d.ts +11 -12
  26. package/dist/recall.js +2 -3
  27. package/dist/{repl-DeKzfvNV.js → repl-BvDZy-Ut.js} +52 -26
  28. package/dist/{row-SRhura12.d.ts → row-D0If4qif.d.ts} +91 -13
  29. package/dist/run-BT123RV1.js +2443 -0
  30. package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
  31. package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
  32. package/dist/script-runner.js +78 -0
  33. package/dist/sdk.d.ts +236 -38
  34. package/dist/sdk.js +5 -110
  35. package/dist/semver-D_zdq0hi.js +17 -0
  36. package/dist/src-BMD2OE--.js +8289 -0
  37. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  38. package/dist/{src-DjIuRjzF.js → src-CKSJ13p8.js} +10231 -4237
  39. package/dist/{src-C12EA0w9.js → src-CW7eRDss.js} +179 -96
  40. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  41. package/dist/{src-DCy7Iy2l.js → src-DmjwFMu8.js} +900 -77
  42. package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
  43. package/dist/substrate-admin.js +17 -782
  44. package/dist/substrate.js +4 -5302
  45. package/dist/testing.d.ts +473 -96
  46. package/dist/testing.js +19 -165
  47. package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
  48. package/package.json +26 -26
  49. package/dist/dataset-CqrqTYPz.js +0 -1535
  50. package/dist/pg-edges-store-KH_FQCxx.js +0 -381
  51. package/dist/schema-g4FQLr0V.d.ts +0 -433
  52. package/dist/src-BD27zeGF.js +0 -2339
@@ -0,0 +1,4086 @@
1
+ import { A as isReservedAutoCrudField, Bn as DEFAULT_FILTER_WRITE_LIMITS, Gt as WS_REASON_SERVER_RESTART, Ht as parseAuthConfig, It as HttpBridgeClient, Rt as buildContext, Z as MemoryEdgesStore, _ as AUDIT_EVENT_TYPE, a as composeFromManifests, bt as registerExtensionOperator, c as MemoryDataset, et as effectiveFilterOperators, g as buildAuditRow, h as SYSTEM_TYPE_DEFS, i as PluginLoadError, n as kernelMigrationTracking, o as DEFAULT_NAMESPACE, r as mountKernelRoute, s as compose, t as composeKernelPlugins, u as isStoreProfileName, vt as getExtensionOperator, xt as unregisterExtensionOperator, yt as listExtensionOperators } from "./src-CKSJ13p8.js";
2
+ import { a as adminClaimCapabilities, d as resolveDefaultKidPath, l as resolveAdminCredential, n as trimTrailingSlashes, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, t as parsePositiveInt, u as resolveDefaultKeyPath } from "./env-utils-s25Z1YSA.js";
3
+ import { D as isActiveAdminKeyRow, E as describeGrant, L as encodeList, M as grantEntryError, T as SYSTEM_NAMESPACE, v as grantEntriesConfer } from "./src-DmiUWOLp.js";
4
+ import { r as FRAMES_JSON_MIME, s as decodeStreamFrames, u as withIdleTimeout } from "./src-B_kHkbsr.js";
5
+ import { C as diagnose, S as DIAGNOSE_CHECKS, T as substrateFetch, _ as SKIPPABLE_STEPS, b as planOnboarding, h as CURRENT_MARK, i as tokenAudience, v as STEP_MARKS, x as requiredOutstanding, y as currentStep } from "./src-FXO5JPyk.js";
6
+ import { b as runMigrations, g as deriveListIndexMigration, h as assertTablesLayout, n as PgEdgesStore, p as assertNotMigrating, r as PgDataset, t as PgIdempotencyStore, v as pendingMigrations, y as runDerivedMigrations } from "./src-BMD2OE--.js";
7
+ import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-CW7eRDss.js";
8
+ import { et as memberKey } from "./plugin-CEOhrEme.js";
9
+ import { existsSync, linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
10
+ import { homedir } from "node:os";
11
+ import { basename, dirname, join, resolve } from "node:path";
12
+ import { createHash, createPublicKey, generateKeyPairSync, randomUUID } from "node:crypto";
13
+ import { BlockList, isIP } from "node:net";
14
+ import { constants } from "node:http2";
15
+ import { readFile, readdir, stat, statfs } from "node:fs/promises";
16
+ import postgres from "postgres";
17
+ import { pathToFileURL } from "node:url";
18
+ import compressPlugin from "@fastify/compress";
19
+ import corsPlugin from "@fastify/cors";
20
+ import Fastify from "fastify";
21
+ import { Readable } from "node:stream";
22
+ import { setTimeout as setTimeout$1 } from "node:timers/promises";
23
+
24
+ //#region ../../packages/substrate-core/src/memory-bridge-credential-store.ts
25
+ var MemoryBridgeCredentialStore = class {
26
+ #creds = /* @__PURE__ */ new Map();
27
+ constructor(entries = {}) {
28
+ for (const [name, cred] of Object.entries(entries)) this.#creds.set(name, cred);
29
+ }
30
+ get(bridgeName) {
31
+ return this.#creds.get(bridgeName);
32
+ }
33
+ set(bridgeName, cred) {
34
+ this.#creds.set(bridgeName, cred);
35
+ }
36
+ };
37
+
38
+ //#endregion
39
+ //#region ../../packages/substrate-core/src/memory-bridge-registry.ts
40
+ var DuplicateBridgeRegistration = class extends Error {
41
+ name = "DuplicateBridgeRegistration";
42
+ constructor(ns) {
43
+ super(`bridge already registered under namespace alias '${ns}'`);
44
+ }
45
+ };
46
+ var MemoryBridgeRegistry = class {
47
+ #bridges = /* @__PURE__ */ new Map();
48
+ register(ns, client) {
49
+ if (this.#bridges.has(ns)) throw new DuplicateBridgeRegistration(ns);
50
+ this.#bridges.set(ns, client);
51
+ }
52
+ unregister(ns) {
53
+ this.#bridges.delete(ns);
54
+ }
55
+ has(ns) {
56
+ return this.#bridges.has(ns);
57
+ }
58
+ get(ns) {
59
+ return this.#bridges.get(ns);
60
+ }
61
+ isUnreachable(ns) {
62
+ const client = this.#bridges.get(ns);
63
+ if (client === void 0) return false;
64
+ return !client.isReachable();
65
+ }
66
+ entries() {
67
+ return Array.from(this.#bridges.entries());
68
+ }
69
+ /** Dispose every registered bridge and clear the registry. Idempotent. */
70
+ dispose() {
71
+ for (const [, client] of this.#bridges) client.dispose();
72
+ this.#bridges.clear();
73
+ }
74
+ };
75
+
76
+ //#endregion
77
+ //#region ../../packages/substrate-core/src/memory-idempotency-store.ts
78
+ var MemoryIdempotencyStore = class {
79
+ #entries = /* @__PURE__ */ new Map();
80
+ #now;
81
+ constructor(options = {}) {
82
+ this.#now = options.now ?? (() => Date.now());
83
+ }
84
+ async get(key) {
85
+ const entry = this.#entries.get(key);
86
+ if (entry === void 0) return void 0;
87
+ if (entry.expiresAt <= this.#now()) {
88
+ this.#entries.delete(key);
89
+ return;
90
+ }
91
+ return entry.envelope;
92
+ }
93
+ async put(key, envelope, ttlMs) {
94
+ const now = this.#now();
95
+ const expiresAt = now + ttlMs;
96
+ const existing = this.#entries.get(key);
97
+ if (existing !== void 0 && existing.expiresAt > now) {
98
+ existing.expiresAt = Math.max(existing.expiresAt, expiresAt);
99
+ return;
100
+ }
101
+ this.#entries.set(key, {
102
+ envelope,
103
+ expiresAt
104
+ });
105
+ }
106
+ async reapExpired() {
107
+ const now = this.#now();
108
+ let deleted = 0;
109
+ for (const [key, entry] of this.#entries) if (entry.expiresAt <= now) {
110
+ this.#entries.delete(key);
111
+ deleted += 1;
112
+ }
113
+ return { deleted };
114
+ }
115
+ };
116
+
117
+ //#endregion
118
+ //#region ../../packages/substrate-dataset-pg/src/disk-guard.ts
119
+ function makeDiskGuard(opts) {
120
+ const { path, marginBytes } = opts;
121
+ const statfs$2 = opts.statfs ?? ((p) => statfs(p, { bigint: true }));
122
+ return {
123
+ path,
124
+ async check(estimateBytes) {
125
+ if (path === void 0) return { ok: true };
126
+ const s = await statfs$2(path);
127
+ const freeBytes = Number(s.bavail * s.bsize);
128
+ const needBytes = estimateBytes + marginBytes;
129
+ return freeBytes >= needBytes ? { ok: true } : {
130
+ ok: false,
131
+ freeBytes,
132
+ needBytes
133
+ };
134
+ }
135
+ };
136
+ }
137
+
138
+ //#endregion
139
+ //#region src/pg-client.ts
140
+ function formatPgNotice(notice) {
141
+ const candidate = typeof notice === "object" && notice !== null ? notice : null;
142
+ const message = typeof candidate?.message === "string" ? candidate.message : String(notice);
143
+ return `pg ${(typeof candidate?.severity === "string" ? candidate.severity : "NOTICE").toLowerCase()}: ${message}\n`;
144
+ }
145
+ /**
146
+ * The `onnotice` option, with an injectable sink so the routing is testable
147
+ * without opening a connection.
148
+ */
149
+ function pgNoticeOptions(write = (s) => void process.stderr.write(s)) {
150
+ return { onnotice: (notice) => write(formatPgNotice(notice)) };
151
+ }
152
+ /**
153
+ * Open a pg client with substrate's standard options. Prefer this over calling
154
+ * `postgres()` directly so NOTICE routing stays consistent across `serve`, the
155
+ * admin CLI, `substrate federate`, and the migrate CLI.
156
+ *
157
+ * `queueTimeoutMs` bounds how long a query, transaction or reserve waits for a
158
+ * free connection before it rejects with the driver's `QUEUE_TIMEOUT`. Unset,
159
+ * it waits as long as it takes.
160
+ */
161
+ function openSql(url, opts = {}) {
162
+ return postgres(url, {
163
+ ...pgNoticeOptions(),
164
+ ...opts.queueTimeoutMs !== void 0 ? { queue_timeout: opts.queueTimeoutMs / 1e3 } : {}
165
+ });
166
+ }
167
+
168
+ //#endregion
169
+ //#region src/admin/errors.ts
170
+ /**
171
+ * Shared CLI error carrying a process exit code. Used by `substrate-admin` and by
172
+ * the `substrate federate` verbs that write direct-to-pg.
173
+ */
174
+ var AdminCliError = class extends Error {
175
+ name = "AdminCliError";
176
+ exitCode;
177
+ constructor(message, exitCode = 1) {
178
+ super(message);
179
+ this.exitCode = exitCode;
180
+ }
181
+ };
182
+
183
+ //#endregion
184
+ //#region src/admin/usage.ts
185
+ /** The `--help` text, kept beside the dispatch that has to stay true to it. */
186
+ const USAGE = [
187
+ "Usage: substrate-admin <subcommand>",
188
+ " substrate-admin --version print the package version (also -v, version)",
189
+ "",
190
+ "Subcommands:",
191
+ " bootstrap [--encrypt] seed the genesis admin Key",
192
+ " doctor [--url <base>] check this deployment end to end and say what is wrong",
193
+ " onboard [--url <base>] [--check] walk a deployment to ready, offering to run each fix",
194
+ " list print active Key rows (DIRECT to pg — does not authenticate)",
195
+ " list --url <base> ask a SERVER over the admin-gated route (authenticates)",
196
+ " revoke <kid> soft-delete a Key by kid",
197
+ " rotate <kid> --out <path> [--encrypt] rotate a Key (new key to <path>)",
198
+ " register <kid> --pubkey <path> --ns <csv> register an existing ed25519 pubkey as an agent Key",
199
+ " update <kid> [--ns <csv>] ... change a live key's namespaces/caps/name in place",
200
+ " migrate-store [options] copy a store into a fresh, empty PG 18 store on per-type tables",
201
+ " promote-fields [--url <base>] run the promotion sweep now on a running server",
202
+ "",
203
+ " register transport: drives POST /substrate/v1/_system/keys (credential + directory row,",
204
+ " one transaction, no restart) using --url or SUBSTRATE_URL and an admin identity",
205
+ " (SUBSTRATE_ADMIN_TOKEN, or SUBSTRATE_ADMIN_KEY_PATH + SUBSTRATE_ADMIN_KEY_ID).",
206
+ " --direct forces the legacy direct-to-postgres write — break-glass only:",
207
+ " it needs the pg superuser password and CANNOT write the directory row.",
208
+ " register directory flags: --no-directory (credential only), --no-broadcast",
209
+ " (directory row with broadcastEligible false), --project <p>.",
210
+ " register flags: --ns <csv> is REQUIRED (use --ns '*' to grant every namespace);",
211
+ " --name <n> --caps <csv> --allow-admin are optional.",
212
+ " update flags: --name <n> --ns <csv> --caps <csv> --widen --allow-admin",
213
+ " omitted flags leave that field unchanged; --widen is required",
214
+ " only when the change grants authority the key does not have.",
215
+ " --ns entries may carry per-namespace capabilities:",
216
+ " --ns inventory:read,notes:read+mutate read inventory, write notes.",
217
+ " A bare entry takes --caps, so --ns notes is unchanged.",
218
+ " --allow-unknown-ns (register + update): confirm a grant naming a namespace",
219
+ " this deployment does not host. Without it such a grant is",
220
+ " refused, because it is accepted by the store and then",
221
+ " refused at every frame — it reads as granted and reaches",
222
+ " nothing. Pass it to register ahead of a plugin install.",
223
+ " TARGET (register / revoke / update): --url <base> goes through a running",
224
+ " server; --direct writes to SUBSTRATE_DATABASE_URL. Say neither and the",
225
+ " target comes from SUBSTRATE_URL, or from SUBSTRATE_DATABASE_URL when no",
226
+ " SUBSTRATE_URL is set. If BOTH are set and you name neither, the",
227
+ " command REFUSES rather than guessing — these are credential",
228
+ " writes and a silent choice can PATCH the wrong store. Every",
229
+ " run prints the target and where it came from before acting.",
230
+ " doctor goes through the running server on purpose: it is the one command that can",
231
+ " answer NO about auth. It checks reachability, whether the server verifies",
232
+ " credentials at all, whether YOUR admin credential resolves, whether the grant it",
233
+ " resolves to confers admin, and how many admin keys the deployment has left.",
234
+ " A check it could not run prints as `skip`, never as a pass.",
235
+ " promote-fields: gives each field added at runtime (propose_field) its own column now,",
236
+ " instead of at the next SUBSTRATE_PROMOTE_INTERVAL_MS sweep. Goes through the server",
237
+ " (--url or SUBSTRATE_URL) with an admin identity; prints one line per field touched,",
238
+ " and exits 1 when any failed. Also retries a field held back by a unique conflict,",
239
+ " which the timed sweep leaves until its type changes: run it after fixing the data.",
240
+ " --encrypt produces a PKCS#8+PBES2 (aes-256-cbc) encrypted private-key PEM.",
241
+ " Passphrase is read from SUBSTRATE_ADMIN_KEY_PASSPHRASE (required when --encrypt is set).",
242
+ " An encrypted admin key is read with SUBSTRATE_ADMIN_KEY_PASSPHRASE for every command that signs.",
243
+ " migrate-store: reads the source and target connection strings from environment variables,",
244
+ " SUBSTRATE_MIGRATE_FROM_URL and SUBSTRATE_MIGRATE_TO_URL unless --from-env / --to-env name",
245
+ " others; a connection string on argv is refused. Stop the service first. The source is",
246
+ " only read. The target must be empty and on PostgreSQL 18; it is prepared with the same",
247
+ " migrations and plugins (SUBSTRATE_PLUGIN_DIR) serve uses, copied, indexed and verified.",
248
+ " SUBSTRATE_INDEX_DISK_PATH must be set (the target volume mount, or off).",
249
+ " SUBSTRATE_SYSTEM_ACTOR is not needed: the prepare boot serves no request, so nothing is attributed to it.",
250
+ " The rest of the serve env (SUBSTRATE_*) is checked before preflight; a value serve would refuse exits 2.",
251
+ " --from-schema / --to-schema <s> pin a side to schema <s>",
252
+ " --dry-run preflight only: the plan, every refusal, nothing written",
253
+ " --verify-only build indexes, then verify a finished copy against its source",
254
+ " --skip-index-build leave non-unique index builds to the first serve boot",
255
+ " --full-checksum hash every row rather than a sample per type",
256
+ " --batch-rows <n> rows between progress lines (default 10000)",
257
+ " --skip-table <t> waive a source table nothing declares (repeatable)",
258
+ " --json the final report as one JSON object on stdout; progress is on stderr",
259
+ " Exit: 0 copied and verified; 2 refused or a usage error; 3 verification failed; 1 otherwise."
260
+ ].join("\n");
261
+ /** One-line synopsis per subcommand — the shape the operator typed wrong. */
262
+ const SYNOPSIS = {
263
+ bootstrap: "substrate-admin bootstrap [--encrypt]",
264
+ doctor: "substrate-admin doctor [--url <base> | --direct]",
265
+ onboard: "substrate-admin onboard [--url <base>] [--check]",
266
+ list: "substrate-admin list [--url <base>]",
267
+ revoke: "substrate-admin revoke <kid> [--url <base> | --direct]",
268
+ rotate: "substrate-admin rotate <kid> --out <path> [--encrypt]",
269
+ register: "substrate-admin register <kid> --pubkey <path> --ns <csv> [--name <n>] [--caps <csv>] [--allow-admin]",
270
+ update: "substrate-admin update <kid> [--name <n>] [--ns <csv>] [--caps <csv>] [--widen] [--allow-admin]",
271
+ "promote-fields": "substrate-admin promote-fields [--url <base>]",
272
+ "migrate-store": "substrate-admin migrate-store [--from-env <VAR>] [--to-env <VAR>] [--from-schema <s>] [--to-schema <s>] [--dry-run | --verify-only] [--skip-index-build] [--full-checksum] [--batch-rows <n>] [--skip-table <t>]... [--json]"
273
+ };
274
+ /**
275
+ * An argv-parse failure with the command's usage synopsis attached. Every
276
+ * throw inside a parse*Args function goes through here; run-phase errors keep
277
+ * bare messages because they name the refusing layer instead.
278
+ */
279
+ function argvError(cmd, message, exitCode = 1) {
280
+ const synopsis = SYNOPSIS[cmd];
281
+ return new AdminCliError(synopsis === void 0 ? message : `${message}\nusage: ${synopsis}`, exitCode);
282
+ }
283
+ /**
284
+ * Printed after every DIRECT-to-postgres credential write. No interceptor
285
+ * fires, so the running server does not see the change until its re-prime
286
+ * interval elapses or it restarts.
287
+ */
288
+ const RESTART_NOTE = [
289
+ "A RUNNING binary will not see this change until its registry re-primes —",
290
+ "restart it (e.g. `sudo systemctl restart substrate-binary`), or set",
291
+ "SUBSTRATE_KEY_REFRESH_INTERVAL_MS so it converges without one."
292
+ ].join("\n");
293
+
294
+ //#endregion
295
+ //#region src/admin/argv.ts
296
+ /**
297
+ * One argv contract for every subcommand, declared once.
298
+ *
299
+ * This owns exactly two questions: is this flag known, and is this positional
300
+ * one too many. Everything semantic stays with each parser — duplicate
301
+ * detection, mutual exclusion (`--direct` vs `--url`), required flags, value
302
+ * SHAPES, and missing required positionals.
303
+ */
304
+ /**
305
+ * The subcommands, and the whole of what each accepts.
306
+ *
307
+ * This table is also the definition of "known command": `main` refuses anything
308
+ * absent from it BEFORE dispatching, so a subcommand added to the dispatch
309
+ * switch without an entry here does not run at all.
310
+ *
311
+ * Per-command wording (`hint`, `excess`) and `list`'s `--url=` form are
312
+ * deliberate and pinned by tests.
313
+ */
314
+ const ARGV_SPEC = {
315
+ bootstrap: {
316
+ valueFlags: [],
317
+ boolFlags: ["--encrypt"],
318
+ maxPositionals: 0
319
+ },
320
+ doctor: {
321
+ valueFlags: ["--url"],
322
+ boolFlags: ["--direct"],
323
+ maxPositionals: 0,
324
+ hint: " (accepts --url <base> or --direct)",
325
+ excess: (tok) => `doctor: unexpected argument '${tok}' (accepts --url <base> or --direct)`
326
+ },
327
+ onboard: {
328
+ valueFlags: ["--url"],
329
+ boolFlags: ["--direct", "--check"],
330
+ maxPositionals: 0,
331
+ hint: " (accepts --url <base> and --check)",
332
+ excess: (tok) => `onboard: unexpected argument '${tok}' (accepts --url <base> and --check)`
333
+ },
334
+ list: {
335
+ valueFlags: ["--url"],
336
+ boolFlags: [],
337
+ maxPositionals: 0,
338
+ hint: " (list accepts only --url <base>)",
339
+ excess: (tok) => `list: unexpected argument '${tok}' (list accepts only --url <base>)`,
340
+ equalsForm: true
341
+ },
342
+ revoke: {
343
+ valueFlags: ["--url"],
344
+ boolFlags: ["--direct"],
345
+ maxPositionals: 1,
346
+ excess: (tok) => `revoke: unexpected extra argument '${tok}' — one <kid> at a time`
347
+ },
348
+ rotate: {
349
+ valueFlags: ["--out"],
350
+ boolFlags: ["--encrypt"],
351
+ maxPositionals: 1
352
+ },
353
+ register: {
354
+ valueFlags: [
355
+ "--pubkey",
356
+ "--name",
357
+ "--ns",
358
+ "--caps",
359
+ "--url",
360
+ "--project"
361
+ ],
362
+ boolFlags: [
363
+ "--allow-admin",
364
+ "--allow-unknown-ns",
365
+ "--direct",
366
+ "--no-directory",
367
+ "--no-broadcast"
368
+ ],
369
+ maxPositionals: 1
370
+ },
371
+ update: {
372
+ valueFlags: [
373
+ "--name",
374
+ "--ns",
375
+ "--caps",
376
+ "--url"
377
+ ],
378
+ boolFlags: [
379
+ "--direct",
380
+ "--allow-unknown-ns",
381
+ "--widen",
382
+ "--allow-admin"
383
+ ],
384
+ maxPositionals: 1
385
+ },
386
+ "promote-fields": {
387
+ valueFlags: ["--url"],
388
+ boolFlags: [],
389
+ maxPositionals: 0,
390
+ hint: " (promote-fields accepts only --url <base>)",
391
+ excess: (tok) => `promote-fields: unexpected argument '${tok}' (promote-fields accepts only --url <base>)`
392
+ },
393
+ "migrate-store": {
394
+ valueFlags: [
395
+ "--from-env",
396
+ "--to-env",
397
+ "--from-schema",
398
+ "--to-schema",
399
+ "--batch-rows",
400
+ "--skip-table"
401
+ ],
402
+ boolFlags: [
403
+ "--dry-run",
404
+ "--verify-only",
405
+ "--json",
406
+ "--skip-index-build",
407
+ "--full-checksum"
408
+ ],
409
+ maxPositionals: 0,
410
+ hint: " (connection strings never go on argv: name their environment variables with --from-env / --to-env)",
411
+ excess: (tok) => `migrate-store: unexpected argument '${tok}' (connection strings never go on argv: name their environment variables with --from-env / --to-env)`,
412
+ exitCode: 2
413
+ }
414
+ };
415
+ /** A command with no descriptor accepts nothing at all. */
416
+ const FAIL_CLOSED = {
417
+ valueFlags: [],
418
+ boolFlags: [],
419
+ maxPositionals: 0
420
+ };
421
+ /**
422
+ * Refuse unknown flags and surplus positionals for `cmd`, given its tail
423
+ * (argv WITHOUT the subcommand name).
424
+ *
425
+ * Pure and idempotent, which is why it is safe to call from both `main` —
426
+ * once, before dispatch — and from each `parse*Args`. The parsers are exported
427
+ * from `bin/substrate-admin.ts` and called directly, so they cannot delegate their
428
+ * guarantee to a caller they do not have.
429
+ */
430
+ function validateArgv(cmd, tail) {
431
+ const spec = ARGV_SPEC[cmd] ?? FAIL_CLOSED;
432
+ let positionals = 0;
433
+ for (let i = 0; i < tail.length; i++) {
434
+ const tok = tail[i];
435
+ if (tok === void 0) continue;
436
+ if (tok.startsWith("--")) {
437
+ if (spec.valueFlags.includes(tok)) {
438
+ const next = tail[i + 1];
439
+ const nextIsKnownFlag = next !== void 0 && (spec.valueFlags.includes(next) || spec.boolFlags.includes(next));
440
+ if (next !== void 0 && !nextIsKnownFlag) i += 1;
441
+ continue;
442
+ }
443
+ if (spec.boolFlags.includes(tok)) continue;
444
+ if (spec.equalsForm === true && spec.valueFlags.some((f) => tok.startsWith(`${f}=`))) continue;
445
+ throw argvError(cmd, `${cmd}: unknown flag ${tok}${spec.hint ?? ""}`, spec.exitCode ?? 1);
446
+ }
447
+ positionals += 1;
448
+ if (positionals > spec.maxPositionals) throw argvError(cmd, spec.excess?.(tok) ?? `${cmd}: unexpected positional arg '${tok}'`, spec.exitCode ?? 1);
449
+ }
450
+ }
451
+
452
+ //#endregion
453
+ //#region src/admin/identity.ts
454
+ /**
455
+ * WHICH store a credential write lands in, and WHICH identity signs it —
456
+ * each resolved explicitly and reported with where the choice came from.
457
+ */
458
+ /**
459
+ * Resolve the target for `update` / `revoke` / `register`.
460
+ *
461
+ * `explicitUrl` is the parser's tri-state: a base URL from `--url`, the empty
462
+ * string from `--direct`, and `null` for "said nothing".
463
+ *
464
+ * When both `SUBSTRATE_URL` and `SUBSTRATE_DATABASE_URL` are set ambiently and no flag
465
+ * chooses, this throws naming both escape hatches rather than picking: they
466
+ * name two different stores, and a credential write to the wrong one can
467
+ * succeed.
468
+ */
469
+ function resolveAdminTarget(explicitUrl, env) {
470
+ if (explicitUrl !== null) return explicitUrl.length > 0 ? {
471
+ kind: "route",
472
+ baseUrl: explicitUrl,
473
+ source: "flag"
474
+ } : {
475
+ kind: "direct",
476
+ source: "flag"
477
+ };
478
+ const ambientUrl = env.SUBSTRATE_URL !== void 0 && env.SUBSTRATE_URL.length > 0 ? env.SUBSTRATE_URL : null;
479
+ const ambientStore = env.SUBSTRATE_DATABASE_URL !== void 0 && env.SUBSTRATE_DATABASE_URL.length > 0 ? env.SUBSTRATE_DATABASE_URL : null;
480
+ if (ambientUrl !== null && ambientStore !== null) throw new AdminCliError(`two targets given and neither was chosen: SUBSTRATE_URL names a running server (${ambientUrl}) and SUBSTRATE_DATABASE_URL names a postgres store. This is a credential write, so it will not guess. Pass \`--url <base>\` to go through the server, or \`--direct\` to write to SUBSTRATE_DATABASE_URL.`, 1);
481
+ return ambientUrl !== null ? {
482
+ kind: "route",
483
+ baseUrl: ambientUrl,
484
+ source: "env"
485
+ } : {
486
+ kind: "direct",
487
+ source: "fallback"
488
+ };
489
+ }
490
+ /**
491
+ * One line, printed BEFORE the write, naming the destination and its
492
+ * provenance, so a misdirected command is self-diagnosing.
493
+ */
494
+ function describeAdminTarget(command, target) {
495
+ if (target.kind === "route") {
496
+ const from = target.source === "flag" ? "--url" : "SUBSTRATE_URL";
497
+ return `${command}: targeting ${target.baseUrl} (from ${from})`;
498
+ }
499
+ return `${command}: targeting the postgres store DIRECTLY, bypassing the running server (from ${target.source === "flag" ? "--direct" : "SUBSTRATE_DATABASE_URL"})`;
500
+ }
501
+ /**
502
+ * Build the `Authorization` value for an admin route at `baseUrl`, or explain
503
+ * what to set. A minted token names `baseUrl`'s origin as its `aud`; a
504
+ * `baseUrl` that is plain http to a non-loopback host is refused.
505
+ *
506
+ * Fail-loud: a message naming the missing key is more use than the 401 an
507
+ * unauthenticated admin call would get.
508
+ */
509
+ function resolveAdminAuth(env, baseUrl) {
510
+ let audience;
511
+ try {
512
+ audience = tokenAudience(baseUrl);
513
+ } catch (err) {
514
+ return { error: err instanceof Error ? err.message : String(err) };
515
+ }
516
+ const cred = resolveAdminCredential(env);
517
+ if (cred.kind === "error") return { error: cred.error };
518
+ if (cred.kind === "token") return { ok: cred.authorization };
519
+ const passphrase = env.SUBSTRATE_ADMIN_KEY_PASSPHRASE !== void 0 && env.SUBSTRATE_ADMIN_KEY_PASSPHRASE.length > 0 ? { passphrase: env.SUBSTRATE_ADMIN_KEY_PASSPHRASE } : {};
520
+ try {
521
+ return { ok: makeAuthorizationProvider({
522
+ keyPath: cred.keyPath,
523
+ kid: cred.kid
524
+ }, {
525
+ capabilities: adminClaimCapabilities(env),
526
+ audience,
527
+ ...passphrase
528
+ })() };
529
+ } catch (err) {
530
+ return { error: `could not sign with ${cred.keyPath}: ${err instanceof Error ? err.message : err}` };
531
+ }
532
+ }
533
+
534
+ //#endregion
535
+ //#region src/admin/keys.ts
536
+ /**
537
+ * Key row plumbing shared by every subcommand: reading rows, classifying
538
+ * the admin ones, minting keypairs, and the write-attribution hint.
539
+ *
540
+ * `listActiveAdminKeys` classifies through `isActiveAdminKeyRow` rather than
541
+ * reading the flat `capabilities` column: a key stored
542
+ * `namespaces: '*:read+mutate+admin'` carries no `admin` in `capabilities`
543
+ * and is nonetheless an admin.
544
+ */
545
+ /** Sentinel `actorKid` stamped on every audit row emitted by this CLI. */
546
+ const CLI_ACTOR_KID = "substrate-admin-cli";
547
+ /**
548
+ * Substrate auto-fill hint for every `_system` write this CLI makes. Without
549
+ * it the row metadata (`createdBy` / `updatedBy`) lands NULL.
550
+ *
551
+ * `kind: 'system'` rather than `'agent'`: this is a component acting, not a
552
+ * registered identity signing.
553
+ */
554
+ const ACTOR_HINT = { identity: {
555
+ kind: "system",
556
+ id: CLI_ACTOR_KID
557
+ } };
558
+ /**
559
+ * Strip `_metadata` from a row read back for update, so the write's
560
+ * {@link ACTOR_HINT} actually takes effect.
561
+ *
562
+ * A dataset auto-fills metadata from `options.identity` only when the
563
+ * incoming row has NO `_metadata`, so a row built as `{ ...existing.row, ... }`
564
+ * would silently keep the previous `updatedBy`.
565
+ *
566
+ * Stripping is safe and does not lose `createdBy`: the dataset merges per-field
567
+ * against the STORED row (`createdBy: existing.createdBy ?? incoming.createdBy`),
568
+ * so `created*` survive from storage while `updated*` come from the hint.
569
+ */
570
+ function forUpdate(row) {
571
+ const { _metadata: _dropped, ...rest } = row;
572
+ return rest;
573
+ }
574
+ /**
575
+ * Mint an ed25519 keypair for `bootstrap` / `rotate`. When `wantsEncrypt` is
576
+ * true, the private-key PEM is PKCS#8+PBES2 (aes-256-cbc) encrypted with
577
+ * `SUBSTRATE_ADMIN_KEY_PASSPHRASE` — the env var MUST be set to a non-empty value
578
+ * or this helper hard-errors. When false, the PEM is cleartext PKCS#8.
579
+ *
580
+ * At-rest encryption is purely operator-side: the server only ever reads the
581
+ * public key from pg, so the encrypted-ness of the on-disk private key has no
582
+ * server-side coupling.
583
+ */
584
+ function generateAdminKeypair(env, wantsEncrypt) {
585
+ if (wantsEncrypt) {
586
+ const passphrase = env.SUBSTRATE_ADMIN_KEY_PASSPHRASE;
587
+ if (passphrase === void 0 || passphrase.length === 0) throw new AdminCliError("--encrypt requires SUBSTRATE_ADMIN_KEY_PASSPHRASE to be set to a non-empty value", 6);
588
+ const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
589
+ publicKeyEncoding: {
590
+ format: "pem",
591
+ type: "spki"
592
+ },
593
+ privateKeyEncoding: {
594
+ format: "pem",
595
+ type: "pkcs8",
596
+ cipher: "aes-256-cbc",
597
+ passphrase
598
+ }
599
+ });
600
+ return {
601
+ publicKeyPem: publicKey.toString(),
602
+ privateKeyPem: privateKey.toString(),
603
+ encrypted: true
604
+ };
605
+ }
606
+ const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
607
+ publicKeyEncoding: {
608
+ format: "pem",
609
+ type: "spki"
610
+ },
611
+ privateKeyEncoding: {
612
+ format: "pem",
613
+ type: "pkcs8"
614
+ }
615
+ });
616
+ return {
617
+ publicKeyPem: publicKey.toString(),
618
+ privateKeyPem: privateKey.toString(),
619
+ encrypted: false
620
+ };
621
+ }
622
+ var BootstrapError = class extends Error {
623
+ name = "BootstrapError";
624
+ exitCode;
625
+ constructor(message, exitCode = 1) {
626
+ super(message);
627
+ this.exitCode = exitCode;
628
+ }
629
+ };
630
+ function base64Url(buf) {
631
+ return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
632
+ }
633
+ function rowAsAdminKey(row) {
634
+ const kid = row.kid;
635
+ if (typeof kid !== "string" || kid.length === 0) return null;
636
+ return {
637
+ kid,
638
+ name: typeof row.name === "string" ? row.name : "",
639
+ namespaces: typeof row.namespaces === "string" ? row.namespaces : "",
640
+ capabilities: typeof row.capabilities === "string" ? row.capabilities : "",
641
+ createdAt: row._metadata?.createdAt ?? null
642
+ };
643
+ }
644
+ /**
645
+ * Read every non-revoked Key row whose grant confers `adminCapability`
646
+ * on `_system` (per `isActiveAdminKeyRow`). Scans the whole table, which is
647
+ * fine at CLI cadence.
648
+ */
649
+ async function listActiveAdminKeys(dataset, adminCapability) {
650
+ const { rows } = await dataset.read("Key", {});
651
+ const out = [];
652
+ for (const row of rows) {
653
+ if (!isActiveAdminKeyRow(row, adminCapability)) continue;
654
+ const ak = rowAsAdminKey(row);
655
+ if (ak === null) continue;
656
+ out.push(ak);
657
+ }
658
+ return out;
659
+ }
660
+ /**
661
+ * `bootstrap`-specific helper: first matching admin row or `null`. Wraps
662
+ * `listActiveAdminKeys` so the bootstrap contract ("refuse if ANY admin row
663
+ * exists") doesn't leak the array shape out of this module.
664
+ */
665
+ async function firstAdminKey(dataset, adminCapability) {
666
+ return (await listActiveAdminKeys(dataset, adminCapability))[0] ?? null;
667
+ }
668
+ /** The capability name that means "admin" when `SUBSTRATE_ADMIN_CAPABILITY` is unset. */
669
+ const DEFAULT_ADMIN_CAPABILITY = "admin";
670
+ async function readKeyById(dataset, kid) {
671
+ const { rows } = await dataset.read("Key", { where: { kid: { eq: kid } } });
672
+ const row = rows.find((r) => r.revokedAt == null) ?? rows[0];
673
+ if (row === void 0) return null;
674
+ return {
675
+ row,
676
+ revokedAt: row.revokedAt instanceof Date ? row.revokedAt : typeof row.revokedAt === "string" ? row.revokedAt : null
677
+ };
678
+ }
679
+ /**
680
+ * Read a public-key PEM from disk and assert it is Ed25519. Returns the PEM
681
+ * text verbatim for storage on the Key row. Throws AdminCliError(2) on a
682
+ * missing/unreadable file, a private-key PEM (missing `BEGIN PUBLIC KEY`
683
+ * header — prevents accidental private-key leakage when the operator passes
684
+ * the wrong file to `--pubkey`), an unparseable PEM, or a non-ed25519 key.
685
+ * `register` only mints/accepts Ed25519 agent identities (the one alg the
686
+ * verifier + signer support).
687
+ */
688
+ function readEd25519PublicKey(path) {
689
+ let pem;
690
+ try {
691
+ pem = readFileSync(path, "utf8");
692
+ } catch (err) {
693
+ const msg = err instanceof Error ? err.message : String(err);
694
+ throw new AdminCliError(`register: cannot read --pubkey '${path}': ${msg}`, 2);
695
+ }
696
+ if (!pem.includes("BEGIN PUBLIC KEY")) throw new AdminCliError(`register: --pubkey '${path}' is not a public-key PEM (missing 'BEGIN PUBLIC KEY' header) — did you pass the private key by mistake?`, 2);
697
+ let keyType;
698
+ try {
699
+ keyType = createPublicKey(pem).asymmetricKeyType;
700
+ } catch (err) {
701
+ const msg = err instanceof Error ? err.message : String(err);
702
+ throw new AdminCliError(`register: --pubkey '${path}' is not a valid public key: ${msg}`, 2);
703
+ }
704
+ if (keyType !== "ed25519") throw new AdminCliError(`register: --pubkey '${path}' is ${keyType ?? "unknown"}, expected ed25519`, 2);
705
+ return pem;
706
+ }
707
+
708
+ //#endregion
709
+ //#region src/admin/route.ts
710
+ /**
711
+ * Driving the admin-gated `PATCH /substrate/v1/_system/keys` route, and the refusal ->
712
+ * exit-code maps that go with it.
713
+ *
714
+ * The route is the DEFAULT for every mutating subcommand and `--direct` is what
715
+ * an operator has to type, because a direct write leaves the running server's
716
+ * registry stale — for `revoke` that means the credential keeps authenticating.
717
+ */
718
+ /**
719
+ * Drive `PATCH /substrate/v1/_system/keys`. A write through the engine reaches the
720
+ * running server's key registry; a direct write does not.
721
+ *
722
+ * Refusals come back with the same `code` the CLI's own guards produce,
723
+ * because both sides ask `key-guards`. Statuses are mapped back to the
724
+ * same exit codes so scripts do not care which transport ran.
725
+ */
726
+ async function runKeyPatchViaRoute(body, baseUrl, env, exitCodes, fetchImpl = substrateFetch) {
727
+ const auth = resolveAdminAuth(env, baseUrl);
728
+ if ("error" in auth) throw new AdminCliError(`${body.revoke === true ? "revoke" : "update"}: ${auth.error}`, 1);
729
+ const url = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
730
+ let res;
731
+ try {
732
+ res = await fetchImpl(url, {
733
+ method: "PATCH",
734
+ headers: {
735
+ "content-type": "application/json",
736
+ authorization: auth.ok
737
+ },
738
+ body: JSON.stringify(body),
739
+ redirect: "error"
740
+ });
741
+ } catch (err) {
742
+ throw new AdminCliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, 1);
743
+ }
744
+ const payload = await res.json().catch(() => ({}));
745
+ if (!res.ok) {
746
+ const code = typeof payload.code === "string" ? payload.code : "request_failed";
747
+ const message = failureText(payload, res.status);
748
+ throw new AdminCliError(message, exitCodes[code] ?? 1);
749
+ }
750
+ return payload;
751
+ }
752
+ /**
753
+ * `revoke` refusal code -> CLI exit code. The route maps the same reasons to
754
+ * HTTP statuses. Values are stable: scripts key on them.
755
+ */
756
+ const REVOKE_EXIT_CODES = {
757
+ unknown_kid: 2,
758
+ already_revoked: 3,
759
+ last_active_admin: 4
760
+ };
761
+ /**
762
+ * `update` refusal code -> CLI exit code. Values are stable: scripts key on
763
+ * them. Guards, in the order they fire:
764
+ * - unknown kid → exit 2; revoked kid → exit 3 (updating a revoked key would
765
+ * be a quiet way to resurrect a retired identity)
766
+ * - dropping admin from the last active admin → exit 4, mirroring `revoke`'s
767
+ * lockout guard. Fires BEFORE the widen gate: it cannot be lifted by a flag,
768
+ * and one request can trip both.
769
+ * - a change that GRANTS authority the key lacks → exit 5 unless `--widen`
770
+ * - granting `admin` → additionally requires `--allow-admin`, mirroring
771
+ * `register`
772
+ */
773
+ const UPDATE_EXIT_CODES = {
774
+ unknown_kid: 2,
775
+ already_revoked: 3,
776
+ last_active_admin: 4,
777
+ last_admin_deadmin: 4,
778
+ requires_widen: 5,
779
+ requires_allow_admin: 1,
780
+ invalid_grant: 1
781
+ };
782
+ /**
783
+ * Drive `GET /substrate/v1/_system/keys` — the authenticated read behind
784
+ * `list --url`, gated by the server's admin check.
785
+ *
786
+ * Pages to exhaustion rather than returning the first page: a silently
787
+ * truncated answer to "which identities exist" is worse than an error.
788
+ */
789
+ async function runKeyListViaRoute(baseUrl, env, fetchImpl = substrateFetch) {
790
+ const auth = resolveAdminAuth(env, baseUrl);
791
+ if ("error" in auth) throw new AdminCliError(`list: ${auth.error}`, 1);
792
+ const base = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
793
+ const keys = [];
794
+ let cursor;
795
+ for (let page = 0; page < 50; page += 1) {
796
+ const url = cursor === void 0 ? base : `${base}?cursor=${encodeURIComponent(cursor)}`;
797
+ let res;
798
+ try {
799
+ res = await fetchImpl(url, {
800
+ method: "GET",
801
+ headers: { authorization: auth.ok },
802
+ redirect: "error"
803
+ });
804
+ } catch (err) {
805
+ throw new AdminCliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, 1);
806
+ }
807
+ const payload = await res.json().catch(() => ({}));
808
+ if (!res.ok) {
809
+ const message = failureText(payload, res.status);
810
+ throw new AdminCliError(res.status === 403 ? `list --url: refused by ${baseUrl} — ${message}\n This is the server's verdict on the credential you presented, which is exactly what \`list\` without --url cannot tell you.` : `list --url: ${message}`, res.status === 403 ? 5 : 1);
811
+ }
812
+ const batch = payload.keys;
813
+ if (!Array.isArray(batch)) throw new AdminCliError("list --url: response carried no `keys` array", 1);
814
+ keys.push(...batch);
815
+ if (payload.hasMore !== true) return keys;
816
+ cursor = typeof payload.nextCursor === "string" ? payload.nextCursor : void 0;
817
+ if (cursor === void 0) throw new AdminCliError("list --url: server reported hasMore with no nextCursor — refusing to report a partial list as complete", 1);
818
+ }
819
+ throw new AdminCliError("list --url: pagination did not terminate after 50 pages", 1);
820
+ }
821
+ /** A refusal body as one line: its `message`, else `code (reason): detail`, else the status. */
822
+ function failureText(payload, status) {
823
+ if (typeof payload.message === "string") return payload.message;
824
+ if (typeof payload.code !== "string") return `HTTP ${status}`;
825
+ const reason = typeof payload.reason === "string" ? ` (${payload.reason})` : "";
826
+ const detail = typeof payload.detail === "string" ? `: ${payload.detail}` : "";
827
+ return `${payload.code}${reason}${detail}`;
828
+ }
829
+
830
+ //#endregion
831
+ //#region src/admin/env.ts
832
+ /**
833
+ * Where the admin CLI's key files live, and the env it reads them from.
834
+ *
835
+ * These resolvers live together because they answer one question — *which
836
+ * file is this deployment's admin identity?* — and `bootstrap` (the writer)
837
+ * and `resolveAdminAuth` (the reader) must agree on it.
838
+ */
839
+ /**
840
+ * Where `bootstrap` writes the kid. Beside the key when one was named
841
+ * explicitly, else the default path.
842
+ */
843
+ function bootstrapKidPath(env) {
844
+ return env.SUBSTRATE_ADMIN_KEY_PATH !== void 0 && env.SUBSTRATE_ADMIN_KEY_PATH.length > 0 ? `${resolveDefaultKeyPath(env).replace(/\.key$/, "")}.kid` : resolveDefaultKidPath(env);
845
+ }
846
+
847
+ //#endregion
848
+ //#region src/admin/commands/bootstrap.ts
849
+ /**
850
+ * `bootstrap` — seed the genesis admin Key on a fresh `_system` namespace.
851
+ *
852
+ * The one subcommand that CANNOT go through the route: it exists to create the
853
+ * first admin identity, so there is none to present. Direct-to-postgres is not
854
+ * a legacy path here, it is the only possible one.
855
+ */
856
+ /**
857
+ * What the genesis row grants: the admin capability plus `read` / `mutate`.
858
+ *
859
+ * `resolveAdminAuth` mints with `adminClaimCapabilities`, a superset of this
860
+ * row for any `adminCapability`, and `auth.ts` intersects that claim against
861
+ * the row, so the row is the ceiling. Derived from the same constant so the
862
+ * two cannot drift; `admin` alone does not satisfy the per-frame `read` /
863
+ * `mutate` gates.
864
+ */
865
+ function seedCapabilities(adminCapability) {
866
+ return [...ADMIN_CAPABILITIES.filter((c) => c !== DEFAULT_ADMIN_CAPABILITY), adminCapability];
867
+ }
868
+ /**
869
+ * Perform the bootstrap.
870
+ *
871
+ * `wantsEncrypt` controls whether the on-disk private-key PEM is
872
+ * PBES2-encrypted with `SUBSTRATE_ADMIN_KEY_PASSPHRASE`. Defaults to false.
873
+ */
874
+ async function runBootstrap(env, wantsEncrypt = false, openSql = postgres) {
875
+ const storeSpec = env.SUBSTRATE_DATABASE_URL;
876
+ if (storeSpec === void 0 || storeSpec.length === 0) throw new BootstrapError("SUBSTRATE_DATABASE_URL is required (must be a postgres:// URL)");
877
+ if (!storeSpec.startsWith("postgres://") && !storeSpec.startsWith("postgresql://")) throw new BootstrapError(`SUBSTRATE_DATABASE_URL must be a postgres:// URL for bootstrap (got '${redactStore(storeSpec)}'). Memory-backed stores cannot persist the admin key across restarts.`);
878
+ const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : DEFAULT_ADMIN_CAPABILITY;
879
+ const seededCapabilities = seedCapabilities(adminCapability);
880
+ const privateKeyPath = resolveDefaultKeyPath(env);
881
+ if (existsSync(privateKeyPath)) throw new BootstrapError(`private key path '${privateKeyPath}' already exists — move it aside and retry`);
882
+ const kidPath = bootstrapKidPath(env);
883
+ if (existsSync(kidPath)) throw new BootstrapError(`kid path '${kidPath}' already exists — move it aside and retry`);
884
+ const { publicKeyPem, privateKeyPem, encrypted } = generateAdminKeypair(env, wantsEncrypt);
885
+ const sql = openSql(storeSpec);
886
+ let dataset;
887
+ try {
888
+ await assertNotMigrating(sql);
889
+ await runMigrations(sql);
890
+ dataset = new PgDataset({
891
+ namespace: SYSTEM_NAMESPACE,
892
+ sql,
893
+ typeDefLookup: systemTypeDefLookup
894
+ });
895
+ await dataset.ensureTypeStorage("Key");
896
+ return await dataset.withAdvisoryLock("substrate:bootstrap", async () => {
897
+ const existing = await firstAdminKey(dataset, adminCapability);
898
+ if (existing !== null) throw new BootstrapError(`admin Key already bootstrapped (kid: ${existing.kid}). Revoke or purge it via the _system namespace before running bootstrap again.`);
899
+ const kid = randomUUID();
900
+ const shaFull = createHash("sha256").update(publicKeyPem).digest();
901
+ const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
902
+ const parentDir = dirname(privateKeyPath);
903
+ mkdirSync(parentDir, {
904
+ recursive: true,
905
+ mode: 448
906
+ });
907
+ const files = [[
908
+ privateKeyPath,
909
+ `${privateKeyPath}.tmp-${randomUUID()}`,
910
+ privateKeyPem
911
+ ], [
912
+ kidPath,
913
+ `${kidPath}.tmp-${randomUUID()}`,
914
+ `${kid}\n`
915
+ ]];
916
+ const removeTemps = () => {
917
+ for (const [, temp] of files) rmSync(temp, { force: true });
918
+ };
919
+ try {
920
+ for (const [, temp, content] of files) writeFileSync(temp, content, {
921
+ mode: 384,
922
+ flag: "wx"
923
+ });
924
+ const now = /* @__PURE__ */ new Date();
925
+ await dataset.write("Key", [{
926
+ id: kid,
927
+ kid,
928
+ name: "bootstrap-admin",
929
+ algorithm: "EdDSA",
930
+ publicKey: publicKeyPem,
931
+ namespaces: "*",
932
+ capabilities: encodeList(seededCapabilities),
933
+ revokedAt: null
934
+ }], {
935
+ identity: {
936
+ kind: "system",
937
+ id: "bootstrap"
938
+ },
939
+ now
940
+ });
941
+ } catch (err) {
942
+ removeTemps();
943
+ throw err;
944
+ }
945
+ try {
946
+ for (const [final, temp] of files) linkSync(temp, final);
947
+ } finally {
948
+ removeTemps();
949
+ }
950
+ return {
951
+ kid,
952
+ fingerprint,
953
+ privateKeyPath,
954
+ namespaces: "*",
955
+ capabilities: seededCapabilities.join(","),
956
+ encrypted
957
+ };
958
+ });
959
+ } finally {
960
+ try {
961
+ await sql.end();
962
+ } catch {}
963
+ }
964
+ }
965
+ function formatBootstrapOutput(result) {
966
+ const encLabel = result.encrypted ? "encrypted: aes-256-cbc+pbes2" : "unencrypted";
967
+ return [
968
+ "substrate-admin bootstrap complete.",
969
+ `kid: ${result.kid}`,
970
+ `fingerprint: ${result.fingerprint}`,
971
+ `private key: ${result.privateKeyPath} (mode 0600, ${encLabel})`,
972
+ `namespaces: ${result.namespaces}`,
973
+ `capabilities: ${result.capabilities}`,
974
+ "",
975
+ `Use the private key to sign JWTs with kid=${result.kid} to authenticate as admin.`,
976
+ "",
977
+ RESTART_NOTE,
978
+ ""
979
+ ].join("\n");
980
+ }
981
+ function parseBootstrapArgs(argv) {
982
+ try {
983
+ return parseBootstrapArgsInner(argv);
984
+ } catch (err) {
985
+ if (err instanceof AdminCliError) throw argvError("bootstrap", err.message, err.exitCode);
986
+ throw err;
987
+ }
988
+ }
989
+ function parseBootstrapArgsInner(argv) {
990
+ const rest = argv.slice(1);
991
+ validateArgv("bootstrap", rest);
992
+ let wantsEncrypt = false;
993
+ for (const tok of rest) if (tok === "--encrypt") {
994
+ if (wantsEncrypt) throw new AdminCliError("bootstrap: --encrypt specified more than once", 1);
995
+ wantsEncrypt = true;
996
+ }
997
+ return { wantsEncrypt };
998
+ }
999
+
1000
+ //#endregion
1001
+ //#region src/admin/commands/doctor.ts
1002
+ /**
1003
+ * `substrate-admin doctor` — diagnoses an admin deployment through checks that
1004
+ * can each answer NO.
1005
+ *
1006
+ * 1. **Route-only.** Every auth claim is checked through the running server;
1007
+ * a direct postgres read never authenticates, so it cannot test auth.
1008
+ * 2. **A SKIP is not an OK.** A check whose precondition failed renders as
1009
+ * `skip` with the reason — never as a pass, and never omitted.
1010
+ * 3. **Shared classifiers.** Admin checks use `isActiveAdminKeyRow` and
1011
+ * `capabilitiesFor`, the same predicates the server's guards use, so the
1012
+ * doctor cannot agree with a copy that has drifted from the guard.
1013
+ */
1014
+ /** The NO a non-route target gets: doctor and onboard both refuse to measure through postgres. */
1015
+ const DIRECT_TARGET_REFUSAL = {
1016
+ name: "target",
1017
+ status: "no",
1018
+ detail: "resolved to the postgres store, bypassing the running server. Nothing below can be measured from there: a direct read never authenticates, so it answers a different question from the one you asked (this is what made `substrate-admin list` misleading — it printed the admin row while admin auth was broken).",
1019
+ fix: "Pass `--url <base>`, or set SUBSTRATE_URL, so the checks go through the server that is doing the refusing."
1020
+ };
1021
+ /**
1022
+ * Runs every check against `target`, in dependency order. A failure
1023
+ * short-circuits its dependants into explicit skips.
1024
+ */
1025
+ async function runDoctor(env, target, fetchImpl = substrateFetch) {
1026
+ if (target.kind !== "route") return {
1027
+ checks: [DIRECT_TARGET_REFUSAL, ...DIAGNOSE_CHECKS.map((name) => ({
1028
+ name,
1029
+ status: "skip",
1030
+ detail: "not asked — target answered no"
1031
+ }))],
1032
+ exitCode: 1
1033
+ };
1034
+ const result = await diagnoseTarget(env, target.baseUrl, fetchImpl);
1035
+ return {
1036
+ checks: [{
1037
+ name: "target",
1038
+ status: "ok",
1039
+ detail: describeAdminTarget("doctor", target).replace(/^doctor: /, "")
1040
+ }, ...result.checks],
1041
+ exitCode: result.exitCode
1042
+ };
1043
+ }
1044
+ /** Diagnose `baseUrl` with the admin credential `env` resolves — shared by doctor and onboard. */
1045
+ async function diagnoseTarget(env, baseUrl, fetchImpl = substrateFetch) {
1046
+ const auth = resolveAdminAuth(env, baseUrl);
1047
+ return diagnose({
1048
+ baseUrl,
1049
+ credential: "error" in auth ? { error: auth.error } : {
1050
+ authorization: () => auth.ok,
1051
+ label: describeCredential(env)
1052
+ },
1053
+ ...env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? { adminCapability: env.SUBSTRATE_ADMIN_CAPABILITY } : {},
1054
+ fetch: (input, init) => fetchImpl(input, {
1055
+ ...init,
1056
+ redirect: "error"
1057
+ })
1058
+ });
1059
+ }
1060
+ /** Which credential the run used, without printing any of it. */
1061
+ function describeCredential(env) {
1062
+ if (env.SUBSTRATE_ADMIN_TOKEN !== void 0 && env.SUBSTRATE_ADMIN_TOKEN.length > 0) return "SUBSTRATE_ADMIN_TOKEN";
1063
+ return `${env.SUBSTRATE_ADMIN_KEY_PATH !== void 0 && env.SUBSTRATE_ADMIN_KEY_PATH.length > 0 ? env.SUBSTRATE_ADMIN_KEY_PATH : "the default admin key path"} (the file path only — no key material is read out here)`;
1064
+ }
1065
+ const GLYPH = {
1066
+ ok: "ok ",
1067
+ no: "NO ",
1068
+ skip: "skip"
1069
+ };
1070
+ /**
1071
+ * Renders the report. The trailer counts skips separately from passes so a
1072
+ * reader cannot sum unasked checks into a verdict.
1073
+ */
1074
+ function formatDoctorReport(report) {
1075
+ const width = Math.max(...report.checks.map((c) => c.name.length));
1076
+ const lines = ["substrate-admin doctor", ""];
1077
+ for (const check of report.checks) {
1078
+ lines.push(` ${GLYPH[check.status]} ${check.name.padEnd(width)} ${check.detail}`);
1079
+ if (check.fix !== void 0) lines.push(` ${" ".repeat(width)} fix: ${check.fix}`);
1080
+ }
1081
+ const ok = report.checks.filter((c) => c.status === "ok").length;
1082
+ const no = report.checks.filter((c) => c.status === "no").length;
1083
+ const skipped = report.checks.filter((c) => c.status === "skip").length;
1084
+ lines.push("", skipped > 0 ? `${ok} ok, ${no} failed, ${skipped} NOT ASKED (a skipped check is not a passing one).` : `${ok} ok, ${no} failed.`);
1085
+ return `${lines.join("\n")}\n`;
1086
+ }
1087
+ /** Resolve the target and run — the shape `main` dispatches to. */
1088
+ async function doctorCommand(argv, env, fetchImpl = substrateFetch) {
1089
+ validateArgv("doctor", argv);
1090
+ let url;
1091
+ let direct = false;
1092
+ for (let i = 0; i < argv.length; i++) {
1093
+ const tok = argv[i];
1094
+ if (tok === void 0) continue;
1095
+ if (tok === "--url") {
1096
+ if (url !== void 0) throw argvError("doctor", "doctor: --url specified more than once", 1);
1097
+ url = argv[i + 1] ?? "";
1098
+ i += 1;
1099
+ continue;
1100
+ }
1101
+ if (tok === "--direct") direct = true;
1102
+ }
1103
+ return runDoctor(env, resolveAdminTarget(direct ? "" : url ?? null, env), fetchImpl);
1104
+ }
1105
+
1106
+ //#endregion
1107
+ //#region src/admin/commands/onboard-keys.ts
1108
+ /**
1109
+ * Key-file helpers for onboarding: generating a keypair for the register steps, and
1110
+ * knowing in advance when `bootstrap` would refuse. Both refuse to overwrite, like
1111
+ * `bootstrap`: clobbering key material destroys an identity silently.
1112
+ */
1113
+ /** `~` and `~/…` against HOME; a shell would have done this, a prompt does not. */
1114
+ function expandHome(env, path) {
1115
+ if (path !== "~" && !path.startsWith("~/")) return path;
1116
+ return join(env.HOME ?? homedir(), path.slice(1));
1117
+ }
1118
+ /**
1119
+ * Writes `<path>` (0600) and `<path>.pub`, plus `<path minus .key>.kid` when a kid is
1120
+ * given — the file the credential resolver reads beside a named key. Creates missing
1121
+ * parent directories 0700. On a failed write, removes whatever this call already wrote.
1122
+ */
1123
+ function writeKeypair(env, path, kid) {
1124
+ const privateKeyPath = expandHome(env, path);
1125
+ const publicKeyPath = `${privateKeyPath}.pub`;
1126
+ const kidPath = kid === void 0 ? void 0 : `${privateKeyPath.replace(/\.key$/, "")}.kid`;
1127
+ const targets = [
1128
+ privateKeyPath,
1129
+ publicKeyPath,
1130
+ ...kidPath === void 0 ? [] : [kidPath]
1131
+ ];
1132
+ for (const p of targets) if (existsSync(p)) throw new AdminCliError(`'${p}' already exists — choose another path`, 1);
1133
+ const { publicKeyPem, privateKeyPem } = generateAdminKeypair(env, false);
1134
+ mkdirSync(dirname(privateKeyPath), {
1135
+ recursive: true,
1136
+ mode: 448
1137
+ });
1138
+ const written = [];
1139
+ try {
1140
+ writeFileSync(privateKeyPath, privateKeyPem, {
1141
+ mode: 384,
1142
+ flag: "wx"
1143
+ });
1144
+ written.push(privateKeyPath);
1145
+ writeFileSync(publicKeyPath, publicKeyPem, {
1146
+ mode: 420,
1147
+ flag: "wx"
1148
+ });
1149
+ written.push(publicKeyPath);
1150
+ if (kidPath !== void 0 && kid !== void 0) writeFileSync(kidPath, `${kid}\n`, {
1151
+ mode: 384,
1152
+ flag: "wx"
1153
+ });
1154
+ } catch (err) {
1155
+ for (const p of written) rmSync(p, { force: true });
1156
+ throw err;
1157
+ }
1158
+ return {
1159
+ privateKeyPath,
1160
+ publicKeyPath,
1161
+ ...kidPath === void 0 ? {} : { kidPath }
1162
+ };
1163
+ }
1164
+ /**
1165
+ * The files whose presence makes `bootstrap` refuse — its own guards, checked without
1166
+ * opening postgres, so onboard offers bootstrap only when it can succeed.
1167
+ */
1168
+ function bootstrapBlockers(env) {
1169
+ return [resolveDefaultKeyPath(env), bootstrapKidPath(env)].filter((p) => existsSync(p));
1170
+ }
1171
+
1172
+ //#endregion
1173
+ //#region src/admin/grant-display.ts
1174
+ /**
1175
+ * Rendering a stored grant as the AUTHORITY it confers, rather than as the two
1176
+ * columns it happens to be stored in.
1177
+ *
1178
+ * The two columns only mean anything jointly: `capabilities` is the default
1179
+ * for BARE `--ns` entries only, so `--ns 'notes:read'` with default
1180
+ * capabilities `read,mutate` is a read-only grant, not a write grant.
1181
+ */
1182
+ /**
1183
+ * `describeGrant` laid out under a label, continuation lines aligned.
1184
+ *
1185
+ * The label is passed in rather than fixed so `register` and `update` can align
1186
+ * the grant block with their own existing columns.
1187
+ */
1188
+ function grantLines(label, namespaces, capabilities) {
1189
+ const entries = describeGrant(namespaces, capabilities);
1190
+ const pad = " ".repeat(label.length);
1191
+ return entries.map((e, i) => `${i === 0 ? label : pad}${e}`);
1192
+ }
1193
+
1194
+ //#endregion
1195
+ //#region src/admin/commands/register.ts
1196
+ /**
1197
+ * `register` — add an existing ed25519 public key as an agent Key.
1198
+ *
1199
+ * `--ns` is REQUIRED and has no default, because a default here is an unbounded
1200
+ * grant nobody chose. The route path also writes the directory row in the same
1201
+ * transaction: a credential with no directory row keeps authenticating while
1202
+ * mail routing and agent listing quietly break.
1203
+ */
1204
+ /**
1205
+ * Parse `register <kid> --pubkey <path> --ns <csv> [--name <n>] [--caps <csv>]
1206
+ * [--allow-admin]`. Positional <kid> exactly once, single-valued flags.
1207
+ * Defaults (kid as name, caps read,mutate) are resolved here; `--ns` has no
1208
+ * default and its absence throws `AdminCliError`.
1209
+ */
1210
+ function parseRegisterArgs(argv) {
1211
+ try {
1212
+ return parseRegisterArgsInner(argv);
1213
+ } catch (err) {
1214
+ if (err instanceof AdminCliError) throw argvError("register", err.message, err.exitCode);
1215
+ throw err;
1216
+ }
1217
+ }
1218
+ function parseRegisterArgsInner(argv) {
1219
+ const rest = argv.slice(1);
1220
+ validateArgv("register", rest);
1221
+ let kid;
1222
+ let pubkeyPath;
1223
+ let name;
1224
+ let nsCsv;
1225
+ let capsCsv;
1226
+ let allowAdmin = false;
1227
+ let allowUnknownNs = false;
1228
+ let url;
1229
+ let direct = false;
1230
+ let noDirectory = false;
1231
+ let noBroadcast = false;
1232
+ let project;
1233
+ const takeValue = (flag, i) => {
1234
+ const val = rest[i + 1];
1235
+ if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError(`register: ${flag} requires a value`, 1);
1236
+ return val;
1237
+ };
1238
+ for (let i = 0; i < rest.length; i++) {
1239
+ const tok = rest[i];
1240
+ if (tok === void 0) continue;
1241
+ if (tok === "--pubkey") {
1242
+ if (pubkeyPath !== void 0) throw new AdminCliError("register: --pubkey specified more than once", 1);
1243
+ pubkeyPath = takeValue("--pubkey", i);
1244
+ i += 1;
1245
+ } else if (tok === "--name") {
1246
+ if (name !== void 0) throw new AdminCliError("register: --name specified more than once", 1);
1247
+ name = takeValue("--name", i);
1248
+ i += 1;
1249
+ } else if (tok === "--ns") {
1250
+ if (nsCsv !== void 0) throw new AdminCliError("register: --ns specified more than once", 1);
1251
+ nsCsv = takeValue("--ns", i);
1252
+ i += 1;
1253
+ } else if (tok === "--caps") {
1254
+ if (capsCsv !== void 0) throw new AdminCliError("register: --caps specified more than once", 1);
1255
+ capsCsv = takeValue("--caps", i);
1256
+ i += 1;
1257
+ } else if (tok === "--allow-admin") {
1258
+ if (allowAdmin) throw new AdminCliError("register: --allow-admin specified more than once", 1);
1259
+ allowAdmin = true;
1260
+ } else if (tok === "--allow-unknown-ns") allowUnknownNs = true;
1261
+ else if (tok === "--url") {
1262
+ if (direct) throw new AdminCliError("register: --direct and --url are mutually exclusive", 1);
1263
+ if (url !== void 0) throw new AdminCliError("register: --url specified more than once", 1);
1264
+ url = takeValue("--url", i);
1265
+ i += 1;
1266
+ } else if (tok === "--direct") {
1267
+ if (url !== void 0) throw new AdminCliError("register: --direct and --url are mutually exclusive", 1);
1268
+ direct = true;
1269
+ url = "";
1270
+ } else if (tok === "--no-directory") noDirectory = true;
1271
+ else if (tok === "--no-broadcast") noBroadcast = true;
1272
+ else if (tok === "--project") {
1273
+ if (project !== void 0) throw new AdminCliError("register: --project specified more than once", 1);
1274
+ project = takeValue("--project", i);
1275
+ i += 1;
1276
+ } else kid = tok;
1277
+ }
1278
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("register requires a <kid> positional arg", 1);
1279
+ if (pubkeyPath === void 0 || pubkeyPath.length === 0) throw new AdminCliError("register requires --pubkey <path>", 1);
1280
+ const splitCsv = (csv) => csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
1281
+ if (nsCsv === void 0) throw new AdminCliError("register requires --ns <csv> — namespaces are granted explicitly, never by default. Pass the namespaces this identity needs (e.g. --ns notes,recall), or --ns '*' to deliberately grant every namespace.", 1);
1282
+ const namespaces = splitCsv(nsCsv);
1283
+ if (namespaces.length === 0) throw new AdminCliError(`register: --ns '${nsCsv}' resolves to an empty namespace list — an identity that can reach nothing is almost certainly a mistake. Pass real namespaces, or --ns '*'.`, 1);
1284
+ const nsError = grantEntryError(namespaces, ["read", "mutate"]);
1285
+ if (nsError !== null) throw new AdminCliError(`register: ${nsError} — e.g. --ns inventory:read,notes:read+mutate`, 1);
1286
+ const capabilities = capsCsv === void 0 ? ["read", "mutate"] : splitCsv(capsCsv);
1287
+ return {
1288
+ kid,
1289
+ pubkeyPath,
1290
+ name: name ?? kid,
1291
+ namespaces,
1292
+ capabilities,
1293
+ allowAdmin,
1294
+ allowUnknownNs,
1295
+ url: url ?? null,
1296
+ noDirectory,
1297
+ noBroadcast,
1298
+ project: project ?? null
1299
+ };
1300
+ }
1301
+ /**
1302
+ * Register an existing Ed25519 public key as an agent Key row directly
1303
+ * in postgres, with one `key_registered` audit row written in the SAME tx.
1304
+ *
1305
+ * Unlike `bootstrap`/`rotate`, the kid is operator-chosen. The row id is a
1306
+ * freshly-minted UUID; the kid is the principal field stored separately. A
1307
+ * previously-revoked same-kid row is re-registered (same UUID id, clears
1308
+ * revokedAt). A LIVE same-kid row is refused — rotate/revoke is the path.
1309
+ */
1310
+ async function runRegister(args, env, openDataset = openPgDataset) {
1311
+ if (grantEntriesConfer(args.namespaces, args.capabilities, "admin") && !args.allowAdmin) throw new AdminCliError("register: 'admin' capability requires --allow-admin (bootstrap is the deliberate admin path)", 1);
1312
+ const publicKeyPem = readEd25519PublicKey(args.pubkeyPath);
1313
+ const shaFull = createHash("sha256").update(publicKeyPem).digest();
1314
+ const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
1315
+ const namespaces = encodeList(args.namespaces);
1316
+ const capabilities = encodeList(args.capabilities);
1317
+ const { dataset, close } = await openDataset(env);
1318
+ try {
1319
+ const replacedRevoked = await dataset.withTransaction(async (tx) => {
1320
+ const { rows: existingRows } = await tx.read("Key", { where: { kid: { eq: args.kid } } });
1321
+ const existing = existingRows.find((r) => r.revokedAt == null) ?? existingRows[0];
1322
+ let wasRevoked = false;
1323
+ let rowId;
1324
+ if (existing !== void 0) {
1325
+ if ((existing.revokedAt instanceof Date ? existing.revokedAt : typeof existing.revokedAt === "string" ? existing.revokedAt : null) == null) throw new AdminCliError(`kid '${args.kid}' is already registered and live — rotate or revoke it instead`, 3);
1326
+ wasRevoked = true;
1327
+ rowId = existing.id;
1328
+ }
1329
+ const now = /* @__PURE__ */ new Date();
1330
+ await tx.write("Key", [{
1331
+ ...rowId !== void 0 && { id: rowId },
1332
+ kid: args.kid,
1333
+ name: args.name,
1334
+ algorithm: "EdDSA",
1335
+ publicKey: publicKeyPem,
1336
+ namespaces,
1337
+ capabilities,
1338
+ revokedAt: null
1339
+ }], ACTOR_HINT);
1340
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1341
+ actorKid: CLI_ACTOR_KID,
1342
+ kind: "key_registered",
1343
+ targetKid: args.kid,
1344
+ details: {
1345
+ kid: args.kid,
1346
+ name: args.name,
1347
+ namespaces,
1348
+ capabilities,
1349
+ fingerprint,
1350
+ replacedRevoked: wasRevoked
1351
+ },
1352
+ now
1353
+ })], ACTOR_HINT);
1354
+ return wasRevoked;
1355
+ });
1356
+ return {
1357
+ kid: args.kid,
1358
+ name: args.name,
1359
+ fingerprint,
1360
+ namespaces,
1361
+ capabilities,
1362
+ replacedRevoked,
1363
+ via: "direct",
1364
+ directoryCreated: false,
1365
+ directoryDetail: "direct-to-postgres cannot reach a plugin namespace"
1366
+ };
1367
+ } finally {
1368
+ await close();
1369
+ }
1370
+ }
1371
+ /**
1372
+ * Register a key through the admin-gated `POST /substrate/v1/_system/keys` route,
1373
+ * which needs an `admin` identity rather than postgres write access, and
1374
+ * writes the directory row in the same transaction. Throws `AdminCliError`
1375
+ * on a non-2xx response.
1376
+ */
1377
+ async function runRegisterViaRoute(args, baseUrl, env, fetchImpl = substrateFetch) {
1378
+ if (grantEntriesConfer(args.namespaces, args.capabilities, "admin") && !args.allowAdmin) throw new AdminCliError("register: 'admin' capability requires --allow-admin (bootstrap is the deliberate admin path)", 1);
1379
+ const publicKeyPem = readEd25519PublicKey(args.pubkeyPath);
1380
+ const fingerprint = `sha256:${base64Url(createHash("sha256").update(publicKeyPem).digest()).slice(0, 8)}`;
1381
+ const auth = resolveAdminAuth(env, baseUrl);
1382
+ if ("error" in auth) throw new AdminCliError(`register: ${auth.error}`, 1);
1383
+ const directoryParams = {};
1384
+ if (args.noBroadcast) directoryParams.broadcastEligible = false;
1385
+ if (args.project !== null) directoryParams.project = args.project;
1386
+ const body = {
1387
+ kid: args.kid,
1388
+ publicKey: publicKeyPem,
1389
+ name: args.name,
1390
+ algorithm: "EdDSA",
1391
+ namespaces: args.namespaces,
1392
+ capabilities: args.capabilities,
1393
+ allowAdmin: args.allowAdmin,
1394
+ allowUnknownNs: args.allowUnknownNs,
1395
+ directory: {
1396
+ create: !args.noDirectory,
1397
+ ...Object.keys(directoryParams).length > 0 ? { params: directoryParams } : {}
1398
+ }
1399
+ };
1400
+ const url = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
1401
+ let res;
1402
+ try {
1403
+ res = await fetchImpl(url, {
1404
+ method: "POST",
1405
+ headers: {
1406
+ "content-type": "application/json",
1407
+ authorization: auth.ok
1408
+ },
1409
+ body: JSON.stringify(body),
1410
+ redirect: "error"
1411
+ });
1412
+ } catch (err) {
1413
+ const msg = err instanceof Error ? err.message : String(err);
1414
+ throw new AdminCliError(`register: could not reach ${url}: ${msg}. Pass --direct to write to postgres instead (break-glass; leaves no directory row).`, 2);
1415
+ }
1416
+ const text = await res.text();
1417
+ let parsed = null;
1418
+ try {
1419
+ parsed = JSON.parse(text);
1420
+ } catch {}
1421
+ if (!res.ok) {
1422
+ const code = typeof parsed?.code === "string" ? parsed.code : `http_${res.status}`;
1423
+ const message = typeof parsed?.message === "string" ? parsed.message : text.slice(0, 500);
1424
+ if (res.status === 404) throw new AdminCliError(`register: ${url} returned 404 — this server predates the keys route. Upgrade it, or pass --direct.`, 2);
1425
+ throw new AdminCliError(`register: ${code}: ${message}`, 3);
1426
+ }
1427
+ const dir = parsed?.directory ?? {};
1428
+ return {
1429
+ kid: typeof parsed?.kid === "string" ? parsed.kid : args.kid,
1430
+ name: args.name,
1431
+ fingerprint: typeof parsed?.fingerprint === "string" ? parsed.fingerprint : fingerprint,
1432
+ namespaces: encodeList(args.namespaces),
1433
+ capabilities: encodeList(args.capabilities),
1434
+ replacedRevoked: parsed?.replacedRevoked === true,
1435
+ via: "route",
1436
+ directoryCreated: dir.created === true,
1437
+ directoryDetail: dir.created === true ? typeof dir.frame === "string" ? dir.frame : "created" : typeof dir.reason === "string" ? dir.reason : "not created"
1438
+ };
1439
+ }
1440
+ function formatRegisterOutput(result, opts = {}) {
1441
+ const lines = [
1442
+ "substrate-admin register complete.",
1443
+ `kid: ${result.kid}`,
1444
+ `name: ${result.name}`,
1445
+ `fingerprint: ${result.fingerprint}`,
1446
+ ...grantLines("grant: ", result.namespaces, result.capabilities),
1447
+ ` (stored as: namespaces='${result.namespaces}' capabilities='${result.capabilities}')`,
1448
+ `transport: ${result.via === "route" ? "POST /substrate/v1/_system/keys" : "direct-to-postgres (--direct)"}`,
1449
+ `directory row: ${result.directoryCreated ? `created in ${result.directoryDetail}` : `NOT created — ${result.directoryDetail}`}`
1450
+ ];
1451
+ if (result.replacedRevoked) lines.push("re-registered over a previously-revoked kid.");
1452
+ lines.push("");
1453
+ if (result.via === "route") {
1454
+ lines.push("This build refreshes the key registry post-commit, so no restart should be needed.");
1455
+ lines.push("Verify before relying on it: mint a token with this kid's private key and call /substrate/v1/whoami.");
1456
+ } else lines.push("A RUNNING binary will not see this key until its registry re-primes —", "restart it (e.g. `sudo systemctl restart substrate-binary`) for the key to verify.");
1457
+ if (!result.directoryCreated && opts.adminRoot === true) lines.push("", "No directory row, by design: admin roots are exempt by capability, like the bootstrap key.");
1458
+ else if (!result.directoryCreated) lines.push("", "WARNING: this identity has a credential but NO directory row. It will", "authenticate normally and be invisible to fleet listing and mail routing.", result.via === "direct" ? "Re-run without --direct (or with --url) to write both rows in one transaction." : result.directoryDetail === "not_configured" ? "This deployment has no identity directory configured, so there is nowhere to write one. Expected for a substrate with no mailbox; alarming for a fleet member. Configure SUBSTRATE_AGENT_DIRECTORY_TYPE if it should have one." : "Create the directory row by hand, or re-run without --no-directory.");
1459
+ lines.push("");
1460
+ return lines.join("\n");
1461
+ }
1462
+
1463
+ //#endregion
1464
+ //#region src/admin/commands/onboard.ts
1465
+ /**
1466
+ * `substrate-admin onboard` — guided onboarding. Runs diagnose, plans the steps,
1467
+ * stops at the first one still to do, and offers to run its fix when a client
1468
+ * can. Every action is confirmed; nothing runs unattended.
1469
+ */
1470
+ function formatChecklist(steps) {
1471
+ const current = currentStep(steps);
1472
+ const width = Math.max(...steps.map((s) => s.name.length));
1473
+ return `${steps.map((s) => {
1474
+ const mark = s === current ? "▶" : STEP_MARKS[s.status];
1475
+ const tag = s.optional ? " (optional)" : "";
1476
+ return ` ${mark} ${s.name.padEnd(width)} ${s.detail}${tag}`;
1477
+ }).join("\n")}\n`;
1478
+ }
1479
+ function describeAction(action, store, adminCapability) {
1480
+ switch (action.kind) {
1481
+ case "bootstrap": return `substrate-admin bootstrap — writes straight to SUBSTRATE_DATABASE_URL=${store ?? "(unset)"}. It must be the same database the server you named serves; nothing here can check that.`;
1482
+ case "register-admin": return `substrate-admin register <kid> --pubkey <path> --ns '*' --caps ${seedCapabilities(adminCapability).join(",")} --allow-admin --no-directory`;
1483
+ case "register-agent": return "substrate-admin register <kid> --pubkey <path> --ns <namespace,…>";
1484
+ case "revoke": return action.kids.map((k) => `substrate-admin revoke ${k}`).join(" && ");
1485
+ }
1486
+ }
1487
+ /** Thrown when input ends mid-action; the loop turns it into a quit. */
1488
+ var EndOfInput = class extends Error {};
1489
+ async function need(io, prompt) {
1490
+ const line = await io.ask(prompt);
1491
+ if (line === null) throw new EndOfInput();
1492
+ return line.trim();
1493
+ }
1494
+ /** Asks for a public key, offering to generate a keypair when the operator has none. */
1495
+ async function publicKeyPath(io, actions, kid) {
1496
+ const given = await need(io, "public key path (Enter to generate a keypair here): ");
1497
+ if (given.length > 0) return given;
1498
+ io.out("A private key must live with whoever will use it, and never travel. Generate it on the machine that will sign with it.\n");
1499
+ const target = await need(io, "write the new private key to (Enter to cancel): ");
1500
+ if (target.length === 0) return null;
1501
+ const written = actions.generateKeypair(target, kid);
1502
+ io.out(`wrote ${written.privateKeyPath} (0600) and ${written.publicKeyPath}\n`);
1503
+ if (written.kidPath !== void 0) io.out(`wrote ${written.kidPath} — point the signing-key variable at the private key and the kid is read from beside it.
1504
+ `);
1505
+ return written.publicKeyPath;
1506
+ }
1507
+ /** Runs one action. Returns the output to show, or null when the operator cancelled. */
1508
+ async function perform(action, io, actions) {
1509
+ switch (action.kind) {
1510
+ case "bootstrap": return actions.bootstrap();
1511
+ case "register-admin": {
1512
+ const kid = await need(io, "kid for the second admin: ");
1513
+ if (kid.length === 0) return null;
1514
+ const pub = await publicKeyPath(io, actions, kid);
1515
+ return pub === null ? null : actions.registerAdmin(kid, pub);
1516
+ }
1517
+ case "register-agent": {
1518
+ const kid = await need(io, "kid for the agent (e.g. myrepo-claude@host): ");
1519
+ if (kid.length === 0) return null;
1520
+ const pub = await publicKeyPath(io, actions, kid);
1521
+ if (pub === null) return null;
1522
+ const ns = await need(io, "grant namespaces (comma-separated): ");
1523
+ const namespaces = ns.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
1524
+ if (namespaces.length === 0) {
1525
+ io.out("a namespace is required\n");
1526
+ return null;
1527
+ }
1528
+ const grantError = grantEntryError(namespaces, ["read", "mutate"]);
1529
+ if (grantError !== null) {
1530
+ io.out(`grant '${ns}' refused: ${grantError}\n`);
1531
+ return null;
1532
+ }
1533
+ return actions.registerAgent(kid, pub, namespaces);
1534
+ }
1535
+ case "revoke": {
1536
+ const done = [];
1537
+ for (const kid of action.kids) {
1538
+ const typed = await need(io, `type '${kid}' to revoke it: `);
1539
+ if (typed !== kid) {
1540
+ io.out(`'${typed}' did not match — ${kid} left alone\n`);
1541
+ continue;
1542
+ }
1543
+ try {
1544
+ done.push(await actions.revoke(kid));
1545
+ } catch (err) {
1546
+ done.push(`failed: ${kid}: ${err instanceof Error ? err.message : String(err)}`);
1547
+ }
1548
+ }
1549
+ return done.length > 0 ? done.join("\n") : null;
1550
+ }
1551
+ }
1552
+ }
1553
+ function summary(steps, stopped) {
1554
+ const skipped = steps.filter((s) => s.status === "skipped").map((s) => s.name);
1555
+ const blocked = steps.filter((s) => s.status === "blocked").map((s) => s.name);
1556
+ const lines = [stopped ? "onboarding stopped before it finished." : requiredOutstanding(steps) ? "onboarding has required steps outstanding." : "onboarding complete."];
1557
+ if (skipped.length > 0) lines.push(`skipped: ${skipped.join(", ")}`);
1558
+ if (blocked.length > 0) lines.push(`not checked: ${blocked.join(", ")}`);
1559
+ return `\n${lines.join("\n")}\n`;
1560
+ }
1561
+ async function runOnboard(opts) {
1562
+ const { io, actions } = opts;
1563
+ const adminCapability = opts.adminCapability ?? "admin";
1564
+ const skipped = /* @__PURE__ */ new Set();
1565
+ let declined = null;
1566
+ for (;;) {
1567
+ let result;
1568
+ try {
1569
+ result = await opts.diagnose();
1570
+ } catch (err) {
1571
+ io.out(`diagnose failed: ${err instanceof Error ? err.message : String(err)}\n`);
1572
+ return 2;
1573
+ }
1574
+ const steps = planOnboarding(result, {
1575
+ canBootstrap: opts.canBootstrap,
1576
+ skipped
1577
+ });
1578
+ io.out(`\n${formatChecklist(steps)}`);
1579
+ const step = currentStep(steps);
1580
+ const exitCode = requiredOutstanding(steps) ? 1 : 0;
1581
+ if (step === void 0 || !opts.interactive) {
1582
+ io.out(summary(steps, false));
1583
+ return exitCode;
1584
+ }
1585
+ if (declined !== step.name) declined = null;
1586
+ io.out(`\n${step.name}: ${step.detail}\n`);
1587
+ try {
1588
+ if (step.action !== void 0 && declined === null) {
1589
+ io.out(` would run: ${describeAction(step.action, opts.bootstrapStore, adminCapability)}\n`);
1590
+ if ((await need(io, "Run it? [y/N] ")).toLowerCase() === "y") {
1591
+ try {
1592
+ const output = await perform(step.action, io, actions);
1593
+ if (output !== null) io.out(`${output}\n`);
1594
+ } catch (err) {
1595
+ if (err instanceof EndOfInput) throw err;
1596
+ io.out(`failed: ${err instanceof Error ? err.message : String(err)}\n`);
1597
+ }
1598
+ continue;
1599
+ }
1600
+ declined = step.name;
1601
+ }
1602
+ if (step.fix !== void 0) io.out(` fix: ${step.fix}\n`);
1603
+ const offerRun = step.action !== void 0 && declined === step.name;
1604
+ const choice = (await need(io, `Enter re-checks${offerRun ? ", r runs the fix" : ""}${step.skippable ? ", s skips" : ""}, q quits: `)).toLowerCase();
1605
+ if (choice === "q") {
1606
+ io.out(summary(steps, true));
1607
+ return exitCode;
1608
+ }
1609
+ if (choice === "r" && offerRun) declined = null;
1610
+ if (choice === "s") {
1611
+ if (SKIPPABLE_STEPS.has(step.name)) skipped.add(step.name);
1612
+ else io.out(`${step.name} cannot be skipped\n`);
1613
+ }
1614
+ } catch (err) {
1615
+ if (!(err instanceof EndOfInput)) throw err;
1616
+ io.out(summary(steps, true));
1617
+ return exitCode;
1618
+ }
1619
+ }
1620
+ }
1621
+ /** A postgres URL fit to print: the password is never echoed. */
1622
+ function redactStore(url) {
1623
+ let u;
1624
+ try {
1625
+ u = new URL(url);
1626
+ } catch {
1627
+ return "(an unparseable postgres URL)";
1628
+ }
1629
+ const auth = u.username.length > 0 ? `${u.username}${u.password.length > 0 ? ":***" : ""}@` : "";
1630
+ return `${u.protocol}//${auth}${u.host}${u.pathname}`;
1631
+ }
1632
+ function registerArgs(kid, pubkeyPath, over) {
1633
+ return {
1634
+ kid,
1635
+ pubkeyPath,
1636
+ name: kid,
1637
+ namespaces: [],
1638
+ capabilities: ["read", "mutate"],
1639
+ allowAdmin: false,
1640
+ allowUnknownNs: false,
1641
+ url: null,
1642
+ noDirectory: false,
1643
+ noBroadcast: false,
1644
+ project: null,
1645
+ ...over
1646
+ };
1647
+ }
1648
+ /** The production action runners: the same functions the standalone subcommands call. */
1649
+ function realOnboardActions(env, baseUrl, fetchImpl = substrateFetch) {
1650
+ const cap = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : DEFAULT_ADMIN_CAPABILITY;
1651
+ return {
1652
+ bootstrap: async () => formatBootstrapOutput(await runBootstrap(env)),
1653
+ registerAdmin: async (kid, pub) => formatRegisterOutput(await runRegisterViaRoute(registerArgs(kid, pub, {
1654
+ namespaces: ["*"],
1655
+ capabilities: seedCapabilities(cap),
1656
+ allowAdmin: true,
1657
+ noDirectory: true
1658
+ }), baseUrl, env, fetchImpl), { adminRoot: true }),
1659
+ registerAgent: async (kid, pub, namespaces) => formatRegisterOutput(await runRegisterViaRoute(registerArgs(kid, pub, { namespaces: [...namespaces] }), baseUrl, env, fetchImpl)),
1660
+ revoke: async (kid) => {
1661
+ await runKeyPatchViaRoute({
1662
+ kid,
1663
+ revoke: true
1664
+ }, baseUrl, env, REVOKE_EXIT_CODES, fetchImpl);
1665
+ return `revoked ${kid}`;
1666
+ },
1667
+ generateKeypair: (path, kid) => writeKeypair(env, path, kid)
1668
+ };
1669
+ }
1670
+ /** Parse argv, resolve the target, and run — the shape `main` dispatches to. */
1671
+ async function onboardCommand(argv, env, io, interactive, fetchImpl = substrateFetch) {
1672
+ validateArgv("onboard", argv);
1673
+ let url;
1674
+ let direct = false;
1675
+ let check = false;
1676
+ for (let i = 0; i < argv.length; i++) {
1677
+ const tok = argv[i];
1678
+ if (tok === "--url") {
1679
+ if (url !== void 0) throw argvError("onboard", "onboard: --url specified more than once", 1);
1680
+ url = argv[i + 1] ?? "";
1681
+ i += 1;
1682
+ } else if (tok === "--direct") direct = true;
1683
+ else if (tok === "--check") check = true;
1684
+ }
1685
+ const target = resolveAdminTarget(direct ? "" : url ?? null, env);
1686
+ if (target.kind !== "route") {
1687
+ io.out(formatDoctorReport({
1688
+ checks: [DIRECT_TARGET_REFUSAL],
1689
+ exitCode: 1
1690
+ }));
1691
+ return 1;
1692
+ }
1693
+ const store = env.SUBSTRATE_DATABASE_URL ?? "";
1694
+ const canBootstrap = (store.startsWith("postgres://") || store.startsWith("postgresql://")) && bootstrapBlockers(env).length === 0;
1695
+ return runOnboard({
1696
+ diagnose: () => diagnoseTarget(env, target.baseUrl, fetchImpl),
1697
+ canBootstrap,
1698
+ ...canBootstrap ? { bootstrapStore: redactStore(store) } : {},
1699
+ ...env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? { adminCapability: env.SUBSTRATE_ADMIN_CAPABILITY } : {},
1700
+ interactive: interactive && !check,
1701
+ io,
1702
+ actions: realOnboardActions(env, target.baseUrl, fetchImpl)
1703
+ });
1704
+ }
1705
+
1706
+ //#endregion
1707
+ //#region src/admin/dataset.ts
1708
+ /**
1709
+ * Direct-to-pg dataset opener shared by every CLI path that writes `_system`
1710
+ * rows without going through the running binary, including
1711
+ * `substrate federate enroll`.
1712
+ *
1713
+ * It never migrates: only `bootstrap` and the server change the schema. A
1714
+ * store in an old layout, or missing a migration this CLI knows, is refused.
1715
+ */
1716
+ /**
1717
+ * `_system`'s type defs, as serve's boot reconciles them, so a type the CLI
1718
+ * writes first gets its table typed, with `Key`'s live-kid unique index.
1719
+ */
1720
+ const systemTypeDefLookup = (type, namespace) => namespace === "_system" && Object.hasOwn(SYSTEM_TYPE_DEFS, type) ? SYSTEM_TYPE_DEFS[type] : void 0;
1721
+ async function openPgDataset(env, openSql$1 = openSql) {
1722
+ const storeSpec = env.SUBSTRATE_DATABASE_URL;
1723
+ if (storeSpec === void 0 || storeSpec.length === 0) throw new AdminCliError("SUBSTRATE_DATABASE_URL is required (must be a postgres:// URL)");
1724
+ if (!storeSpec.startsWith("postgres://") && !storeSpec.startsWith("postgresql://")) throw new AdminCliError(`SUBSTRATE_DATABASE_URL must be a postgres:// URL (got '${redactStore(storeSpec)}'). Memory-backed stores cannot persist admin state across restarts.`);
1725
+ const sql = openSql$1(storeSpec);
1726
+ let pending;
1727
+ try {
1728
+ await assertTablesLayout(sql);
1729
+ await assertNotMigrating(sql);
1730
+ pending = await pendingMigrations(sql);
1731
+ } catch (err) {
1732
+ await closeQuietly(sql);
1733
+ throw err;
1734
+ }
1735
+ if (pending.length > 0) {
1736
+ await closeQuietly(sql);
1737
+ throw new AdminCliError(`the store at SUBSTRATE_DATABASE_URL is missing migration(s) ${pending.join(", ")}. This command does not migrate: start the server (or run bootstrap) against it, or use a substrate-admin matching the server version.`);
1738
+ }
1739
+ return {
1740
+ dataset: new PgDataset({
1741
+ namespace: SYSTEM_NAMESPACE,
1742
+ sql,
1743
+ typeDefLookup: systemTypeDefLookup
1744
+ }),
1745
+ close: () => closeQuietly(sql)
1746
+ };
1747
+ }
1748
+ async function closeQuietly(sql) {
1749
+ try {
1750
+ await sql.end();
1751
+ } catch {}
1752
+ }
1753
+
1754
+ //#endregion
1755
+ //#region package.json
1756
+ var version = "1.0.0-beta.1";
1757
+
1758
+ //#endregion
1759
+ //#region src/plugin-manifest.ts
1760
+ var PluginManifestError = class extends Error {
1761
+ packageName;
1762
+ constructor(packageName, message) {
1763
+ const prefix = packageName !== void 0 ? `[${packageName}] ` : "";
1764
+ super(`${prefix}${message}`);
1765
+ this.name = "PluginManifestError";
1766
+ this.packageName = packageName;
1767
+ }
1768
+ };
1769
+ async function listPluginManifests(pluginDir) {
1770
+ const declared = await declaredDependencies(pluginDir);
1771
+ if (declared.size === 0) return [];
1772
+ const nodeModulesDir = resolve(pluginDir, "node_modules");
1773
+ if (!await isDirectory(nodeModulesDir)) throw new PluginManifestError(void 0, `${pluginDir}/package.json lists ${[...declared].join(", ")} but there is no node_modules: run \`pnpm install\` in ${pluginDir}`);
1774
+ const packageDirs = await listPackageDirs(nodeModulesDir, declared);
1775
+ const manifests = [];
1776
+ for (const packageDir of packageDirs) manifests.push(...await readManifestsIfPresent(packageDir));
1777
+ if (manifests.length === 0) process.stderr.write(`substrate: SUBSTRATE_PLUGIN_DIR=${pluginDir} lists ${[...declared].join(", ")}, none of which is an installed substrate plugin; booting without plugins\n`);
1778
+ return manifests;
1779
+ }
1780
+ /**
1781
+ * The names `<pluginDir>/package.json` lists under `dependencies`. Only these
1782
+ * are plugin candidates: a transitive package hoisted into `node_modules` is
1783
+ * not something the operator chose to run. A missing package.json refuses
1784
+ * boot, since a plugin dir that can name no plugin is a misconfiguration.
1785
+ */
1786
+ async function declaredDependencies(pluginDir) {
1787
+ let raw;
1788
+ try {
1789
+ raw = await readFile(resolve(pluginDir, "package.json"), "utf8");
1790
+ } catch (err) {
1791
+ if (err.code !== "ENOENT") throw err;
1792
+ throw new PluginManifestError(void 0, `SUBSTRATE_PLUGIN_DIR=${pluginDir} has no package.json, so no plugin can load. List each plugin under "dependencies" there (\`substrate init\` writes one) and run \`pnpm install\`, or unset SUBSTRATE_PLUGIN_DIR to boot without plugins`);
1793
+ }
1794
+ let parsed;
1795
+ try {
1796
+ parsed = JSON.parse(raw);
1797
+ } catch (err) {
1798
+ const msg = err instanceof Error ? err.message : String(err);
1799
+ throw new PluginManifestError(void 0, `${pluginDir}/package.json is not valid JSON: ${msg}`);
1800
+ }
1801
+ const deps = parsed?.dependencies;
1802
+ return new Set(deps !== null && typeof deps === "object" ? Object.keys(deps) : []);
1803
+ }
1804
+ async function listPackageDirs(nodeModulesDir, declared) {
1805
+ const entries = await readdir(nodeModulesDir, { withFileTypes: true });
1806
+ const result = [];
1807
+ for (const entry of entries) {
1808
+ if (entry.name.startsWith(".")) continue;
1809
+ if (!await isDirectoryEntry(nodeModulesDir, entry)) continue;
1810
+ if (entry.name.startsWith("@")) {
1811
+ const scopeDir = resolve(nodeModulesDir, entry.name);
1812
+ const scopedEntries = await readdir(scopeDir, { withFileTypes: true });
1813
+ for (const scoped of scopedEntries) {
1814
+ if (scoped.name.startsWith(".")) continue;
1815
+ if (!declared.has(`${entry.name}/${scoped.name}`)) continue;
1816
+ if (!await isDirectoryEntry(scopeDir, scoped)) continue;
1817
+ result.push(resolve(scopeDir, scoped.name));
1818
+ }
1819
+ } else if (declared.has(entry.name)) result.push(resolve(nodeModulesDir, entry.name));
1820
+ }
1821
+ return result;
1822
+ }
1823
+ /**
1824
+ * Treat both real directories AND symlinks-to-directories as plugin
1825
+ * candidates. `Dirent.isDirectory()` is false for symlinks (it returns
1826
+ * true for `isSymbolicLink()` instead) — without the follow-through,
1827
+ * operators using a symlinked node_modules layout (the typical pattern
1828
+ * when wiring the workspace's plugin dirs into a runtime plugin dir
1829
+ * via `ln -s`) would see their plugins silently skipped.
1830
+ */
1831
+ async function isDirectoryEntry(parentDir, entry) {
1832
+ if (entry.isDirectory()) return true;
1833
+ if (!entry.isSymbolicLink()) return false;
1834
+ try {
1835
+ return (await stat(resolve(parentDir, entry.name))).isDirectory();
1836
+ } catch {
1837
+ return false;
1838
+ }
1839
+ }
1840
+ async function readManifestsIfPresent(packageDir) {
1841
+ const pkgPath = resolve(packageDir, "package.json");
1842
+ let raw;
1843
+ try {
1844
+ raw = await readFile(pkgPath, "utf8");
1845
+ } catch {
1846
+ return [];
1847
+ }
1848
+ let pkg;
1849
+ try {
1850
+ pkg = JSON.parse(raw);
1851
+ } catch (err) {
1852
+ throw new PluginManifestError(void 0, `package.json at '${pkgPath}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
1853
+ }
1854
+ if (pkg.substrate === void 0) return [];
1855
+ return parseManifests(pkg, packageDir);
1856
+ }
1857
+ const PLUGIN_NAME = /^[a-z0-9][a-z0-9-]*$/;
1858
+ function parseManifests(pkg, packageDir) {
1859
+ const packageName = typeof pkg.name === "string" ? pkg.name : void 0;
1860
+ if (packageName === void 0 || packageName.length === 0) throw new PluginManifestError(void 0, `package.json at '${packageDir}' is missing a name`);
1861
+ if (!isPlainObject(pkg.substrate)) throw new PluginManifestError(packageName, "`substrate` manifest must be an object");
1862
+ const block = pkg.substrate;
1863
+ if (block.plugins === void 0) return [parseEntry(block, packageName, packageDir, void 0, "`substrate")];
1864
+ const strays = Object.keys(block).filter((key) => key !== "plugins");
1865
+ if (strays.length > 0) throw new PluginManifestError(packageName, `\`substrate.plugins\` cannot sit beside single-plugin keys (${strays.join(", ")}); move them into the entries`);
1866
+ if (!Array.isArray(block.plugins) || block.plugins.length === 0) throw new PluginManifestError(packageName, "`substrate.plugins` must be a non-empty array");
1867
+ const names = /* @__PURE__ */ new Set();
1868
+ return block.plugins.map((raw, i) => {
1869
+ const at = `\`substrate.plugins[${i}]`;
1870
+ if (!isPlainObject(raw)) throw new PluginManifestError(packageName, `${at}\` must be an object`);
1871
+ const entry = raw;
1872
+ if (typeof entry.name !== "string" || !PLUGIN_NAME.test(entry.name)) throw new PluginManifestError(packageName, `${at}.name\` must be lowercase letters, digits and hyphens (got ${JSON.stringify(entry.name)})`);
1873
+ if (names.has(entry.name)) throw new PluginManifestError(packageName, `${at}.name\` '${entry.name}' is declared twice`);
1874
+ names.add(entry.name);
1875
+ if (entry.plugins !== void 0) throw new PluginManifestError(packageName, `${at}\` cannot nest \`plugins\``);
1876
+ return parseEntry(entry, packageName, packageDir, entry.name, at);
1877
+ });
1878
+ }
1879
+ function parseEntry(block, packageName, packageDir, name, at) {
1880
+ if (name === void 0 && block.name !== void 0) throw new PluginManifestError(packageName, "`substrate.name` is only meaningful inside a `substrate.plugins` entry");
1881
+ if (block.tier !== "kernel" && block.tier !== "coordinator") throw new PluginManifestError(packageName, `${at}.tier\` must be 'kernel' or 'coordinator' (got ${JSON.stringify(block.tier)})`);
1882
+ if (typeof block.entry !== "string" || block.entry.length === 0) throw new PluginManifestError(packageName, `${at}.entry\` must be a non-empty string`);
1883
+ if (block.configSchema !== void 0 && (typeof block.configSchema !== "string" || block.configSchema.length === 0)) throw new PluginManifestError(packageName, `${at}.configSchema\` must be a non-empty string when present`);
1884
+ if (block.defaultConfig !== void 0 && (typeof block.defaultConfig !== "string" || block.defaultConfig.length === 0)) throw new PluginManifestError(packageName, `${at}.defaultConfig\` must be a non-empty string when present`);
1885
+ if (block.configBasename !== void 0 && (typeof block.configBasename !== "string" || block.configBasename.length === 0)) throw new PluginManifestError(packageName, `${at}.configBasename\` must be a non-empty string when present`);
1886
+ const defaultConfigPath = typeof block.defaultConfig === "string" ? resolve(packageDir, block.defaultConfig) : void 0;
1887
+ const configSchemaPath = typeof block.configSchema === "string" ? resolve(packageDir, block.configSchema) : void 0;
1888
+ const bareName = basename(packageName);
1889
+ const configBasename = typeof block.configBasename === "string" ? block.configBasename : name === void 0 ? bareName : `${bareName}-${name}`;
1890
+ return {
1891
+ packageName,
1892
+ pluginId: name === void 0 ? packageName : `${packageName}/${name}`,
1893
+ packageDir,
1894
+ tier: block.tier,
1895
+ entry: block.entry,
1896
+ defaultConfigPath,
1897
+ configSchemaPath,
1898
+ configBasename
1899
+ };
1900
+ }
1901
+ function isPlainObject(value) {
1902
+ return value !== null && typeof value === "object" && !Array.isArray(value);
1903
+ }
1904
+ async function isDirectory(path) {
1905
+ try {
1906
+ return (await stat(path)).isDirectory();
1907
+ } catch {
1908
+ return false;
1909
+ }
1910
+ }
1911
+
1912
+ //#endregion
1913
+ //#region src/plugin-dir-loader.ts
1914
+ /**
1915
+ * Plugin discovery + loader for the `SUBSTRATE_PLUGIN_DIR` boot path.
1916
+ *
1917
+ * Scans `<dir>/node_modules/{*,@*\/*}/package.json` for the dependencies
1918
+ * `<dir>/package.json` lists that declare a
1919
+ * `substrate` manifest, reads each plugin's defaults + the operator's colocated
1920
+ * `<basename>.config.json` overrides, and invokes each plugin's structured
1921
+ * `bootstrap(rawConfig[, hostDeps])` from `@mnmal-ai/substrate-bootstrap`.
1922
+ *
1923
+ * This module owns the fs-specific parts — directory scan, config-file reads,
1924
+ * dynamic `import()` of the bootstrap entry. The tier ordering (substrate
1925
+ * before coordinator, alphabetical within tier) + bootstrap invocation +
1926
+ * `BootstrapConfigError` wrapping live in `composeFromManifests`
1927
+ * (`@mnmal-ai/substrate-compose`), shared with downstream consumers that load from
1928
+ * a statically-bundled manifest list rather than an fs scan.
1929
+ *
1930
+ * Failure mode: refuse boot. Manifest parse errors,
1931
+ * `BootstrapConfigError` from a plugin's zod schema, and import errors all
1932
+ * surface as `PluginLoadError` with the offending package name attached so
1933
+ * the operator sees `<plugin>: <issue>` rather than a bare zod dump.
1934
+ *
1935
+ * Coordinator plugins receive operator config only — no code-shaped extras.
1936
+ * The substrate-driven postWrite registry (substrate-recall's `contributePostWrites`)
1937
+ * is the correct path for cross-plugin wiring; the binary does not post-attach
1938
+ * anything to specific coordinators.
1939
+ */
1940
+ const defaultImportResolver = async (entryPath) => {
1941
+ return import(pathToFileURL(entryPath).href);
1942
+ };
1943
+ async function loadPluginsFromDir(opts) {
1944
+ const importResolver = opts.importResolver ?? defaultImportResolver;
1945
+ const manifests = await listPluginManifests(opts.pluginDir);
1946
+ const { kernel, coordinators, configs } = await composeFromManifests({
1947
+ manifests,
1948
+ kernelHostDeps: opts.kernelHostDeps,
1949
+ ...opts.contractCheck !== void 0 ? { contractCheck: opts.contractCheck } : {},
1950
+ resolveConfig: (manifest) => readMergedConfig(manifest, opts.pluginDir),
1951
+ resolveBootstrap: async (manifest) => {
1952
+ return (await importBootstrapModule(manifest, importResolver)).default;
1953
+ }
1954
+ });
1955
+ const manifestMap = /* @__PURE__ */ new Map();
1956
+ for (const m of manifests) manifestMap.set(m.pluginId, m);
1957
+ return {
1958
+ kernel,
1959
+ coordinators,
1960
+ manifests: manifestMap,
1961
+ configs
1962
+ };
1963
+ }
1964
+ async function importBootstrapModule(manifest, importResolver) {
1965
+ const entryAbs = resolve(manifest.packageDir, manifest.entry);
1966
+ let mod;
1967
+ try {
1968
+ mod = await importResolver(entryAbs);
1969
+ } catch (err) {
1970
+ throw new PluginLoadError(manifest.pluginId, `failed to import bootstrap entry '${manifest.entry}': ${describeError(err)}`, err);
1971
+ }
1972
+ if (typeof mod.default !== "function") throw new PluginLoadError(manifest.pluginId, `bootstrap entry '${manifest.entry}' must default-export a function (got ${typeof mod.default})`, void 0);
1973
+ return mod;
1974
+ }
1975
+ async function readMergedConfig(manifest, pluginDir) {
1976
+ const defaults = await readJsonIfPresent(manifest.defaultConfigPath, manifest.pluginId);
1977
+ const overrides = await readJsonIfPresent(resolve(pluginDir, `${manifest.configBasename}.config.json`), manifest.pluginId);
1978
+ return {
1979
+ ...defaults,
1980
+ ...overrides
1981
+ };
1982
+ }
1983
+ async function readJsonIfPresent(path, pluginId) {
1984
+ if (path === void 0) return {};
1985
+ let content;
1986
+ try {
1987
+ content = await readFile(path, "utf8");
1988
+ } catch (err) {
1989
+ if (isENOENT(err)) return {};
1990
+ throw new PluginLoadError(pluginId, `failed to read config at '${path}'`, err);
1991
+ }
1992
+ try {
1993
+ const parsed = JSON.parse(content);
1994
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new PluginLoadError(pluginId, `config at '${path}' must be a JSON object (got ${Array.isArray(parsed) ? "array" : typeof parsed})`, void 0);
1995
+ return parsed;
1996
+ } catch (err) {
1997
+ if (err instanceof PluginLoadError) throw err;
1998
+ throw new PluginLoadError(pluginId, `config at '${path}' is not valid JSON`, err);
1999
+ }
2000
+ }
2001
+ function isENOENT(err) {
2002
+ return err !== null && typeof err === "object" && "code" in err && err.code === "ENOENT";
2003
+ }
2004
+ function describeError(err) {
2005
+ if (err instanceof Error) return err.message;
2006
+ return String(err);
2007
+ }
2008
+
2009
+ //#endregion
2010
+ //#region ../../packages/substrate-server-fastify/src/translate.ts
2011
+ /**
2012
+ * Fastify <-> Substrate translators. The only file (along with
2013
+ * fastify-substrate-server.ts) that may import from `fastify`. Nothing from
2014
+ * `fastify` leaks out of this module.
2015
+ *
2016
+ * Body rule:
2017
+ * - No Content-Length AND no buffered body -> `null`
2018
+ * - Content-Length: 0 or empty buffered body -> `Buffer.alloc(0)`
2019
+ * - Otherwise -> Buffer with the bytes the parser produced
2020
+ *
2021
+ * Header rule:
2022
+ * - Fastify normalizes header names to lowercase; we preserve that.
2023
+ * - Array-valued headers (e.g. set-cookie on inbound, rare) are joined with
2024
+ * ", " which matches the RFC 7230 field-value folding rule the rest of the
2025
+ * ecosystem assumes. `set-cookie` on responses is a known exception, but
2026
+ * inbound requests never carry multiple set-cookie headers so the join is
2027
+ * safe for the SubstrateRequest direction.
2028
+ */
2029
+ const HTTP_METHODS = /* @__PURE__ */ new Set([
2030
+ "GET",
2031
+ "POST",
2032
+ "PUT",
2033
+ "DELETE",
2034
+ "PATCH",
2035
+ "HEAD",
2036
+ "OPTIONS"
2037
+ ]);
2038
+ function coerceMethod(raw) {
2039
+ const upper = raw.toUpperCase();
2040
+ if (!HTTP_METHODS.has(upper)) throw new Error(`Unsupported HTTP method: ${raw}`);
2041
+ return upper;
2042
+ }
2043
+ function stripQuery(url) {
2044
+ const q = url.indexOf("?");
2045
+ return q === -1 ? url : url.slice(0, q);
2046
+ }
2047
+ function flattenHeaders(raw) {
2048
+ const out = {};
2049
+ for (const [k, v] of Object.entries(raw)) {
2050
+ if (v === void 0) continue;
2051
+ if (Array.isArray(v)) out[k] = v.join(", ");
2052
+ else if (typeof v === "number") out[k] = String(v);
2053
+ else out[k] = v;
2054
+ }
2055
+ return out;
2056
+ }
2057
+ function flattenQuery(raw) {
2058
+ if (raw === null || typeof raw !== "object") return {};
2059
+ const out = {};
2060
+ for (const [k, v] of Object.entries(raw)) {
2061
+ if (v === void 0 || v === null) continue;
2062
+ if (Array.isArray(v)) {
2063
+ const first = v[0];
2064
+ if (first === void 0 || first === null) continue;
2065
+ out[k] = String(first);
2066
+ } else out[k] = String(v);
2067
+ }
2068
+ return out;
2069
+ }
2070
+ function flattenParams(raw) {
2071
+ if (raw === null || typeof raw !== "object") return {};
2072
+ const out = {};
2073
+ for (const [k, v] of Object.entries(raw)) {
2074
+ if (v === void 0 || v === null) continue;
2075
+ out[k] = String(v);
2076
+ }
2077
+ return out;
2078
+ }
2079
+ function coerceBody(req) {
2080
+ const body = req.body;
2081
+ const cl = req.headers["content-length"];
2082
+ const hasContentLength = typeof cl === "string" && cl.length > 0;
2083
+ if (body === void 0 || body === null) return hasContentLength ? Buffer.alloc(0) : null;
2084
+ if (Buffer.isBuffer(body)) return body;
2085
+ if (body instanceof Uint8Array) return Buffer.from(body);
2086
+ if (typeof body === "string") return Buffer.from(body, "utf8");
2087
+ return Buffer.from(JSON.stringify(body), "utf8");
2088
+ }
2089
+ function toSubstrateRequest(req, signal) {
2090
+ return {
2091
+ method: coerceMethod(req.method),
2092
+ path: stripQuery(req.url),
2093
+ headers: flattenHeaders(req.headers),
2094
+ query: flattenQuery(req.query),
2095
+ params: flattenParams(req.params),
2096
+ body: coerceBody(req),
2097
+ ...typeof req.ip === "string" && req.ip.length > 0 ? { peerIp: req.ip } : {},
2098
+ ...signal !== void 0 ? { signal } : {}
2099
+ };
2100
+ }
2101
+ async function applySubstrateResponse(reply, res) {
2102
+ reply.status(res.status);
2103
+ if (res.headers) for (const [k, v] of Object.entries(res.headers)) reply.header(k, v);
2104
+ const body = res.body;
2105
+ if (body === void 0) {
2106
+ await reply.send();
2107
+ return;
2108
+ }
2109
+ if (typeof body === "string") {
2110
+ await reply.send(body);
2111
+ return;
2112
+ }
2113
+ if (Buffer.isBuffer(body)) {
2114
+ await reply.send(body);
2115
+ return;
2116
+ }
2117
+ if (body instanceof Uint8Array) {
2118
+ await reply.send(Buffer.from(body));
2119
+ return;
2120
+ }
2121
+ await reply.send(Readable.fromWeb(body));
2122
+ }
2123
+
2124
+ //#endregion
2125
+ //#region ../../packages/substrate-server-fastify/src/fastify-server.ts
2126
+ /**
2127
+ * Reference SubstrateServer backed by Fastify 5.x.
2128
+ *
2129
+ * TLS design call: Fastify requires the https options at construction time, so
2130
+ * `tls` must be passed to the constructor. Passing `tls` on `start()` when the
2131
+ * instance was built without it is a programming error and throws — we do not
2132
+ * silently re-construct.
2133
+ *
2134
+ * onError design call: we register BOTH `setErrorHandler` and the `onError`
2135
+ * hook. The `onError` hook fires for errors that surface inside the request
2136
+ * lifecycle (including those thrown by handlers before the reply is sent); the
2137
+ * `setErrorHandler` override preserves Fastify's default 500 response shape
2138
+ * while still invoking the user hook. A per-request WeakSet guard stops the
2139
+ * hook from firing twice for the same error.
2140
+ *
2141
+ * createPluginRouter design call: plugin routes are mounted under
2142
+ * `/substrate/v1/plugins/<name>` so they can never shadow `/substrate/v1/*` and two plugins
2143
+ * declaring the same subpath (e.g. `/ping`) stay isolated. The facade
2144
+ * prefixes every path before handing it to `registerRoute`
2145
+ * — the main Fastify instance still sees one flat routing table.
2146
+ *
2147
+ * start() twice: Fastify's listen() rejects on a second call. We surface that
2148
+ * error as-is rather than caching and returning the prior address — the
2149
+ * caller's intent is ambiguous, fail loudly.
2150
+ */
2151
+ /** @fastify/compress's default filter. It already leaves `text/event-stream` alone. */
2152
+ const COMPRESSIBLE = /^text\/(?!event-stream)|(?:\+|\/)json(?:;|$)|(?:\+|\/)text(?:;|$)|(?:\+|\/)xml(?:;|$)|octet-stream(?:;|$)/u;
2153
+ /** Frame streams are `+json`, but a gzip stream buffers, which would stop them streaming. */
2154
+ const FRAME_STREAM = /^application\/vnd\.substrate\.frames\+/u;
2155
+ const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
2156
+ const DEFAULT_PING_INTERVAL_MS = 3e4;
2157
+ /** Streams one HTTP/2 connection may have open at once. Node's default is unbounded. */
2158
+ const H2_MAX_CONCURRENT_STREAMS = 128;
2159
+ const HANDLED_ERRORS = /* @__PURE__ */ new WeakSet();
2160
+ var FastifySubstrateServer = class {
2161
+ fastify;
2162
+ hasTls;
2163
+ errorHook;
2164
+ #observer;
2165
+ #inFlightObserver;
2166
+ inFlight = /* @__PURE__ */ new Set();
2167
+ #shutdownHooks = /* @__PURE__ */ new Set();
2168
+ #sockets = /* @__PURE__ */ new Set();
2169
+ #refused = /* @__PURE__ */ new Set();
2170
+ constructor(options = {}) {
2171
+ const { logger = false, bodyLimit, tls, cors, compression = true, requestTimeout = DEFAULT_REQUEST_TIMEOUT_MS, pingIntervalMs = DEFAULT_PING_INTERVAL_MS } = options;
2172
+ this.hasTls = tls !== void 0;
2173
+ const common = {
2174
+ logger,
2175
+ requestTimeout,
2176
+ ...bodyLimit !== void 0 ? { bodyLimit } : {}
2177
+ };
2178
+ const settings = { maxConcurrentStreams: H2_MAX_CONCURRENT_STREAMS };
2179
+ this.fastify = Fastify({
2180
+ ...common,
2181
+ http2: true,
2182
+ ...tls ? { https: {
2183
+ allowHTTP1: false,
2184
+ cert: tls.cert,
2185
+ key: tls.key,
2186
+ ...tls.ca !== void 0 ? { ca: tls.ca } : {},
2187
+ settings
2188
+ } } : { http: { settings } }
2189
+ });
2190
+ if (requestTimeout > 0) boundH2Requests(this.fastify, requestTimeout);
2191
+ this.#watch(this.fastify.server, pingIntervalMs);
2192
+ this.fastify.addHook("onListen", async () => {
2193
+ for (const server of secondaryServers(this.fastify)) this.#watch(server, pingIntervalMs);
2194
+ });
2195
+ this.fastify.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
2196
+ this.fastify.addContentTypeParser("application/vnd.substrate.pack", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
2197
+ this.fastify.setErrorHandler((err, req, reply) => {
2198
+ this.invokeErrorHook(err, req);
2199
+ const statusCode = err.statusCode ?? 500;
2200
+ const internal = statusCode >= 500;
2201
+ reply.status(statusCode).header("content-type", "application/json; charset=utf-8").send({
2202
+ schemaVersion: "",
2203
+ data: {},
2204
+ shapes: {},
2205
+ errors: [internal ? {
2206
+ message: "internal server error",
2207
+ code: "internal_error"
2208
+ } : {
2209
+ message: err.message,
2210
+ code: typeof err.code === "string" && err.code.length > 0 ? err.code : "request_error"
2211
+ }]
2212
+ });
2213
+ });
2214
+ this.fastify.addHook("onError", async (req, _reply, err) => {
2215
+ this.invokeErrorHook(err, req);
2216
+ });
2217
+ if (compression) this.fastify.register(compressPlugin, {
2218
+ threshold: 1024,
2219
+ customTypes: (type) => COMPRESSIBLE.test(type) && !FRAME_STREAM.test(type)
2220
+ });
2221
+ if (cors !== void 0) this.fastify.register(corsPlugin, {
2222
+ origin: cors.origins === "*" ? "*" : cors.origins,
2223
+ credentials: cors.credentials ?? cors.origins !== "*",
2224
+ methods: [
2225
+ "GET",
2226
+ "POST",
2227
+ "PUT",
2228
+ "PATCH",
2229
+ "DELETE",
2230
+ "OPTIONS"
2231
+ ],
2232
+ allowedHeaders: [
2233
+ "Authorization",
2234
+ "Content-Type",
2235
+ "Accept"
2236
+ ]
2237
+ });
2238
+ }
2239
+ invokeErrorHook(err, req) {
2240
+ if (!this.errorHook) return;
2241
+ if (HANDLED_ERRORS.has(err)) return;
2242
+ HANDLED_ERRORS.add(err);
2243
+ try {
2244
+ this.errorHook(err, req ? toSubstrateRequest(req) : void 0);
2245
+ } catch {}
2246
+ }
2247
+ /** Track `server`'s connections for `stop()`, and ping its HTTP/2 sessions. */
2248
+ #watch(server, pingIntervalMs) {
2249
+ if (pingIntervalMs > 0) pingSessions(server, pingIntervalMs);
2250
+ server.on("connection", (socket) => {
2251
+ this.#sockets.add(socket);
2252
+ socket.once("close", () => this.#sockets.delete(socket));
2253
+ });
2254
+ server.on("secureConnection", (socket) => {
2255
+ if (socket.alpnProtocol === "h2") return;
2256
+ this.#refused.add(socket);
2257
+ socket.once("close", () => this.#refused.delete(socket));
2258
+ });
2259
+ }
2260
+ async start(opts) {
2261
+ if (opts?.tls && !this.hasTls) throw new Error("FastifySubstrateServer: tls must be supplied at construction time, not to start()");
2262
+ const host = opts?.host ?? "0.0.0.0";
2263
+ const port = opts?.port ?? 0;
2264
+ await this.fastify.ready();
2265
+ const address = await this.fastify.listen({
2266
+ host,
2267
+ port
2268
+ });
2269
+ const info = this.fastify.addresses()[0];
2270
+ if (!info) {
2271
+ const match = /:(\d+)$/.exec(address);
2272
+ return {
2273
+ address: host,
2274
+ port: match?.[1] ? Number.parseInt(match[1], 10) : port
2275
+ };
2276
+ }
2277
+ return {
2278
+ address: info.address,
2279
+ port: info.port
2280
+ };
2281
+ }
2282
+ async stop(opts) {
2283
+ this.#notifyShutdown(WS_REASON_SERVER_RESTART);
2284
+ if (opts?.abortInFlight === true) this.abortAllRequests("server_shutdown");
2285
+ for (const socket of this.#refused) socket.destroy();
2286
+ const closed = Promise.all([this.fastify.close(), ...secondaryServers(this.fastify).filter((s) => s.listening).map((s) => new Promise((resolve) => s.once("close", resolve)))]);
2287
+ const grace = opts?.grace;
2288
+ if (grace !== void 0) {
2289
+ let timer;
2290
+ const late = await Promise.race([closed.then(() => false, () => false), new Promise((resolve) => {
2291
+ timer = setTimeout(() => resolve(true), grace);
2292
+ timer.unref();
2293
+ })]);
2294
+ clearTimeout(timer);
2295
+ if (late) for (const socket of this.#sockets) socket.destroy();
2296
+ }
2297
+ await closed;
2298
+ }
2299
+ abortAllRequests(reason) {
2300
+ const controllers = [...this.inFlight];
2301
+ for (const controller of controllers) if (!controller.signal.aborted) controller.abort(reason ?? "aborted");
2302
+ }
2303
+ onShutdown(cb) {
2304
+ this.#shutdownHooks.add(cb);
2305
+ }
2306
+ /**
2307
+ * Fan the shutdown notice out to every registered route hook. Synchronous so
2308
+ * a hook's final writes are queued before `fastify.close()` starts draining.
2309
+ */
2310
+ #notifyShutdown(reason) {
2311
+ for (const hook of [...this.#shutdownHooks]) try {
2312
+ hook(reason);
2313
+ } catch {}
2314
+ }
2315
+ /**
2316
+ * Wrap an HTTP-method route in a child plugin so it lands in the plugin
2317
+ * queue *after* compress / cors have finished loading.
2318
+ * @fastify/compress installs an `onRoute` hook that decorates each route
2319
+ * with compression metadata; routes added directly to the parent scope
2320
+ * before ready() runs miss that hook and are never compressed.
2321
+ *
2322
+ * Done-callback form (not `async`) because registerRoute is synchronous —
2323
+ * no extra Promise to discard.
2324
+ */
2325
+ #registerWrapped(method, path, handler, inFlight = this.inFlight) {
2326
+ this.fastify.register((scope, _opts, done) => {
2327
+ registerRoute(scope, method, path, handler, inFlight);
2328
+ done();
2329
+ });
2330
+ }
2331
+ route(method, path, handler) {
2332
+ this.#registerWrapped(method, path, this.#instrument(method, path, handler));
2333
+ }
2334
+ #instrument(method, path, handler) {
2335
+ const op = method === "POST" && path === "/substrate/v1/query" ? "query" : method === "POST" && path === "/substrate/v1/mutate" ? "mutate" : null;
2336
+ if (op === null) return handler;
2337
+ return async (req) => {
2338
+ const inflight = this.#inFlightObserver;
2339
+ this.#notifyInFlight(inflight, op, 1);
2340
+ try {
2341
+ const startedAt = Date.now();
2342
+ const res = await handler(req);
2343
+ const obs = this.#observer;
2344
+ if (obs !== void 0) try {
2345
+ obs({
2346
+ op,
2347
+ ok: res.status < 400,
2348
+ durationMs: Date.now() - startedAt
2349
+ });
2350
+ } catch {}
2351
+ return res;
2352
+ } finally {
2353
+ this.#notifyInFlight(inflight, op, -1);
2354
+ }
2355
+ };
2356
+ }
2357
+ #notifyInFlight(fn, op, delta) {
2358
+ if (fn === void 0) return;
2359
+ try {
2360
+ fn(op, delta);
2361
+ } catch {}
2362
+ }
2363
+ observeInFlight(fn) {
2364
+ this.#inFlightObserver = fn;
2365
+ }
2366
+ observeRequests(observer) {
2367
+ this.#observer = observer;
2368
+ }
2369
+ onError(hook) {
2370
+ this.errorHook = hook;
2371
+ }
2372
+ createPluginRouter(plugin) {
2373
+ const prefix = `/substrate/v1/plugins/${plugin.name}`;
2374
+ const prefixed = (path) => `${prefix}${path.length === 0 ? "/" : path.startsWith("/") ? path : `/${path}`}`;
2375
+ const verbEntries = [
2376
+ "GET",
2377
+ "POST",
2378
+ "PUT",
2379
+ "DELETE",
2380
+ "PATCH"
2381
+ ].map((method) => [method.toLowerCase(), (path, handler) => this.#registerWrapped(method, prefixed(path), handler, this.inFlight)]);
2382
+ return { ...Object.fromEntries(verbEntries) };
2383
+ }
2384
+ async inject(req) {
2385
+ await this.fastify.ready();
2386
+ const method = req.method ?? "GET";
2387
+ const url = buildInjectUrl(req.path ?? "/", req.query ?? {});
2388
+ const headers = { ...req.headers ?? {} };
2389
+ const payload = req.body ?? void 0;
2390
+ const injectOpts = {
2391
+ method,
2392
+ url,
2393
+ headers,
2394
+ ...payload !== void 0 ? { payload } : {}
2395
+ };
2396
+ const result = await this.fastify.inject(injectOpts);
2397
+ const rawHeaders = result.headers;
2398
+ const outHeaders = {};
2399
+ for (const [k, v] of Object.entries(rawHeaders)) {
2400
+ if (v === void 0) continue;
2401
+ outHeaders[k] = Array.isArray(v) ? v.join(", ") : String(v);
2402
+ }
2403
+ return {
2404
+ status: result.statusCode,
2405
+ headers: outHeaders,
2406
+ body: result.rawPayload
2407
+ };
2408
+ }
2409
+ };
2410
+ function buildInjectUrl(path, query) {
2411
+ const keys = Object.keys(query);
2412
+ if (keys.length === 0) return path;
2413
+ const qs = new URLSearchParams();
2414
+ for (const k of keys) {
2415
+ const v = query[k];
2416
+ if (v !== void 0) qs.set(k, v);
2417
+ }
2418
+ return `${path}${path.includes("?") ? "&" : "?"}${qs.toString()}`;
2419
+ }
2420
+ function registerRoute(fastify, method, path, handler, inFlight) {
2421
+ fastify.route({
2422
+ method,
2423
+ url: path,
2424
+ handler: async (req, reply) => {
2425
+ const controller = new AbortController();
2426
+ inFlight.add(controller);
2427
+ const onResponseClose = () => {
2428
+ if (!reply.raw.writableEnded && !controller.signal.aborted) controller.abort("client_disconnect");
2429
+ };
2430
+ reply.raw.once("close", onResponseClose);
2431
+ try {
2432
+ const hRes = await handler(toSubstrateRequest(req, controller.signal));
2433
+ await applySubstrateResponse(reply, hRes);
2434
+ } finally {
2435
+ reply.raw.off("close", onResponseClose);
2436
+ inFlight.delete(controller);
2437
+ }
2438
+ }
2439
+ });
2440
+ }
2441
+ /**
2442
+ * HTTP/2 has no `requestTimeout`: give each h2 request `ms` to arrive in full
2443
+ * (headers and body), then reset its stream. The clock stops once the handler
2444
+ * runs, so a streamed response is not bounded by it.
2445
+ */
2446
+ function boundH2Requests(fastify, ms) {
2447
+ const timers = /* @__PURE__ */ new WeakMap();
2448
+ fastify.addHook("onRequest", async (req) => {
2449
+ const stream = req.raw.stream;
2450
+ if (stream === void 0) return;
2451
+ const timer = setTimeout(() => stream.close(constants.NGHTTP2_CANCEL), ms);
2452
+ timers.set(req.raw, timer);
2453
+ stream.once("close", () => clearTimeout(timer));
2454
+ });
2455
+ fastify.addHook("preHandler", async (req, reply) => {
2456
+ clearTimeout(timers.get(req.raw));
2457
+ if (req.raw.stream?.closed === true) return reply.code(408).send();
2458
+ });
2459
+ }
2460
+ /**
2461
+ * Ping each HTTP/2 session every `ms`; a session with two pings in a row
2462
+ * unanswered is destroyed. That is how a peer that vanished without closing
2463
+ * its socket is noticed, and its streams' close paths run. Two, not one: a
2464
+ * ping can queue behind a full write buffer on a slow link, or its ack behind
2465
+ * a blocked event loop.
2466
+ */
2467
+ function pingSessions(server, ms) {
2468
+ server.on("session", (session) => {
2469
+ let unanswered = 0;
2470
+ const timer = setInterval(() => {
2471
+ if (unanswered >= 2) {
2472
+ session.destroy();
2473
+ return;
2474
+ }
2475
+ unanswered++;
2476
+ try {
2477
+ session.ping((err) => {
2478
+ if (err === null) unanswered = 0;
2479
+ });
2480
+ } catch {}
2481
+ }, ms);
2482
+ timer.unref();
2483
+ session.once("close", () => clearInterval(timer));
2484
+ });
2485
+ }
2486
+ /**
2487
+ * Fastify's secondary listeners. Fastify 5 keeps them only under its private
2488
+ * `fastify.serverBindings` symbol (lib/server.js `multipleBindings`), with no
2489
+ * public accessor, so look the symbol up by its description.
2490
+ */
2491
+ function secondaryServers(fastify) {
2492
+ const key = Object.getOwnPropertySymbols(fastify).find((s) => s.description === "fastify.serverBindings");
2493
+ const bindings = key === void 0 ? void 0 : fastify[key];
2494
+ return Array.isArray(bindings) ? bindings : [];
2495
+ }
2496
+
2497
+ //#endregion
2498
+ //#region ../../packages/substrate-sentinel-client/src/client.ts
2499
+ /**
2500
+ * substrate-sentinel-client — watches a sentinel instance's topology feed and
2501
+ * mutates a caller-owned BridgeRegistry on online/offline events.
2502
+ *
2503
+ * - GET <sentinel>/substrate/v1/plugins/substrate-sentinel/watch, a stream of
2504
+ * length-prefixed JSON frames
2505
+ * - on {event:'online'}: create HttpBridgeClient, register in bridges,
2506
+ * call engine.refreshBridgeSchemas()
2507
+ * - on {event:'offline'}: unregister bridge + dispose client
2508
+ * - on a refusal or a dropped stream: reconnect with exponential backoff,
2509
+ * reset only after a stream that lasted `reconnectMaxMs`
2510
+ * - stop(): ends the stream + disposes all active bridges
2511
+ */
2512
+ const WATCH_PATH = "/substrate/v1/plugins/substrate-sentinel/watch";
2513
+ /** Three of the sentinel's heartbeats at its 30 s maximum `pingIntervalMs`, plus a margin. */
2514
+ const SENTINEL_IDLE_MS = 95e3;
2515
+ const NO_OP_METRIC = () => {};
2516
+ function startSentinelClient(opts) {
2517
+ const metric = opts.metric ?? NO_OP_METRIC;
2518
+ const watchAuth = opts.auth;
2519
+ const fetchImpl = opts.fetch ?? substrateFetch;
2520
+ const watchUrl = `${trimTrailingSlashes(opts.sentinelUrl)}${WATCH_PATH}`;
2521
+ const baseMs = opts.reconnectBaseMs ?? 500;
2522
+ const maxMs = opts.reconnectMaxMs ?? 3e4;
2523
+ const idleMs = opts.idleMs ?? SENTINEL_IDLE_MS;
2524
+ const ownedBridges = /* @__PURE__ */ new Map();
2525
+ const ctrl = new AbortController();
2526
+ let stopped = false;
2527
+ let connected = false;
2528
+ let currentBackoff = baseMs;
2529
+ /** Resolves after `ms`, or at once when stopped. The timer never holds the process open. */
2530
+ function pause(ms) {
2531
+ return new Promise((resolve) => {
2532
+ const timer = setTimeout(done, ms);
2533
+ timer.unref();
2534
+ function done() {
2535
+ clearTimeout(timer);
2536
+ ctrl.signal.removeEventListener("abort", done);
2537
+ resolve();
2538
+ }
2539
+ ctrl.signal.addEventListener("abort", done, { once: true });
2540
+ });
2541
+ }
2542
+ /** One watch request, read to its end. */
2543
+ async function watchOnce() {
2544
+ const headers = { accept: FRAMES_JSON_MIME };
2545
+ if (watchAuth !== void 0) headers.authorization = watchAuth();
2546
+ const res = await fetchImpl(watchUrl, {
2547
+ method: "GET",
2548
+ headers,
2549
+ signal: ctrl.signal
2550
+ });
2551
+ const type = res.headers.get("content-type") ?? "";
2552
+ if (!res.ok || res.body === null || !type.startsWith("application/vnd.substrate.frames+json")) {
2553
+ await res.body?.cancel();
2554
+ metric("sentinel_client_error", {
2555
+ status: res.status,
2556
+ error: `watch answered ${res.status} ${type}`
2557
+ });
2558
+ return;
2559
+ }
2560
+ const openedAt = Date.now();
2561
+ connected = true;
2562
+ metric("sentinel_client_connected");
2563
+ try {
2564
+ const utf8 = new TextDecoder();
2565
+ for await (const payload of decodeStreamFrames(idleMs > 0 ? withIdleTimeout(res.body, idleMs) : res.body)) {
2566
+ let frame;
2567
+ try {
2568
+ frame = JSON.parse(utf8.decode(payload));
2569
+ } catch {
2570
+ continue;
2571
+ }
2572
+ if (frame.event === "online") handleOnline(frame);
2573
+ else if (frame.event === "offline") handleOffline(frame);
2574
+ }
2575
+ } finally {
2576
+ connected = false;
2577
+ if (Date.now() - openedAt >= maxMs) currentBackoff = baseMs;
2578
+ }
2579
+ }
2580
+ async function run() {
2581
+ while (!stopped) {
2582
+ try {
2583
+ await watchOnce();
2584
+ } catch {}
2585
+ if (stopped) return;
2586
+ metric("sentinel_client_disconnected");
2587
+ const delay = currentBackoff;
2588
+ metric("sentinel_client_reconnecting", { delayMs: delay });
2589
+ currentBackoff = Math.min(currentBackoff * 2, maxMs);
2590
+ await pause(delay);
2591
+ }
2592
+ }
2593
+ async function handleOnline(frame) {
2594
+ const name = typeof frame.name === "string" ? frame.name : void 0;
2595
+ const url = typeof frame.url === "string" ? frame.url : void 0;
2596
+ const namespaces = Array.isArray(frame.namespaces) ? frame.namespaces : [];
2597
+ if (name === void 0 || url === void 0) return;
2598
+ const cred = opts.creds.get(name);
2599
+ if (cred === void 0) {
2600
+ metric("bridge_discovery_rejected", {
2601
+ name,
2602
+ url
2603
+ });
2604
+ return;
2605
+ }
2606
+ let advertisedOrigin;
2607
+ try {
2608
+ advertisedOrigin = new URL(url).origin;
2609
+ } catch {
2610
+ metric("bridge_discovery_origin_mismatch", {
2611
+ name,
2612
+ url,
2613
+ expected: cred.origin
2614
+ });
2615
+ return;
2616
+ }
2617
+ if (advertisedOrigin !== cred.origin) {
2618
+ metric("bridge_discovery_origin_mismatch", {
2619
+ name,
2620
+ url,
2621
+ expected: cred.origin
2622
+ });
2623
+ return;
2624
+ }
2625
+ const auth = makeAuthorizationProvider(cred, {
2626
+ lazyKey: true,
2627
+ audience: cred.origin
2628
+ });
2629
+ for (const nsValue of namespaces) {
2630
+ if (stopped) return;
2631
+ if (typeof nsValue !== "string" || nsValue.length === 0) continue;
2632
+ const ns = nsValue;
2633
+ if (opts.bridges.has(ns)) continue;
2634
+ if (opts.engine.registryFor(ns) !== void 0) {
2635
+ metric("bridge_discovery_local_namespace", {
2636
+ name,
2637
+ ns
2638
+ });
2639
+ continue;
2640
+ }
2641
+ const client = new HttpBridgeClient({
2642
+ name,
2643
+ baseUrl: url,
2644
+ auth,
2645
+ fetch: substrateFetch
2646
+ });
2647
+ opts.bridges.register(ns, client);
2648
+ ownedBridges.set(ns, client);
2649
+ metric("sentinel_client_online", {
2650
+ ns,
2651
+ url
2652
+ });
2653
+ try {
2654
+ await opts.engine.refreshBridgeSchemas();
2655
+ } catch {
2656
+ metric("sentinel_client_refresh_failed", { ns });
2657
+ }
2658
+ if (stopped) {
2659
+ try {
2660
+ opts.bridges.unregister(ns);
2661
+ } catch {}
2662
+ client.dispose();
2663
+ ownedBridges.delete(ns);
2664
+ return;
2665
+ }
2666
+ }
2667
+ }
2668
+ function handleOffline(frame) {
2669
+ const name = typeof frame.name === "string" ? frame.name : void 0;
2670
+ const raw = typeof frame.url === "string" ? frame.url : void 0;
2671
+ if (name === void 0 || raw === void 0) return;
2672
+ const url = raw.endsWith("/") ? raw.slice(0, -1) : raw;
2673
+ for (const [ns, client] of [...ownedBridges]) {
2674
+ if (client.baseUrl !== url || client.name !== name) continue;
2675
+ try {
2676
+ opts.bridges.unregister(ns);
2677
+ } catch {}
2678
+ client.dispose();
2679
+ ownedBridges.delete(ns);
2680
+ metric("sentinel_client_offline", { ns });
2681
+ }
2682
+ }
2683
+ const running = run();
2684
+ return {
2685
+ isConnected: () => connected,
2686
+ stop: async () => {
2687
+ if (stopped) return;
2688
+ stopped = true;
2689
+ ctrl.abort();
2690
+ for (const [ns, client] of ownedBridges) {
2691
+ try {
2692
+ opts.bridges.unregister(ns);
2693
+ } catch {}
2694
+ client.dispose();
2695
+ }
2696
+ ownedBridges.clear();
2697
+ await running;
2698
+ }
2699
+ };
2700
+ }
2701
+
2702
+ //#endregion
2703
+ //#region ../../packages/substrate-sentinel-client/src/config.ts
2704
+ function parseCred(raw) {
2705
+ if (raw === void 0 || raw.trim() === "") throw new Error("SUBSTRATE_SENTINEL_URL is set but SUBSTRATE_SENTINEL_CREDENTIAL is not — sentinel requires an authenticated client");
2706
+ let parsed;
2707
+ try {
2708
+ parsed = JSON.parse(raw);
2709
+ } catch (err) {
2710
+ throw new Error(`SUBSTRATE_SENTINEL_CREDENTIAL: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
2711
+ }
2712
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: must be a JSON object of { keyPath, kid }");
2713
+ const e = parsed;
2714
+ if (typeof e.keyPath !== "string" || e.keyPath.length === 0) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: missing string 'keyPath'");
2715
+ if (typeof e.kid !== "string" || e.kid.length === 0) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: missing string 'kid'");
2716
+ return {
2717
+ keyPath: e.keyPath,
2718
+ kid: e.kid
2719
+ };
2720
+ }
2721
+ const DEFAULT_RECONNECT_BASE_MS = 500;
2722
+ const DEFAULT_RECONNECT_MAX_MS = 3e4;
2723
+ function loadConfig(env = process.env) {
2724
+ const rawUrl = env.SUBSTRATE_SENTINEL_URL;
2725
+ if (rawUrl === void 0 || rawUrl.length === 0) return null;
2726
+ if (!rawUrl.startsWith("http://") && !rawUrl.startsWith("https://")) throw new Error("SUBSTRATE_SENTINEL_URL must be the sentinel's http:// or https:// base URL (e.g. https://sentinel.example:3100); the ws:// endpoint is retired");
2727
+ return {
2728
+ url: rawUrl,
2729
+ cred: parseCred(env.SUBSTRATE_SENTINEL_CREDENTIAL),
2730
+ reconnectBaseMs: parsePositiveInt(env.SUBSTRATE_SENTINEL_RECONNECT_BASE_MS, "SUBSTRATE_SENTINEL_RECONNECT_BASE_MS", DEFAULT_RECONNECT_BASE_MS),
2731
+ reconnectMaxMs: parsePositiveInt(env.SUBSTRATE_SENTINEL_RECONNECT_MAX_MS, "SUBSTRATE_SENTINEL_RECONNECT_MAX_MS", DEFAULT_RECONNECT_MAX_MS)
2732
+ };
2733
+ }
2734
+
2735
+ //#endregion
2736
+ //#region src/serve/knobs.ts
2737
+ /** Treat explicitly-empty string env values as unset. */
2738
+ function nonEmpty(v) {
2739
+ return v !== void 0 && v !== "" ? v : void 0;
2740
+ }
2741
+ function createKnobRecorder() {
2742
+ const entries = /* @__PURE__ */ new Map();
2743
+ const sourceOf = (raw) => nonEmpty(raw) === void 0 ? "default" : "explicit";
2744
+ return {
2745
+ record(key, env, raw, value) {
2746
+ entries.set(key, {
2747
+ env,
2748
+ value,
2749
+ source: sourceOf(raw)
2750
+ });
2751
+ return value;
2752
+ },
2753
+ recordSecret(key, env, raw) {
2754
+ const present = nonEmpty(raw?.trim()) !== void 0;
2755
+ entries.set(key, {
2756
+ env,
2757
+ value: present ? "<set>" : null,
2758
+ source: sourceOf(raw),
2759
+ redacted: true
2760
+ });
2761
+ },
2762
+ report() {
2763
+ return Object.fromEntries(entries);
2764
+ }
2765
+ };
2766
+ }
2767
+
2768
+ //#endregion
2769
+ //#region src/serve/wiring.ts
2770
+ /**
2771
+ * serve/wiring.ts — substrate + bridge + dataset wiring.
2772
+ *
2773
+ * Everything `runServe()` needs between `parseEnv()` and `compose()`:
2774
+ * store construction, bridge registry, per-namespace datasets, migration
2775
+ * tracking, and the two substrate-composition singletons (filter-operator
2776
+ * registry, pending MCP tools).
2777
+ */
2778
+ const filterRegistry = { register(name, op) {
2779
+ if (getExtensionOperator(name) !== void 0) throw new EnvConfigError(`Filter operator '${name}' already registered`);
2780
+ registerExtensionOperator(name, op);
2781
+ } };
2782
+ const pendingMcpTools = [];
2783
+ /** Seconds `close` waits for in-flight queries before it drops their connections. */
2784
+ const STORE_END_TIMEOUT_S = 2;
2785
+ async function wireStore(storeSpec, fieldDefLookupFor, typeDefLookupFor, diskGuard, statementTimeoutMs) {
2786
+ if (storeSpec === "memory") return {
2787
+ dataset: new MemoryDataset({
2788
+ namespace: DEFAULT_NAMESPACE,
2789
+ fieldDefLookup: fieldDefLookupFor(DEFAULT_NAMESPACE),
2790
+ ...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE) } : {}
2791
+ }),
2792
+ edges: new MemoryEdgesStore({ now: () => /* @__PURE__ */ new Date() }),
2793
+ substrateNamespaceDataset: null,
2794
+ sql: null,
2795
+ close: null
2796
+ };
2797
+ if (storeSpec.startsWith("postgres://") || storeSpec.startsWith("postgresql://")) {
2798
+ const sql = openSql(storeSpec, statementTimeoutMs !== void 0 ? { queueTimeoutMs: statementTimeoutMs } : {});
2799
+ try {
2800
+ await runMigrations(sql);
2801
+ } catch (err) {
2802
+ await sql.end({ timeout: 2 }).catch(() => void 0);
2803
+ throw err;
2804
+ }
2805
+ const edges = new PgEdgesStore({ sql });
2806
+ return {
2807
+ dataset: new PgDataset({
2808
+ namespace: DEFAULT_NAMESPACE,
2809
+ sql,
2810
+ edgesStore: edges,
2811
+ fieldDefLookup: fieldDefLookupFor(DEFAULT_NAMESPACE),
2812
+ ...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE) } : {},
2813
+ ...diskGuard !== void 0 ? { diskGuard } : {},
2814
+ ...statementTimeoutMs !== void 0 ? { statementTimeoutMs } : {}
2815
+ }),
2816
+ edges,
2817
+ substrateNamespaceDataset: new PgDataset({
2818
+ namespace: SYSTEM_NAMESPACE,
2819
+ sql,
2820
+ edgesStore: edges,
2821
+ fieldDefLookup: fieldDefLookupFor(SYSTEM_NAMESPACE),
2822
+ ...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(SYSTEM_NAMESPACE) } : {},
2823
+ ...diskGuard !== void 0 ? { diskGuard } : {},
2824
+ ...statementTimeoutMs !== void 0 ? { statementTimeoutMs } : {}
2825
+ }),
2826
+ sql,
2827
+ close: () => sql.end({ timeout: 2 })
2828
+ };
2829
+ }
2830
+ throw new EnvConfigError(`SUBSTRATE_DATABASE_URL: invalid value '${storeSpec}' — expected 'memory' or a postgres:// URL`);
2831
+ }
2832
+ /**
2833
+ * Builds a bridge registry from `specs`, returning it with a `dispose` that
2834
+ * releases every client. Throws if a spec has no credential, a malformed
2835
+ * url, or a url whose origin differs from its credential's.
2836
+ */
2837
+ function buildBridgeRegistry(specs, creds) {
2838
+ const registry = new MemoryBridgeRegistry();
2839
+ const clients = [];
2840
+ for (const spec of specs) {
2841
+ const cred = creds.get(spec.name);
2842
+ if (cred === void 0) throw new Error(`bridge '${spec.name}' has no credential`);
2843
+ let specOrigin;
2844
+ try {
2845
+ specOrigin = new URL(spec.url).origin;
2846
+ } catch {
2847
+ throw new Error(`bridge '${spec.name}' has a malformed url '${spec.url}'`);
2848
+ }
2849
+ if (specOrigin !== cred.origin) throw new Error(`bridge '${spec.name}' url origin '${specOrigin}' does not match its credential origin '${cred.origin}'`);
2850
+ const auth = makeAuthorizationProvider(cred, { audience: cred.origin });
2851
+ const client = new HttpBridgeClient({
2852
+ name: spec.name,
2853
+ baseUrl: spec.url,
2854
+ auth,
2855
+ fetch: substrateFetch
2856
+ });
2857
+ clients.push(client);
2858
+ registry.register(spec.ns, client);
2859
+ }
2860
+ return {
2861
+ registry,
2862
+ dispose: () => {
2863
+ for (const c of clients) c.dispose();
2864
+ }
2865
+ };
2866
+ }
2867
+ /**
2868
+ * Build a per-namespace {@link FieldDefLookup} factory backed by a mutable
2869
+ * registry of loaded namespace definitions. The default + `_system` datasets are
2870
+ * constructed (in `wireStore`) BEFORE plugins load, so the returned closures
2871
+ * resolve lazily — the same late-binding contract as `datasetRegistryRef` /
2872
+ * `engineRef`. `runServe` populates `nsDefs` once plugins are loaded and well
2873
+ * before the server listens, so every query resolves against a populated map.
2874
+ *
2875
+ * A field no definition declares (a type or field proposed at runtime) resolves
2876
+ * from the live registry once `registryFor` does, as in
2877
+ * {@link makeTypeDefLookupFactory}; without it a walk over a proposed crossRef
2878
+ * throws and a pending number field sorts as text.
2879
+ *
2880
+ * A miss (namespace absent, or a hand-crafted `NamespaceDefinition` whose
2881
+ * `types` is undefined because it bypassed `defineNamespace`) returns
2882
+ * `undefined`, and the dataset falls back to lexicographic text compare.
2883
+ */
2884
+ function makeFieldDefLookupFactory(nsDefs, registryFor = () => void 0) {
2885
+ return (namespace) => (type, field) => {
2886
+ const declared = nsDefs.get(namespace)?.types?.[type]?.fields?.[field];
2887
+ if (declared !== void 0) return declared;
2888
+ const entry = registryFor(namespace)?.get(type);
2889
+ const def = entry?.kind === "type" && Object.hasOwn(entry.fields, field) ? entry.fields[field] : void 0;
2890
+ return def === void 0 || isReservedAutoCrudField(def) ? void 0 : def;
2891
+ };
2892
+ }
2893
+ /**
2894
+ * Build a {@link TypeDefLookup} factory over the same late-bound `nsDefs`
2895
+ * registry as {@link makeFieldDefLookupFactory}: a type's fields and declared
2896
+ * indexes, which `PgDataset.ensureTypeStorage` builds indexes from. Once
2897
+ * `registryFor` resolves, the live registry's fields, which include proposed
2898
+ * ones, are merged over the declared fields, and the declared `indexes` are
2899
+ * kept; a type no definition declares (proposed at runtime, or registered at
2900
+ * install) has the registry's fields alone. The engine's reserved fields are
2901
+ * left out where autoCRUD registered them, since they are not body fields.
2902
+ * The lookup answers for the namespace it is asked about, so clones made by
2903
+ * `forNamespace` resolve their own types.
2904
+ */
2905
+ function makeTypeDefLookupFactory(nsDefs, registryFor = () => void 0) {
2906
+ const lookup = (type, namespace) => {
2907
+ const declared = nsDefs.get(namespace)?.types?.[type];
2908
+ const entry = registryFor(namespace)?.get(type);
2909
+ const registered = entry?.kind === "type" ? entry : void 0;
2910
+ const orderedBy = registered !== void 0 ? registered.orderedBy : declared?.autoCrud === false ? void 0 : declared?.orderedBy;
2911
+ if (registered === void 0 && (declared === void 0 || orderedBy === declared.orderedBy)) return declared;
2912
+ const { orderedBy: _ignored, ...rest } = declared ?? { fields: {} };
2913
+ const live = registered === void 0 ? {} : Object.fromEntries(Object.entries(registered.fields).filter(([, def]) => !isReservedAutoCrudField(def)));
2914
+ const indexes = rest.indexes ?? registered?.indexes;
2915
+ const expectedSize = rest.expectedSize ?? registered?.expectedSize;
2916
+ return {
2917
+ ...rest,
2918
+ fields: {
2919
+ ...rest.fields,
2920
+ ...live
2921
+ },
2922
+ ...orderedBy !== void 0 ? { orderedBy } : {},
2923
+ ...indexes !== void 0 ? { indexes } : {},
2924
+ ...expectedSize !== void 0 ? { expectedSize } : {}
2925
+ };
2926
+ };
2927
+ return () => lookup;
2928
+ }
2929
+ /**
2930
+ * Prepares storage for every type the namespace definitions declare: its
2931
+ * table and its unique indexes, through `Dataset.ensureTypeStorage`. Runs
2932
+ * before any kernel migration, so a migration can rely on a declared unique
2933
+ * index. Non-unique indexes are left to {@link buildDeferredIndexes}. Errors
2934
+ * propagate and fail the boot, among them `UniqueIndexDuplicatesError` and
2935
+ * `IndexDefinitionConflictError`, which name the index, and a declared
2936
+ * namespace with no dataset. Index builds run CONCURRENTLY, so the process
2937
+ * must hold no open transaction meanwhile.
2938
+ */
2939
+ async function reconcileDeclaredStorage(datasetFor, nsDefs) {
2940
+ for (const [ns, def] of nsDefs) {
2941
+ const dataset = datasetFor(ns);
2942
+ if (dataset === void 0) throw new Error(`namespace '${ns}' is declared but has no dataset; its storage cannot be prepared`);
2943
+ for (const type of Object.keys(def.types ?? {})) await dataset.ensureTypeStorage?.(type, {
2944
+ indexes: "unique",
2945
+ newFields: "column"
2946
+ });
2947
+ }
2948
+ }
2949
+ /** Every type registered in a namespace with a local dataset, with that dataset. */
2950
+ function* registeredTypes(engine, datasets) {
2951
+ for (const ns of Object.keys(engine.federatedSchema())) {
2952
+ if (!datasets.has(ns)) continue;
2953
+ const dataset = datasets.get(ns);
2954
+ for (const [type, entry] of engine.registryFor(ns)?.all() ?? []) if (entry.kind === "type") yield {
2955
+ ns,
2956
+ type,
2957
+ dataset
2958
+ };
2959
+ }
2960
+ }
2961
+ const message = (err) => err instanceof Error ? err.message : String(err);
2962
+ /**
2963
+ * Prepares storage, table and unique indexes, for every type registered in
2964
+ * every local namespace once compose has run: `_system`, install-time types
2965
+ * such as the proposals plugin's, and proposed types replayed at start.
2966
+ * Namespaces without a local dataset (bridged, virtual) are skipped. A type the
2967
+ * operator's `nsDefs` declares fails the boot on error, since its unique
2968
+ * indexes must exist. A type only the registry knows (proposed by a principal
2969
+ * who can merely propose) logs the error naming it and the boot continues.
2970
+ */
2971
+ async function reconcileRegisteredStorage(engine, datasets, nsDefs) {
2972
+ for (const { ns, type, dataset } of registeredTypes(engine, datasets)) try {
2973
+ await dataset?.ensureTypeStorage?.(type, { indexes: "unique" });
2974
+ } catch (err) {
2975
+ if (nsDefs.get(ns)?.types?.[type] !== void 0) throw err;
2976
+ process.stderr.write(`storage for registered type ${ns}/${type} was not prepared: ${message(err)}\n`);
2977
+ }
2978
+ }
2979
+ /**
2980
+ * When `SUBSTRATE_INDEX_DISK_PATH` is unset, logs how many non-unique index
2981
+ * builds the boot pass faces and their estimated size, since none of them
2982
+ * will be checked against free disk. Logs nothing when none is pending.
2983
+ */
2984
+ async function reportUnguardedIndexBuilds(engine, datasets, write = (line) => void process.stderr.write(line)) {
2985
+ let count = 0;
2986
+ let bytes = 0;
2987
+ for (const { type, dataset } of registeredTypes(engine, datasets)) {
2988
+ if (!(dataset instanceof PgDataset)) continue;
2989
+ for (const p of await dataset.pendingIndexBuilds(type)) {
2990
+ count++;
2991
+ bytes += p.estimateBytes;
2992
+ }
2993
+ }
2994
+ if (count === 0) return;
2995
+ write(`${count} index build${count === 1 ? "" : "s"} pending, estimated ${(bytes / 2 ** 30).toFixed(1)} GiB in total, and SUBSTRATE_INDEX_DISK_PATH is unset, so free disk is not checked before them; set it to the database volume's mount (or 'off')
2996
+ `);
2997
+ }
2998
+ /**
2999
+ * Builds the non-unique indexes of every registered type, one type at a time.
3000
+ * Started after the server listens: until an index is valid, filters it would
3001
+ * serve scan. Never rejects: a type whose build fails is logged, and reported
3002
+ * `failed`, until the next build pass (periodic, or the next boot) retries it. `signal` cancels the build in
3003
+ * flight, whose INVALID leftover the next reconcile drops, and skips the rest.
3004
+ * Resolves to the logged failures, one line per type, for a caller that must
3005
+ * not pass over them.
3006
+ */
3007
+ async function buildDeferredIndexes(engine, datasets, signal, opts = {}) {
3008
+ const failures = [];
3009
+ for (const { ns, type, dataset } of registeredTypes(engine, datasets)) {
3010
+ if (signal?.aborted === true) break;
3011
+ try {
3012
+ if (opts.onlyUnsettled === true && !await unsettled(dataset, type)) continue;
3013
+ await dataset?.ensureTypeStorage?.(type, {
3014
+ indexes: "nonUnique",
3015
+ ...signal !== void 0 ? { signal } : {}
3016
+ });
3017
+ } catch (err) {
3018
+ const line = `indexes of ${ns}/${type} were not built and will be retried by the next build pass: ${message(err)}`;
3019
+ failures.push(line);
3020
+ process.stderr.write(`${line}\n`);
3021
+ }
3022
+ }
3023
+ return failures;
3024
+ }
3025
+ /** Whether `type` has a non-unique index still pending, failed or invalid. */
3026
+ async function unsettled(dataset, type) {
3027
+ return ((await dataset?.describeStorage?.(type))?.indexes ?? []).some((i) => !i.unique && (i.state === "pending" || i.state === "failed" || i.state === "invalid"));
3028
+ }
3029
+ /**
3030
+ * The boot pass of {@link buildDeferredIndexes}, then every `intervalMs` a
3031
+ * pass over only the types with a non-unique index still pending, failed or invalid,
3032
+ * such as one the disk guard refused. 0 runs the boot pass alone. Passes run
3033
+ * one after another, so never overlap. Resolves once `signal` aborts.
3034
+ */
3035
+ async function runDeferredIndexBuilds(engine, datasets, intervalMs, signal) {
3036
+ await buildDeferredIndexes(engine, datasets, signal);
3037
+ while (intervalMs > 0 && !signal.aborted) {
3038
+ try {
3039
+ await setTimeout$1(intervalMs, void 0, {
3040
+ signal,
3041
+ ref: false
3042
+ });
3043
+ } catch {
3044
+ return;
3045
+ }
3046
+ await buildDeferredIndexes(engine, datasets, signal, { onlyUnsettled: true });
3047
+ }
3048
+ }
3049
+ /**
3050
+ * Walk loaded namespace definitions for `field.list({ indexed: true })` and
3051
+ * `field.json({ indexed: true })` fields. Each becomes an auto-derived GIN
3052
+ * migration so the `indexed` flag — the physical-index contract —
3053
+ * can't drift from the physical index.
3054
+ */
3055
+ function extractIndexedListFields(nsDefs) {
3056
+ const out = [];
3057
+ for (const [namespace, def] of nsDefs) {
3058
+ const types = def.types;
3059
+ if (types === void 0) continue;
3060
+ for (const [type, typeDef] of Object.entries(types)) for (const [field, fieldDef] of Object.entries(typeDef.fields)) {
3061
+ const indexedJson = fieldDef.kind === "scalar" && fieldDef.type === "json" && fieldDef.indexed === true;
3062
+ if (fieldDef.kind === "list" && fieldDef.indexed === true || indexedJson) out.push({
3063
+ namespace,
3064
+ type,
3065
+ field
3066
+ });
3067
+ }
3068
+ }
3069
+ return out;
3070
+ }
3071
+ /**
3072
+ * Pick per-namespace datasets for plugin-contributed namespaces.
3073
+ *
3074
+ * When the store is pg (`sharedSql` is non-null) every plugin namespace is
3075
+ * backed by a `PgDataset` pointing at the same connection pool — each
3076
+ * type in a table of its own, listed by namespace in the type catalog, which
3077
+ * is the core multi-namespace model. Multi-pg (namespace → distinct DB)
3078
+ * deployments should override `datasets` on the `compose()` call site
3079
+ * directly; this helper only covers the common single-pg-many-namespaces
3080
+ * shape.
3081
+ *
3082
+ * When the store is memory, every plugin namespace gets a fresh
3083
+ * `MemoryDataset` so the contribution boots cleanly without reaching
3084
+ * across to the default substrate.
3085
+ *
3086
+ * `fieldDefLookupFor` yields the namespace-scoped lookup that lets pg datasets
3087
+ * cast numeric/date/boolean body fields in orderBy + range + cursor compares.
3088
+ * Memory datasets ignore it.
3089
+ */
3090
+ function buildPluginDatasetMap(plugins, defaultDataset, sharedSql, sharedEdges, fieldDefLookupFor, typeDefLookup, diskGuard, statementTimeoutMs) {
3091
+ const datasets = {};
3092
+ for (const plugin of plugins) for (const nsDef of plugin.namespaces) {
3093
+ const ns = nsDef.namespace;
3094
+ if (ns === "default") {
3095
+ datasets[ns] = defaultDataset;
3096
+ continue;
3097
+ }
3098
+ if (datasets[ns] !== void 0) continue;
3099
+ datasets[ns] = sharedSql !== null ? new PgDataset({
3100
+ namespace: ns,
3101
+ sql: sharedSql,
3102
+ fieldDefLookup: fieldDefLookupFor(ns),
3103
+ typeDefLookup: typeDefLookup ?? ((type) => nsDef.types?.[type]),
3104
+ ...sharedEdges !== null ? { edgesStore: sharedEdges } : {},
3105
+ ...diskGuard !== void 0 ? { diskGuard } : {},
3106
+ ...statementTimeoutMs !== void 0 ? { statementTimeoutMs } : {}
3107
+ }) : new MemoryDataset({
3108
+ namespace: ns,
3109
+ fieldDefLookup: fieldDefLookupFor(ns),
3110
+ typeDefLookup: typeDefLookup ?? ((type) => nsDef.types?.[type])
3111
+ });
3112
+ }
3113
+ return datasets;
3114
+ }
3115
+ /**
3116
+ * Redact the password component of a `SUBSTRATE_DATABASE_URL` value so it can be safely
3117
+ * written to stdout / journald at boot. Operates on postgres URLs; passes
3118
+ * `memory` (and any other non-URL value) through unchanged.
3119
+ */
3120
+ function redactStoreSpec(spec) {
3121
+ if (!spec.startsWith("postgres://") && !spec.startsWith("postgresql://")) return spec;
3122
+ return spec.replace(/^(postgres(?:ql)?:\/\/[^:@/]+):[^@]*@/, "$1:<redacted>@");
3123
+ }
3124
+ /**
3125
+ * Ensure the `kernel_migrations` tracking table exists. Distinct
3126
+ * from `migrations` (which the dataset-pg framework owns for its own
3127
+ * `version`/`checksum`-keyed migrations) — this table tracks
3128
+ * KernelPlugin-contributed migrations by `(plugin_name, migration_id)`.
3129
+ * Idempotent CREATE-IF-NOT-EXISTS. No-op on memory-backed deployments.
3130
+ */
3131
+ async function ensureMigrationsTable(sql) {
3132
+ await kernelMigrationTracking(sql).ensure();
3133
+ }
3134
+ /**
3135
+ * Return the set of migration IDs already recorded as applied for the given
3136
+ * plugin. Returns an empty Set on memory-backed deployments (sql null).
3137
+ */
3138
+ async function getAppliedMigrationIds(sql, pluginName) {
3139
+ return kernelMigrationTracking(sql).getAppliedMigrationIds(pluginName);
3140
+ }
3141
+ /**
3142
+ * Record a migration as applied. ON CONFLICT DO NOTHING makes this safe to
3143
+ * call even if the row already exists (concurrent boot, retry after a partial
3144
+ * failure). No-op on memory-backed deployments.
3145
+ */
3146
+ async function recordMigrationApplied(sql, pluginName, migrationId) {
3147
+ await kernelMigrationTracking(sql).recordMigrationApplied(pluginName, migrationId);
3148
+ }
3149
+
3150
+ //#endregion
3151
+ //#region src/serve/config.ts
3152
+ /**
3153
+ * serve/config.ts — env-var configuration parsing for `substrate serve`.
3154
+ */
3155
+ const DEFAULT_SWEEP_INTERVAL_MS = 3e5;
3156
+ const DEFAULT_STATEMENT_TIMEOUT_MS = 3e4;
3157
+ const DEFAULT_INVITE_SWEEP_INTERVAL_MS = 36e5;
3158
+ const DEFAULT_TOMBSTONE_RETENTION_DAYS = 30;
3159
+ const DEFAULT_SHUTDOWN_GRACE_MS = 5e3;
3160
+ const DEFAULT_TYPE_TABLE_BUDGET = 500;
3161
+ const DEFAULT_INDEX_DISK_MARGIN_MB = 2048;
3162
+ const DEFAULT_INDEX_RETRY_INTERVAL_MS = 6e5;
3163
+ const DEFAULT_ADVISOR_INTERVAL_MS = 6e5;
3164
+ const DEFAULT_PROMOTE_INTERVAL_MS = 216e5;
3165
+ const MS_PER_DAY = 864e5;
3166
+ const DEFAULT_PORT = 3100;
3167
+ var EnvConfigError = class extends Error {
3168
+ name = "EnvConfigError";
3169
+ };
3170
+ /** Set once the retired `SUBSTRATE_STORAGE_LAYOUT` has been warned about. */
3171
+ let warnedStorageLayout = false;
3172
+ /** Set once the deprecated `SUBSTRATE_PARTITION_BUDGET` has been warned about. */
3173
+ let warnedPartitionBudget = false;
3174
+ /**
3175
+ * Parses the serve env into a fully resolved `ParsedConfig`. The only I/O is
3176
+ * reading the auth and TLS PEM / JSON files. Throws `EnvConfigError` on any
3177
+ * malformed input.
3178
+ */
3179
+ function parseEnv(env) {
3180
+ if (env.SUBSTRATE_STORAGE_LAYOUT !== void 0 && !warnedStorageLayout) {
3181
+ warnedStorageLayout = true;
3182
+ process.stderr.write("warning: SUBSTRATE_STORAGE_LAYOUT is no longer read; every store uses per-type tables\n");
3183
+ }
3184
+ const knobs = createKnobRecorder();
3185
+ const storeSpec = env.SUBSTRATE_DATABASE_URL ?? "memory";
3186
+ knobs.record("storeSpec", "SUBSTRATE_DATABASE_URL", env.SUBSTRATE_DATABASE_URL, redactStoreSpec(storeSpec));
3187
+ const memoryByDefault = env.SUBSTRATE_DATABASE_URL === void 0;
3188
+ const bridges = parseBridges(env.SUBSTRATE_BRIDGES);
3189
+ const bridgeCreds = parseBridgeCreds(env.SUBSTRATE_BRIDGE_CREDENTIALS);
3190
+ for (const spec of bridges) {
3191
+ const cred = bridgeCreds.get(spec.name);
3192
+ if (cred === void 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' has no entry in SUBSTRATE_BRIDGE_CREDENTIALS — every configured bridge must carry a credential`);
3193
+ let specOrigin;
3194
+ try {
3195
+ specOrigin = new URL(spec.url).origin;
3196
+ } catch {
3197
+ throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' has a malformed url '${spec.url}'`);
3198
+ }
3199
+ if (specOrigin !== cred.origin) throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' url origin '${specOrigin}' does not match its SUBSTRATE_BRIDGE_CREDENTIALS origin '${cred.origin}'`);
3200
+ }
3201
+ const auth = parseAuthConfig(env);
3202
+ const tls = parseTlsConfig(env);
3203
+ knobs.record("authMode", "SUBSTRATE_AUTH_MODE", env.SUBSTRATE_AUTH_MODE, auth?.mode ?? "off");
3204
+ const publicOrigins = parsePublicOrigins(env.SUBSTRATE_PUBLIC_ORIGIN);
3205
+ const sweepIntervalMs = parseSweepIntervalMs(env, knobs);
3206
+ const inviteSweepIntervalMs = parseInviteSweepIntervalMs(env, knobs);
3207
+ const tombstoneRetentionDays = parseTombstoneRetentionDays(env, knobs);
3208
+ const shutdownGraceMs = parseShutdownGraceMs(env, knobs);
3209
+ const oldBudget = nonEmpty(env.SUBSTRATE_PARTITION_BUDGET) !== void 0;
3210
+ if (oldBudget && !warnedPartitionBudget) {
3211
+ warnedPartitionBudget = true;
3212
+ process.stderr.write("warning: SUBSTRATE_PARTITION_BUDGET is deprecated; set SUBSTRATE_TYPE_TABLE_BUDGET instead (the old name is read only while the new one is unset)\n");
3213
+ }
3214
+ const typeTableBudget = parsePositiveIntEnv(env, knobs, "typeTableBudget", oldBudget && nonEmpty(env.SUBSTRATE_TYPE_TABLE_BUDGET) === void 0 ? "SUBSTRATE_PARTITION_BUDGET" : "SUBSTRATE_TYPE_TABLE_BUDGET", DEFAULT_TYPE_TABLE_BUDGET, "type tables");
3215
+ const statementTimeoutMs = parsePositiveIntEnv(env, knobs, "statementTimeoutMs", "SUBSTRATE_STATEMENT_TIMEOUT_MS", DEFAULT_STATEMENT_TIMEOUT_MS, "milliseconds");
3216
+ if (statementTimeoutMs > 2147483647) throw new EnvConfigError(`SUBSTRATE_STATEMENT_TIMEOUT_MS must be at most 2147483647 (got '${statementTimeoutMs}')`);
3217
+ const indexDiskPath = knobs.record("indexDiskPath", "SUBSTRATE_INDEX_DISK_PATH", env.SUBSTRATE_INDEX_DISK_PATH, diskPathOf(nonEmpty(env.SUBSTRATE_INDEX_DISK_PATH?.trim())));
3218
+ const indexDiskMarginMb = parseNonNegativeIntEnv(env, knobs, "indexDiskMarginMb", "SUBSTRATE_INDEX_DISK_MARGIN_MB", DEFAULT_INDEX_DISK_MARGIN_MB, "megabytes");
3219
+ const indexRetryIntervalMs = parseNonNegativeIntEnv(env, knobs, "indexRetryIntervalMs", "SUBSTRATE_INDEX_RETRY_INTERVAL_MS", DEFAULT_INDEX_RETRY_INTERVAL_MS, "milliseconds, 0 to disable");
3220
+ const advisorIntervalMs = parseNonNegativeIntEnv(env, knobs, "advisorIntervalMs", "SUBSTRATE_ADVISOR_INTERVAL_MS", DEFAULT_ADVISOR_INTERVAL_MS, "milliseconds, 0 to disable");
3221
+ const promoteIntervalMs = parseNonNegativeIntEnv(env, knobs, "promoteIntervalMs", "SUBSTRATE_PROMOTE_INTERVAL_MS", DEFAULT_PROMOTE_INTERVAL_MS, "milliseconds, 0 to disable");
3222
+ const profileRaw = nonEmpty(env.SUBSTRATE_STORE_PROFILE?.trim());
3223
+ if (profileRaw !== void 0 && !isStoreProfileName(profileRaw)) throw new EnvConfigError(`SUBSTRATE_STORE_PROFILE must be personal, growth or scale, got '${profileRaw}'`);
3224
+ const storeProfile = knobs.record("storeProfile", "SUBSTRATE_STORE_PROFILE", env.SUBSTRATE_STORE_PROFILE, profileRaw ?? null);
3225
+ const writeHeavyRaw = env.SUBSTRATE_STORE_WRITE_HEAVY;
3226
+ const writeHeavyWord = (writeHeavyRaw ?? "").trim().toLowerCase();
3227
+ if (![
3228
+ "",
3229
+ "0",
3230
+ "false",
3231
+ "1",
3232
+ "true"
3233
+ ].includes(writeHeavyWord)) throw new EnvConfigError(`SUBSTRATE_STORE_WRITE_HEAVY must be 1, true, 0 or false, got '${writeHeavyRaw}'`);
3234
+ const storeWriteHeavy = knobs.record("storeWriteHeavy", "SUBSTRATE_STORE_WRITE_HEAVY", writeHeavyRaw, writeHeavyWord === "1" || writeHeavyWord === "true");
3235
+ const idempotency = parseIdempotencyConfig(env, knobs);
3236
+ const trustedProxies = parseTrustedProxies(env, knobs);
3237
+ const port = parsePort(env, knobs);
3238
+ const host = knobs.record("host", "HOST", env.HOST, env.HOST ?? (auth === null ? "127.0.0.1" : "0.0.0.0"));
3239
+ const openRaw = env.SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST;
3240
+ const allowOpenHost = knobs.record("allowUnauthenticatedHost", "SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST", openRaw, openRaw !== void 0 && (openRaw === "1" || openRaw.toLowerCase() === "true"));
3241
+ if (auth === null && !isLoopbackHost(host) && !allowOpenHost) throw new EnvConfigError(`HOST '${host}' is not loopback and auth is off, so every caller would act as the system actor (admin routes included). Enable auth, bind to loopback, or set SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST=1. Inside a container, a port published only on the host's 127.0.0.1 still needs the opt-in: the server binds a non-loopback interface there.`);
3242
+ if (auth !== null && publicOrigins === null && !isLoopbackHost(host)) throw new EnvConfigError(`SUBSTRATE_PUBLIC_ORIGIN is required when auth is on and HOST '${host}' is not loopback: set it to the origins callers reach this server by (e.g. https://host:3100), so a token minted for another origin is refused.`);
3243
+ let audiences = publicOrigins;
3244
+ if (auth !== null && audiences === null) {
3245
+ const bound = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
3246
+ const scheme = tls !== null ? "https" : "http";
3247
+ audiences = [...new Set([
3248
+ "127.0.0.1",
3249
+ "localhost",
3250
+ "[::1]",
3251
+ bound
3252
+ ].map((h) => new URL(`${scheme}://${h}:${port}`).origin))];
3253
+ }
3254
+ if (auth !== null && audiences !== null) auth.audiences = audiences;
3255
+ knobs.record("publicOrigin", "SUBSTRATE_PUBLIC_ORIGIN", env.SUBSTRATE_PUBLIC_ORIGIN, audiences?.join(",") ?? null);
3256
+ const cors = parseCorsConfig(env, knobs);
3257
+ const bodyLimit = parseBodyLimit(env, knobs);
3258
+ const pageLimits = parsePageLimits(env, knobs);
3259
+ const snapshotLimit = parseSnapshotLimit(env, knobs, pageLimits.maxLimit);
3260
+ const filterWriteLimits = parseFilterWriteLimits(env, knobs);
3261
+ const keyReprimeIntervalMs = parseKeyReprimeIntervalMs(env, knobs);
3262
+ const cursorEnv = nonEmpty(env.SUBSTRATE_CURSOR_SECRET?.trim()) === void 0 && nonEmpty(env.SUBSTRATE_STREAM_TICKET_SECRET?.trim()) !== void 0 ? "SUBSTRATE_STREAM_TICKET_SECRET" : "SUBSTRATE_CURSOR_SECRET";
3263
+ knobs.recordSecret("cursorSealSecret", cursorEnv, env[cursorEnv]);
3264
+ knobs.record("systemActor", "SUBSTRATE_SYSTEM_ACTOR", env.SUBSTRATE_SYSTEM_ACTOR, nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null);
3265
+ const cursorSealSecret = nonEmpty(env[cursorEnv]?.trim()) ?? null;
3266
+ return {
3267
+ storeSpec,
3268
+ memoryByDefault,
3269
+ bridges,
3270
+ bridgeCreds,
3271
+ auth,
3272
+ tls,
3273
+ sweepIntervalMs,
3274
+ inviteSweepIntervalMs,
3275
+ tombstoneRetentionDays,
3276
+ shutdownGraceMs,
3277
+ typeTableBudget,
3278
+ statementTimeoutMs,
3279
+ indexDiskPath,
3280
+ indexDiskMarginMb,
3281
+ indexRetryIntervalMs,
3282
+ advisorIntervalMs,
3283
+ promoteIntervalMs,
3284
+ storeProfile,
3285
+ storeWriteHeavy,
3286
+ idempotency,
3287
+ trustedProxies,
3288
+ port,
3289
+ host,
3290
+ cors,
3291
+ bodyLimit,
3292
+ pageLimits,
3293
+ snapshotLimit,
3294
+ filterWriteLimits,
3295
+ keyReprimeIntervalMs,
3296
+ knobs: knobs.report(),
3297
+ cursorSealSecret,
3298
+ systemActor: nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null
3299
+ };
3300
+ }
3301
+ /**
3302
+ * Parse `SUBSTRATE_KEY_REFRESH_INTERVAL_MS` — periodic public-key-cache re-prime
3303
+ * interval in ms. Unset or empty → {@link DEFAULT_KEY_REPRIME_INTERVAL_MS}.
3304
+ * The literal `off` disables it. A set value must otherwise be a positive
3305
+ * integer; anything else is a config bug and throws rather than silently
3306
+ * disabling the safety net.
3307
+ *
3308
+ * On by default: single-instance deployments are exactly where nothing else
3309
+ * repairs a stale cache entry.
3310
+ */
3311
+ const DEFAULT_KEY_REPRIME_INTERVAL_MS = 3e4;
3312
+ function parseKeyReprimeIntervalMs(env, knobs) {
3313
+ const note = (v) => knobs.record("keyReprimeIntervalMs", "SUBSTRATE_KEY_REFRESH_INTERVAL_MS", env.SUBSTRATE_KEY_REFRESH_INTERVAL_MS, v);
3314
+ const raw = nonEmpty(env.SUBSTRATE_KEY_REFRESH_INTERVAL_MS);
3315
+ if (raw === void 0) return note(DEFAULT_KEY_REPRIME_INTERVAL_MS);
3316
+ if (raw.trim().toLowerCase() === "off") return note(null);
3317
+ try {
3318
+ return note(parsePositiveInt(raw, "SUBSTRATE_KEY_REFRESH_INTERVAL_MS", 0));
3319
+ } catch (err) {
3320
+ throw new EnvConfigError(`${err instanceof Error ? err.message : String(err)} — expected a positive integer (milliseconds)`);
3321
+ }
3322
+ }
3323
+ /**
3324
+ * Parse `SUBSTRATE_BODY_LIMIT_BYTES` — max Fastify request body size in bytes. Unset or
3325
+ * empty (docker `${VAR:-}` substitution) → `null`, leaving Fastify's 1 MiB
3326
+ * default in place. A set value must be a positive integer; anything else is a
3327
+ * config bug and throws rather than silently falling back.
3328
+ */
3329
+ function parseBodyLimit(env, knobs) {
3330
+ const note = (v) => knobs.record("bodyLimit", "SUBSTRATE_BODY_LIMIT_BYTES", env.SUBSTRATE_BODY_LIMIT_BYTES, v);
3331
+ const raw = nonEmpty(env.SUBSTRATE_BODY_LIMIT_BYTES);
3332
+ if (raw === void 0) return note(null);
3333
+ try {
3334
+ return note(parsePositiveInt(raw, "SUBSTRATE_BODY_LIMIT_BYTES", 0));
3335
+ } catch (err) {
3336
+ throw new EnvConfigError(`${err instanceof Error ? err.message : String(err)} — expected a positive integer (bytes)`);
3337
+ }
3338
+ }
3339
+ /** Parse `SUBSTRATE_PAGE_LIMIT_DEFAULT` (100) and `SUBSTRATE_PAGE_LIMIT_MAX` (1000). */
3340
+ function parsePageLimits(env, knobs) {
3341
+ const read = (name, fallback) => {
3342
+ const raw = nonEmpty(env[name]);
3343
+ const v = raw === void 0 ? fallback : Number(raw);
3344
+ if (!Number.isInteger(v) || v <= 0) throw new EnvConfigError(`${name}: invalid value '${raw}' — expected a positive integer`);
3345
+ return knobs.record(name === "SUBSTRATE_PAGE_LIMIT_MAX" ? "pageLimitMax" : "pageLimitDefault", name, env[name], v);
3346
+ };
3347
+ const defaultLimit = read("SUBSTRATE_PAGE_LIMIT_DEFAULT", 100);
3348
+ const maxLimit = read("SUBSTRATE_PAGE_LIMIT_MAX", 1e3);
3349
+ if (defaultLimit > maxLimit) throw new EnvConfigError(`SUBSTRATE_PAGE_LIMIT_DEFAULT (${defaultLimit}) exceeds SUBSTRATE_PAGE_LIMIT_MAX (${maxLimit})`);
3350
+ return {
3351
+ defaultLimit,
3352
+ maxLimit
3353
+ };
3354
+ }
3355
+ /** Parse `SUBSTRATE_SNAPSHOT_LIMIT`, defaulting to the max page size. */
3356
+ function parseSnapshotLimit(env, knobs, fallback) {
3357
+ const raw = nonEmpty(env.SUBSTRATE_SNAPSHOT_LIMIT);
3358
+ const v = raw === void 0 ? fallback : Number(raw);
3359
+ if (!Number.isInteger(v) || v <= 0) throw new EnvConfigError(`SUBSTRATE_SNAPSHOT_LIMIT: invalid value '${raw}' — expected a positive integer`);
3360
+ return knobs.record("snapshotLimit", "SUBSTRATE_SNAPSHOT_LIMIT", env.SUBSTRATE_SNAPSHOT_LIMIT, v);
3361
+ }
3362
+ /** Parse `SUBSTRATE_FILTER_WRITE_MAX_MATCH` (10000) and `SUBSTRATE_FILTER_WRITE_IDS_CAP` (1000). */
3363
+ function parseFilterWriteLimits(env, knobs) {
3364
+ const read = (key, name, fallback) => {
3365
+ const raw = nonEmpty(env[name]);
3366
+ const v = raw === void 0 ? fallback : Number(raw);
3367
+ if (!Number.isSafeInteger(v) || v <= 0) throw new EnvConfigError(`${name}: invalid value '${raw}' — expected a positive integer`);
3368
+ return knobs.record(key, name, env[name], v);
3369
+ };
3370
+ return {
3371
+ maxMatch: read("filterWriteMaxMatch", "SUBSTRATE_FILTER_WRITE_MAX_MATCH", DEFAULT_FILTER_WRITE_LIMITS.maxMatch),
3372
+ idsCap: read("filterWriteIdsCap", "SUBSTRATE_FILTER_WRITE_IDS_CAP", DEFAULT_FILTER_WRITE_LIMITS.idsCap)
3373
+ };
3374
+ }
3375
+ /**
3376
+ * Parse `SUBSTRATE_TRUSTED_PROXIES` — CSV of exact peer-IP strings. Entries are
3377
+ * trimmed; empty entries are dropped. A non-empty value that devolves to an
3378
+ * empty set after trimming (e.g. `",,,"`) is a config bug and throws —
3379
+ * silently treating it as "no trust" would mask a deployment typo.
3380
+ */
3381
+ function parseTrustedProxies(env, knobs) {
3382
+ const raw = env.SUBSTRATE_TRUSTED_PROXIES;
3383
+ const note = (ips) => {
3384
+ knobs.record("trustedProxies", "SUBSTRATE_TRUSTED_PROXIES", raw, [...ips].join(",") || null);
3385
+ return ips;
3386
+ };
3387
+ if (raw === void 0 || raw.trim() === "") return note(/* @__PURE__ */ new Set());
3388
+ const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
3389
+ if (parts.length === 0) throw new EnvConfigError(`SUBSTRATE_TRUSTED_PROXIES: value '${raw}' contains no usable IP entries — supply a CSV of exact peer-IP strings or unset the var`);
3390
+ return note(new Set(parts));
3391
+ }
3392
+ /**
3393
+ * Parse `SUBSTRATE_CORS_ORIGINS` — optional CORS origin allowlist for browser clients.
3394
+ *
3395
+ * Returns `null` when the env var is unset or empty — the CORS plugin is not
3396
+ * registered and the server behaves as it does today (agent-only deployments).
3397
+ *
3398
+ * `'*'` allows any origin. Credentials are automatically disabled for wildcard
3399
+ * origins because browsers reject `Access-Control-Allow-Credentials: true` when
3400
+ * the origin is `*`. An explicit comma-separated list enables credentialed
3401
+ * cross-origin requests (Authorization header) from those origins.
3402
+ */
3403
+ function parseCorsConfig(env, knobs) {
3404
+ const raw = env.SUBSTRATE_CORS_ORIGINS;
3405
+ const note = (c) => {
3406
+ const value = c === null ? null : c.origins === "*" ? "*" : c.origins.join(",");
3407
+ knobs.record("cors", "SUBSTRATE_CORS_ORIGINS", raw, value);
3408
+ return c;
3409
+ };
3410
+ if (raw === void 0 || raw.trim() === "") return note(null);
3411
+ const trimmed = raw.trim();
3412
+ if (trimmed === "*") return note({
3413
+ origins: "*",
3414
+ credentials: false
3415
+ });
3416
+ const origins = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
3417
+ if (origins.length === 0) throw new EnvConfigError(`SUBSTRATE_CORS_ORIGINS: value '${raw}' contains no usable origin entries — supply a CSV of origins, '*', or unset the var`);
3418
+ return note({
3419
+ origins,
3420
+ credentials: true
3421
+ });
3422
+ }
3423
+ const diskPathOf = (raw) => raw === void 0 ? null : raw.toLowerCase() === "off" ? "off" : raw;
3424
+ /** As {@link parsePositiveIntEnv}, but 0 is allowed. */
3425
+ function parseNonNegativeIntEnv(env, knobs, key, varName, defaultValue, units) {
3426
+ const raw = nonEmpty(env[varName]);
3427
+ const n = raw === void 0 ? defaultValue : Number(raw);
3428
+ if (!Number.isInteger(n) || n < 0) throw new EnvConfigError(`${varName}: got '${raw}' — expected a non-negative integer (${units})`);
3429
+ return knobs.record(key, varName, env[varName], n);
3430
+ }
3431
+ /**
3432
+ * Parses positive-integer env var `varName`, falling back to `defaultValue`
3433
+ * when unset or empty, and records it under `key`. Throws `EnvConfigError`
3434
+ * naming the var and `units` on a malformed value.
3435
+ *
3436
+ * Empty must mean unset: docker-compose `${VAR:-}` passes `""`, and NaN
3437
+ * flowing into `setInterval` fires the callback every 1 ms.
3438
+ */
3439
+ function parsePositiveIntEnv(env, knobs, key, varName, defaultValue, units) {
3440
+ const raw = env[varName];
3441
+ try {
3442
+ return knobs.record(key, varName, raw, parsePositiveInt(nonEmpty(raw), varName, defaultValue));
3443
+ } catch (err) {
3444
+ throw new EnvConfigError(`${varName}: ${err instanceof Error ? err.message : String(err)} — expected a positive integer (${units})`);
3445
+ }
3446
+ }
3447
+ /** Parse `SUBSTRATE_SWEEP_INTERVAL_MS` — main edge-sweep cadence (§6.4 reaper). Default 5min. */
3448
+ function parseSweepIntervalMs(env, knobs) {
3449
+ return parsePositiveIntEnv(env, knobs, "sweepIntervalMs", "SUBSTRATE_SWEEP_INTERVAL_MS", DEFAULT_SWEEP_INTERVAL_MS, "milliseconds");
3450
+ }
3451
+ /** Parse `SUBSTRATE_INVITE_SWEEP_INTERVAL_MS` — reaper cadence for expired `Invite` rows. Default 1h. */
3452
+ function parseInviteSweepIntervalMs(env, knobs) {
3453
+ return parsePositiveIntEnv(env, knobs, "inviteSweepIntervalMs", "SUBSTRATE_INVITE_SWEEP_INTERVAL_MS", DEFAULT_INVITE_SWEEP_INTERVAL_MS, "milliseconds");
3454
+ }
3455
+ /**
3456
+ * Parse `SUBSTRATE_TOMBSTONE_RETENTION_DAYS` — retention window before tombstoned
3457
+ * type-table rows / `edges` are hard-deleted by the sweep loop. Default 30.
3458
+ */
3459
+ function parseTombstoneRetentionDays(env, knobs) {
3460
+ return parsePositiveIntEnv(env, knobs, "tombstoneRetentionDays", "SUBSTRATE_TOMBSTONE_RETENTION_DAYS", DEFAULT_TOMBSTONE_RETENTION_DAYS, "days");
3461
+ }
3462
+ /** Parse `SUBSTRATE_SHUTDOWN_GRACE_MS` — graceful drain deadline. Default 5s. */
3463
+ function parseShutdownGraceMs(env, knobs) {
3464
+ return parsePositiveIntEnv(env, knobs, "shutdownGraceMs", "SUBSTRATE_SHUTDOWN_GRACE_MS", DEFAULT_SHUTDOWN_GRACE_MS, "milliseconds");
3465
+ }
3466
+ /**
3467
+ * Parse `PORT` — Fastify HTTP listen port. Defaults to 3100. Empty string
3468
+ * and unset both fall back to the default; malformed values throw at boot.
3469
+ */
3470
+ function parsePort(env, knobs) {
3471
+ const raw = env.PORT;
3472
+ const note = (v) => knobs.record("port", "PORT", raw, v);
3473
+ if (raw === void 0 || raw === "") return note(DEFAULT_PORT);
3474
+ const parsed = Number(raw);
3475
+ if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) throw new EnvConfigError(`PORT: invalid value '${raw}' — expected an integer in 1..65535`);
3476
+ return note(parsed);
3477
+ }
3478
+ /**
3479
+ * `SUBSTRATE_PUBLIC_ORIGIN`: comma-separated origins (`https://a:3100,https://b`)
3480
+ * a token's `aud` may name. Null when unset; anything not a bare http(s)
3481
+ * origin throws.
3482
+ */
3483
+ function parsePublicOrigins(raw) {
3484
+ if (raw === void 0 || raw.trim() === "") return null;
3485
+ return raw.split(",").map((part) => {
3486
+ const entry = part.trim();
3487
+ let origin;
3488
+ try {
3489
+ const url = new URL(entry);
3490
+ if (url.protocol === "https:" || url.protocol === "http:") origin = url.origin;
3491
+ } catch {}
3492
+ if (origin === void 0 || origin !== entry.replace(/\/$/, "")) throw new EnvConfigError(`SUBSTRATE_PUBLIC_ORIGIN: '${entry}' is not an origin like 'https://host:3100'`);
3493
+ return origin;
3494
+ });
3495
+ }
3496
+ const LOOPBACK = new BlockList();
3497
+ LOOPBACK.addSubnet("127.0.0.0", 8, "ipv4");
3498
+ LOOPBACK.addAddress("::1", "ipv6");
3499
+ function isLoopbackHost(host) {
3500
+ const h = host.replace(/^\[(.*)\]$/, "$1");
3501
+ if (h.toLowerCase() === "localhost") return true;
3502
+ const family = isIP(h);
3503
+ return family !== 0 && LOOPBACK.check(h, family === 4 ? "ipv4" : "ipv6");
3504
+ }
3505
+ /**
3506
+ * Parses the §5.13 idempotency knobs. Dedup is on by default;
3507
+ * `SUBSTRATE_IDEMPOTENCY_DISABLED` honours `1` / `true` (case-insensitive). A
3508
+ * malformed TTL (non-integer, negative) throws `EnvConfigError`.
3509
+ */
3510
+ function parseIdempotencyConfig(env, knobs) {
3511
+ const disabledRaw = env.SUBSTRATE_IDEMPOTENCY_DISABLED;
3512
+ const disabled = disabledRaw !== void 0 && (disabledRaw === "1" || disabledRaw.toLowerCase() === "true");
3513
+ knobs.record("idempotencyDisabled", "SUBSTRATE_IDEMPOTENCY_DISABLED", disabledRaw, disabled);
3514
+ const ttlRaw = env.SUBSTRATE_IDEMPOTENCY_TTL_MS;
3515
+ const noteTtl = (v) => knobs.record("idempotencyTtlMs", "SUBSTRATE_IDEMPOTENCY_TTL_MS", ttlRaw, v);
3516
+ if (disabled) {
3517
+ noteTtl(null);
3518
+ return {
3519
+ defaultTtlMs: null,
3520
+ disabled: true
3521
+ };
3522
+ }
3523
+ if (ttlRaw === void 0 || ttlRaw === "") return {
3524
+ defaultTtlMs: noteTtl(null),
3525
+ disabled: false
3526
+ };
3527
+ const parsed = Number(ttlRaw);
3528
+ if (!Number.isInteger(parsed) || parsed < 0) throw new EnvConfigError(`SUBSTRATE_IDEMPOTENCY_TTL_MS: invalid value '${ttlRaw}' — expected a non-negative integer (milliseconds)`);
3529
+ return {
3530
+ defaultTtlMs: noteTtl(parsed),
3531
+ disabled: false
3532
+ };
3533
+ }
3534
+ /**
3535
+ * Read TLS material off disk at parse time. Partial key/cert pairs are a
3536
+ * config bug — silently downgrading to plaintext would mask a deployment
3537
+ * mistake, so we throw. CA is optional (many deployments use the server cert
3538
+ * alone or a `fullchain.pem` with the chain inlined).
3539
+ */
3540
+ function parseTlsConfig(env) {
3541
+ const keyPath = env.SUBSTRATE_TLS_KEY_PATH;
3542
+ const certPath = env.SUBSTRATE_TLS_CERT_PATH;
3543
+ const caPath = env.SUBSTRATE_TLS_CA_PATH;
3544
+ const hasKey = typeof keyPath === "string" && keyPath.length > 0;
3545
+ const hasCert = typeof certPath === "string" && certPath.length > 0;
3546
+ if (!hasKey && !hasCert) {
3547
+ if (typeof caPath === "string" && caPath.length > 0) throw new EnvConfigError("SUBSTRATE_TLS_CA_PATH set but SUBSTRATE_TLS_KEY_PATH and SUBSTRATE_TLS_CERT_PATH are not");
3548
+ return null;
3549
+ }
3550
+ if (!hasKey) throw new EnvConfigError("SUBSTRATE_TLS_CERT_PATH set but SUBSTRATE_TLS_KEY_PATH is not");
3551
+ if (!hasCert) throw new EnvConfigError("SUBSTRATE_TLS_KEY_PATH set but SUBSTRATE_TLS_CERT_PATH is not");
3552
+ const tls = {
3553
+ key: readTlsFile("SUBSTRATE_TLS_KEY_PATH", keyPath),
3554
+ cert: readTlsFile("SUBSTRATE_TLS_CERT_PATH", certPath)
3555
+ };
3556
+ if (typeof caPath === "string" && caPath.length > 0) tls.ca = readTlsFile("SUBSTRATE_TLS_CA_PATH", caPath);
3557
+ return tls;
3558
+ }
3559
+ function readTlsFile(envVar, path) {
3560
+ try {
3561
+ return readFileSync(path);
3562
+ } catch (err) {
3563
+ throw new EnvConfigError(`${envVar}: cannot read '${path}': ${err instanceof Error ? err.message : String(err)}`);
3564
+ }
3565
+ }
3566
+ function readPackageVersion() {
3567
+ if (typeof version === "string" && version.length > 0) return version;
3568
+ process.stderr.write("warning: apps/substrate package.json has no string 'version' field — onboard will report '0.0.0'\n");
3569
+ return "0.0.0";
3570
+ }
3571
+ /**
3572
+ * The binary's substrate-types contract version. Lifted from package.json at
3573
+ * build time; vite inlines the import so the bundled binary carries the
3574
+ * literal value. Plugin contractVersion ranges are checked against this.
3575
+ */
3576
+ const BINARY_CONTRACT_VERSION = readPackageVersion();
3577
+ /**
3578
+ * Throws `EnvConfigError` for a plugin whose `contractVersion` does not admit
3579
+ * this binary. Fatal by design: a plugin built against an unsatisfied
3580
+ * contract fails silently rather than loudly.
3581
+ */
3582
+ function refuseContractViolation(v) {
3583
+ const detail = v.reason === "invalid-range" ? `declares contractVersion '${v.declared}', which is not a valid semver range` : `declares contractVersion '${v.declared}', which does not admit this binary (${v.hostVersion})`;
3584
+ throw new EnvConfigError(`[${v.packageName}] ${v.tier} plugin ${detail}. Refusing to load it: a plugin built against a contract this binary does not satisfy fails silently rather than loudly, which is why this is fatal. Fix by widening that plugin's contractVersion to admit ${v.hostVersion} — a range's ceiling tracks actual compatibility, so it moves only when a major genuinely breaks the plugin interface, not at every major boundary.`);
3585
+ }
3586
+ function parseBridges(raw) {
3587
+ if (raw === void 0 || raw.trim() === "") return [];
3588
+ let parsed;
3589
+ try {
3590
+ parsed = JSON.parse(raw);
3591
+ } catch (err) {
3592
+ throw new EnvConfigError(`SUBSTRATE_BRIDGES: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
3593
+ }
3594
+ if (!Array.isArray(parsed)) throw new EnvConfigError("SUBSTRATE_BRIDGES: must be a JSON array of { ns, name, url } entries");
3595
+ const out = [];
3596
+ for (const [i, entry] of parsed.entries()) {
3597
+ if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} must be an object`);
3598
+ const e = entry;
3599
+ const ns = e.ns;
3600
+ const name = e.name;
3601
+ const url = e.url;
3602
+ if (typeof ns !== "string" || ns.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'ns'`);
3603
+ if (typeof name !== "string" || name.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'name'`);
3604
+ if (typeof url !== "string" || url.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'url'`);
3605
+ out.push({
3606
+ ns,
3607
+ name,
3608
+ url
3609
+ });
3610
+ }
3611
+ return out;
3612
+ }
3613
+ function parseBridgeCreds(raw) {
3614
+ const store = new MemoryBridgeCredentialStore();
3615
+ if (raw === void 0 || raw.trim() === "") return store;
3616
+ let parsed;
3617
+ try {
3618
+ parsed = JSON.parse(raw);
3619
+ } catch (err) {
3620
+ throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
3621
+ }
3622
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new EnvConfigError("SUBSTRATE_BRIDGE_CREDENTIALS: must be a JSON object mapping bridge name → { keyPath, kid }");
3623
+ for (const [name, entry] of Object.entries(parsed)) {
3624
+ if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' must be an object`);
3625
+ const e = entry;
3626
+ if (typeof e.keyPath !== "string" || e.keyPath.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'keyPath'`);
3627
+ if (typeof e.kid !== "string" || e.kid.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'kid'`);
3628
+ if (typeof e.origin !== "string" || e.origin.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'origin'`);
3629
+ let origin;
3630
+ try {
3631
+ const parsed = new URL(e.origin);
3632
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' has a non-http(s) 'origin' — expected http:// or https://, got '${e.origin}'`);
3633
+ origin = parsed.origin;
3634
+ } catch (err) {
3635
+ if (err instanceof EnvConfigError) throw err;
3636
+ throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' has a malformed 'origin' — expected scheme://host[:port], got '${e.origin}'`);
3637
+ }
3638
+ store.set(name, {
3639
+ keyPath: e.keyPath,
3640
+ kid: e.kid,
3641
+ origin
3642
+ });
3643
+ }
3644
+ return store;
3645
+ }
3646
+
3647
+ //#endregion
3648
+ //#region src/serve/compose-opts.ts
3649
+ /**
3650
+ * serve/compose-opts.ts — `compose()` options assembly.
3651
+ *
3652
+ * Pure assembly over already-built pieces: datasets, bridges, auth, the
3653
+ * cursor seal secret, idempotency. No I/O except the sentinel-client env read; the
3654
+ * substrate-migrations table ensure runs here too so it lands before any
3655
+ * substrate plugin migration.
3656
+ */
3657
+ /**
3658
+ * The free-disk check every pg dataset runs before a background index build,
3659
+ * or none when `SUBSTRATE_INDEX_DISK_PATH=off`. A configured path is statted
3660
+ * once here, so a typo fails the boot rather than every build.
3661
+ */
3662
+ async function indexDiskGuard(config, statfs$1 = (p) => statfs(p)) {
3663
+ const path = config.indexDiskPath;
3664
+ if (path === "off") return void 0;
3665
+ if (path !== null) try {
3666
+ await statfs$1(path);
3667
+ } catch (err) {
3668
+ throw new EnvConfigError(`SUBSTRATE_INDEX_DISK_PATH: ${path} is not readable: ${err instanceof Error ? err.message : String(err)}`);
3669
+ }
3670
+ return makeDiskGuard({
3671
+ ...path !== null ? { path } : {},
3672
+ marginBytes: config.indexDiskMarginMb * 1024 * 1024
3673
+ });
3674
+ }
3675
+ async function buildComposeOpts(args) {
3676
+ const { config, server, dataset, edges, coordinators, storeSql, substrateNamespaceDataset, fieldDefLookupFor, typeDefLookup, kernel, diskGuard } = args;
3677
+ const composeOpts = {
3678
+ server,
3679
+ dataset,
3680
+ edges,
3681
+ trustedProxies: config.trustedProxies,
3682
+ pageLimits: config.pageLimits,
3683
+ subscriptions: { snapshotLimit: config.snapshotLimit },
3684
+ filterWriteLimits: config.filterWriteLimits,
3685
+ configReport: config.knobs,
3686
+ advisor: {
3687
+ intervalMs: config.advisorIntervalMs,
3688
+ ...config.storeProfile !== null ? { storeProfile: config.storeProfile } : {},
3689
+ writeHeavy: config.storeWriteHeavy
3690
+ },
3691
+ promoteFields: { intervalMs: config.promoteIntervalMs }
3692
+ };
3693
+ if (dataset.storageReport !== void 0) {
3694
+ const report = dataset.storageReport.bind(dataset);
3695
+ composeOpts.storageReport = () => report({ partitionBudget: config.typeTableBudget });
3696
+ }
3697
+ if (coordinators.length > 0) {
3698
+ composeOpts.coordinators = coordinators;
3699
+ composeOpts.datasets = buildPluginDatasetMap(coordinators, dataset, storeSql, storeSql !== null ? edges : null, fieldDefLookupFor, typeDefLookup, diskGuard, config.statementTimeoutMs);
3700
+ }
3701
+ if (substrateNamespaceDataset !== null) {
3702
+ if (composeOpts.datasets === void 0) composeOpts.datasets = {};
3703
+ if (composeOpts.datasets["_system"] !== void 0) process.stdout.write(`warning: coordinator-contributed '${SYSTEM_NAMESPACE}' dataset overridden by main.ts pg wiring\n`);
3704
+ composeOpts.datasets[SYSTEM_NAMESPACE] = substrateNamespaceDataset;
3705
+ }
3706
+ const { registry: bridgeRegistry, dispose: disposeBridges } = buildBridgeRegistry(config.bridges, config.bridgeCreds);
3707
+ try {
3708
+ const sentinelClientConfig = loadConfig(process.env);
3709
+ if (config.bridges.length > 0 || sentinelClientConfig !== null) composeOpts.bridges = bridgeRegistry;
3710
+ if (config.auth !== null) composeOpts.auth = config.auth;
3711
+ if (config.keyReprimeIntervalMs !== null) composeOpts.keyReprimeIntervalMs = config.keyReprimeIntervalMs;
3712
+ if (config.systemActor !== null) composeOpts.systemActor = config.systemActor;
3713
+ if (config.cursorSealSecret !== null) composeOpts.cursorSealSecret = config.cursorSealSecret;
3714
+ let idempotencyStore = null;
3715
+ if (!config.idempotency.disabled) {
3716
+ idempotencyStore = storeSql !== null ? new PgIdempotencyStore({ sql: storeSql }) : new MemoryIdempotencyStore();
3717
+ const idempotencyOpt = { store: idempotencyStore };
3718
+ if (config.idempotency.defaultTtlMs !== null) idempotencyOpt.defaultTtlMs = config.idempotency.defaultTtlMs;
3719
+ composeOpts.idempotency = idempotencyOpt;
3720
+ }
3721
+ composeOpts.version = readPackageVersion();
3722
+ if (kernel.length > 0) composeOpts.kernelPlugins = kernel;
3723
+ await ensureMigrationsTable(storeSql);
3724
+ return {
3725
+ composeOpts,
3726
+ idempotencyStore,
3727
+ sentinelClientConfig,
3728
+ bridgeRegistry,
3729
+ disposeBridges
3730
+ };
3731
+ } catch (err) {
3732
+ disposeBridges();
3733
+ throw err;
3734
+ }
3735
+ }
3736
+
3737
+ //#endregion
3738
+ //#region src/serve/late-refs.ts
3739
+ function createLateRefs(auth) {
3740
+ const datasetRegistryRef = { current: null };
3741
+ const resolveDataset = (namespace) => datasetRegistryRef.current?.get(namespace) ?? null;
3742
+ const engineRef = { current: null };
3743
+ const checkReadPolicy = (ns, type, identity, probe) => engineRef.current?.evaluateReadPolicy(ns, type, identity, probe) ?? {
3744
+ allow: false,
3745
+ reason: "engine not ready"
3746
+ };
3747
+ const checkWritePolicy = (ns, type, identity, probe) => engineRef.current?.evaluateWritePolicy(ns, type, identity, probe) ?? {
3748
+ allow: false,
3749
+ reason: "engine not ready"
3750
+ };
3751
+ return {
3752
+ datasetRegistryRef,
3753
+ resolveDataset,
3754
+ engineRef,
3755
+ checkReadPolicy,
3756
+ checkWritePolicy,
3757
+ kernelAuth: auth === null ? null : { ...auth }
3758
+ };
3759
+ }
3760
+ /**
3761
+ * Populate the late-bound holders after `compose()`, including handing
3762
+ * kernel routes the key registry compose primed.
3763
+ *
3764
+ * Throws when auth is enabled and `keyRegistry` is absent: that is always a
3765
+ * mismatched install (`@mnmal-ai/substrate-compose` is an external runtime
3766
+ * dependency), and serving on would 401 every signed agent silently.
3767
+ */
3768
+ function populateLateRefs(refs, composedDatasets, engine, keyRegistry) {
3769
+ const kernelAuth = refs.kernelAuth;
3770
+ if (kernelAuth !== null) {
3771
+ if (keyRegistry === null || keyRegistry === void 0) throw new Error("substrate: auth is enabled but compose returned no keyRegistry. This is a MISMATCHED INSTALL, not a config problem — @mnmal-ai/substrate-compose is older than @mnmal-ai/substrate and predates ComposeResult.keyRegistry. Every signed agent request to a kernel route would 401 while unsigned ones succeed. Reinstall the substrate line together rather than swapping one dist.");
3772
+ kernelAuth.keyRegistry = keyRegistry;
3773
+ }
3774
+ refs.datasetRegistryRef.current = composedDatasets;
3775
+ refs.engineRef.current = engine;
3776
+ }
3777
+
3778
+ //#endregion
3779
+ //#region src/serve/nl-engine.ts
3780
+ /**
3781
+ * serve/nl-engine.ts — the engine access substrate-nl is handed.
3782
+ *
3783
+ * Fail-closed: the plugin only calls these from inside a request, after
3784
+ * compose() populated the ref, so a null engine means a fault. Queries run
3785
+ * under the caller's request context and the remote page bounds, since an NL
3786
+ * request is a remote read.
3787
+ */
3788
+ function nlEngineAccess(engineRef, trustedProxies, pageLimits) {
3789
+ const ready = () => {
3790
+ const engine = engineRef.current;
3791
+ if (engine === null) throw new Error("substrate-nl: engine not ready");
3792
+ return engine;
3793
+ };
3794
+ return {
3795
+ federatedSchema: () => ready().federatedSchema(),
3796
+ operators: (ns) => {
3797
+ const dataset = ready().datasetFor(ns);
3798
+ return dataset === void 0 ? void 0 : effectiveFilterOperators(dataset.capabilities);
3799
+ },
3800
+ query: async (frame, req) => ready().query({
3801
+ frame,
3802
+ ctx: buildContext(req, trustedProxies),
3803
+ pageLimits,
3804
+ ...req.signal !== void 0 ? { signal: req.signal } : {}
3805
+ })
3806
+ };
3807
+ }
3808
+
3809
+ //#endregion
3810
+ //#region src/serve/plugins.ts
3811
+ function resolvePluginDir(env = process.env) {
3812
+ const pluginDirRaw = env.SUBSTRATE_PLUGIN_DIR?.trim();
3813
+ return pluginDirRaw !== void 0 && pluginDirRaw.length > 0 ? pluginDirRaw : null;
3814
+ }
3815
+ async function loadServePlugins(opts) {
3816
+ let kernel = [];
3817
+ let coordinators = [];
3818
+ if (opts.pluginDir !== null) {
3819
+ const result = await loadPluginsFromDir({
3820
+ pluginDir: opts.pluginDir,
3821
+ kernelHostDeps: opts.kernelHostDeps,
3822
+ contractCheck: opts.contractCheck
3823
+ });
3824
+ kernel = result.kernel;
3825
+ coordinators = [...result.coordinators];
3826
+ }
3827
+ for (const plugin of coordinators) for (const nsDef of plugin.namespaces) if (!opts.nsDefs.has(nsDef.namespace)) opts.nsDefs.set(nsDef.namespace, nsDef);
3828
+ if (opts.storeSql !== null) {
3829
+ const indexedListFields = extractIndexedListFields(opts.nsDefs);
3830
+ if (indexedListFields.length > 0) await runDerivedMigrations(opts.storeSql, indexedListFields.map(deriveListIndexMigration));
3831
+ }
3832
+ return {
3833
+ kernel,
3834
+ coordinators
3835
+ };
3836
+ }
3837
+ /**
3838
+ * Compose substrate-tier plugins BEFORE coordinator compose, wiring each
3839
+ * KernelPlugin slot (filterOperators, kernelRoutes, mcpTools, migrations,
3840
+ * onKernelReady) into the host's registries. Declared storage is reconciled
3841
+ * first, so kernel migrations run against it.
3842
+ */
3843
+ async function composeKernelPhase(args) {
3844
+ const { kernel, server, storeSql, coordinators, kernelAuth, trustedProxies } = args;
3845
+ await reconcileDeclaredStorage(args.datasetFor, args.nsDefs);
3846
+ await composeKernelPlugins(kernel, {
3847
+ sql: storeSql,
3848
+ layout: storeSql === null ? null : "tables",
3849
+ background: args.background ?? true,
3850
+ coordinatorNamespaces: coordinators.flatMap((p) => p.namespaces.map((n) => n.namespace)),
3851
+ coordinatorNamespacesByPlugin: coordinators.flatMap((p) => p.namespaces.map((n) => ({
3852
+ plugin: p.name,
3853
+ namespace: n.namespace
3854
+ }))),
3855
+ metric: (name, payload) => {
3856
+ process.stdout.write(`[substrate/metric] ${name} ${payload === void 0 ? "" : JSON.stringify(payload)}\n`);
3857
+ },
3858
+ registerKernelRoute: (claim) => {
3859
+ mountKernelRoute(server, claim, kernelAuth, trustedProxies);
3860
+ },
3861
+ registerMcpTool: (tool) => {
3862
+ pendingMcpTools.push(tool);
3863
+ },
3864
+ registerFilterOperator: (name, op) => {
3865
+ filterRegistry.register(name, op);
3866
+ },
3867
+ getAppliedMigrationIds: (pluginName) => getAppliedMigrationIds(storeSql, pluginName),
3868
+ applyMigration: async (pluginName, migrationId) => {
3869
+ await recordMigrationApplied(storeSql, pluginName, migrationId);
3870
+ process.stdout.write(`[substrate] kernel migration applied: ${pluginName}:${migrationId}\n`);
3871
+ }
3872
+ });
3873
+ }
3874
+
3875
+ //#endregion
3876
+ //#region src/rows-missing-probe.ts
3877
+ /**
3878
+ * Host side of substrate-recall's membership decay sweep: "of these cluster
3879
+ * members, which source rows are gone?" Answered with one read per
3880
+ * (namespace, type) group, since only the binary holds the dataset registry.
3881
+ *
3882
+ * POLARITY IS THE SAFETY PROPERTY. This reports rows it can positively
3883
+ * establish are absent. A namespace that will not resolve, a group that never
3884
+ * gets asked, a dataset that answers nothing — all leave their refs OUT of
3885
+ * the result and therefore attached. The sweep's only action is
3886
+ * `markDeparted` and there is no un-depart, so under-reporting is corrected
3887
+ * by the next pass while over-reporting is corrected by nothing.
3888
+ */
3889
+ function createRowsMissingProbe(opts) {
3890
+ return async (refs) => {
3891
+ const groups = /* @__PURE__ */ new Map();
3892
+ for (const ref of refs) {
3893
+ const key = `${ref.namespace}/${ref.type}`;
3894
+ const group = groups.get(key);
3895
+ if (group === void 0) groups.set(key, {
3896
+ namespace: ref.namespace,
3897
+ type: ref.type,
3898
+ ids: /* @__PURE__ */ new Set([ref.id])
3899
+ });
3900
+ else group.ids.add(ref.id);
3901
+ }
3902
+ const missing = /* @__PURE__ */ new Set();
3903
+ for (const { namespace, type, ids } of groups.values()) {
3904
+ const dataset = opts.resolveDataset(namespace);
3905
+ if (dataset === null) continue;
3906
+ const asked = [...ids];
3907
+ const result = await dataset.read(type, {
3908
+ ids: asked,
3909
+ fields: {}
3910
+ });
3911
+ const found = new Set(result.rows.map((row) => String(row.id)));
3912
+ for (const id of asked) if (!found.has(id)) missing.add(memberKey({
3913
+ namespace,
3914
+ type,
3915
+ id
3916
+ }));
3917
+ }
3918
+ return missing;
3919
+ };
3920
+ }
3921
+
3922
+ //#endregion
3923
+ //#region src/serve/stores.ts
3924
+ /**
3925
+ * serve/stores.ts — recall/cluster store construction.
3926
+ *
3927
+ * The binary owns the pg pool and constructs the EmbeddingsStore, handing it
3928
+ * to recall via kernelHostDeps. Same pg-vs-memory split for all three
3929
+ * stores; memory variants close over the late-bound dataset registry so
3930
+ * content joins resolve after `compose()` populates it.
3931
+ */
3932
+ function buildRecallStores(storeSql, datasetRegistryRef, resolveDataset) {
3933
+ return {
3934
+ recallStore: storeSql !== null ? new PgEmbeddingsStore({ sql: storeSql }) : new InMemoryEmbeddingsStore({ datasetFor: (ns) => datasetRegistryRef.current?.get(ns) }),
3935
+ lexicalStore: storeSql !== null ? new PgLexicalStore(storeSql) : new InMemoryLexicalStore({ datasetFor: (ns) => datasetRegistryRef.current?.get(ns) }),
3936
+ clusterStore: storeSql !== null ? new PgClusterStore({ sql: storeSql }) : new InMemoryClusterStore(),
3937
+ rowsMissing: createRowsMissingProbe({ resolveDataset })
3938
+ };
3939
+ }
3940
+
3941
+ //#endregion
3942
+ //#region src/serve/boot-store.ts
3943
+ /**
3944
+ * serve/boot-store.ts — every step of `substrate serve`'s boot before the
3945
+ * server listens: open and migrate the store, load plugins, compose the kernel
3946
+ * and coordinators, and reconcile registered storage. `runServe` listens on
3947
+ * the result; `substrate-admin migrate-store` prepares a target with it.
3948
+ */
3949
+ async function bootStore(opts) {
3950
+ const { pluginDir } = opts;
3951
+ const background = opts.background ?? true;
3952
+ const config = background ? opts.config : {
3953
+ ...opts.config,
3954
+ advisorIntervalMs: 0,
3955
+ promoteIntervalMs: 0
3956
+ };
3957
+ const nsDefs = /* @__PURE__ */ new Map();
3958
+ const diskGuard = await indexDiskGuard(config);
3959
+ const refs = createLateRefs(config.auth);
3960
+ const fieldDefLookupFor = makeFieldDefLookupFactory(nsDefs, (ns) => refs.engineRef.current?.registryFor(ns));
3961
+ const typeDefLookupFor = makeTypeDefLookupFactory(nsDefs, (ns) => refs.engineRef.current?.registryFor(ns));
3962
+ const { dataset, edges, substrateNamespaceDataset, sql: storeSql, close: closeStore } = await wireStore(config.storeSpec, fieldDefLookupFor, typeDefLookupFor, diskGuard, config.statementTimeoutMs);
3963
+ const opened = [];
3964
+ if (closeStore !== null) opened.push(closeStore);
3965
+ try {
3966
+ if (storeSql !== null && opts.allowMigrating !== true) await assertNotMigrating(storeSql);
3967
+ const { datasetRegistryRef, resolveDataset, engineRef, checkReadPolicy, checkWritePolicy } = refs;
3968
+ const { recallStore, lexicalStore, clusterStore, rowsMissing } = buildRecallStores(storeSql, datasetRegistryRef, resolveDataset);
3969
+ const { kernel, coordinators } = await loadServePlugins({
3970
+ pluginDir,
3971
+ kernelHostDeps: {
3972
+ store: recallStore,
3973
+ lexicalStore,
3974
+ resolveDataset,
3975
+ edges,
3976
+ checkReadPolicy,
3977
+ checkWritePolicy,
3978
+ clusters: clusterStore,
3979
+ rowsMissing,
3980
+ nlEngine: nlEngineAccess(engineRef, config.trustedProxies, config.pageLimits)
3981
+ },
3982
+ contractCheck: {
3983
+ hostVersion: BINARY_CONTRACT_VERSION,
3984
+ onViolation: refuseContractViolation
3985
+ },
3986
+ nsDefs,
3987
+ storeSql
3988
+ });
3989
+ const stopKernel = async () => {
3990
+ for (const plugin of kernel) await plugin.onKernelStop?.();
3991
+ };
3992
+ opened.push(stopKernel);
3993
+ const server = new FastifySubstrateServer({
3994
+ logger: false,
3995
+ ...config.tls !== null ? { tls: config.tls } : {},
3996
+ ...config.cors !== null ? { cors: config.cors } : {},
3997
+ ...config.bodyLimit !== null ? { bodyLimit: config.bodyLimit } : {}
3998
+ });
3999
+ server.onError((err, req) => {
4000
+ if ((err.statusCode ?? 500) < 500) return;
4001
+ const where = req !== void 0 ? `${req.method} ${req.path}` : "background";
4002
+ process.stderr.write(`[substrate] internal error on ${where}: ${err.stack ?? err.message}\n`);
4003
+ });
4004
+ const { composeOpts, idempotencyStore, sentinelClientConfig, bridgeRegistry, disposeBridges } = await buildComposeOpts({
4005
+ config,
4006
+ server,
4007
+ dataset,
4008
+ edges,
4009
+ coordinators,
4010
+ storeSql,
4011
+ substrateNamespaceDataset,
4012
+ fieldDefLookupFor,
4013
+ typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE),
4014
+ kernel,
4015
+ diskGuard
4016
+ });
4017
+ opened.push(disposeBridges);
4018
+ const operatorsBefore = new Set(listExtensionOperators());
4019
+ opened.push(() => {
4020
+ for (const name of listExtensionOperators()) if (!operatorsBefore.has(name)) unregisterExtensionOperator(name);
4021
+ });
4022
+ await composeKernelPhase({
4023
+ kernel,
4024
+ server,
4025
+ storeSql,
4026
+ coordinators,
4027
+ kernelAuth: refs.kernelAuth,
4028
+ trustedProxies: config.trustedProxies,
4029
+ datasetFor: (ns) => composeOpts.datasets?.[ns],
4030
+ nsDefs,
4031
+ background
4032
+ });
4033
+ const { engine, keyRegistry, sweepDeps, scheduler, datasets: composedDatasets, runPromoteFieldsNow, stop } = await compose(composeOpts);
4034
+ opened.push(() => stop());
4035
+ populateLateRefs(refs, composedDatasets, engine, keyRegistry);
4036
+ await reconcileRegisteredStorage(engine, composedDatasets, nsDefs);
4037
+ if (background) runPromoteFieldsNow().catch((err) => {
4038
+ process.stderr.write(`[substrate] boot promotion sweep failed and will run again: ${err instanceof Error ? err.message : String(err)}\n`);
4039
+ });
4040
+ return {
4041
+ engine,
4042
+ datasets: composedDatasets,
4043
+ nsDefs,
4044
+ sql: storeSql,
4045
+ server,
4046
+ close: () => release(opened),
4047
+ dataset,
4048
+ edges,
4049
+ substrateNamespaceDataset,
4050
+ closeStore: closeStore === null ? null : async () => {
4051
+ try {
4052
+ await stopKernel();
4053
+ } finally {
4054
+ await closeStore();
4055
+ }
4056
+ },
4057
+ kernel,
4058
+ coordinators,
4059
+ recallStore,
4060
+ lexicalStore,
4061
+ idempotencyStore,
4062
+ sentinelClientConfig,
4063
+ bridgeRegistry,
4064
+ disposeBridges,
4065
+ sweepDeps,
4066
+ scheduler,
4067
+ stop
4068
+ };
4069
+ } catch (err) {
4070
+ await release(opened).catch(() => void 0);
4071
+ throw err;
4072
+ }
4073
+ }
4074
+ /** Runs each release step, last opened first, then throws the first failure. */
4075
+ async function release(opened) {
4076
+ let failure;
4077
+ for (const step of [...opened].reverse()) try {
4078
+ await step();
4079
+ } catch (err) {
4080
+ failure ??= err;
4081
+ }
4082
+ if (failure !== void 0) throw failure;
4083
+ }
4084
+
4085
+ //#endregion
4086
+ export { REVOKE_EXIT_CODES as A, listActiveAdminKeys as B, runRegisterViaRoute as C, formatBootstrapOutput as D, formatDoctorReport as E, BootstrapError as F, ARGV_SPEC as G, describeAdminTarget as H, CLI_ACTOR_KID as I, USAGE as J, validateArgv as K, base64Url as L, runKeyListViaRoute as M, runKeyPatchViaRoute as N, parseBootstrapArgs as O, ACTOR_HINT as P, forUpdate as R, runRegister as S, doctorCommand as T, resolveAdminAuth as U, readKeyById as V, resolveAdminTarget as W, AdminCliError as X, argvError as Y, pgNoticeOptions as Z, version as _, MS_PER_DAY as a, formatRegisterOutput as b, parseEnv as c, redactStoreSpec as d, registeredTypes as f, loadPluginsFromDir as g, startSentinelClient as h, EnvConfigError as i, UPDATE_EXIT_CODES as j, runBootstrap as k, refuseContractViolation as l, runDeferredIndexBuilds as m, resolvePluginDir as n, parseBridgeCreds as o, reportUnguardedIndexBuilds as p, RESTART_NOTE as q, BINARY_CONTRACT_VERSION as r, parseBridges as s, bootStore as t, buildDeferredIndexes as u, openPgDataset as v, grantLines as w, parseRegisterArgs as x, onboardCommand as y, generateAdminKeypair as z };