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

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