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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +51 -9
  2. package/dist/boot-store-BVqfFxh1.js +4060 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-Cp4PaIYO.d.ts} +2 -87
  4. package/dist/cli-hSCBywhE.js +3126 -0
  5. package/dist/client.d.ts +130 -8
  6. package/dist/client.js +6 -5
  7. package/dist/{plugin-t2g2wX0b.d.ts → dataset-CejF-Fr_.d.ts} +1640 -1320
  8. package/dist/{agent-token-BIboWOU0.js → env-utils-CGNazUNt.js} +31 -2
  9. package/dist/{errors-D4vKuwz8.d.ts → errors-7mycvNGq.d.ts} +1 -1
  10. package/dist/{index-D7mSOFlM.d.ts → index-DgSfwx7M.d.ts} +1 -1
  11. package/dist/node-version-C5FSmwJX.js +26 -0
  12. package/dist/pack.d.ts +2 -2
  13. package/dist/pack.js +1 -1
  14. package/dist/pg-edges-store-Lxsl5ZnK.js +381 -0
  15. package/dist/{plugin-j1jt1l3n.js → plugin-CtwOINCM.js} +171 -18
  16. package/dist/proposals-bootstrap.js +6 -4
  17. package/dist/proposals.config.schema.json +5 -0
  18. package/dist/proposals.d.ts +15 -4
  19. package/dist/proposals.default-config.json +2 -1
  20. package/dist/proposals.js +2 -2
  21. package/dist/recall-bootstrap.js +13 -4
  22. package/dist/recall.config.schema.json +12 -0
  23. package/dist/recall.d.ts +54 -9
  24. package/dist/recall.js +2 -2
  25. package/dist/{repl-C52wyfMs.js → repl-DqfHelK7.js} +62 -29
  26. package/dist/{row-ByLFE2Wx.d.ts → row-BKKCXIG6.d.ts} +5 -3
  27. package/dist/run-B5dTbZ3g.js +1997 -0
  28. package/dist/{schema-g4FQLr0V.d.ts → schema-DoSc-4ig.d.ts} +44 -7
  29. package/dist/script-C6DSa_Na.js +134 -0
  30. package/dist/sdk.d.ts +90 -12
  31. package/dist/sdk.js +5 -110
  32. package/dist/{src-D91yij6C.js → src-5SJ5GEIM.js} +1557 -327
  33. package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
  34. package/dist/{src-CrEgiMJQ.js → src-Bi849yhn.js} +39 -15
  35. package/dist/{src-D88LvCX8.js → src-CqT-QWZ_.js} +697 -57
  36. package/dist/src-CyvV7dCK.js +4333 -0
  37. package/dist/{row-DK7lPZVe.js → src-Da0t6si5.js} +11 -11
  38. package/dist/{src-C4DzaIQZ.js → src-hZb8wfvg.js} +12 -1
  39. package/dist/substrate-admin.js +17 -781
  40. package/dist/substrate.js +4 -5471
  41. package/dist/testing.d.ts +557 -8
  42. package/dist/testing.js +39 -3
  43. package/dist/{ws-C72iVS5T.d.ts → ws-ByZyHk7m.d.ts} +3 -3
  44. package/package.json +21 -20
  45. package/dist/dataset-BXkus75W.js +0 -1527
  46. package/dist/env-utils-B7SGmoeJ.js +0 -21
  47. package/dist/src-CzxvmhFn.js +0 -2327
@@ -0,0 +1,3126 @@
1
+ import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
+ import { It as validateHardDeleteEnv, X as runSweep, Y as loadSweepState, Z as saveSweepState, g as INVITE_TYPE, h as AUDIT_EVENT_TYPE, m as buildAuditRow, p as runInviteSweep, u as isStoreProfileName } from "./src-5SJ5GEIM.js";
3
+ import { n as trimTrailingSlashes, s as makeAuthorizationProvider } from "./env-utils-CGNazUNt.js";
4
+ import { L as encodeList, T as SYSTEM_NAMESPACE, f as coversNamespace, m as grantedIn, p as grantOf } from "./src-Da0t6si5.js";
5
+ import "./src-hZb8wfvg.js";
6
+ import { a as parseBridgeCreds, d as reportUnguardedIndexBuilds, f as runDeferredIndexBuilds, g as openPgDataset, h as version, i as MS_PER_DAY, n as resolvePluginDir, o as parseBridges, p as startSentinelClient, q as AdminCliError, s as parseEnv, t as bootStore, u as redactStoreSpec } from "./boot-store-BVqfFxh1.js";
7
+ import { a as SubstrateClient, d as NetworkError, i as tokenAudience, n as resolveAgentCapabilities, p as AdminBackfillError, r as noRedirectFetch, t as createClientFromEnv, u as AuthError } from "./src-7CUSMK66.js";
8
+ import { n as runScript, t as DEFAULT_MAX_WRITES } from "./script-C6DSa_Na.js";
9
+ import { _ as tryWithPgAdvisoryLock } from "./src-CyvV7dCK.js";
10
+ import { n as PgLexicalStore, r as PgEmbeddingsStore } from "./src-Bi849yhn.js";
11
+ import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
12
+ import { homedir, hostname } from "node:os";
13
+ import { basename, dirname, join, resolve } from "node:path";
14
+ import { createHash, generateKeyPairSync, randomBytes } from "node:crypto";
15
+ import { pathToFileURL } from "node:url";
16
+ import { z } from "zod";
17
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
18
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
19
+
20
+ //#region src/cli/ask/main.ts
21
+ const USAGE$1 = "usage: substrate ask [--ns <namespace>] [--project <name>] [--json] <question…>\n";
22
+ async function runAsk(argv, options = {}) {
23
+ const write = options.write ?? ((s) => process.stdout.write(s));
24
+ const env = options.env ?? process.env;
25
+ let ns = env.SUBSTRATE_NAMESPACE !== void 0 && env.SUBSTRATE_NAMESPACE !== "" ? env.SUBSTRATE_NAMESPACE : void 0;
26
+ let project = basename(options.cwd ?? process.cwd());
27
+ let json = false;
28
+ const words = [];
29
+ for (let i = 0; i < argv.length; i++) {
30
+ const a = argv[i];
31
+ if (a === "--") {
32
+ words.push(...argv.slice(i + 1));
33
+ break;
34
+ }
35
+ if (a === "--json") json = true;
36
+ else if (a === "--ns" || a === "--project") {
37
+ const v = argv[++i];
38
+ if (v === void 0 || v.startsWith("--")) {
39
+ write(USAGE$1);
40
+ return 2;
41
+ }
42
+ if (a === "--ns") ns = v;
43
+ else project = v;
44
+ } else words.push(a);
45
+ }
46
+ if ((env.SUBSTRATE_URL ?? "") === "") {
47
+ write("SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)\n");
48
+ return 2;
49
+ }
50
+ const question = words.join(" ").trim();
51
+ if (question === "") {
52
+ write(USAGE$1);
53
+ return 2;
54
+ }
55
+ if (ns === void 0) {
56
+ write("substrate ask: name the namespace with --ns or SUBSTRATE_NAMESPACE\n");
57
+ return 2;
58
+ }
59
+ let client;
60
+ try {
61
+ ({client} = createClientFromEnv({
62
+ env,
63
+ allowAnonymous: true,
64
+ ...options.fetchImpl !== void 0 ? { fetch: options.fetchImpl } : {}
65
+ }));
66
+ } catch (err) {
67
+ write(`substrate ask: agent identity: ${messageOf$1(err)}\n`);
68
+ return 2;
69
+ }
70
+ let result;
71
+ try {
72
+ result = await client.nl.askJson({
73
+ namespace: ns,
74
+ question,
75
+ project
76
+ });
77
+ } catch (err) {
78
+ if (err instanceof NetworkError && err.status === 404 && err.code !== "nl_unknown_namespace") write("substrate ask: the server has no NL route (is @mnmal-ai/substrate-nl installed?)\n");
79
+ else if (err instanceof NetworkError && err.serverMessage !== void 0) write(`substrate ask: ${err.serverMessage}\n`);
80
+ else write(`substrate ask: ${messageOf$1(err)}\n`);
81
+ return 1;
82
+ }
83
+ const outcome = result.outcome;
84
+ if (json) write(`${JSON.stringify(result, null, 2)}\n`);
85
+ else write(render(outcome));
86
+ if (outcome === null) return 0;
87
+ if (outcome.kind === "refuse") return 1;
88
+ if (outcome.kind === "rows" && Array.isArray(outcome.errors) && outcome.errors.length > 0) return 1;
89
+ return 0;
90
+ }
91
+ function messageOf$1(err) {
92
+ return err instanceof Error ? err.message : String(err);
93
+ }
94
+ function render(o) {
95
+ if (o === null) return "{}\n";
96
+ switch (o.kind) {
97
+ case "rows": {
98
+ const key = Object.keys(o.frame)[0] ?? "?";
99
+ const rows = Array.isArray(o.data) ? o.data : void 0;
100
+ const tail = rows === void 0 ? "rejected" : `${rows.length} rows`;
101
+ const head = `▸ ${key} · ${o.source}${o.handoff !== void 0 ? ` (${o.handoff})` : ""} · ${tail}\n`;
102
+ const errs = (o.errors ?? []).map((e) => ` ✗ ${JSON.stringify(e)}\n`).join("");
103
+ const body = (rows ?? []).map((r) => ` ${String(r.shortId ?? r.id ?? "")} ${String(r.title ?? r.synopsis ?? r.name ?? "")}\n`).join("");
104
+ return head + errs + body;
105
+ }
106
+ case "recall": {
107
+ const errs = (o.errors ?? []).map((e) => ` ✗ ${JSON.stringify(e)}\n`).join("");
108
+ if (!Array.isArray(o.hits)) return `▸ recall · rejected\n${errs}`;
109
+ const hits = o.hits;
110
+ return `▸ recall · ${hits.length} hits\n${errs}${hits.map((h) => ` ${String(h.type)} ${String(h.id)} ${Number(h.score).toFixed(2)}\n`).join("")}`;
111
+ }
112
+ case "clarify": {
113
+ const opts = Array.isArray(o.options) ? o.options : [];
114
+ return `? ${o.reason}\n${opts.map((x, i) => ` ${i + 1}. ${x.label}\n`).join("")}`;
115
+ }
116
+ case "refuse": return `✗ ${o.reason}\n`;
117
+ }
118
+ }
119
+
120
+ //#endregion
121
+ //#region src/cli/backfill-field/main.ts
122
+ /**
123
+ * `substrate backfill-field <namespace> <Type> <field> --values <file.json> [--apply] [--overwrite] [--json]`
124
+ *
125
+ * Writes per-row values of one field (`{ "<row id>": value, ... }` in the
126
+ * file) through the admin route `POST /substrate/v1/_system/backfill-field`, with
127
+ * row metadata preserved. Dry run unless `--apply`; fills only empty values
128
+ * unless `--overwrite`. Chunking lives in `client.admin.backfill`.
129
+ *
130
+ * Env: SUBSTRATE_URL, SUBSTRATE_ADMIN_TOKEN (admin Bearer token). Exit 0 on success,
131
+ * 1 when the server refuses the values, 2 on usage or transport errors.
132
+ */
133
+ async function runBackfillField(argv, options = {}) {
134
+ const write = options.write ?? ((text) => process.stdout.write(text));
135
+ const [namespace, type, field] = argv.filter((a, i) => !a.startsWith("--") && argv[i - 1] !== "--values");
136
+ const valuesAt = argv.indexOf("--values");
137
+ const file = valuesAt >= 0 ? argv[valuesAt + 1] : void 0;
138
+ if (namespace === void 0 || type === void 0 || field === void 0 || file === void 0) {
139
+ write("usage: substrate backfill-field <namespace> <Type> <field> --values <file.json> [--apply] [--overwrite] [--json]\n");
140
+ return 2;
141
+ }
142
+ const baseUrl = trimTrailingSlashes(options.baseUrl ?? process.env.SUBSTRATE_URL ?? "");
143
+ if (baseUrl === "") {
144
+ write("SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)\n");
145
+ return 2;
146
+ }
147
+ let values;
148
+ try {
149
+ values = JSON.parse((options.readFile ?? ((p) => readFileSync(p, "utf8")))(file));
150
+ } catch (err) {
151
+ write(`cannot read ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
152
+ return 2;
153
+ }
154
+ if (values === null || typeof values !== "object" || Array.isArray(values)) {
155
+ write(`${file} must hold an object of row id -> value\n`);
156
+ return 2;
157
+ }
158
+ const token = options.token ?? process.env.SUBSTRATE_ADMIN_TOKEN;
159
+ const apply = argv.includes("--apply");
160
+ const overwrite = argv.includes("--overwrite");
161
+ const entries = Object.entries(values);
162
+ const json = argv.includes("--json");
163
+ if (token !== void 0 && token.length > 0) try {
164
+ tokenAudience(baseUrl);
165
+ } catch (err) {
166
+ write(`${err instanceof Error ? err.message : String(err)}\n`);
167
+ return 2;
168
+ }
169
+ const client = new SubstrateClient({
170
+ endpoint: baseUrl,
171
+ ...token !== void 0 && token.length > 0 ? { token } : {},
172
+ fetch: noRedirectFetch(options.fetchImpl)
173
+ });
174
+ let total;
175
+ try {
176
+ total = await client.admin.backfill({
177
+ namespace,
178
+ type,
179
+ field,
180
+ values,
181
+ apply,
182
+ overwrite
183
+ }, { onChunk: (c) => {
184
+ if (json) write(`${JSON.stringify(c.body)}\n`);
185
+ } });
186
+ } catch (err) {
187
+ const cause = err instanceof AdminBackfillError ? err.cause : err;
188
+ const refusal = cause instanceof NetworkError || cause instanceof AuthError ? cause : void 0;
189
+ const body = refusal?.body ?? {};
190
+ const transport = refusal instanceof NetworkError && refusal.status === void 0 ? refusal.cause instanceof Error ? refusal.cause.message : refusal.message : void 0;
191
+ if (json) write(`${JSON.stringify(refusal?.body ?? { message: transport ?? String(cause) })}\n`);
192
+ else if (refusal !== void 0 && refusal.status !== void 0) {
193
+ write(`HTTP ${refusal.status}: ${refusal.code ?? ""} ${refusal.serverMessage ?? ""}\n`);
194
+ for (const v of body.invalid ?? []) write(` ${v.id}: ${String(v.value)} (${v.reason})\n`);
195
+ } else write(`request failed: ${transport ?? (cause instanceof Error ? cause.message : String(cause))}\n`);
196
+ if (!json && err instanceof AdminBackfillError && apply) {
197
+ if (err.chunksDone > 0) write(`${err.chunksDone} of ${err.chunks} chunk(s) were written before the refusal\n`);
198
+ const status = refusal?.status;
199
+ if (status === void 0 || status < 400 || status >= 500) write("the failing chunk's own state is unknown — re-running is safe (written rows come back unchanged)\n");
200
+ }
201
+ return refusal?.status === 400 ? 1 : 2;
202
+ }
203
+ if (json) return 0;
204
+ write(`${namespace}/${type}.${field}: ${entries.length} requested — ${apply ? "wrote" : "would write (dry run; pass --apply)"} ${total.write}\n`);
205
+ for (const [k, n] of Object.entries(total.counts).sort((a, b) => b[1] - a[1])) write(` ${k} ${n}\n`);
206
+ if (total.kept > 0) write(`kept ${total.kept} existing value(s)${overwrite ? "" : " (pass --overwrite to replace)"}\n`);
207
+ if (total.unchanged > 0) write(`unchanged ${total.unchanged}\n`);
208
+ if (total.missing.length > 0) write(`missing ${total.missing.length} id(s)\n`);
209
+ return 0;
210
+ }
211
+
212
+ //#endregion
213
+ //#region src/cli/check-enums/main.ts
214
+ /**
215
+ * `substrate check-enums` — report stored values that fall outside a field's
216
+ * declared `enum` vocabulary.
217
+ *
218
+ * Write-time validation does not cover rows that predate an enum declaration,
219
+ * nor fields absent from an update patch, so stored values can drift from
220
+ * the published vocabulary.
221
+ *
222
+ * Read-only by default and runs over HTTP, so it needs no database
223
+ * credential. `--record` writes `_system/EnumCheckVerdict` rows and needs a
224
+ * credential with `_system` mutate via SUBSTRATE_ENUM_CHECK_TOKEN.
225
+ */
226
+ /**
227
+ * Walk a federated schema and collect every scalar field declaring an `enum`.
228
+ * Exported so the scan and the reporting can be tested without a server.
229
+ */
230
+ function collectEnumFields(federated) {
231
+ const out = [];
232
+ for (const [namespace, schema] of Object.entries(federated)) for (const [type, entry] of Object.entries(schema.types ?? {})) for (const [field, def] of Object.entries(entry.fields ?? {})) if (def.kind === "scalar" && def.enum !== void 0 && def.enum.length > 0) out.push({
233
+ namespace,
234
+ type,
235
+ field,
236
+ vocabulary: def.enum,
237
+ ...def.aliases !== void 0 ? { aliases: def.aliases } : {},
238
+ ...def.strict === false ? { strict: false } : {}
239
+ });
240
+ return out;
241
+ }
242
+ /**
243
+ * Tally values outside the vocabulary. `null`/`undefined` are skipped rather
244
+ * than reported: a nullable enum legitimately holds null, and
245
+ * `assertEnumValues` skips them on write for the same reason — flagging them
246
+ * here would contradict the writer and bury the real offenders.
247
+ */
248
+ function tallyOffenders(values, vocabulary, opts = {}) {
249
+ const allowed = new Set(vocabulary);
250
+ const normalisable = /* @__PURE__ */ new Set([...vocabulary.map((v) => v.toLowerCase()), ...Object.keys(opts.aliases ?? {}).map((a) => a.toLowerCase())]);
251
+ const counts = /* @__PURE__ */ new Map();
252
+ for (const value of values) {
253
+ if (value === null || value === void 0) continue;
254
+ const asString = typeof value === "string" ? value : String(value);
255
+ if (allowed.has(asString)) continue;
256
+ if (opts.strict === false && !normalisable.has(asString.toLowerCase())) continue;
257
+ counts.set(asString, (counts.get(asString) ?? 0) + 1);
258
+ }
259
+ return [...counts.entries()].map(([value, count]) => ({
260
+ value,
261
+ count
262
+ })).sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
263
+ }
264
+ /**
265
+ * Project a single field across one type, following `_pagination.nextCursor`.
266
+ *
267
+ * Projecting ONE field keeps the response small, and it is also the only
268
+ * projection guaranteed safe: any other field name could itself be undeclared,
269
+ * which would land in `_diagnostics.unknownProjectionFields` and come back null
270
+ * on every row.
271
+ */
272
+ async function scanField(field, opts) {
273
+ const key = `${field.namespace}/${field.type}`;
274
+ const values = [];
275
+ let cursor;
276
+ let truncated = false;
277
+ for (;;) {
278
+ const params = { limit: opts.pageSize };
279
+ if (cursor !== void 0) params.cursor = cursor;
280
+ const res = await opts.fetchImpl(`${opts.baseUrl}/substrate/v1/query`, {
281
+ method: "POST",
282
+ headers: {
283
+ "content-type": "application/json",
284
+ ...opts.authorization !== void 0 ? { authorization: opts.authorization } : {}
285
+ },
286
+ body: JSON.stringify({ [key]: {
287
+ params,
288
+ fields: { [field.field]: true }
289
+ } })
290
+ });
291
+ if (!res.ok) throw new Error(`query ${key} failed: HTTP ${res.status}`);
292
+ const envelope = await res.json();
293
+ const failure = envelope.errors?.[0];
294
+ if (failure !== void 0) throw new Error(`query ${key} rejected: ${failure.code ?? "error"} ${failure.message ?? ""}`);
295
+ const rows = envelope.data?.[key];
296
+ if (Array.isArray(rows)) for (const row of rows) values.push(row?.[field.field]);
297
+ if (values.length >= opts.maxRows) {
298
+ truncated = true;
299
+ break;
300
+ }
301
+ const page = envelope._pagination?.[key];
302
+ if (page?.hasMore !== true || page.nextCursor === void 0) break;
303
+ cursor = page.nextCursor;
304
+ }
305
+ return {
306
+ ...field,
307
+ rowsScanned: values.length,
308
+ offenders: tallyOffenders(values, field.vocabulary, field),
309
+ truncated
310
+ };
311
+ }
312
+ /**
313
+ * Returns 0 when every enum-declared field agrees with its stored rows, 1 when
314
+ * any drift is found — usable as a CI or cron gate.
315
+ */
316
+ async function runCheckEnums(argv = [], options = {}) {
317
+ const write = options.write ?? ((text) => process.stdout.write(text));
318
+ const asJson = argv.includes("--json");
319
+ const baseUrl = trimTrailingSlashes(options.baseUrl ?? process.env.SUBSTRATE_URL ?? "");
320
+ if (baseUrl === "") {
321
+ write("SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)\n");
322
+ return 2;
323
+ }
324
+ const baseFetch = options.fetchImpl ?? fetch;
325
+ const fetchImpl = (url, init) => baseFetch(url, {
326
+ ...init,
327
+ redirect: "error"
328
+ });
329
+ const pageSize = options.pageSize ?? 500;
330
+ const maxRows = options.maxRows ?? 5e4;
331
+ const token = options.token ?? process.env.SUBSTRATE_ENUM_CHECK_TOKEN;
332
+ const authorization = token !== void 0 && token.length > 0 ? `Bearer ${token}` : void 0;
333
+ if (authorization !== void 0) try {
334
+ tokenAudience(baseUrl);
335
+ } catch (err) {
336
+ write(`${err instanceof Error ? err.message : String(err)}\n`);
337
+ return 2;
338
+ }
339
+ const schemaRes = await fetchImpl(`${baseUrl}/substrate/v1/federated-schema`, { headers: authorization !== void 0 ? { authorization } : {} });
340
+ if (!schemaRes.ok) {
341
+ const hint = schemaRes.status === 401 ? " — the server needs a key: set SUBSTRATE_ENUM_CHECK_TOKEN to a Bearer token with read" : "";
342
+ write(`federated-schema failed: HTTP ${schemaRes.status}${hint}\n`);
343
+ return 2;
344
+ }
345
+ const fields = collectEnumFields(await schemaRes.json());
346
+ const reports = [];
347
+ for (const field of fields) reports.push(await scanField(field, {
348
+ baseUrl,
349
+ fetchImpl,
350
+ pageSize,
351
+ maxRows,
352
+ authorization
353
+ }));
354
+ const drifted = reports.filter((r) => r.offenders.length > 0);
355
+ const result = {
356
+ fieldsChecked: fields.length,
357
+ reports,
358
+ drifted
359
+ };
360
+ if (argv.includes("--record")) {
361
+ const recordCode = await recordVerdicts(baseUrl, fetchImpl, reports);
362
+ if (recordCode !== 0) return recordCode;
363
+ }
364
+ if (asJson) {
365
+ write(`${JSON.stringify(result, null, 2)}\n`);
366
+ return drifted.length > 0 ? 1 : 0;
367
+ }
368
+ write(`Checked ${fields.length} enum-declared field(s).\n`);
369
+ for (const report of drifted) {
370
+ write(`\n DRIFT ${report.namespace}/${report.type}.${report.field}\n`);
371
+ write(` declared: ${report.vocabulary.join(", ")}\n`);
372
+ for (const { value, count } of report.offenders) write(` stored: '${value}' x${count} (not declared)\n`);
373
+ if (report.truncated) write(` NOTE: stopped at ${report.rowsScanned} rows — counts are a floor.\n`);
374
+ }
375
+ for (const report of reports) if (report.offenders.length === 0 && report.truncated) write(`\n PARTIAL ${report.namespace}/${report.type}.${report.field} — clean over the first ${report.rowsScanned} rows, table not exhausted.\n`);
376
+ if (drifted.length === 0) write("\nNo drift found.\n");
377
+ return drifted.length > 0 ? 1 : 0;
378
+ }
379
+ /**
380
+ * sha256 of the vocabulary JSON — a vocab edit invalidates the verdict
381
+ * structurally. Aliases and strictness change what counts as an offender, so
382
+ * they join the hash when declared; a plain enum hashes exactly as before.
383
+ */
384
+ function vocabHash(vocabulary, opts = {}) {
385
+ const subject = opts.aliases === void 0 && opts.strict !== false ? [...vocabulary] : {
386
+ vocabulary: [...vocabulary],
387
+ aliases: opts.aliases ?? {},
388
+ strict: opts.strict !== false
389
+ };
390
+ return createHash("sha256").update(JSON.stringify(subject)).digest("hex");
391
+ }
392
+ /** Deterministic verdict-row id: one live verdict per (namespace, type, field). */
393
+ function verdictId(report) {
394
+ return `${report.namespace}/${report.type}/${report.field}`;
395
+ }
396
+ /**
397
+ * Write one `_system/EnumCheckVerdict` row per scanned field.
398
+ *
399
+ * Upsert by deterministic id: `updateEnumCheckVerdict` when the row exists,
400
+ * `createEnumCheckVerdict` when it does not (distinguished by a get, not by
401
+ * catching — a failed create must stay a failure, not a silent update).
402
+ * A run that found drift still records: the verdict carries the outlier
403
+ * count, and "checked with drift" is a different fact from "unchecked".
404
+ *
405
+ * Returns a process exit code: 3 when the credential is absent or refused
406
+ * (recording needs `_system` mutate; the scan itself already succeeded, so
407
+ * this is neither a 1 (drift) nor a 2 (usage/transport)).
408
+ */
409
+ async function recordVerdicts(baseUrl, fetchImpl, reports, opts = {}) {
410
+ const token = opts.token ?? process.env.SUBSTRATE_ENUM_CHECK_TOKEN;
411
+ if (token === void 0 || token.length === 0) {
412
+ process.stderr.write("check-enums --record needs SUBSTRATE_ENUM_CHECK_TOKEN (Bearer token with _system mutate) — recording a verdict is a claim about the deployment, and anonymous callers must not mint one.\n");
413
+ return 3;
414
+ }
415
+ try {
416
+ tokenAudience(baseUrl);
417
+ } catch (err) {
418
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
419
+ return 2;
420
+ }
421
+ const headers = {
422
+ "content-type": "application/json",
423
+ authorization: `Bearer ${token}`
424
+ };
425
+ const checkedAt = (opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
426
+ for (const report of reports) {
427
+ const id = verdictId(report);
428
+ const params = {
429
+ id,
430
+ namespace: report.namespace,
431
+ type: report.type,
432
+ field: report.field,
433
+ vocabHash: vocabHash(report.vocabulary, report),
434
+ checkedAt,
435
+ rowsScanned: report.rowsScanned,
436
+ outlierCount: report.offenders.reduce((n, o) => n + o.count, 0),
437
+ truncated: report.truncated,
438
+ verdictKey: id
439
+ };
440
+ const getRes = await fetchImpl(`${baseUrl}/substrate/v1/query`, {
441
+ method: "POST",
442
+ headers,
443
+ body: JSON.stringify({ "_system/EnumCheckVerdict": {
444
+ params: { id },
445
+ fields: { id: true }
446
+ } })
447
+ });
448
+ if (!getRes.ok) {
449
+ process.stderr.write(`verdict lookup for ${id} failed: HTTP ${getRes.status}\n`);
450
+ return 3;
451
+ }
452
+ const envelope = await getRes.json();
453
+ if (envelope.errors?.[0] !== void 0) {
454
+ process.stderr.write(`verdict lookup for ${id} refused: ${envelope.errors[0].code ?? "error"} ${envelope.errors[0].message ?? ""}\n`);
455
+ return 3;
456
+ }
457
+ const existing = envelope.data?.["_system/EnumCheckVerdict"];
458
+ const mutation = Array.isArray(existing) && existing.length > 0 ? "update" : "create";
459
+ const mutRes = await fetchImpl(`${baseUrl}/substrate/v1/mutate`, {
460
+ method: "POST",
461
+ headers,
462
+ body: JSON.stringify({ [`_system/${mutation}EnumCheckVerdict`]: {
463
+ params,
464
+ fields: { id: true }
465
+ } })
466
+ });
467
+ if (!mutRes.ok) {
468
+ process.stderr.write(`verdict write for ${id} failed: HTTP ${mutRes.status}\n`);
469
+ return 3;
470
+ }
471
+ const mutFailure = (await mutRes.json()).errors?.[0];
472
+ if (mutFailure !== void 0) {
473
+ process.stderr.write(`verdict write for ${id} refused: ${mutFailure.code ?? "error"} ${mutFailure.message ?? ""}\n`);
474
+ return 3;
475
+ }
476
+ }
477
+ return 0;
478
+ }
479
+
480
+ //#endregion
481
+ //#region src/sweep-cycle.ts
482
+ var SweepStageError = class extends Error {
483
+ name = "SweepStageError";
484
+ stage;
485
+ constructor(stage, cause) {
486
+ super(cause instanceof Error ? cause.message : String(cause), { cause });
487
+ this.stage = stage;
488
+ }
489
+ };
490
+ async function runSweepCycle(sweepFn, reapFn, purgeFn = null, embeddingsGcFn = null) {
491
+ let nextState;
492
+ try {
493
+ nextState = await sweepFn();
494
+ } catch (err) {
495
+ throw new SweepStageError("edge-sweep", err);
496
+ }
497
+ let reap;
498
+ if (reapFn !== null) try {
499
+ reap = await reapFn();
500
+ } catch (err) {
501
+ throw new SweepStageError("idempotency-reap", err);
502
+ }
503
+ let tombstonePurge;
504
+ if (purgeFn !== null) try {
505
+ tombstonePurge = await purgeFn();
506
+ } catch (err) {
507
+ throw new SweepStageError("tombstone-purge", err);
508
+ }
509
+ let embeddingsGc;
510
+ if (embeddingsGcFn !== null) try {
511
+ embeddingsGc = await embeddingsGcFn();
512
+ } catch (err) {
513
+ throw new SweepStageError("embeddings-gc", err);
514
+ }
515
+ const result = { state: nextState };
516
+ if (reap !== void 0) result.reap = reap;
517
+ if (tombstonePurge !== void 0) result.tombstonePurge = tombstonePurge;
518
+ if (embeddingsGc !== void 0) result.embeddingsGc = embeddingsGc;
519
+ return result;
520
+ }
521
+
522
+ //#endregion
523
+ //#region src/serve/background.ts
524
+ /**
525
+ * serve/background.ts — background timers: sweep, invite reaper, sentinel
526
+ * watcher.
527
+ */
528
+ /** Wall-clock one sweep tick may spend walking edge batches before it yields. */
529
+ const SWEEP_TICK_BUDGET_MS = 3e4;
530
+ const SWEEP_LOCK_KEY = "substrate:sweep";
531
+ function startBackground(args) {
532
+ const { config, sweepDeps, idempotencyStore, dataset, edges, storeSql, stores, composedDatasets, sentinelClientConfig, bridgeRegistry, engine } = args;
533
+ const { recallStore, lexicalStore } = stores;
534
+ const tombstoneRetentionMs = config.tombstoneRetentionDays * MS_PER_DAY;
535
+ const pgDatasetForPurge = storeSql !== null ? dataset : null;
536
+ const pgEdgesForPurge = storeSql !== null ? edges : null;
537
+ const cursorDataset = composedDatasets.get(SYSTEM_NAMESPACE);
538
+ let sweepState = { lastSweptCursor: null };
539
+ const sweepFn = async () => {
540
+ const state = cursorDataset === void 0 ? sweepState : await loadSweepState(cursorDataset);
541
+ const next = await runSweep(sweepDeps, state, void 0, SWEEP_TICK_BUDGET_MS);
542
+ if (cursorDataset !== void 0) await saveSweepState(cursorDataset, next);
543
+ return next;
544
+ };
545
+ let sweepRunning = false;
546
+ const sweepTimer = setInterval(() => {
547
+ if (sweepRunning) return;
548
+ sweepRunning = true;
549
+ const reapFn = idempotencyStore !== null ? () => idempotencyStore.reapExpired() : null;
550
+ const purgeFn = pgDatasetForPurge !== null && pgEdgesForPurge !== null ? async () => {
551
+ const olderThan = new Date(Date.now() - tombstoneRetentionMs);
552
+ const rowsResult = await pgDatasetForPurge.purgeTombstonedRows({ olderThan });
553
+ const edgesResult = await pgEdgesForPurge.purgeTombstonedEdges({ olderThan });
554
+ return {
555
+ rows: rowsResult.deleted,
556
+ edges: edgesResult.deleted
557
+ };
558
+ } : null;
559
+ const pgRecall = recallStore instanceof PgEmbeddingsStore ? recallStore : null;
560
+ const pgLexical = lexicalStore instanceof PgLexicalStore ? lexicalStore : null;
561
+ const embeddingsGcFn = pgRecall !== null || pgLexical !== null ? async () => (await pgRecall?.purgeOrphans() ?? 0) + (await pgLexical?.purgeOrphans() ?? 0) : null;
562
+ const cycle = () => runSweepCycle(sweepFn, reapFn, purgeFn, embeddingsGcFn);
563
+ (storeSql === null ? cycle() : tryWithPgAdvisoryLock(storeSql, SWEEP_LOCK_KEY, cycle).then((r) => {
564
+ if (r.acquired) return r.value;
565
+ process.stdout.write(`sweep.skipped ${JSON.stringify({ reason: "lock_held" })}\n`);
566
+ return null;
567
+ })).then((result) => {
568
+ if (result === null) return;
569
+ const { state, reap, tombstonePurge, embeddingsGc } = result;
570
+ sweepState = state;
571
+ if (reap !== void 0) process.stdout.write(`plugin.idempotency_reap ${JSON.stringify(reap)}\n`);
572
+ if (tombstonePurge !== void 0 && (tombstonePurge.rows > 0 || tombstonePurge.edges > 0)) process.stdout.write(`tombstone_purge ${JSON.stringify(tombstonePurge)}\n`);
573
+ if (embeddingsGc !== void 0 && embeddingsGc > 0) process.stdout.write(`embeddings_gc ${JSON.stringify({ orphans: embeddingsGc })}\n`);
574
+ }).catch((err) => {
575
+ if (err instanceof SweepStageError) process.stderr.write(`sweep cycle failed [${err.stage}]: ${err.message}\n`);
576
+ else process.stderr.write(`sweep cycle failed: ${err instanceof Error ? err.message : String(err)}\n`);
577
+ }).finally(() => {
578
+ sweepRunning = false;
579
+ });
580
+ }, config.sweepIntervalMs);
581
+ sweepTimer.unref();
582
+ let inviteSweepTimer = null;
583
+ if (config.auth !== null) {
584
+ const inviteDataset = composedDatasets.get(SYSTEM_NAMESPACE);
585
+ if (inviteDataset === void 0) process.stderr.write(`invite sweep disabled: '${SYSTEM_NAMESPACE}' dataset missing from registry\n`);
586
+ else {
587
+ inviteSweepTimer = setInterval(() => {
588
+ runInviteSweep(inviteDataset).then((result) => {
589
+ process.stdout.write(`plugin.invite_sweep ${JSON.stringify(result)}\n`);
590
+ }).catch((err) => {
591
+ process.stderr.write(`invite sweep cycle failed: ${err instanceof Error ? err.message : String(err)}\n`);
592
+ });
593
+ }, config.inviteSweepIntervalMs);
594
+ inviteSweepTimer.unref();
595
+ }
596
+ }
597
+ let sentinelClient = null;
598
+ if (sentinelClientConfig !== null) {
599
+ sentinelClient = startSentinelClient({
600
+ sentinelUrl: sentinelClientConfig.url,
601
+ bridges: bridgeRegistry,
602
+ engine,
603
+ creds: config.bridgeCreds,
604
+ auth: makeAuthorizationProvider(sentinelClientConfig.cred, { audience: new URL(sentinelClientConfig.url.replace(/^ws/, "http")).origin }),
605
+ metric: (name, payload) => {
606
+ process.stdout.write(`sentinel-client.${name} ${JSON.stringify(payload ?? null)}\n`);
607
+ },
608
+ reconnectBaseMs: sentinelClientConfig.reconnectBaseMs,
609
+ reconnectMaxMs: sentinelClientConfig.reconnectMaxMs
610
+ });
611
+ process.stdout.write(`sentinel-client: watching ${sentinelClientConfig.url}\n`);
612
+ }
613
+ return {
614
+ sweepTimer,
615
+ inviteSweepTimer,
616
+ sentinelClient
617
+ };
618
+ }
619
+
620
+ //#endregion
621
+ //#region src/serve/banners.ts
622
+ /**
623
+ * The "listening at" line, with the scheme matching whether TLS is on.
624
+ * Operators copy a base URL from here, and `substrate federate enroll --origin`
625
+ * validates the scheme.
626
+ */
627
+ function listeningBanner(address, port, tlsEnabled) {
628
+ return `@mnmal-ai/substrate listening at ${tlsEnabled ? "https" : "http"}://${address}:${port}\n`;
629
+ }
630
+ /**
631
+ * The "you have a server that can do nothing" banner, for a plugin-less boot
632
+ * that mounts only `_system` admin + `/health`.
633
+ *
634
+ * Unset and set-but-empty get different text because they have different
635
+ * fixes: point SUBSTRATE_PLUGIN_DIR somewhere, or install packages under
636
+ * `<dir>/node_modules`.
637
+ */
638
+ function noPluginsBanner(pluginDir) {
639
+ return [
640
+ "",
641
+ "┌─ no plugins ──────────────────────────────────────────────────────┐",
642
+ ...pluginDir === null ? [
643
+ "│ SUBSTRATE_PLUGIN_DIR is not set, so no plugins were loaded. │",
644
+ "│ Serving `_system` admin + /health only — no user types. │",
645
+ "│ Point it at a directory holding plugins, e.g.: │",
646
+ "│ SUBSTRATE_PLUGIN_DIR=/srv/substrate (with plugins under node_modules) │"
647
+ ] : [
648
+ "│ No plugins found — serving `_system` admin + /health only. │",
649
+ "│ Looked under <SUBSTRATE_PLUGIN_DIR>/node_modules for packages │",
650
+ "│ declaring a `substrate` manifest, and found none. If you have not │",
651
+ "│ installed any there yet, that is the next step. │"
652
+ ],
653
+ "└───────────────────────────────────────────────────────────────────┘",
654
+ ""
655
+ ].join("\n");
656
+ }
657
+ /**
658
+ * Loud banner emitted at boot whenever the substrate is running on memory
659
+ * mode, so operators can't accidentally believe their data is durable.
660
+ *
661
+ * `byDefault` is `true` when `SUBSTRATE_DATABASE_URL` was unset and we fell back to
662
+ * memory; `false` when the operator chose memory explicitly.
663
+ */
664
+ function memoryStoreBanner(byDefault) {
665
+ return [
666
+ "",
667
+ "┌─ memory mode ─────────────────────────────────────────────────────┐",
668
+ `│ ${(byDefault ? "SUBSTRATE_DATABASE_URL not set — defaulting to in-memory store." : "SUBSTRATE_DATABASE_URL=memory — running with in-memory store.").padEnd(65)} │`,
669
+ "│ Data is NOT persisted; all writes vanish on restart. │",
670
+ "│ For durable storage, set SUBSTRATE_DATABASE_URL to a postgres:// URL, e.g.: │",
671
+ "│ SUBSTRATE_DATABASE_URL='postgres://substrate:substrate@localhost:5432/substrate' │",
672
+ "└───────────────────────────────────────────────────────────────────┘",
673
+ ""
674
+ ].join("\n");
675
+ }
676
+ /**
677
+ * The knob block — every defaulted knob, its effective value, and whether
678
+ * that value came from the operator or from the default. Sorted by env var
679
+ * and column-aligned so two hosts' blocks can be `diff`ed.
680
+ *
681
+ * `—` is an effective value of null: off, or deferred to a layer further down
682
+ * (Fastify's 1 MiB body cap, the engine's 24h idempotency TTL). Every knob
683
+ * appears whether set or not.
684
+ */
685
+ function knobsBanner(knobs) {
686
+ const rows = Object.values(knobs).sort((a, b) => a.env < b.env ? -1 : a.env > b.env ? 1 : 0);
687
+ if (rows.length === 0) return "";
688
+ const width = Math.max(...rows.map((r) => r.env.length));
689
+ return [
690
+ "knobs (effective value, source):",
691
+ ...rows.map((r) => {
692
+ const value = r.value === null ? "—" : String(r.value);
693
+ return ` ${r.env.padEnd(width)} ${value.padEnd(14)} ${r.source}`;
694
+ }),
695
+ ""
696
+ ].join("\n");
697
+ }
698
+
699
+ //#endregion
700
+ //#region src/serve/boot-report.ts
701
+ function reportBoot(args) {
702
+ const { config, info, storeSql, substrateNamespaceDataset, coordinators, kernel, pluginDir } = args;
703
+ process.stdout.write(listeningBanner(info.address, info.port, config.tls !== null));
704
+ process.stdout.write(`store: ${redactStoreSpec(config.storeSpec)}\n`);
705
+ if (config.storeSpec === "memory") process.stdout.write(memoryStoreBanner(config.memoryByDefault));
706
+ process.stdout.write(substrateNamespaceDataset !== null ? `_system: pg-backed\n` : `_system: memory-backed (keys ephemeral)\n`);
707
+ if (coordinators.length > 0) process.stdout.write(`coordinators: ${coordinators.map((p) => p.name).join(", ")}\n`);
708
+ if (kernel.length > 0) process.stdout.write(`kernel: ${kernel.map((p) => p.name).join(", ")}\n`);
709
+ if (pluginDir !== null) process.stdout.write(`plugin-dir: ${pluginDir}\n`);
710
+ if (coordinators.length === 0 && kernel.length === 0) process.stdout.write(noPluginsBanner(pluginDir));
711
+ if (config.bridges.length > 0) process.stdout.write(`bridges: ${config.bridges.map((b) => b.ns).join(", ")}\n`);
712
+ if (config.auth !== null) {
713
+ const fileKeys = config.auth.keys.length;
714
+ const source = fileKeys === 0 ? "database-registered keys only" : `${fileKeys} file key(s)`;
715
+ process.stdout.write(`auth: enabled, mode=${config.auth.mode ?? "required"} (${source})\n`);
716
+ const reprime = config.keyReprimeIntervalMs;
717
+ const reprimeSource = ` (${config.knobs.keyReprimeIntervalMs?.source ?? "default"})`;
718
+ process.stdout.write(reprime === null ? `key cache: reprime off${reprimeSource}\n` : `key cache: reprime every ${reprime}ms${reprimeSource}\n`);
719
+ } else process.stdout.write("auth: DISABLED — all requests are anonymous\n");
720
+ if (config.tls !== null) process.stdout.write(`tls: enabled${config.tls.ca !== void 0 ? " (with CA chain)" : ""}\n`);
721
+ if (config.idempotency.disabled) process.stdout.write(`idempotency: disabled\n`);
722
+ else {
723
+ const backend = storeSql !== null ? "pg-backed" : "memory-backed";
724
+ const ttl = config.idempotency.defaultTtlMs === null ? "default 24h" : `${config.idempotency.defaultTtlMs}ms`;
725
+ process.stdout.write(`idempotency: enabled (${backend}, ttl=${ttl})\n`);
726
+ }
727
+ if (storeSql !== null) process.stdout.write(`tombstone purge: enabled (retention=${config.tombstoneRetentionDays}d, cadence=${config.sweepIntervalMs}ms)\n`);
728
+ process.stdout.write(knobsBanner(config.knobs));
729
+ }
730
+
731
+ //#endregion
732
+ //#region src/serve/shutdown.ts
733
+ /** The longest shutdown waits for the background index builds to stop. */
734
+ const INDEX_BUILDS_STOP_MS = 2e3;
735
+ /**
736
+ * Re-entrancy guard: systemd retries SIGTERM under load, and a double-fire
737
+ * here would clear already-cleared timers and call `stop()` twice. The flag
738
+ * flips on first entry and stays set; subsequent signals just log.
739
+ */
740
+ function installShutdown(args) {
741
+ const { config, sweepTimer, inviteSweepTimer, sentinelClient, disposeBridges, stop, closeStore, stopIndexBuilds } = args;
742
+ let shuttingDown = false;
743
+ const shutdown = (signal) => {
744
+ if (shuttingDown) {
745
+ process.stdout.write(`received ${signal} again — already shutting down\n`);
746
+ return;
747
+ }
748
+ shuttingDown = true;
749
+ process.stdout.write(`\nreceived ${signal} — shutting down (grace ${config.shutdownGraceMs}ms)\n`);
750
+ setTimeout(() => {
751
+ process.stderr.write("shutdown exceeded its grace; exiting with work still pending\n");
752
+ process.exit(1);
753
+ }, config.shutdownGraceMs + 1e3).unref();
754
+ clearInterval(sweepTimer);
755
+ if (inviteSweepTimer !== null) clearInterval(inviteSweepTimer);
756
+ const buildsBound = Math.min(INDEX_BUILDS_STOP_MS, config.shutdownGraceMs / 2);
757
+ const stopBuilds = new Promise((resolve) => {
758
+ if (stopIndexBuilds === void 0) return resolve();
759
+ const timer = setTimeout(() => {
760
+ process.stderr.write(`index builds did not stop within ${buildsBound}ms; abandoning them\n`);
761
+ resolve();
762
+ }, buildsBound);
763
+ timer.unref();
764
+ stopIndexBuilds().catch(() => void 0).then(() => {
765
+ clearTimeout(timer);
766
+ resolve();
767
+ });
768
+ });
769
+ (sentinelClient !== null ? sentinelClient.stop().catch((err) => {
770
+ process.stderr.write(`sentinel-client stop failed: ${err instanceof Error ? err.message : String(err)}\n`);
771
+ }) : Promise.resolve()).then(() => {
772
+ disposeBridges();
773
+ return stop({
774
+ grace: config.shutdownGraceMs,
775
+ abortInFlight: true
776
+ });
777
+ }).then(async () => {
778
+ await stopBuilds;
779
+ if (closeStore) await closeStore();
780
+ }).then(() => {
781
+ process.exit(0);
782
+ }).catch((err) => {
783
+ process.stderr.write(`shutdown error: ${err instanceof Error ? err.message : String(err)}\n`);
784
+ process.exit(1);
785
+ });
786
+ };
787
+ process.on("SIGTERM", () => shutdown("SIGTERM"));
788
+ process.on("SIGINT", () => shutdown("SIGINT"));
789
+ }
790
+
791
+ //#endregion
792
+ //#region src/main.ts
793
+ /**
794
+ * @mnmal-ai/substrate — §5.12 binary entry point.
795
+ *
796
+ * Wires SubstrateServer + Dataset + EdgesStore + optional coordinator plugins
797
+ * + optional bridges + optional JWT auth into a running process. The entry
798
+ * surface is env-var driven:
799
+ *
800
+ * SUBSTRATE_DATABASE_URL memory | postgres://... (default: memory)
801
+ * SUBSTRATE_PLUGIN_DIR abs path to plugin install root (optional). The
802
+ * manifest-driven loader scans
803
+ * <dir>/node_modules/{*,@*\/*} for packages
804
+ * declaring a `substrate` manifest, merges each
805
+ * plugin's default-config.json with the colocated
806
+ * operator override at <dir>/<basename>.config.json,
807
+ * and bootstraps substrate plugins (alphabetical)
808
+ * before coordinators (alphabetical). Unset = no
809
+ * plugins; binary boots with `_system` admin
810
+ * namespace + /health only.
811
+ * SUBSTRATE_BRIDGES JSON array of { ns, name, url } bridge defs (optional)
812
+ * SUBSTRATE_BRIDGE_CREDENTIALS JSON map bridgeName -> { keyPath, kid, origin }.
813
+ * REQUIRED for every entry in SUBSTRATE_BRIDGES — a
814
+ * bridge without one refuses to boot rather than
815
+ * connecting unauthenticated.
816
+ * SUBSTRATE_SENTINEL_CREDENTIAL JSON { keyPath, kid } the sentinel-client signs its
817
+ * WS upgrade with. REQUIRED whenever
818
+ * SUBSTRATE_SENTINEL_URL is set.
819
+ * SUBSTRATE_AUTH_KEY_REGISTRY path to JSON key file (optional — auth opt-in)
820
+ * SUBSTRATE_ADMIN_CAPABILITY JWT claim value granting admin (optional)
821
+ * SUBSTRATE_JWT_LEEWAY_SECONDS clock-skew tolerance for JWT exp/nbf (optional;
822
+ * default 0 = strict). 30 absorbs typical NTP drift.
823
+ * SUBSTRATE_KEY_REFRESH_INTERVAL_MS periodic full re-prime of the public-key
824
+ * cache in ms (default 30000; `off` disables). Bounds
825
+ * revocation staleness. Auth-gated.
826
+ * SUBSTRATE_TLS_KEY_PATH path to TLS private key PEM (optional — TLS opt-in)
827
+ * SUBSTRATE_TLS_CERT_PATH path to TLS certificate PEM (optional — TLS opt-in)
828
+ * SUBSTRATE_TLS_CA_PATH path to CA chain PEM (optional)
829
+ * SUBSTRATE_BODY_LIMIT_BYTES max request body size in bytes (optional). Unset =
830
+ * Fastify's 1 MiB default. Raise for bulk batched
831
+ * mutation frames that exceed 1 MiB.
832
+ * SUBSTRATE_SWEEP_INTERVAL_MS sweep cadence in ms (default 300000)
833
+ * SUBSTRATE_INVITE_SWEEP_INTERVAL_MS invite reaper cadence in ms (default 3600000 = 1h)
834
+ * SUBSTRATE_TOMBSTONE_RETENTION_DAYS retention window for tombstoned rows /
835
+ * edges before they're hard-deleted by the
836
+ * sweep loop. Default 30. Pg-backed only — memory
837
+ * mode tombstones vanish on restart anyway.
838
+ * SUBSTRATE_IDEMPOTENCY_TTL_MS override §5.13 dedup TTL (default: engine 24h)
839
+ * SUBSTRATE_IDEMPOTENCY_DISABLED truthy (1/true) disables mutation dedup
840
+ * SUBSTRATE_TRUSTED_PROXIES CSV of exact peer-IP strings whose x-forwarded-for
841
+ * header is honoured by `/substrate/v1/_system/register`.
842
+ * Exact IP strings only — no CIDR. Callers needing
843
+ * CIDR should terminate XFF parsing at their reverse
844
+ * proxy. See §13 for the scope limit.
845
+ * SUBSTRATE_CORS_ORIGINS comma-separated list of allowed CORS origins for
846
+ * browser clients, or '*' to allow any origin.
847
+ * Unset (default) = no CORS plugin registered —
848
+ * agent-only deployments don't need it.
849
+ * Example: SUBSTRATE_CORS_ORIGINS=https://app.example.com
850
+ * Example: SUBSTRATE_CORS_ORIGINS=* (allow any origin;
851
+ * pairs with credentials:false — anonymous only)
852
+ * PORT / HOST listen args (default 3100; 0.0.0.0 with auth, 127.0.0.1 without)
853
+ *
854
+ * Env parsing is the pure `parseEnv(env)`; `runServe()` sequences the I/O.
855
+ */
856
+ /**
857
+ * Boot the Substrate HTTP/WS server. Reads env, wires substrate + coordinators,
858
+ * starts Fastify, registers signal handlers for graceful shutdown. Invoked
859
+ * through the `substrate serve` subcommand.
860
+ */
861
+ async function runServe() {
862
+ validateHardDeleteEnv();
863
+ const config = parseEnv(process.env);
864
+ const pluginDir = resolvePluginDir();
865
+ const { engine, datasets: composedDatasets, sql: storeSql, server, dataset, edges, substrateNamespaceDataset, closeStore, kernel, coordinators, recallStore, lexicalStore, idempotencyStore, sentinelClientConfig, bridgeRegistry, disposeBridges, sweepDeps, scheduler, stop } = await bootStore({
866
+ config,
867
+ pluginDir
868
+ });
869
+ if (config.indexDiskPath === null) await reportUnguardedIndexBuilds(engine, composedDatasets);
870
+ const info = await server.start({
871
+ host: config.host,
872
+ port: config.port
873
+ });
874
+ const indexBuilds = new AbortController();
875
+ const deferredIndexes = runDeferredIndexBuilds(engine, composedDatasets, config.indexRetryIntervalMs, indexBuilds.signal);
876
+ if (scheduler !== null) scheduler.start();
877
+ reportBoot({
878
+ config,
879
+ info,
880
+ storeSql,
881
+ substrateNamespaceDataset,
882
+ coordinators,
883
+ kernel,
884
+ pluginDir
885
+ });
886
+ const { sweepTimer, inviteSweepTimer, sentinelClient } = startBackground({
887
+ config,
888
+ sweepDeps,
889
+ idempotencyStore,
890
+ dataset,
891
+ edges,
892
+ storeSql,
893
+ stores: {
894
+ recallStore,
895
+ lexicalStore
896
+ },
897
+ composedDatasets,
898
+ sentinelClientConfig,
899
+ bridgeRegistry,
900
+ engine
901
+ });
902
+ installShutdown({
903
+ config,
904
+ sweepTimer,
905
+ inviteSweepTimer,
906
+ sentinelClient,
907
+ disposeBridges,
908
+ stop,
909
+ closeStore,
910
+ stopIndexBuilds: () => {
911
+ indexBuilds.abort();
912
+ return deferredIndexes;
913
+ }
914
+ });
915
+ }
916
+
917
+ //#endregion
918
+ //#region src/cli/federate/http.ts
919
+ /**
920
+ * Minimal JSON-over-HTTP client for the `substrate federate` verbs.
921
+ *
922
+ * A non-2xx status is a RESULT, not an error: callers map peer error codes to
923
+ * specific operator-facing messages, which they cannot do from an exception.
924
+ * Only transport failures and timeouts reject.
925
+ *
926
+ * There is deliberately no way to skip TLS verification. Every caller of this
927
+ * module puts a secret on the wire — `join` sends a single-use invite code an
928
+ * active MITM could steal and redeem as itself, and `check` sends a live
929
+ * bearer JWT. A self-signed lab CA belongs in NODE_EXTRA_CA_CERTS, which Node
930
+ * honours natively and which still verifies the chain.
931
+ */
932
+ const DEFAULT_TIMEOUT_MS = 1e4;
933
+ var HttpJsonError = class extends Error {
934
+ name = "HttpJsonError";
935
+ };
936
+ async function httpJson(url, opts = {}) {
937
+ const headers = {
938
+ accept: "application/json",
939
+ ...opts.headers
940
+ };
941
+ const init = {
942
+ method: opts.method ?? "GET",
943
+ headers,
944
+ signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
945
+ };
946
+ if (opts.body !== void 0) {
947
+ headers["content-type"] = "application/json";
948
+ init.body = JSON.stringify(opts.body);
949
+ }
950
+ try {
951
+ tokenAudience(url);
952
+ } catch (err) {
953
+ throw new HttpJsonError(err instanceof Error ? err.message : String(err));
954
+ }
955
+ init.redirect = "error";
956
+ let res;
957
+ try {
958
+ res = await fetch(url, init);
959
+ } catch (err) {
960
+ throw new HttpJsonError(`${url}: ${err instanceof Error ? err.message : String(err)}`);
961
+ }
962
+ const raw = await res.text();
963
+ let body;
964
+ try {
965
+ body = raw.length > 0 ? JSON.parse(raw) : void 0;
966
+ } catch {
967
+ body = void 0;
968
+ }
969
+ return {
970
+ status: res.status,
971
+ body,
972
+ raw
973
+ };
974
+ }
975
+
976
+ //#endregion
977
+ //#region src/cli/federate/check.ts
978
+ /**
979
+ * `substrate federate check` — diagnose a configured bridge, naming the fault.
980
+ *
981
+ * All six failure modes below present to a caller identically, as
982
+ * `_completeness: { complete: false, unreachable: ["peer-b"] }`; this command
983
+ * tells them apart.
984
+ *
985
+ * Steps run in dependency order and stop at the first failure — a scope
986
+ * verdict computed against an unreachable peer would be noise. That applies to
987
+ * config/key file/reachable/auth, which are properties of the coordinator, not
988
+ * of any one namespace. Scope and namespace are properties of a GRANT, and one
989
+ * coordinator can carry several — `formatJoinOutput` emits one `SUBSTRATE_BRIDGES`
990
+ * entry per namespace under a single coordinator name — so those two steps run
991
+ * once per configured namespace rather than stopping at the first.
992
+ */
993
+ /**
994
+ * Step names for the per-namespace pair. A single namespace (the common case)
995
+ * keeps the plain `scope`/`namespace` labels; two or more get the namespace
996
+ * folded into the label so an operator can see which one failed without
997
+ * cross-referencing detail text.
998
+ */
999
+ function namespaceStepNames(namespaces) {
1000
+ if (namespaces.length <= 1) return ["scope", "namespace"];
1001
+ return namespaces.flatMap((ns) => [`scope:${ns}`, `namespace:${ns}`]);
1002
+ }
1003
+ async function runCheck(name, env, deps = {}) {
1004
+ const call = deps.httpJson ?? httpJson;
1005
+ const mintToken = deps.tokenFor ?? ((cred) => makeAuthorizationProvider(cred)());
1006
+ const specs = parseBridges(env.SUBSTRATE_BRIDGES);
1007
+ const creds = parseBridgeCreds(env.SUBSTRATE_BRIDGE_CREDENTIALS);
1008
+ const byName = /* @__PURE__ */ new Map();
1009
+ for (const spec of specs) {
1010
+ const existing = byName.get(spec.name);
1011
+ if (existing === void 0) byName.set(spec.name, [spec]);
1012
+ else existing.push(spec);
1013
+ }
1014
+ const targets = name === void 0 ? [...byName.entries()].map(([n, list]) => ({
1015
+ name: n,
1016
+ specs: list
1017
+ })) : [{
1018
+ name,
1019
+ specs: byName.get(name) ?? []
1020
+ }];
1021
+ if (targets.length === 0) throw new AdminCliError("no bridges configured — SUBSTRATE_BRIDGES is empty. Run `substrate federate join` first, or pass --env-file pointing at the env file your instance actually reads.", 2);
1022
+ const results = [];
1023
+ for (const target of targets) results.push(await checkOne(target.name, target.specs, creds, call, mintToken));
1024
+ return results;
1025
+ }
1026
+ async function checkOne(bridgeName, specs, creds, call, mintToken) {
1027
+ const spec = specs[0];
1028
+ const steps = [
1029
+ "config",
1030
+ "key file",
1031
+ "reachable",
1032
+ "auth",
1033
+ ...namespaceStepNames(specs.map((s) => s.ns))
1034
+ ].map((n) => ({
1035
+ name: n,
1036
+ status: "skipped",
1037
+ detail: ""
1038
+ }));
1039
+ const setStep = (index, status, detail) => {
1040
+ const step = steps[index];
1041
+ if (step !== void 0) {
1042
+ step.status = status;
1043
+ step.detail = detail;
1044
+ }
1045
+ };
1046
+ const pass = (index, detail) => setStep(index, "ok", detail);
1047
+ const fail = (index, detail) => {
1048
+ setStep(index, "fail", detail);
1049
+ return {
1050
+ bridge: bridgeName,
1051
+ ok: false,
1052
+ steps
1053
+ };
1054
+ };
1055
+ if (spec === void 0) return fail(0, `bridge '${bridgeName}' is not configured in SUBSTRATE_BRIDGES`);
1056
+ const cred = creds.get(bridgeName);
1057
+ if (cred === void 0) return fail(0, `bridge '${bridgeName}' has no entry in SUBSTRATE_BRIDGE_CREDENTIALS`);
1058
+ let specOrigin;
1059
+ try {
1060
+ specOrigin = new URL(spec.url).origin;
1061
+ } catch {
1062
+ return fail(0, `bridge url '${spec.url}' is malformed`);
1063
+ }
1064
+ if (specOrigin !== cred.origin) return fail(0, `bridge url origin '${specOrigin}' does not match the credential origin '${cred.origin}'`);
1065
+ pass(0, `SUBSTRATE_BRIDGES + CREDS agree on ${specOrigin}`);
1066
+ if (!existsSync(cred.keyPath)) return fail(1, `key file '${cred.keyPath}' does not exist`);
1067
+ let authorization;
1068
+ try {
1069
+ authorization = mintToken(cred);
1070
+ } catch (err) {
1071
+ return fail(1, `key file '${cred.keyPath}' could not be used to mint a token: ${err instanceof Error ? err.message : String(err)}`);
1072
+ }
1073
+ pass(1, cred.keyPath);
1074
+ try {
1075
+ const health = await call(`${cred.origin}/health`);
1076
+ if (health.status !== 200) return fail(2, `${cred.origin}/health returned HTTP ${health.status}`);
1077
+ } catch (err) {
1078
+ return fail(2, `${cred.origin} — ${err instanceof Error ? err.message : String(err)}`);
1079
+ }
1080
+ pass(2, `${cred.origin}/health`);
1081
+ let whoami;
1082
+ try {
1083
+ const res = await call(`${cred.origin}/substrate/v1/whoami`, { headers: { authorization } });
1084
+ if (res.status === 401) return fail(3, `peer does not recognise kid '${cred.kid}' — register it there, or it was revoked`);
1085
+ if (res.status === 404) return fail(3, `${cred.origin} does not expose /substrate/v1/whoami — the peer is likely running a release that predates it, or one still serving the older \`/substrate/v1/_system/whoami\`. Upgrade the peer, or verify auth by hand in the meantime.`);
1086
+ if (res.status !== 200) return fail(3, `whoami returned HTTP ${res.status}`);
1087
+ whoami = res.body ?? {};
1088
+ } catch (err) {
1089
+ return fail(3, `whoami failed: ${err instanceof Error ? err.message : String(err)}`);
1090
+ }
1091
+ if (whoami.authEnabled !== true) return fail(3, "peer reports auth DISABLED — your credential is not being verified. Anything that \"works\" against it proves nothing");
1092
+ if (whoami.identity === null || whoami.identity === void 0) return fail(3, `the peer verified nothing for kid '${cred.kid}' — auth is enabled there, but this request arrived without a credential. Check SUBSTRATE_BRIDGE_CREDENTIALS / the key path rather than the peer`);
1093
+ const granted = grantOf(whoami.identity);
1094
+ const summary = granted === null ? "peer reported no grant" : Object.entries(granted).map(([ns, caps]) => `${ns}:${caps.length > 0 ? caps.join("+") : "(nothing)"}`).join(", ");
1095
+ pass(3, `peer accepted kid '${cred.kid}' — grant: ${summary}`);
1096
+ let anyNsFailed = false;
1097
+ for (let i = 0; i < specs.length; i++) {
1098
+ const nsSpec = specs[i];
1099
+ if (nsSpec === void 0) continue;
1100
+ const scopeIdx = 4 + i * 2;
1101
+ const namespaceIdx = 5 + i * 2;
1102
+ if (!coversNamespace(granted, nsSpec.ns)) {
1103
+ setStep(scopeIdx, "fail", `peer grants ${summary} — this bridge needs '${nsSpec.ns}'`);
1104
+ anyNsFailed = true;
1105
+ continue;
1106
+ }
1107
+ const here = grantedIn(granted, nsSpec.ns);
1108
+ const writable = here.includes("mutate") || here.includes("admin");
1109
+ setStep(scopeIdx, "ok", `peer grants '${nsSpec.ns}': ${here.length === 0 ? "(nothing)" : here.join(", ")}` + (writable ? "" : " — read-only, writes through this bridge will be refused"));
1110
+ try {
1111
+ const schema = await call(`${cred.origin}/substrate/v1/schema/${nsSpec.ns}`);
1112
+ if (schema.status !== 200) {
1113
+ setStep(namespaceIdx, "fail", `peer is reachable and authorised but does not serve namespace '${nsSpec.ns}' (HTTP ${schema.status})`);
1114
+ anyNsFailed = true;
1115
+ continue;
1116
+ }
1117
+ } catch (err) {
1118
+ setStep(namespaceIdx, "fail", `schema lookup failed: ${err instanceof Error ? err.message : String(err)}`);
1119
+ anyNsFailed = true;
1120
+ continue;
1121
+ }
1122
+ setStep(namespaceIdx, "ok", `peer serves '${nsSpec.ns}'`);
1123
+ }
1124
+ return {
1125
+ bridge: bridgeName,
1126
+ ok: !anyNsFailed,
1127
+ steps
1128
+ };
1129
+ }
1130
+ function formatCheckOutput(results) {
1131
+ const lines = [];
1132
+ for (const result of results) {
1133
+ lines.push("", `${result.bridge}`);
1134
+ for (const step of result.steps) {
1135
+ const mark = step.status === "ok" ? "OK " : step.status === "fail" ? "FAIL" : "-- ";
1136
+ lines.push(` ${mark} ${step.name.padEnd(10)} ${step.detail}`);
1137
+ }
1138
+ }
1139
+ lines.push("");
1140
+ return lines.join("\n");
1141
+ }
1142
+
1143
+ //#endregion
1144
+ //#region src/cli/federate/duration.ts
1145
+ /**
1146
+ * `--ttl` parsing for `substrate federate enroll`.
1147
+ *
1148
+ * The 30-day ceiling matches MAX_TTL_MS in the `_system` invites route, so a
1149
+ * CLI-minted invite can never outlive what the HTTP route would allow.
1150
+ */
1151
+ const MAX_TTL_MS = 2592e6;
1152
+ const DURATION = /^(\d+)(s|m|h|d)$/;
1153
+ const UNIT_MS = {
1154
+ s: 1e3,
1155
+ m: 6e4,
1156
+ h: 36e5,
1157
+ d: 864e5
1158
+ };
1159
+ function parseDuration(raw) {
1160
+ const match = DURATION.exec(raw.trim());
1161
+ if (match === null) throw new Error(`invalid duration '${raw}' — expected a value like 30s, 15m, 24h, 7d`);
1162
+ const ms = Number(match[1]) * UNIT_MS[match[2]];
1163
+ if (ms <= 0) throw new Error(`invalid duration '${raw}' — must be greater than zero`);
1164
+ if (ms > 2592e6) throw new Error(`invalid duration '${raw}' — must not exceed 30 days`);
1165
+ return ms;
1166
+ }
1167
+
1168
+ //#endregion
1169
+ //#region src/cli/federate/probe.ts
1170
+ /**
1171
+ * Auth-posture probe used by `substrate federate enroll`.
1172
+ *
1173
+ * A token minted against a callee with auth disabled yields a credential that
1174
+ * proves nothing, with no signal to the operator — so enroll refuses that
1175
+ * case. Anything OTHER than a clear "auth is off" answer reads as
1176
+ * `unreachable`, which enroll treats as a warning: a host legitimately may not
1177
+ * reach its own public URL (split-horizon DNS), and that is not evidence about
1178
+ * auth posture. Guessing either way from an ambiguous response would break one
1179
+ * of the two cases.
1180
+ */
1181
+ const PROBE_TIMEOUT_MS = 5e3;
1182
+ async function probeAuthPosture(origin, opts = {}) {
1183
+ const call = opts.httpJson ?? httpJson;
1184
+ let res;
1185
+ try {
1186
+ res = await call(`${origin}/substrate/v1/whoami`, { timeoutMs: PROBE_TIMEOUT_MS });
1187
+ } catch {
1188
+ return "unreachable";
1189
+ }
1190
+ if (res.status < 200 || res.status >= 300) return "unreachable";
1191
+ const body = res.body;
1192
+ if (body === null || typeof body !== "object") return "unreachable";
1193
+ const authEnabled = body.authEnabled;
1194
+ if (authEnabled === true) return "enabled";
1195
+ if (authEnabled === false) return "disabled";
1196
+ return "unreachable";
1197
+ }
1198
+
1199
+ //#endregion
1200
+ //#region src/cli/federate/token.ts
1201
+ /**
1202
+ * The `substrate federate` join-token envelope.
1203
+ *
1204
+ * substrate-join-v1.<base64url(JSON)> payload: { origin, code }
1205
+ *
1206
+ * Origin and code only. Namespaces and capabilities are deliberately absent:
1207
+ * redemption returns them from the invite row, which is authoritative, and a
1208
+ * second copy in the token would be the one the operator reads while not
1209
+ * being the one that binds.
1210
+ *
1211
+ * The versioned prefix makes a pasted token self-identifying, greppable by
1212
+ * secret scanners, and safe to change later. `.` cannot collide with the
1213
+ * base64url alphabet (which contains `-` and `_`).
1214
+ */
1215
+ const TOKEN_PREFIX = "substrate-join-v1.";
1216
+ /** base64url alphabet, unpadded. Checked explicitly because Buffer's
1217
+ * 'base64url' decoder is lenient and silently drops invalid bytes. */
1218
+ const BASE64URL = /^[A-Za-z0-9_-]+$/;
1219
+ var JoinTokenError = class extends Error {
1220
+ name = "JoinTokenError";
1221
+ exitCode;
1222
+ constructor(message, exitCode = 2) {
1223
+ super(message);
1224
+ this.exitCode = exitCode;
1225
+ }
1226
+ };
1227
+ function encodeJoinToken(payload) {
1228
+ const json = JSON.stringify({
1229
+ origin: payload.origin,
1230
+ code: payload.code
1231
+ });
1232
+ return TOKEN_PREFIX + Buffer.from(json, "utf8").toString("base64url");
1233
+ }
1234
+ function decodeJoinToken(token) {
1235
+ const trimmed = token.trim();
1236
+ if (!trimmed.startsWith(TOKEN_PREFIX)) throw new JoinTokenError(`not a substrate join token — expected a value starting with '${TOKEN_PREFIX}'`);
1237
+ const encoded = trimmed.slice(18);
1238
+ if (encoded.length === 0) throw new JoinTokenError("join token has an empty payload");
1239
+ if (!BASE64URL.test(encoded)) throw new JoinTokenError("join token payload is not valid base64url");
1240
+ const json = Buffer.from(encoded, "base64url").toString("utf8");
1241
+ let parsed;
1242
+ try {
1243
+ parsed = JSON.parse(json);
1244
+ } catch {
1245
+ throw new JoinTokenError("join token payload is not valid JSON");
1246
+ }
1247
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new JoinTokenError("join token payload must be a JSON object");
1248
+ const p = parsed;
1249
+ if (typeof p.code !== "string" || p.code.length === 0) throw new JoinTokenError("join token payload is missing a non-empty 'code'");
1250
+ if (typeof p.origin !== "string" || p.origin.length === 0) throw new JoinTokenError("join token payload is missing a non-empty 'origin'");
1251
+ let url;
1252
+ try {
1253
+ url = new URL(p.origin);
1254
+ } catch {
1255
+ throw new JoinTokenError(`join token origin '${p.origin}' is not a valid URL`);
1256
+ }
1257
+ if (url.protocol !== "http:" && url.protocol !== "https:") throw new JoinTokenError(`join token origin '${p.origin}' must be http(s)`);
1258
+ return {
1259
+ origin: url.origin,
1260
+ code: p.code
1261
+ };
1262
+ }
1263
+
1264
+ //#endregion
1265
+ //#region src/cli/federate/enroll.ts
1266
+ /**
1267
+ * `substrate federate enroll` — mint a single-use enrollment token on the callee.
1268
+ *
1269
+ * Transport is direct-to-pg, mirroring `substrate-admin register`: no admin JWT is
1270
+ * needed, and it works on an instance that was never bootstrapped. That is
1271
+ * what dissolves the chicken-and-egg — the operator with shell on the callee
1272
+ * is exactly the operator with authority to admit a peer.
1273
+ *
1274
+ * The `invite_created` audit row is emitted EXPLICITLY. The HTTP route gets it
1275
+ * from an autoCRUD mutation interceptor; going direct-to-pg bypasses the
1276
+ * engine, so nothing emits it implicitly. Same hand-rolled emit `runRegister`
1277
+ * does for `key_registered`.
1278
+ */
1279
+ /** Actor stamped on audit rows written by the `substrate federate` verbs. */
1280
+ const CLI_ACTOR_KID = "substrate-federate-cli";
1281
+ const defaultProbe = (origin) => probeAuthPosture(origin);
1282
+ async function runEnroll(args, env, openDataset = openPgDataset, probe = defaultProbe) {
1283
+ const posture = await probe(args.origin);
1284
+ if (posture === "disabled") throw new AdminCliError(`${args.origin} reports auth is DISABLED — a credential issued against it would verify nothing. Set SUBSTRATE_AUTH_MODE and SUBSTRATE_STREAM_TICKET_SECRET on the callee, restart it, then retry.`, 7);
1285
+ const probeWarning = posture === "unreachable" ? `could not reach ${args.origin} to confirm auth is enabled — minting anyway. Verify the callee shows \`auth: enabled\` in its boot banner.` : null;
1286
+ const code = randomBytes(32).toString("base64url");
1287
+ const now = /* @__PURE__ */ new Date();
1288
+ const expiresAt = new Date(now.getTime() + args.ttlMs);
1289
+ const { dataset, close } = await openDataset(env);
1290
+ try {
1291
+ await dataset.withTransaction(async (tx) => {
1292
+ await tx.write(INVITE_TYPE, [{
1293
+ id: code,
1294
+ namespaces: encodeList(args.namespaces),
1295
+ capabilities: encodeList(args.capabilities),
1296
+ expiresAt: expiresAt.toISOString(),
1297
+ consumedAt: null,
1298
+ consumedBy: null
1299
+ }], {
1300
+ identity: {
1301
+ kind: "system",
1302
+ id: CLI_ACTOR_KID
1303
+ },
1304
+ now
1305
+ });
1306
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1307
+ actorKid: CLI_ACTOR_KID,
1308
+ kind: "invite_created",
1309
+ targetKid: code,
1310
+ details: {
1311
+ origin: args.origin,
1312
+ namespaces: args.namespaces.join(","),
1313
+ capabilities: args.capabilities.join(","),
1314
+ expiresAt: expiresAt.toISOString()
1315
+ },
1316
+ now
1317
+ })], {
1318
+ identity: {
1319
+ kind: "system",
1320
+ id: CLI_ACTOR_KID
1321
+ },
1322
+ now
1323
+ });
1324
+ });
1325
+ } finally {
1326
+ await close();
1327
+ }
1328
+ return {
1329
+ token: encodeJoinToken({
1330
+ origin: args.origin,
1331
+ code
1332
+ }),
1333
+ origin: args.origin,
1334
+ expiresAt: expiresAt.toISOString(),
1335
+ namespaces: args.namespaces,
1336
+ capabilities: args.capabilities,
1337
+ probeWarning
1338
+ };
1339
+ }
1340
+ function formatEnrollOutput(result) {
1341
+ const lines = [];
1342
+ if (result.probeWarning !== null) lines.push(`warning: ${result.probeWarning}`, "");
1343
+ lines.push("Enrollment token minted.", ` origin: ${result.origin}`, ` namespaces: ${result.namespaces.join(", ")}`, ` capabilities: ${result.capabilities.join(", ")}`, ` expires: ${result.expiresAt}`, "", ` token: ${result.token}`, "", "Run this ON THE CALLER and paste the token at the (silent) prompt.", "Single use — it stops working once redeemed.", "", " read -rs SUBSTRATE_JOIN_TOKEN && SUBSTRATE_JOIN_TOKEN=\"$SUBSTRATE_JOIN_TOKEN\" substrate federate join", "");
1344
+ return lines.join("\n");
1345
+ }
1346
+
1347
+ //#endregion
1348
+ //#region src/cli/federate/env-file.ts
1349
+ /**
1350
+ * Minimal `KEY=VALUE` reader for `substrate federate check --env-file`.
1351
+ *
1352
+ * The bridge config lives in the runtime's `.env` (or a systemd
1353
+ * EnvironmentFile), not in the operator's shell. Without this the operator has
1354
+ * to remember `set -a && source .env && set +a` before every check.
1355
+ *
1356
+ * Deliberately not a full dotenv implementation: no interpolation, no
1357
+ * multi-line values, no `export ` prefix handling. systemd's EnvironmentFile
1358
+ * does not do those either, so matching its subset is the correct target.
1359
+ */
1360
+ function loadEnvFile(path) {
1361
+ let text;
1362
+ try {
1363
+ text = readFileSync(path, "utf8");
1364
+ } catch (err) {
1365
+ throw new Error(`cannot read env file '${path}': ${err instanceof Error ? err.message : String(err)}`);
1366
+ }
1367
+ const out = {};
1368
+ for (const rawLine of text.split("\n")) {
1369
+ const line = rawLine.trim();
1370
+ if (line.length === 0 || line.startsWith("#")) continue;
1371
+ const eq = line.indexOf("=");
1372
+ if (eq <= 0) continue;
1373
+ const key = line.slice(0, eq).trim();
1374
+ let value = line.slice(eq + 1).trim();
1375
+ if (value.startsWith("'") && value.endsWith("'") && value.length >= 2 || value.startsWith("\"") && value.endsWith("\"") && value.length >= 2) value = value.slice(1, -1);
1376
+ out[key] = value;
1377
+ }
1378
+ return out;
1379
+ }
1380
+
1381
+ //#endregion
1382
+ //#region src/cli/federate/join.ts
1383
+ /**
1384
+ * `substrate federate join` — redeem an enrollment token on the caller.
1385
+ *
1386
+ * The ordering below IS the safety property:
1387
+ *
1388
+ * check key-out clobber → generate keypair in memory → redeem → write key
1389
+ *
1390
+ * Checking the output path after redemption would burn a single-use invite
1391
+ * with nowhere to put the resulting key. And a generated-but-unregistered key
1392
+ * is strictly worse than no key: the tooling then signs with something the
1393
+ * peer rejects, so every read fails auth rather than degrading cleanly. Any
1394
+ * failure here leaves the filesystem untouched.
1395
+ */
1396
+ function asStringArray(value) {
1397
+ if (!Array.isArray(value)) return [];
1398
+ return value.filter((v) => typeof v === "string");
1399
+ }
1400
+ /** Map the callee's response into a specific operator-facing message. */
1401
+ function registerFailure(status, body, origin) {
1402
+ const code = typeof body === "object" && body !== null ? body.code : void 0;
1403
+ if (code === "invite_not_found") return new AdminCliError(`token not recognised at ${origin} — it was already swept, or it was minted against a different instance`, 3);
1404
+ if (code === "invite_already_consumed") return new AdminCliError("this token has already been redeemed — tokens are single use. Mint a fresh one on the callee with `substrate federate enroll`.", 4);
1405
+ if (code === "invite_expired") return new AdminCliError("this token has expired. Mint a fresh one on the callee with `substrate federate enroll`.", 5);
1406
+ if (code === "rate_limited") {
1407
+ const retryMs = typeof body === "object" && body !== null ? body.retryAfterMs : void 0;
1408
+ const seconds = typeof retryMs === "number" ? Math.max(1, Math.ceil(retryMs / 1e3)) : 60;
1409
+ return new AdminCliError(`${origin} is rate-limiting registrations — retry in ${seconds}s`, 6);
1410
+ }
1411
+ const message = typeof body === "object" && body !== null ? String(body.message ?? "") : "";
1412
+ return new AdminCliError(`${origin} refused the registration (HTTP ${status})${message.length > 0 ? `: ${message}` : ""}`, 3);
1413
+ }
1414
+ async function runJoin(args, deps = {}) {
1415
+ const call = deps.httpJson ?? httpJson;
1416
+ const host = (deps.hostname ?? hostname)();
1417
+ const home = (deps.homeDir ?? homedir)();
1418
+ const payload = decodeJoinToken(args.token);
1419
+ const name = args.name ?? new URL(payload.origin).hostname;
1420
+ const keyPath = args.keyOut ?? join(home, ".config/substrate/keys", `${name}.key`);
1421
+ if (existsSync(keyPath)) throw new AdminCliError(`key path '${keyPath}' already exists — move it aside and retry, or pass --key-out. Nothing has been redeemed; your token is still valid.`, 2);
1422
+ const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
1423
+ publicKeyEncoding: {
1424
+ format: "pem",
1425
+ type: "spki"
1426
+ },
1427
+ privateKeyEncoding: {
1428
+ format: "pem",
1429
+ type: "pkcs8"
1430
+ }
1431
+ });
1432
+ let res;
1433
+ try {
1434
+ res = await call(`${payload.origin}/substrate/v1/_system/register`, {
1435
+ method: "POST",
1436
+ body: {
1437
+ code: payload.code,
1438
+ publicKey: publicKey.toString(),
1439
+ keyName: `bridge from ${host}`,
1440
+ algorithm: "EdDSA"
1441
+ }
1442
+ });
1443
+ } catch (err) {
1444
+ throw new AdminCliError(`cannot reach ${payload.origin}: ${err instanceof Error ? err.message : String(err)}. That origin came from the token itself, so check it is the URL this machine can reach — a wrong origin at mint time looks identical to a peer being down.`, 3);
1445
+ }
1446
+ if (res.status !== 201) throw registerFailure(res.status, res.body, payload.origin);
1447
+ const body = res.body ?? {};
1448
+ const kid = typeof body.kid === "string" ? body.kid : "";
1449
+ if (kid.length === 0) throw new AdminCliError(`${payload.origin} accepted the registration but returned no kid — nothing was written locally`, 3);
1450
+ try {
1451
+ mkdirSync(dirname(keyPath), {
1452
+ recursive: true,
1453
+ mode: 448
1454
+ });
1455
+ writeFileSync(keyPath, privateKey.toString(), { mode: 384 });
1456
+ } catch (err) {
1457
+ const msg = err instanceof Error ? err.message : String(err);
1458
+ throw new AdminCliError(`redeemed at ${payload.origin} (kid ${kid}) but failed to write the private key to '${keyPath}': ${msg}. The invite token IS consumed — it cannot be redeemed again. Mint a fresh one on the callee with \`substrate federate enroll\`, then retry \`join\` with a path this process can actually create and write.`, 8);
1459
+ }
1460
+ return {
1461
+ origin: payload.origin,
1462
+ name,
1463
+ kid,
1464
+ namespaces: asStringArray(body.namespaces),
1465
+ capabilities: asStringArray(body.capabilities),
1466
+ keyPath
1467
+ };
1468
+ }
1469
+ function formatJoinOutput(result) {
1470
+ const bridges = result.namespaces.map((ns) => ({
1471
+ ns,
1472
+ name: result.name,
1473
+ url: result.origin
1474
+ }));
1475
+ const creds = { [result.name]: {
1476
+ keyPath: result.keyPath,
1477
+ kid: result.kid,
1478
+ origin: result.origin
1479
+ } };
1480
+ return [
1481
+ "",
1482
+ ` redeemed at ${result.origin}`,
1483
+ ` kid: ${result.kid}`,
1484
+ ` namespaces: ${result.namespaces.join(", ")} capabilities: ${result.capabilities.join(", ")}`,
1485
+ ` key: ${result.keyPath} (0600)`,
1486
+ "",
1487
+ "Add to your .env, then restart:",
1488
+ "",
1489
+ `SUBSTRATE_BRIDGES='${JSON.stringify(bridges)}'`,
1490
+ `SUBSTRATE_BRIDGE_CREDENTIALS='${JSON.stringify(creds)}'`,
1491
+ "",
1492
+ `Then verify with: substrate federate check ${result.name}`,
1493
+ ""
1494
+ ].join("\n");
1495
+ }
1496
+
1497
+ //#endregion
1498
+ //#region src/cli/federate/main.ts
1499
+ /**
1500
+ * Mirrors `packages/substrate-compose/src/compose.ts`'s `Capability` union — the
1501
+ * only spellings any route's `gate()` call ever recognises. Anything else
1502
+ * mints a credential that authenticates but never satisfies a capability
1503
+ * check, diagnosable only via `substrate federate check` after the fact.
1504
+ */
1505
+ const KNOWN_CAPABILITIES = [
1506
+ "read",
1507
+ "mutate",
1508
+ "admin"
1509
+ ];
1510
+ const FEDERATE_USAGE = [
1511
+ "Usage: substrate federate <verb> [args...]",
1512
+ "",
1513
+ "Verbs:",
1514
+ " enroll --origin <url> --ns <csv> [--caps <csv>] [--ttl 15m] [--allow-admin]",
1515
+ " ON THE CALLEE. Mints a single-use enrollment token. Needs SUBSTRATE_DATABASE_URL.",
1516
+ " --caps admin requires --allow-admin — the credential leaves this machine.",
1517
+ "",
1518
+ " join [--name <n>] [--key-out <path>]",
1519
+ " ON THE CALLER. Redeems the token in SUBSTRATE_JOIN_TOKEN and prints the config to paste.",
1520
+ " A <token> positional still works but is visible in ps and shell history.",
1521
+ "",
1522
+ " check [<name>] [--env-file <path>]",
1523
+ " ON THE CALLER. Diagnoses a configured bridge end to end.",
1524
+ "",
1525
+ " TLS is always verified. For a private CA, set NODE_EXTRA_CA_CERTS."
1526
+ ].join("\n");
1527
+ function splitCsv(csv) {
1528
+ return csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
1529
+ }
1530
+ /** Shared single-value flag reader — rejects a missing value or a following flag. */
1531
+ function takeValue(rest, index, verb, flag) {
1532
+ const value = rest[index + 1];
1533
+ if (value === void 0 || value.length === 0 || value.startsWith("--")) throw new AdminCliError(`${verb}: ${flag} requires a value`, 1);
1534
+ return value;
1535
+ }
1536
+ function parseEnrollArgs(argv) {
1537
+ const rest = argv.slice(1);
1538
+ let origin;
1539
+ let nsCsv;
1540
+ let capsCsv;
1541
+ let ttlRaw;
1542
+ let allowAdmin = false;
1543
+ for (let i = 0; i < rest.length; i++) {
1544
+ const tok = rest[i];
1545
+ if (tok === void 0) continue;
1546
+ if (tok === "--origin") {
1547
+ if (origin !== void 0) throw new AdminCliError("enroll: --origin specified more than once", 1);
1548
+ origin = takeValue(rest, i, "enroll", "--origin");
1549
+ i += 1;
1550
+ } else if (tok === "--ns") {
1551
+ if (nsCsv !== void 0) throw new AdminCliError("enroll: --ns specified more than once", 1);
1552
+ nsCsv = takeValue(rest, i, "enroll", "--ns");
1553
+ i += 1;
1554
+ } else if (tok === "--caps") {
1555
+ if (capsCsv !== void 0) throw new AdminCliError("enroll: --caps specified more than once", 1);
1556
+ capsCsv = takeValue(rest, i, "enroll", "--caps");
1557
+ i += 1;
1558
+ } else if (tok === "--ttl") {
1559
+ if (ttlRaw !== void 0) throw new AdminCliError("enroll: --ttl specified more than once", 1);
1560
+ ttlRaw = takeValue(rest, i, "enroll", "--ttl");
1561
+ i += 1;
1562
+ } else if (tok === "--allow-admin") {
1563
+ if (allowAdmin) throw new AdminCliError("enroll: --allow-admin specified more than once", 1);
1564
+ allowAdmin = true;
1565
+ } else if (tok.startsWith("--")) throw new AdminCliError(`enroll: unknown flag ${tok}`, 1);
1566
+ else throw new AdminCliError(`enroll: unexpected positional arg '${tok}'`, 1);
1567
+ }
1568
+ if (origin === void 0) throw new AdminCliError("enroll requires --origin <url> (the callee base URL)", 1);
1569
+ let normalisedOrigin;
1570
+ try {
1571
+ const url = new URL(origin);
1572
+ if (url.protocol !== "http:" && url.protocol !== "https:") throw new AdminCliError(`enroll: --origin '${origin}' must be http(s)`, 1);
1573
+ normalisedOrigin = url.origin;
1574
+ } catch (err) {
1575
+ if (err instanceof AdminCliError) throw err;
1576
+ throw new AdminCliError(`enroll: --origin '${origin}' is not a valid URL`, 1);
1577
+ }
1578
+ if (nsCsv === void 0) throw new AdminCliError("enroll requires --ns <csv> naming the namespaces this peer may query", 1);
1579
+ const namespaces = splitCsv(nsCsv);
1580
+ if (namespaces.length === 0) throw new AdminCliError("enroll: --ns must name at least one namespace", 1);
1581
+ if (namespaces.includes("*")) throw new AdminCliError("enroll: --ns does not accept the wildcard '*' — name the namespaces explicitly. A wildcard grant cannot produce a usable SUBSTRATE_BRIDGES entry, because there is no local alias for `*`, and a federation credential should never get wildcard access by default.", 1);
1582
+ const capabilities = capsCsv === void 0 ? ["read"] : splitCsv(capsCsv);
1583
+ if (capabilities.length === 0) throw new AdminCliError("enroll: --caps must name at least one capability", 1);
1584
+ const unknownCaps = capabilities.filter((c) => !KNOWN_CAPABILITIES.includes(c));
1585
+ if (unknownCaps.length > 0) throw new AdminCliError(`enroll: unknown --caps value '${unknownCaps.join("', '")}' — valid values are ${KNOWN_CAPABILITIES.join(", ")}. A misspelled capability mints a credential that authenticates but satisfies no capability check — diagnosable only after the fact via \`substrate federate check\`.`, 1);
1586
+ if (capabilities.includes("admin") && !allowAdmin) throw new AdminCliError("enroll: --caps admin requires --allow-admin — this credential is redeemable remotely by whoever holds the token, so minting an admin-scoped one needs to be deliberate, not a `--caps` typo away from `mutate`.", 1);
1587
+ let ttlMs;
1588
+ try {
1589
+ ttlMs = parseDuration(ttlRaw ?? "15m");
1590
+ } catch (err) {
1591
+ throw new AdminCliError(`enroll: ${err instanceof Error ? err.message : String(err)}`, 1);
1592
+ }
1593
+ return {
1594
+ origin: normalisedOrigin,
1595
+ namespaces,
1596
+ capabilities,
1597
+ ttlMs
1598
+ };
1599
+ }
1600
+ /**
1601
+ * The token comes from `SUBSTRATE_JOIN_TOKEN`, or from a positional, which the
1602
+ * caller warns about: argv is readable by every user on the box via `ps`.
1603
+ */
1604
+ function parseJoinArgs(argv, env = {}) {
1605
+ const rest = argv.slice(1);
1606
+ let token;
1607
+ let name;
1608
+ let keyOut;
1609
+ for (let i = 0; i < rest.length; i++) {
1610
+ const tok = rest[i];
1611
+ if (tok === void 0) continue;
1612
+ if (tok === "--name") {
1613
+ if (name !== void 0) throw new AdminCliError("join: --name specified more than once", 1);
1614
+ name = takeValue(rest, i, "join", "--name");
1615
+ i += 1;
1616
+ } else if (tok === "--key-out") {
1617
+ if (keyOut !== void 0) throw new AdminCliError("join: --key-out specified more than once", 1);
1618
+ keyOut = takeValue(rest, i, "join", "--key-out");
1619
+ i += 1;
1620
+ } else if (tok.startsWith("--")) throw new AdminCliError(`join: unknown flag ${tok}`, 1);
1621
+ else {
1622
+ if (token !== void 0) throw new AdminCliError(`join: unexpected positional arg '${tok}'`, 1);
1623
+ token = tok;
1624
+ }
1625
+ }
1626
+ const envToken = env.SUBSTRATE_JOIN_TOKEN;
1627
+ if (envToken !== void 0 && envToken.length > 0) {
1628
+ if (token !== void 0) throw new AdminCliError("join: token given both in SUBSTRATE_JOIN_TOKEN and on argv", 1);
1629
+ token = envToken;
1630
+ }
1631
+ if (token === void 0 || token.length === 0) throw new AdminCliError("join requires a token: set SUBSTRATE_JOIN_TOKEN", 1);
1632
+ return {
1633
+ token,
1634
+ name,
1635
+ keyOut
1636
+ };
1637
+ }
1638
+ function parseCheckArgs(argv) {
1639
+ const rest = argv.slice(1);
1640
+ let name;
1641
+ let envFile;
1642
+ for (let i = 0; i < rest.length; i++) {
1643
+ const tok = rest[i];
1644
+ if (tok === void 0) continue;
1645
+ if (tok === "--env-file") {
1646
+ if (envFile !== void 0) throw new AdminCliError("check: --env-file specified more than once", 1);
1647
+ envFile = takeValue(rest, i, "check", "--env-file");
1648
+ i += 1;
1649
+ } else if (tok.startsWith("--")) throw new AdminCliError(`check: unknown flag ${tok}`, 1);
1650
+ else {
1651
+ if (name !== void 0) throw new AdminCliError(`check: unexpected positional arg '${tok}'`, 1);
1652
+ name = tok;
1653
+ }
1654
+ }
1655
+ return {
1656
+ name,
1657
+ envFile
1658
+ };
1659
+ }
1660
+ async function runFederate(argv, env, out, errOut) {
1661
+ const verb = argv[0];
1662
+ if (verb === void 0 || verb === "--help" || verb === "-h") {
1663
+ (verb === void 0 ? errOut : out)(`${FEDERATE_USAGE}\n`);
1664
+ return verb === void 0 ? 1 : 0;
1665
+ }
1666
+ try {
1667
+ switch (verb) {
1668
+ case "enroll": {
1669
+ const args = parseEnrollArgs(argv);
1670
+ const result = await runEnroll(args, env);
1671
+ out(formatEnrollOutput(result));
1672
+ return 0;
1673
+ }
1674
+ case "join": {
1675
+ const args = parseJoinArgs(argv, env);
1676
+ if (env.SUBSTRATE_JOIN_TOKEN === void 0 || env.SUBSTRATE_JOIN_TOKEN.length === 0) errOut("warning: a token on the command line is visible in ps and shell history; pass it in SUBSTRATE_JOIN_TOKEN instead\n");
1677
+ const result = await runJoin(args);
1678
+ out(formatJoinOutput(result));
1679
+ return 0;
1680
+ }
1681
+ case "check": {
1682
+ const args = parseCheckArgs(argv);
1683
+ const effectiveEnv = args.envFile === void 0 ? env : {
1684
+ ...env,
1685
+ ...loadEnvFile(args.envFile)
1686
+ };
1687
+ const results = await runCheck(args.name, effectiveEnv);
1688
+ out(formatCheckOutput(results));
1689
+ return results.every((r) => r.ok) ? 0 : 1;
1690
+ }
1691
+ default:
1692
+ errOut(`substrate federate: unknown verb '${verb}'\n\n${FEDERATE_USAGE}\n`);
1693
+ return 1;
1694
+ }
1695
+ } catch (err) {
1696
+ const exitCode = err instanceof AdminCliError || err instanceof JoinTokenError ? err.exitCode : 1;
1697
+ errOut(`${err instanceof Error ? err.message : String(err)}\n`);
1698
+ return exitCode;
1699
+ }
1700
+ }
1701
+
1702
+ //#endregion
1703
+ //#region src/cli/init/sizing.ts
1704
+ /** What an unanswered question assumes: a small personal store. */
1705
+ const DEFAULT_SIZING = {
1706
+ rowsPerDay: 1e3,
1707
+ retentionDays: 365,
1708
+ readTargetMs: 250,
1709
+ writeHeavy: false
1710
+ };
1711
+ /** The profile for the expected row count; `writeHeavy` never changes the name. */
1712
+ function profileFromAnswers(a) {
1713
+ const rows = a.rowsPerDay * a.retentionDays;
1714
+ if (rows >= 5e7 || a.readTargetMs <= 50 && rows >= 5e6) return "scale";
1715
+ if (rows >= 1e6) return "growth";
1716
+ return "personal";
1717
+ }
1718
+ /** A sizing flag or answer: a positive finite number. */
1719
+ function parsePositive(flag, value) {
1720
+ const n = Number(value);
1721
+ if (value.trim() === "" || !Number.isFinite(n) || n <= 0) throw new Error(`--${flag} must be a positive number, got: ${value}`);
1722
+ return n;
1723
+ }
1724
+
1725
+ //#endregion
1726
+ //#region src/cli/init/config.ts
1727
+ const EMBEDDER_MODES = [
1728
+ "bge-base",
1729
+ "minilm",
1730
+ "ollama",
1731
+ "none"
1732
+ ];
1733
+ const KNOWN_FLAGS = /* @__PURE__ */ new Set([
1734
+ "yes",
1735
+ "force",
1736
+ "plugins",
1737
+ "store",
1738
+ "port",
1739
+ "pg-port",
1740
+ "embedder",
1741
+ "substrate-url",
1742
+ "tls",
1743
+ "tls-cert-path",
1744
+ "tls-key-path",
1745
+ "rows-per-day",
1746
+ "retention-days",
1747
+ "read-target-ms",
1748
+ "write-heavy",
1749
+ "profile"
1750
+ ]);
1751
+ function parsePort(flag, value) {
1752
+ const n = Number(value);
1753
+ if (!/^\d+$/.test(value) || n < 1 || n > 65535) throw new Error(`--${flag} must be a positive integer port (1-65535), got: ${value}`);
1754
+ return n;
1755
+ }
1756
+ function parseArgs(argv) {
1757
+ const config = {
1758
+ targetDir: void 0,
1759
+ store: void 0,
1760
+ port: void 0,
1761
+ pgPort: void 0,
1762
+ plugins: void 0,
1763
+ embedder: void 0,
1764
+ substrateUrl: void 0,
1765
+ tls: false,
1766
+ tlsCertPath: void 0,
1767
+ tlsKeyPath: void 0,
1768
+ rowsPerDay: void 0,
1769
+ retentionDays: void 0,
1770
+ readTargetMs: void 0,
1771
+ writeHeavy: false,
1772
+ profile: void 0,
1773
+ yes: false,
1774
+ force: false
1775
+ };
1776
+ for (const arg of argv) {
1777
+ if (!arg.startsWith("--")) {
1778
+ if (config.targetDir === void 0) config.targetDir = arg;
1779
+ continue;
1780
+ }
1781
+ const eqIndex = arg.indexOf("=");
1782
+ const flag = eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex);
1783
+ const value = eqIndex === -1 ? "" : arg.slice(eqIndex + 1);
1784
+ if (!KNOWN_FLAGS.has(flag)) throw new Error(`unknown flag --${flag}`);
1785
+ switch (flag) {
1786
+ case "yes":
1787
+ config.yes = true;
1788
+ break;
1789
+ case "force":
1790
+ config.force = true;
1791
+ break;
1792
+ case "plugins":
1793
+ config.plugins = value.split(",").map((p) => p.trim()).filter(Boolean);
1794
+ break;
1795
+ case "store":
1796
+ if (value !== "memory" && value !== "postgres") throw new Error(`--store must be memory|postgres, got: ${value}`);
1797
+ config.store = value;
1798
+ break;
1799
+ case "port":
1800
+ config.port = parsePort("port", value);
1801
+ break;
1802
+ case "pg-port":
1803
+ config.pgPort = parsePort("pg-port", value);
1804
+ break;
1805
+ case "tls":
1806
+ config.tls = true;
1807
+ break;
1808
+ case "tls-cert-path":
1809
+ config.tlsCertPath = value;
1810
+ break;
1811
+ case "tls-key-path":
1812
+ config.tlsKeyPath = value;
1813
+ break;
1814
+ case "embedder":
1815
+ if (!isEmbedderMode(value)) throw new Error(`--embedder must be ${EMBEDDER_MODES.join("|")}, got: ${value}`);
1816
+ config.embedder = value;
1817
+ break;
1818
+ case "rows-per-day":
1819
+ config.rowsPerDay = parsePositive(flag, value);
1820
+ break;
1821
+ case "retention-days":
1822
+ config.retentionDays = parsePositive(flag, value);
1823
+ break;
1824
+ case "read-target-ms":
1825
+ config.readTargetMs = parsePositive(flag, value);
1826
+ break;
1827
+ case "write-heavy":
1828
+ if (value !== "" && value !== "true" && value !== "false") throw new Error(`--write-heavy must be true|false, got: ${value}`);
1829
+ config.writeHeavy = value !== "false";
1830
+ break;
1831
+ case "profile":
1832
+ if (!isStoreProfileName(value)) throw new Error(`--profile must be personal|growth|scale, got: ${value}`);
1833
+ config.profile = value;
1834
+ break;
1835
+ case "substrate-url": config.substrateUrl = value;
1836
+ }
1837
+ }
1838
+ if (config.tls && (config.tlsCertPath === void 0 || config.tlsKeyPath === void 0)) throw new Error("--tls requires both --tls-cert-path and --tls-key-path");
1839
+ return config;
1840
+ }
1841
+ function isEmbedderMode(value) {
1842
+ return EMBEDDER_MODES.includes(value);
1843
+ }
1844
+
1845
+ //#endregion
1846
+ //#region src/cli/init/plugins.ts
1847
+ /**
1848
+ * The cortext line publishes on its own versions and declares substrate as a
1849
+ * peer range. Raise the floor when a cortext release drops support for the
1850
+ * substrate major this binary is on. The floor names a prerelease because a
1851
+ * caret range admits no prerelease of a version it does not itself name.
1852
+ */
1853
+ const CORTEXT_RANGE = "^1.0.0-alpha.0";
1854
+ const KNOWN_PLUGINS = [
1855
+ {
1856
+ name: "cortext",
1857
+ npmName: "@mnmal-ai/cortext",
1858
+ range: CORTEXT_RANGE,
1859
+ description: "Agent coordination context store (Todos, Decisions, SessionLogs, AgentRules, Memory)."
1860
+ },
1861
+ {
1862
+ name: "substrate-nl",
1863
+ npmName: "@mnmal-ai/substrate-nl",
1864
+ description: "Natural-language questions answered as frames."
1865
+ },
1866
+ {
1867
+ name: "substrate-sentinel",
1868
+ npmName: "@mnmal-ai/substrate-sentinel",
1869
+ description: "Coordinator registry for dynamic bridge discovery."
1870
+ }
1871
+ ];
1872
+ function defaultPluginsForPersona(persona) {
1873
+ switch (persona) {
1874
+ case "agent-context": return ["cortext"];
1875
+ case "minimal": return [];
1876
+ case "full": return KNOWN_PLUGINS.map((p) => p.name);
1877
+ }
1878
+ }
1879
+ function pluginNpmName(name) {
1880
+ const known = KNOWN_PLUGINS.find((p) => p.name === name);
1881
+ if (known !== void 0) return known.npmName;
1882
+ return name.startsWith("@") ? name : `@mnmal-ai/${name}`;
1883
+ }
1884
+ function pluginRange(name, substrateRange) {
1885
+ return KNOWN_PLUGINS.find((p) => p.name === name)?.range ?? substrateRange;
1886
+ }
1887
+
1888
+ //#endregion
1889
+ //#region src/cli/init/templates.ts
1890
+ function envBinaryTemplate(ctx) {
1891
+ const lines = [
1892
+ "# Substrate runtime — environment config.",
1893
+ "# Generated by `substrate init`. Edit values, then `substrate serve` (or wrap in systemd).",
1894
+ ""
1895
+ ];
1896
+ if (ctx.store === "postgres") lines.push(`SUBSTRATE_DATABASE_URL=postgres://substrate:${ctx.pgPassword}@127.0.0.1:${ctx.pgPort}/${ctx.dbName}`, "# Set to the database volume mount path when the database runs on this host, to check free disk before index builds.", "SUBSTRATE_INDEX_DISK_PATH=off");
1897
+ else lines.push("SUBSTRATE_DATABASE_URL=memory");
1898
+ lines.push("");
1899
+ lines.push("# Sizing profile: how sensitive the index advisor is. Seeds the store once; change it live afterwards.");
1900
+ lines.push(`SUBSTRATE_STORE_PROFILE=${ctx.storeProfile}`);
1901
+ if (ctx.writeHeavy) {
1902
+ lines.push("# Write-heavy store: the advisor flags unused indexes at half the write rate.");
1903
+ lines.push("SUBSTRATE_STORE_WRITE_HEAVY=1");
1904
+ }
1905
+ lines.push("");
1906
+ lines.push("# Plugin install root — manifest-driven loader scans node_modules under this dir.");
1907
+ lines.push("SUBSTRATE_PLUGIN_DIR=.");
1908
+ lines.push("");
1909
+ lines.push(`PORT=${ctx.port}`);
1910
+ lines.push("");
1911
+ lines.push("# Who this deployment writes as while auth is off. Every row it writes");
1912
+ lines.push("# carries this in createdBy. Turn auth on and callers are attributed");
1913
+ lines.push("# individually instead, at which point this is ignored.");
1914
+ lines.push("SUBSTRATE_SYSTEM_ACTOR=local-dev");
1915
+ lines.push("");
1916
+ if (ctx.tls) {
1917
+ lines.push("# TLS termination — paths to existing cert + key on disk.");
1918
+ lines.push(`SUBSTRATE_TLS_CERT_PATH=${ctx.tlsCertPath ?? ""}`);
1919
+ lines.push(`SUBSTRATE_TLS_KEY_PATH=${ctx.tlsKeyPath ?? ""}`);
1920
+ lines.push("");
1921
+ }
1922
+ while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
1923
+ return `${lines.join("\n")}\n`;
1924
+ }
1925
+ /**
1926
+ * The in-process models, run by fastembed. Each name is a key of
1927
+ * `OnnxEmbedder`'s model map, and the dimension is the model's own.
1928
+ */
1929
+ const ONNX_MODELS = {
1930
+ minilm: {
1931
+ model: "all-MiniLM-L6-v2",
1932
+ dimension: 384
1933
+ },
1934
+ "bge-base": {
1935
+ model: "bge-base-en-v1.5",
1936
+ dimension: 768
1937
+ }
1938
+ };
1939
+ /** The onnx embedder's backend. Undeclared by substrate-embedder, so the runtime installs it. */
1940
+ const FASTEMBED_RANGE = "^2.1.1";
1941
+ /**
1942
+ * `<runtime>/substrate-recall.config.json`, or null for `--embedder=none`. The
1943
+ * recall plugin reads its embedder from this file (merged by the manifest
1944
+ * loader), not from env.
1945
+ *
1946
+ * `cacheDir` is absolute because fastembed's own default is `local_cache`
1947
+ * under the working directory, which moves with whoever starts the server.
1948
+ */
1949
+ function recallConfigTemplate(embedder, runtimeDir) {
1950
+ if (embedder === "none") return null;
1951
+ const config = embedder === "ollama" ? { embedder: {
1952
+ kind: "ollama",
1953
+ baseUrl: "http://localhost:11434",
1954
+ model: "hf.co/CompendiumLabs/bge-base-en-v1.5-gguf:F16",
1955
+ dimension: 768
1956
+ } } : { embedder: {
1957
+ kind: "onnx",
1958
+ ...ONNX_MODELS[embedder],
1959
+ cacheDir: join(runtimeDir, "models")
1960
+ } };
1961
+ return `${JSON.stringify(config, null, 2)}\n`;
1962
+ }
1963
+ function envDockerTemplate(ctx) {
1964
+ if (ctx.store === "memory") return "";
1965
+ return [
1966
+ "# Postgres compose config — consumed by docker-compose.yml.",
1967
+ `POSTGRES_PASSWORD=${ctx.pgPassword}`,
1968
+ "POSTGRES_USER=substrate",
1969
+ `SUBSTRATE_DATABASE_NAME=${ctx.dbName}`,
1970
+ ""
1971
+ ].join("\n");
1972
+ }
1973
+ function dockerComposeTemplate(ctx) {
1974
+ if (ctx.store === "memory") return "";
1975
+ return `# Generated by \`substrate init\`. Postgres + backup sidecar.
1976
+ name: ${ctx.composeName}
1977
+
1978
+ services:
1979
+ postgres:
1980
+ image: pgvector/pgvector:pg18
1981
+ restart: unless-stopped
1982
+ environment:
1983
+ POSTGRES_USER: \${POSTGRES_USER:-substrate}
1984
+ POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env.docker, so pass --env-file .env.docker}
1985
+ POSTGRES_DB: \${SUBSTRATE_DATABASE_NAME:-${ctx.dbName}}
1986
+ ports:
1987
+ - "127.0.0.1:${ctx.pgPort}:5432"
1988
+ volumes:
1989
+ - ./data/pg:/var/lib/postgresql
1990
+ - ./postgres-init:/docker-entrypoint-initdb.d:ro
1991
+ healthcheck:
1992
+ test: ["CMD-SHELL", "pg_isready -U \${POSTGRES_USER:-substrate} -d \${SUBSTRATE_DATABASE_NAME:-${ctx.dbName}}"]
1993
+ interval: 10s
1994
+ timeout: 5s
1995
+ retries: 6
1996
+ start_period: 30s
1997
+
1998
+ # Backup sidecar — COMMENTED OUT: no backups run until you opt
1999
+ # in. pg_dump on a loop (every 24h, retain 14 days — tunable via
2000
+ # BACKUP_INTERVAL_HOURS / BACKUP_RETENTION_DAYS). To enable:
2001
+ # 1. mkdir backups && touch backups/.substrate-backup-target (the marker the
2002
+ # loop requires — without it the loop refuses to write),
2003
+ # 2. uncomment the block below and run docker compose --env-file .env.docker up -d again.
2004
+ # Each dump is a gzipped plain SQL file: restore with gunzip -c <file> | psql.
2005
+ #
2006
+ # postgres-backup:
2007
+ # image: pgvector/pgvector:pg18
2008
+ # restart: unless-stopped
2009
+ # depends_on:
2010
+ # postgres:
2011
+ # condition: service_healthy
2012
+ # user: "\${HOST_UID:-1000}:\${HOST_GID:-1000}"
2013
+ # environment:
2014
+ # PGHOST: postgres
2015
+ # PGUSER: \${POSTGRES_USER:-substrate}
2016
+ # PGPASSWORD: \${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env.docker}
2017
+ # PGDATABASE: \${SUBSTRATE_DATABASE_NAME:-${ctx.dbName}}
2018
+ # BACKUP_INTERVAL_HOURS: \${BACKUP_INTERVAL_HOURS:-24}
2019
+ # BACKUP_RETENTION_DAYS: \${BACKUP_RETENTION_DAYS:-14}
2020
+ # volumes:
2021
+ # - ./backups:/backups
2022
+ # entrypoint: ["/bin/sh", "-c"]
2023
+ # command:
2024
+ # - |
2025
+ # [ -f /backups/.substrate-backup-target ] || { echo "backups/.substrate-backup-target missing, refusing to write" >&2; exit 1; }
2026
+ # while :; do
2027
+ # out=/backups/$$PGDATABASE-$$(date -u +%Y%m%dT%H%M%SZ).sql.gz
2028
+ # if pg_dump -Z 6 -f "$$out.partial"; then mv "$$out.partial" "$$out"; echo "backup ok $$out"
2029
+ # else rm -f "$$out.partial"; echo "backup FAILED" >&2; fi
2030
+ # find /backups -maxdepth 1 -name '*.sql.gz' -mtime +$$BACKUP_RETENTION_DAYS -delete
2031
+ # sleep $$((BACKUP_INTERVAL_HOURS * 3600))
2032
+ # done
2033
+ `;
2034
+ }
2035
+ function runtimePackageJsonTemplate(ctx) {
2036
+ const range = ctx.substrateVersion.includes("-") ? `^${ctx.substrateVersion}` : `^${ctx.substrateVersion.split(".")[0]}.0.0`;
2037
+ const deps = { "@mnmal-ai/substrate": range };
2038
+ for (const p of ctx.plugins) deps[pluginNpmName(p)] = pluginRange(p, range);
2039
+ if (ctx.embedder === "minilm" || ctx.embedder === "bge-base") deps.fastembed = FASTEMBED_RANGE;
2040
+ return `${JSON.stringify({
2041
+ name: "substrate-runtime",
2042
+ private: true,
2043
+ dependencies: deps
2044
+ }, null, 2)}\n`;
2045
+ }
2046
+ /**
2047
+ * pnpm 11 fails the install outright on a dependency build script nobody has
2048
+ * approved. These two ship prebuilt binaries and their scripts only fetch
2049
+ * extras, but an unanswered script is an error, not a skip.
2050
+ */
2051
+ function pnpmWorkspaceTemplate() {
2052
+ return [
2053
+ "packages: []",
2054
+ "allowBuilds:",
2055
+ " msgpackr-extract: true",
2056
+ " onnxruntime-node: true",
2057
+ ""
2058
+ ].join("\n");
2059
+ }
2060
+ function pgInitSqlTemplate(ctx) {
2061
+ if (ctx.store === "memory") return "";
2062
+ return `-- Idempotent create of the application database.
2063
+ SELECT 'CREATE DATABASE ${ctx.dbName} OWNER substrate'
2064
+ WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '${ctx.dbName}')
2065
+ \\gexec
2066
+ `;
2067
+ }
2068
+ function readmeTemplate(ctx) {
2069
+ const lines = [
2070
+ "# Substrate runtime",
2071
+ "",
2072
+ "Generated by `substrate init`.",
2073
+ "",
2074
+ "## Quickstart",
2075
+ ""
2076
+ ];
2077
+ if (ctx.store === "postgres") {
2078
+ lines.push("```bash");
2079
+ lines.push("# 1. Start postgres.");
2080
+ lines.push("docker compose --env-file .env.docker up -d");
2081
+ lines.push("");
2082
+ lines.push("# 2. Install substrate binary + plugins.");
2083
+ lines.push("pnpm install");
2084
+ lines.push("");
2085
+ lines.push("# 3. Run substrate.");
2086
+ lines.push("set -a && source .env && set +a && ./node_modules/.bin/substrate serve");
2087
+ lines.push("```");
2088
+ } else {
2089
+ lines.push("```bash");
2090
+ lines.push("# Memory mode — data vanishes on restart.");
2091
+ lines.push("pnpm install");
2092
+ lines.push("set -a && source .env && set +a && ./node_modules/.bin/substrate serve");
2093
+ lines.push("```");
2094
+ }
2095
+ if (ctx.store === "postgres") {
2096
+ lines.push("");
2097
+ lines.push("## Backups");
2098
+ lines.push("");
2099
+ lines.push("None are configured. The scaffolded `docker-compose.yml` runs postgres only — the `postgres-backup` sidecar is present but commented out, so this instance has no backup story until you opt in. Uncomment it per the comments in the compose file.");
2100
+ }
2101
+ if (ctx.embedder !== "none") {
2102
+ lines.push("");
2103
+ lines.push("## Semantic recall");
2104
+ lines.push("");
2105
+ lines.push(...recallReadmeLines(ctx.embedder));
2106
+ }
2107
+ lines.push("");
2108
+ lines.push("## Reaching this instance");
2109
+ lines.push("");
2110
+ const curlFlags = ctx.substrateUrl.startsWith("https") ? "-sfk" : "-sf";
2111
+ lines.push(`Health check: \`curl ${curlFlags} ${ctx.substrateUrl}/health\``);
2112
+ lines.push("");
2113
+ lines.push(`Clients (MCP/CLI — e.g. \`.mcp.json\`) connect via \`SUBSTRATE_URL=${ctx.substrateUrl}\`. That's a **client** setting: the server reads \`PORT\`${ctx.tls ? " + the TLS paths" : ""}, not \`SUBSTRATE_URL\`.`);
2114
+ return `${lines.join("\n")}\n`;
2115
+ }
2116
+ function recallReadmeLines(embedder) {
2117
+ const lines = embedder === "ollama" ? ["`substrate-recall.config.json` points at Ollama on `localhost:11434` with bge-base-en-v1.5. Pull the model first: `ollama pull hf.co/CompendiumLabs/bge-base-en-v1.5-gguf:F16`."] : [`\`substrate-recall.config.json\` runs \`${ONNX_MODELS[embedder].model}\` in-process through \`fastembed\`, which \`pnpm install\` adds (about 540MB, most of it ONNX Runtime). The first write downloads the model into \`models/\`.`];
2118
+ lines.push("", "Recall also ranks by keyword, so a small model loses little. Changing model later means emptying the stored vectors and embedding every row again, through the admin route `POST /substrate/v1/embed/reindex`.");
2119
+ return lines;
2120
+ }
2121
+
2122
+ //#endregion
2123
+ //#region src/cli/init/main.ts
2124
+ function normalizeComposeName(targetDir) {
2125
+ return `substrate-${basename(targetDir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "runtime"}`;
2126
+ }
2127
+ /** Both env files carry the postgres password. chmod too: `mode` is ignored when --force overwrites. */
2128
+ function writeSecret(path, content) {
2129
+ writeFileSync(path, content, { mode: 384 });
2130
+ chmodSync(path, 384);
2131
+ }
2132
+ async function runInit(argv) {
2133
+ let config;
2134
+ try {
2135
+ config = parseArgs(argv);
2136
+ } catch (err) {
2137
+ process.stderr.write(`substrate init: ${err.message}\n`);
2138
+ return 1;
2139
+ }
2140
+ if (!config.yes) try {
2141
+ const { runRepl } = await import("./repl-DqfHelK7.js");
2142
+ config = await runRepl(config);
2143
+ } catch (err) {
2144
+ if (err.message?.includes("User force closed")) return 130;
2145
+ throw err;
2146
+ }
2147
+ if (config.targetDir === void 0) {
2148
+ process.stderr.write("substrate init: --yes requires a target directory positional arg\n");
2149
+ return 1;
2150
+ }
2151
+ const target = resolve(config.targetDir);
2152
+ if (existsSync(target) && !config.force) {
2153
+ process.stderr.write(`substrate init: ${target} already exists — pass --force to scaffold anyway\n`);
2154
+ return 1;
2155
+ }
2156
+ const pgData = join(target, "data", "pg");
2157
+ if (existsSync(pgData) && readdirSync(pgData).length > 0) {
2158
+ process.stderr.write(`substrate init: ${pgData} already holds a postgres cluster — refusing to overwrite its credentials. Remove it first to start fresh.\n`);
2159
+ return 1;
2160
+ }
2161
+ mkdirSync(target, { recursive: true });
2162
+ const substrateVersion = typeof version === "string" && version.length > 0 ? version : "0.0.0";
2163
+ const ctx = {
2164
+ store: config.store ?? "postgres",
2165
+ port: config.port ?? 3100,
2166
+ pgPort: config.pgPort ?? 5433,
2167
+ plugins: [...config.plugins ?? []],
2168
+ embedder: config.embedder ?? "bge-base",
2169
+ substrateUrl: config.substrateUrl ?? `${config.tls ? "https" : "http"}://localhost:${config.port ?? 3100}`,
2170
+ tls: config.tls,
2171
+ tlsCertPath: config.tlsCertPath,
2172
+ tlsKeyPath: config.tlsKeyPath,
2173
+ pgPassword: randomBytes(32).toString("hex"),
2174
+ dbName: "substrate_prod",
2175
+ composeName: normalizeComposeName(target),
2176
+ substrateVersion,
2177
+ storeProfile: config.profile ?? profileFromAnswers({
2178
+ rowsPerDay: config.rowsPerDay ?? DEFAULT_SIZING.rowsPerDay,
2179
+ retentionDays: config.retentionDays ?? DEFAULT_SIZING.retentionDays,
2180
+ readTargetMs: config.readTargetMs ?? DEFAULT_SIZING.readTargetMs,
2181
+ writeHeavy: config.writeHeavy
2182
+ }),
2183
+ writeHeavy: config.writeHeavy
2184
+ };
2185
+ writeSecret(join(target, ".env"), envBinaryTemplate(ctx));
2186
+ writeFileSync(join(target, "README.md"), readmeTemplate(ctx));
2187
+ writeFileSync(join(target, "pnpm-workspace.yaml"), pnpmWorkspaceTemplate());
2188
+ writeFileSync(join(target, "package.json"), runtimePackageJsonTemplate(ctx));
2189
+ const recallConfig = recallConfigTemplate(ctx.embedder, target);
2190
+ if (recallConfig !== null) writeFileSync(join(target, "substrate-recall.config.json"), recallConfig);
2191
+ if (ctx.store === "postgres") {
2192
+ writeSecret(join(target, ".env.docker"), envDockerTemplate(ctx));
2193
+ writeFileSync(join(target, "docker-compose.yml"), dockerComposeTemplate(ctx));
2194
+ mkdirSync(join(target, "postgres-init"), { recursive: true });
2195
+ writeFileSync(join(target, "postgres-init", "01-create-database.sql"), pgInitSqlTemplate(ctx));
2196
+ mkdirSync(join(target, "data", "pg"), { recursive: true });
2197
+ }
2198
+ process.stdout.write(`substrate init: wrote runtime to ${target}\n`);
2199
+ if (ctx.store === "postgres") {
2200
+ process.stdout.write("\nNext steps:\n");
2201
+ process.stdout.write(` cd ${config.targetDir}\n`);
2202
+ process.stdout.write(" docker compose --env-file .env.docker up -d\n");
2203
+ process.stdout.write(" pnpm install\n");
2204
+ process.stdout.write(" set -a && source .env && set +a && ./node_modules/.bin/substrate serve\n");
2205
+ process.stdout.write(" No backups are configured — see README \"Backups\" to opt in.\n");
2206
+ } else {
2207
+ process.stdout.write("\nNext steps:\n");
2208
+ process.stdout.write(` cd ${config.targetDir}\n`);
2209
+ process.stdout.write(" pnpm install\n");
2210
+ process.stdout.write(" set -a && source .env && set +a && ./node_modules/.bin/substrate serve\n");
2211
+ }
2212
+ return 0;
2213
+ }
2214
+
2215
+ //#endregion
2216
+ //#region src/cli/normalise-vocab/main.ts
2217
+ /**
2218
+ * `substrate normalise-vocab <namespace> <Type> <field> [--apply] [--reject a,b] [--json]`
2219
+ *
2220
+ * Rewrites stored aliases of a governed vocabulary field to their canonical
2221
+ * value, through the admin route `POST /substrate/v1/_system/normalise-vocab`. Dry
2222
+ * run unless `--apply`. Values no alias explains must be listed in `--reject`
2223
+ * (left as they are) before an apply goes ahead. Row metadata is preserved.
2224
+ *
2225
+ * Env: SUBSTRATE_URL, SUBSTRATE_ADMIN_TOKEN (admin Bearer token). Exit 0 on success,
2226
+ * 1 when the server refuses unmapped values, 2 on usage or transport errors.
2227
+ */
2228
+ async function runNormaliseVocab(argv, options = {}) {
2229
+ const write = options.write ?? ((text) => process.stdout.write(text));
2230
+ const [namespace, type, field] = argv.filter((a, i) => !a.startsWith("--") && argv[i - 1] !== "--reject");
2231
+ if (namespace === void 0 || type === void 0 || field === void 0) {
2232
+ write("usage: substrate normalise-vocab <namespace> <Type> <field> [--apply] [--reject a,b] [--json]\n");
2233
+ return 2;
2234
+ }
2235
+ const baseUrl = trimTrailingSlashes(options.baseUrl ?? process.env.SUBSTRATE_URL ?? "");
2236
+ if (baseUrl === "") {
2237
+ write("SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)\n");
2238
+ return 2;
2239
+ }
2240
+ const token = options.token ?? process.env.SUBSTRATE_ADMIN_TOKEN;
2241
+ const rejectAt = argv.indexOf("--reject");
2242
+ const reject = rejectAt >= 0 ? (argv[rejectAt + 1] ?? "").split(",").filter((v) => v.length > 0) : [];
2243
+ const apply = argv.includes("--apply");
2244
+ if (token !== void 0 && token.length > 0) try {
2245
+ tokenAudience(baseUrl);
2246
+ } catch (err) {
2247
+ write(`${err instanceof Error ? err.message : String(err)}\n`);
2248
+ return 2;
2249
+ }
2250
+ let res;
2251
+ try {
2252
+ res = await noRedirectFetch(options.fetchImpl)(`${baseUrl}/substrate/v1/_system/normalise-vocab`, {
2253
+ method: "POST",
2254
+ headers: {
2255
+ "content-type": "application/json",
2256
+ ...token !== void 0 && token.length > 0 ? { authorization: `Bearer ${token}` } : {}
2257
+ },
2258
+ body: JSON.stringify({
2259
+ namespace,
2260
+ type,
2261
+ field,
2262
+ apply,
2263
+ reject
2264
+ })
2265
+ });
2266
+ } catch (err) {
2267
+ write(`request failed: ${err instanceof Error ? err.message : String(err)}\n`);
2268
+ return 2;
2269
+ }
2270
+ const body = await res.json().catch(() => ({}));
2271
+ if (argv.includes("--json")) write(`${JSON.stringify(body, null, 2)}\n`);
2272
+ if (res.status === 409) {
2273
+ if (!argv.includes("--json")) {
2274
+ write(`refused: ${body.message ?? "unmapped values"}\n`);
2275
+ for (const u of body.unmapped ?? []) write(` ${u.value} ${u.count}\n`);
2276
+ }
2277
+ return 1;
2278
+ }
2279
+ if (!res.ok) {
2280
+ if (!argv.includes("--json")) write(`HTTP ${res.status}: ${body.code ?? ""} ${body.message ?? ""}\n`);
2281
+ return 2;
2282
+ }
2283
+ if (argv.includes("--json")) return 0;
2284
+ write(`${namespace}/${type}.${field}: ${body.scanned ?? "?"} rows scanned${body.truncated ? " (TRUNCATED)" : ""}\n`);
2285
+ const rows = body.applied ? body.migrated ?? [] : body.plan ?? [];
2286
+ write(body.applied ? "rewritten:\n" : "would rewrite (dry run; pass --apply):\n");
2287
+ for (const p of rows) write(` ${p.from} -> ${p.to} ${p.count}\n`);
2288
+ if (rows.length === 0) write(" (nothing)\n");
2289
+ const left = body.applied ? body.stranded ?? [] : body.unmapped ?? [];
2290
+ if (left.length > 0) {
2291
+ write(body.applied ? "left as they are (rejected):\n" : "no alias explains (add one, widen the vocabulary, or --reject):\n");
2292
+ for (const u of left) write(` ${u.value} ${u.count}\n`);
2293
+ }
2294
+ return 0;
2295
+ }
2296
+
2297
+ //#endregion
2298
+ //#region src/cli/run/main.ts
2299
+ const USAGE = "usage: substrate run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]\n";
2300
+ /**
2301
+ * Runs a script's default export against a signed, guarded client and prints
2302
+ * one JSON report: the script's return value, every mutation, warnings, stats.
2303
+ */
2304
+ async function runRun(argv, options = {}) {
2305
+ const write = options.write ?? ((s) => process.stdout.write(s));
2306
+ let script;
2307
+ let mode = "read";
2308
+ let maxWrites = 50;
2309
+ let out;
2310
+ let args = {};
2311
+ for (let i = 0; i < argv.length; i++) {
2312
+ const a = argv[i];
2313
+ if (a === "--dry-run" || a === "--write") {
2314
+ const next = a === "--write" ? "write" : "dry-run";
2315
+ if (mode !== "read" && mode !== next) {
2316
+ write("substrate run: --dry-run and --write are exclusive\n");
2317
+ return 2;
2318
+ }
2319
+ mode = next;
2320
+ } else if (a === "--max-writes" || a === "--out" || a === "--args") {
2321
+ const v = argv[++i];
2322
+ if (v === void 0 || v.startsWith("--")) {
2323
+ write(USAGE);
2324
+ return 2;
2325
+ }
2326
+ if (a === "--out") out = v;
2327
+ else if (a === "--args") {
2328
+ let parsed;
2329
+ try {
2330
+ parsed = JSON.parse(v);
2331
+ } catch {
2332
+ parsed = void 0;
2333
+ }
2334
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
2335
+ write("substrate run: --args takes a JSON object, e.g. '{\"project\":\"substrate\"}'\n");
2336
+ return 2;
2337
+ }
2338
+ args = parsed;
2339
+ } else {
2340
+ maxWrites = Number(v);
2341
+ if (!Number.isInteger(maxWrites) || maxWrites < 0) {
2342
+ write("substrate run: --max-writes takes a non-negative integer\n");
2343
+ return 2;
2344
+ }
2345
+ }
2346
+ } else if (script === void 0 && !a.startsWith("--")) script = a;
2347
+ else {
2348
+ write(USAGE);
2349
+ return 2;
2350
+ }
2351
+ }
2352
+ if (script === void 0) {
2353
+ write(USAGE);
2354
+ return 2;
2355
+ }
2356
+ let entry;
2357
+ try {
2358
+ entry = (await import(pathToFileURL(resolve(script)).href)).default;
2359
+ } catch (err) {
2360
+ write(`substrate run: cannot load ${script}: ${messageOf(err)}\n`);
2361
+ return 2;
2362
+ }
2363
+ if (typeof entry !== "function") {
2364
+ write(`substrate run: ${script} must default-export a function (s) => result\n`);
2365
+ return 2;
2366
+ }
2367
+ let client;
2368
+ let kid;
2369
+ try {
2370
+ ({client, kid} = createClientFromEnv({
2371
+ ...options.env !== void 0 ? { env: options.env } : {},
2372
+ ...options.fetchImpl !== void 0 ? { fetch: options.fetchImpl } : {}
2373
+ }));
2374
+ } catch (err) {
2375
+ write(`substrate run: agent identity: ${messageOf(err)}\n`);
2376
+ return 2;
2377
+ }
2378
+ const report = await runScript(entry, {
2379
+ client,
2380
+ kid,
2381
+ mode,
2382
+ args,
2383
+ maxWrites
2384
+ });
2385
+ await client.close();
2386
+ const json = `${JSON.stringify(report, null, 2)}\n`;
2387
+ if (out !== void 0) {
2388
+ writeFileSync(out, json);
2389
+ write(`${report.ok ? "ok" : `failed: ${report.error}`} · ${report.mutations.length} mutation(s) · ${report.warnings.length} warning(s) · report in ${out}\n`);
2390
+ } else write(json);
2391
+ return report.ok ? 0 : 1;
2392
+ }
2393
+ function messageOf(err) {
2394
+ return err instanceof Error ? err.message : String(err);
2395
+ }
2396
+
2397
+ //#endregion
2398
+ //#region src/mcp/agent-jwt.ts
2399
+ /**
2400
+ * Optional agent-identity JWT provider for the MCP client. When
2401
+ * SUBSTRATE_AGENT_KEY_PATH (path to an Ed25519 private PEM) + SUBSTRATE_AGENT_KEY_ID are
2402
+ * set, returns a cached short-TTL EdDSA JWT (refreshed before expiry) that the
2403
+ * stack verifies in attribute mode → createdBy:{kind:'agent', id:<kid>}.
2404
+ * Returns null when neither is set (the MCP client then sends no Authorization);
2405
+ * setting only one throws.
2406
+ *
2407
+ * Fail-loud by design: a SET-but-missing/malformed SUBSTRATE_AGENT_KEY_PATH
2408
+ * throws at provider construction, crashing MCP startup — misconfiguration
2409
+ * must not silently degrade to anonymous writes.
2410
+ */
2411
+ /**
2412
+ * Returns a provider that yields `Bearer <jwt>` (the full Authorization header
2413
+ * value) when SUBSTRATE_AGENT_KEY_PATH + SUBSTRATE_AGENT_KEY_ID are set, or null when
2414
+ * unconfigured so callers can skip the header entirely.
2415
+ */
2416
+ function makeAgentJwtProvider(env, audience) {
2417
+ const keyPath = env.SUBSTRATE_AGENT_KEY_PATH;
2418
+ const kid = env.SUBSTRATE_AGENT_KEY_ID;
2419
+ const hasPath = keyPath !== void 0 && keyPath !== "";
2420
+ const hasKid = kid !== void 0 && kid !== "";
2421
+ if (!hasPath && !hasKid) return () => null;
2422
+ if (!hasPath || !hasKid) throw new Error(`SUBSTRATE_AGENT_KEY_PATH and SUBSTRATE_AGENT_KEY_ID must be set together; only ${hasPath ? "SUBSTRATE_AGENT_KEY_PATH" : "SUBSTRATE_AGENT_KEY_ID"} is set`);
2423
+ const provider = makeAuthorizationProvider({
2424
+ keyPath,
2425
+ kid
2426
+ }, {
2427
+ capabilities: resolveAgentCapabilities(env),
2428
+ ...audience !== void 0 ? { audience } : {}
2429
+ });
2430
+ return () => provider();
2431
+ }
2432
+
2433
+ //#endregion
2434
+ //#region src/mcp/schema-overview.ts
2435
+ const NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
2436
+ const ENUM_VALUE = /^[A-Za-z0-9_./-]{1,40}$/;
2437
+ const MAX_ENUM_VALUES = 20;
2438
+ const MAX_ENUM_TEXT = 200;
2439
+ function safe(text, pattern) {
2440
+ return typeof text === "string" && pattern.test(text) ? text : "<unsafe>";
2441
+ }
2442
+ function enumText(values) {
2443
+ const shown = [];
2444
+ let length = 0;
2445
+ for (const v of values.slice(0, MAX_ENUM_VALUES)) {
2446
+ const text = safe(v, ENUM_VALUE);
2447
+ if (length + text.length > MAX_ENUM_TEXT) break;
2448
+ shown.push(text);
2449
+ length += text.length + 1;
2450
+ }
2451
+ return [...shown, ...shown.length < values.length ? ["…"] : []].join("|");
2452
+ }
2453
+ function fieldType(f, ns) {
2454
+ let t;
2455
+ if (f.kind === "list" && f.of !== void 0) t = `${fieldType(f.of, ns)}[]`;
2456
+ else if (f.kind === "crossRef") t = `→${f.ns === ns || f.ns === void 0 ? "" : `${safe(f.ns, NAME)}/`}${safe(f.type, NAME)}`;
2457
+ else if (f.kind === "struct") t = `{${Object.keys(f.fields ?? {}).map((k) => safe(k, NAME)).join(", ")}}`;
2458
+ else if (Array.isArray(f.enum)) t = f.nullable ? `(${enumText(f.enum)})` : enumText(f.enum);
2459
+ else t = safe(f.type ?? f.kind, NAME);
2460
+ const tags = [];
2461
+ if (f.readonly === true || f.serverSet !== void 0 && f.serverSet !== false) tags.push("readonly");
2462
+ return `${t}${f.nullable ? "?" : ""}${tags.length > 0 ? ` [${tags.join(", ")}]` : ""}`;
2463
+ }
2464
+ const AUTO_CRUD = /^(get|create|update|delete)(.+)$/;
2465
+ function schemaOverview(federated) {
2466
+ const out = {};
2467
+ for (const [ns, schema] of Object.entries(federated)) {
2468
+ const typeDefs = schema.types ?? {};
2469
+ const types = {};
2470
+ for (const [name, def] of Object.entries(typeDefs)) types[safe(name, NAME)] = Object.entries(def.fields ?? {}).map(([field, shape]) => `${safe(field, NAME)}: ${fieldType(shape, ns)}`).join(", ");
2471
+ const mutations = Object.keys(schema.mutations ?? {}).filter((m) => {
2472
+ const crud = AUTO_CRUD.exec(m);
2473
+ return !(crud?.[2] !== void 0 && crud[2] in typeDefs);
2474
+ }).map((m) => safe(m, NAME));
2475
+ out[safe(ns, NAME)] = mutations.length > 0 ? {
2476
+ types,
2477
+ mutations
2478
+ } : { types };
2479
+ }
2480
+ return out;
2481
+ }
2482
+ /** How to read the overview; rides beside it in the tool result and the instructions. */
2483
+ const OVERVIEW_LEGEND = "Each type is `field: type` pairs. `a|b` is an enum, `?` nullable, `T[]` a list, `→Type` a reference (`→ns/Type` across namespaces). No field needs an index to filter; json filters by path only, and only non-json scalars sort. [readonly] fields are server-set. Generated get/create/update/delete<Type> mutations are not listed; `mutations` holds the rest. For a type's exact write contract call `schema` with `namespace` and `type`.";
2484
+ /** Past this, the instructions carry only type names; the full overview is one `schema` call away. */
2485
+ const INSTRUCTIONS_OVERVIEW_MAX = 12e3;
2486
+ const CONVENTIONS = [
2487
+ "Substrate holds typed records. Every query and mutate key is qualified: `<namespace>/<Type>` or `<namespace>/<mutation>`.",
2488
+ "- Filters go in `params.where`, never top-level params: `{ \"ns/Type\": { \"params\": { \"where\": { \"status\": { \"eq\": \"open\" } }, \"limit\": 20 }, \"fields\": { \"id\": true } } }`. A refused operator is named with the field and its kind; read it rather than guessing.",
2489
+ "- Read `errors` before `data`. A refused frame is ABSENT from `data`; a present empty list means nothing matched. A read with `_pagination.hasMore` is truncated: page with `nextCursor` (default page 100, max 1000).",
2490
+ "- Lists, counts and joins are exact `query` frames; `recall` (similarity search) needs `query`, `namespace` and `type`, and is for finding records by meaning.",
2491
+ "- In one `mutate` call the single-frame keys commit together or not at all, and an array under one key is one transaction. Send unrelated writes as separate calls.",
2492
+ "- `createdAt`, `updatedAt`, `createdBy` and `updatedBy` are server-set: never send them; read them through `_metadata`.",
2493
+ "- `whoami` says which identity this session reads and writes as.",
2494
+ "- With a shell, `substrate run <script.mts>` runs many reads and writes in one call and returns one small report (GET /substrate/v1/onboard, `instructions.codeMode`)."
2495
+ ].join("\n");
2496
+ /** The MCP `instructions` text: the conventions, then this server's types as of session start. */
2497
+ function buildInstructions(overview) {
2498
+ if (overview === null) return `${CONVENTIONS}\n\nThe type list was unavailable at session start; call \`schema\` with no arguments for it.`;
2499
+ const full = JSON.stringify(overview);
2500
+ const body = full.length <= INSTRUCTIONS_OVERVIEW_MAX ? `${OVERVIEW_LEGEND}\n${full}` : `Type names only (the full overview is large; call \`schema\` with no arguments for fields):\n${JSON.stringify(Object.fromEntries(Object.entries(overview).map(([ns, o]) => [ns, Object.keys(o.types)])))}`;
2501
+ return `${CONVENTIONS}\n\nTypes on this server at session start:\n${body}`;
2502
+ }
2503
+
2504
+ //#endregion
2505
+ //#region src/mcp/server.ts
2506
+ /**
2507
+ * stdio MCP server exposing Substrate's query/mutate/schema surface to
2508
+ * MCP-speaking agents. Spec: §5.7.
2509
+ *
2510
+ * Every tool is a thin JSON-over-HTTP proxy to a `/substrate/v1/*` route. Frame keys
2511
+ * are qualified (`<ns>/<Type>`, §4.7), so one call can fan across namespaces.
2512
+ * Subscribe / stream are WS-only and not exposed — stdio cannot host
2513
+ * long-lived push streams cleanly.
2514
+ *
2515
+ * Run by the `substrate mcp` subcommand via `runMcp`.
2516
+ */
2517
+ /** The version the MCP server reports in its initialize serverInfo. */
2518
+ const MCP_SERVER_VERSION = typeof version === "string" && version.length > 0 ? version : "0.0.0";
2519
+ let agentJwt = () => null;
2520
+ /**
2521
+ * Call at MCP server startup (next to where SUBSTRATE_URL is read) to arm the
2522
+ * agent JWT; its `aud` is `endpoint`'s origin.
2523
+ */
2524
+ function configureAgentAuth(env, endpoint) {
2525
+ agentJwt = makeAgentJwtProvider(env, new URL(endpoint).origin);
2526
+ }
2527
+ /** Request headers for `endpoint`; a token is only sent where `tokenAudience` allows. */
2528
+ function authHeaders(endpoint, extra) {
2529
+ const token = agentJwt();
2530
+ if (token === null) return extra;
2531
+ tokenAudience(endpoint);
2532
+ return {
2533
+ ...extra,
2534
+ authorization: token
2535
+ };
2536
+ }
2537
+ const payloadSchema = (example) => z.unknown().transform((raw, ctx) => {
2538
+ if (typeof raw === "string") try {
2539
+ const parsed = JSON.parse(raw);
2540
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
2541
+ ctx.addIssue({
2542
+ code: "custom",
2543
+ message: "payload must decode to a JSON object"
2544
+ });
2545
+ return z.NEVER;
2546
+ }
2547
+ return parsed;
2548
+ } catch {
2549
+ ctx.addIssue({
2550
+ code: "custom",
2551
+ message: "payload must be valid JSON"
2552
+ });
2553
+ return z.NEVER;
2554
+ }
2555
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
2556
+ ctx.addIssue({
2557
+ code: "custom",
2558
+ message: "payload must be an object or a JSON string decoding to an object"
2559
+ });
2560
+ return z.NEVER;
2561
+ }
2562
+ return raw;
2563
+ }).describe(example);
2564
+ function errorResult(message) {
2565
+ return {
2566
+ content: [{
2567
+ type: "text",
2568
+ text: `Error: ${message}`
2569
+ }],
2570
+ isError: true
2571
+ };
2572
+ }
2573
+ function okResult(value) {
2574
+ return { content: [{
2575
+ type: "text",
2576
+ text: JSON.stringify(value)
2577
+ }] };
2578
+ }
2579
+ function toMessage(err) {
2580
+ if (!(err instanceof Error)) return String(err);
2581
+ if (err.cause instanceof Error && err.cause.message) return `${err.message}: ${err.cause.message}`;
2582
+ return err.message;
2583
+ }
2584
+ /**
2585
+ * POST a JSON body to a Substrate HTTP endpoint and return the parsed response.
2586
+ *
2587
+ * `errorMode` controls the !ok branch:
2588
+ * - 'parsedError' — try to parse the response as Substrate's `{error: {message}}`
2589
+ * envelope; throw the inner message. Falls back to `HTTP <status>` if the
2590
+ * body isn't shaped that way. Used by /substrate/v1/recall.
2591
+ * - 'textPreview' (default) — read the response as text and throw a
2592
+ * `POST <path> returned <status>: <preview>` message capped at 500 chars.
2593
+ * Used by /substrate/v1/nl + /substrate/v1/_system/drop-{namespace,type}.
2594
+ */
2595
+ async function postSubstrate(endpoint, path, body, errorMode = "textPreview") {
2596
+ const url = `${trimTrailingSlashes(endpoint)}${path}`;
2597
+ let res;
2598
+ try {
2599
+ res = await fetch(url, {
2600
+ method: "POST",
2601
+ headers: authHeaders(endpoint, {
2602
+ "content-type": "application/json",
2603
+ accept: "application/json"
2604
+ }),
2605
+ body: JSON.stringify(body),
2606
+ redirect: "error"
2607
+ });
2608
+ } catch (err) {
2609
+ throw new Error(`Substrate request to ${url} failed: ${err instanceof Error ? err.message : String(err)}`);
2610
+ }
2611
+ if (!res.ok) {
2612
+ if (errorMode === "parsedError") {
2613
+ let parsed = null;
2614
+ try {
2615
+ parsed = await res.json();
2616
+ } catch {}
2617
+ const env = parsed !== null && typeof parsed === "object" ? parsed : void 0;
2618
+ const flat = typeof env?.message === "string" ? env.message : void 0;
2619
+ const message = env !== void 0 && "error" in env ? env.error?.message ?? flat ?? "unknown error" : flat ?? `HTTP ${res.status}`;
2620
+ throw new Error(message);
2621
+ }
2622
+ const preview = await res.text().catch(() => "<unreadable>");
2623
+ throw new Error(`POST ${path} returned ${res.status}: ${preview.slice(0, 500)}`);
2624
+ }
2625
+ return await res.json();
2626
+ }
2627
+ /**
2628
+ * GET a JSON body from a Substrate HTTP endpoint and return the parsed response.
2629
+ * The read-only sibling of `postSubstrate` — used for `/substrate/v1/federated-schema`.
2630
+ * Non-2xx throws `GET <path> returned <status>: <preview>` (capped 500 chars);
2631
+ * a transport failure wraps the cause with the failing URL.
2632
+ */
2633
+ async function getSubstrate(endpoint, path) {
2634
+ const url = `${trimTrailingSlashes(endpoint)}${path}`;
2635
+ let res;
2636
+ try {
2637
+ res = await fetch(url, {
2638
+ method: "GET",
2639
+ headers: authHeaders(endpoint, { accept: "application/json" }),
2640
+ redirect: "error"
2641
+ });
2642
+ } catch (err) {
2643
+ throw new Error(`Substrate request to ${url} failed: ${err instanceof Error ? err.message : String(err)}`);
2644
+ }
2645
+ if (!res.ok) {
2646
+ const preview = await res.text().catch(() => "<unreadable>");
2647
+ throw new Error(`GET ${path} returned ${res.status}: ${preview.slice(0, 500)}`);
2648
+ }
2649
+ return await res.json();
2650
+ }
2651
+ async function recall(endpoint, body) {
2652
+ return postSubstrate(endpoint, "/substrate/v1/recall", body, "parsedError");
2653
+ }
2654
+ function createSchemaHandler(endpoint) {
2655
+ return async (args) => {
2656
+ const ns = args?.namespace;
2657
+ const type = args?.type;
2658
+ const shape = args?.shape;
2659
+ if ((ns === void 0 || ns === "") && args?.full !== true) try {
2660
+ const federated = await getSubstrate(endpoint, "/substrate/v1/federated-schema");
2661
+ return okResult({
2662
+ legend: OVERVIEW_LEGEND,
2663
+ overview: schemaOverview(federated)
2664
+ });
2665
+ } catch (err) {
2666
+ return errorResult(toMessage(err));
2667
+ }
2668
+ let path = "/substrate/v1/federated-schema";
2669
+ if (ns !== void 0 && ns !== "") {
2670
+ if (type !== void 0 && type !== "") {
2671
+ const q = shape !== void 0 && shape !== "" ? `?shape=${encodeURIComponent(shape)}` : "";
2672
+ path = `/substrate/v1/schema/${encodeURIComponent(ns)}/${encodeURIComponent(type)}${q}`;
2673
+ } else path = `/substrate/v1/schema/${encodeURIComponent(ns)}`;
2674
+ }
2675
+ try {
2676
+ return okResult(await getSubstrate(endpoint, path));
2677
+ } catch (err) {
2678
+ return errorResult(toMessage(err));
2679
+ }
2680
+ };
2681
+ }
2682
+ function createQueryHandler(endpoint) {
2683
+ return async ({ payload }) => {
2684
+ try {
2685
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/query", payload));
2686
+ } catch (err) {
2687
+ return errorResult(toMessage(err));
2688
+ }
2689
+ };
2690
+ }
2691
+ function createMutateHandler(endpoint) {
2692
+ return async ({ payload }) => {
2693
+ try {
2694
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/mutate", payload));
2695
+ } catch (err) {
2696
+ return errorResult(toMessage(err));
2697
+ }
2698
+ };
2699
+ }
2700
+ function createNlHandler(endpoint) {
2701
+ return async (args) => {
2702
+ try {
2703
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/nl", args));
2704
+ } catch (err) {
2705
+ return errorResult(toMessage(err));
2706
+ }
2707
+ };
2708
+ }
2709
+ function createProposeTypeHandler(endpoint) {
2710
+ return async ({ namespace, ...params }) => {
2711
+ try {
2712
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/mutate", { [`${namespace}/propose_type`]: {
2713
+ params,
2714
+ fields: {
2715
+ id: true,
2716
+ typeName: true,
2717
+ applied: true,
2718
+ appliedAt: true
2719
+ }
2720
+ } }));
2721
+ } catch (err) {
2722
+ return errorResult(toMessage(err));
2723
+ }
2724
+ };
2725
+ }
2726
+ function createProposeFieldHandler(endpoint) {
2727
+ return async ({ namespace, targetType, fieldName, fieldSpec, proposedReason }) => {
2728
+ try {
2729
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/mutate", { [`${namespace}/propose_field`]: {
2730
+ params: {
2731
+ targetType,
2732
+ fieldName,
2733
+ fieldSpec,
2734
+ proposedReason
2735
+ },
2736
+ fields: {
2737
+ id: true,
2738
+ targetType: true,
2739
+ fieldName: true,
2740
+ applied: true,
2741
+ appliedAt: true
2742
+ }
2743
+ } }));
2744
+ } catch (err) {
2745
+ return errorResult(toMessage(err));
2746
+ }
2747
+ };
2748
+ }
2749
+ /** `propose_index` lives on the proposals control plane; `namespace` names the target. */
2750
+ function createProposeIndexHandler(endpoint) {
2751
+ return async (args) => {
2752
+ try {
2753
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/mutate", { "_system_proposals/propose_index": {
2754
+ params: Object.fromEntries(Object.entries(args).filter(([, v]) => v !== void 0)),
2755
+ fields: {
2756
+ id: true,
2757
+ action: true,
2758
+ namespace: true,
2759
+ type: true,
2760
+ indexName: true
2761
+ }
2762
+ } }));
2763
+ } catch (err) {
2764
+ return errorResult(toMessage(err));
2765
+ }
2766
+ };
2767
+ }
2768
+ function createDropNamespaceHandler(endpoint) {
2769
+ return async (input) => {
2770
+ try {
2771
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/_system/drop-namespace", input));
2772
+ } catch (err) {
2773
+ return errorResult(toMessage(err));
2774
+ }
2775
+ };
2776
+ }
2777
+ function createDropTypeHandler(endpoint) {
2778
+ return async (input) => {
2779
+ try {
2780
+ return okResult(await postSubstrate(endpoint, "/substrate/v1/_system/drop-type", input));
2781
+ } catch (err) {
2782
+ return errorResult(toMessage(err));
2783
+ }
2784
+ };
2785
+ }
2786
+ function createMcpServer(endpoint, options = {}) {
2787
+ const server = new McpServer({
2788
+ name: "substrate",
2789
+ version: MCP_SERVER_VERSION
2790
+ }, options.instructions !== void 0 ? { instructions: options.instructions } : void 0);
2791
+ const TOOLS = [
2792
+ {
2793
+ name: "schema",
2794
+ config: {
2795
+ description: "Fetch the Substrate schema. No args → a compact overview: every namespace's types, one line of `field: type` each, enough to write a query. `full: true` → the whole federated schema (large; rarely needed). SCOPED + CHEAP: pass `namespace` for one namespace, or `namespace` + `type` for a single type's write contract ({ fields, mutations }). Mine the scoped shape BEFORE a create/update so you send only declared fields — autoCRUD rejects undeclared fields with `unknown_field`. CHEAPER STILL: add `shape: \"fields\"` when you only need the type's field names and kinds — for an autoCRUD type the mutations restate the field block five times over, so the default answer costs about 6x the question.",
2796
+ inputSchema: {
2797
+ namespace: z.string().min(1).optional().describe("Scope to one namespace, e.g. \"notes\". Omit for the full federated schema."),
2798
+ type: z.string().min(1).optional().describe("Scope to one type within `namespace`, e.g. \"Todo\" — returns its field defs + create/update param shapes. Requires `namespace`."),
2799
+ shape: z.enum(["full", "fields"]).optional().describe("Projection of the type contract; requires `namespace` + `type`. \"full\" (default) inlines every mutation's params and returns. \"fields\" returns the field defs plus `mutationNames`, about a sixth the size — use it to answer \"what fields does this type have\"."),
2800
+ full: z.boolean().optional().describe("With no `namespace`: true returns the whole federated schema instead of the overview.")
2801
+ }
2802
+ },
2803
+ handler: createSchemaHandler(endpoint)
2804
+ },
2805
+ {
2806
+ name: "query",
2807
+ config: {
2808
+ description: "Query Substrate. payload is a single frame object mapping qualified keys (<ns>/<Type>) to { params, fields }. ONE call can span multiple namespaces — e.g. { \"prices/Price\": {...}, \"products/Product\": {...} }.",
2809
+ inputSchema: { payload: payloadSchema("Query frame. Example: { \"default/Todo\": { \"params\": { \"limit\": 20 }, \"fields\": { \"id\": true, \"title\": true } } }") }
2810
+ },
2811
+ handler: createQueryHandler(endpoint)
2812
+ },
2813
+ {
2814
+ name: "mutate",
2815
+ config: {
2816
+ description: "Run one or more mutations. payload is a single frame object mapping qualified keys (<ns>/<mutationName>) to { params, fields } (single-frame) or to an array of frames (batched atomic). ONE op-key can accept a single frame or an array. An ARRAY op-key is its own transaction: it commits or rolls back as a unit, independently of every other op-key in the call. The SINGLE-FRAME op-keys share one transaction when they sit on one tx scope (every namespace on one pg handle); across two tx scopes they are refused rather than split. So a single-frame op-key beside an array is NOT rolled back when the array fails — to make writes atomic together, put them in one array under one op-key. The memory dataset mints a fresh tx scope per namespace, so single-frame op-keys in two namespaces are refused there.",
2817
+ inputSchema: { payload: payloadSchema("Mutation frame. Single: { \"default/createTodo\": { \"params\": { \"title\": \"...\" }, \"fields\": { \"id\": true } } }. Batched atomic: { \"default/updateTodo\": [ { \"params\": { \"id\": \"1\", \"done\": true }, \"fields\": { \"id\": true } }, { \"params\": { \"id\": \"2\", \"done\": true }, \"fields\": { \"id\": true } } ] }.") }
2818
+ },
2819
+ handler: createMutateHandler(endpoint)
2820
+ },
2821
+ {
2822
+ name: "ask",
2823
+ config: {
2824
+ description: "Ask a natural-language question of one namespace. The parser answers first; a constrained judge handles what it escalates; a judge outage hands off honestly. Returns { outcome, trail }, where outcome.kind is rows | recall | clarify | refuse. Read-only. Requires the @mnmal-ai/substrate-nl plugin (404 otherwise).",
2825
+ inputSchema: {
2826
+ namespace: z.string().min(1).describe("Namespace to ask, e.g. \"notes\"."),
2827
+ question: z.string().min(1).describe("The question, e.g. \"open todos in billing\"."),
2828
+ project: z.string().min(1).optional().describe("Asking project; scopes project-bearing types."),
2829
+ type: z.string().min(1).optional().describe("force the reading to this type (resubmit a clarify option)")
2830
+ }
2831
+ },
2832
+ handler: createNlHandler(endpoint)
2833
+ },
2834
+ {
2835
+ name: "propose_type",
2836
+ config: {
2837
+ description: "Propose a brand-new type in an owned namespace. The plugin writes a TypeProposal record and registers the type + autoCRUD surface (createX, getX, updateX, deleteX) at runtime — future queries/mutations against this type succeed immediately. Requires the `substrate.propose` capability. Use `propose_field` to extend an existing type; this tool rejects if the type already exists (structured error code `type_already_proposed` or `type_already_exists`).",
2838
+ inputSchema: {
2839
+ namespace: z.string().min(1).describe("Target namespace (must be in the plugin's ownedNamespaces)."),
2840
+ typeName: z.string().min(1).describe("PascalCase type name, e.g. \"Dress\"."),
2841
+ fields: z.record(z.string(), z.unknown()).describe("Initial field map keyed by field name. Each value is a FieldSpecJson: { kind: \"scalar\" | \"crossRef\" | \"struct\" | \"list\", ... }. Example: { \"name\": { \"kind\": \"scalar\", \"type\": \"string\" }, \"owner\": { \"kind\": \"crossRef\", \"ns\": \"household\", \"type\": \"Person\", \"onDelete\": \"set_null\" } }."),
2842
+ proposedReason: z.string().min(1).describe("Short human-readable justification. Why is this type being added?"),
2843
+ orderedBy: z.record(z.string(), z.enum(["asc", "desc"])).optional().describe("What order do you usually read this in? { \"<field>\": \"asc\" | \"desc\" } over a date or number field, or createdAt / updatedAt. Omit for newest first."),
2844
+ indexes: z.array(z.record(z.string(), z.unknown())).optional().describe("Indexes the reads will need: [{ \"fields\": [\"brand\"] }]. Never unique or named."),
2845
+ expectedSize: z.enum(["small", "large"]).optional().describe("\"large\" if the type will hold many rows, so indexes are advised sooner.")
2846
+ }
2847
+ },
2848
+ handler: createProposeTypeHandler(endpoint)
2849
+ },
2850
+ {
2851
+ name: "propose_field",
2852
+ config: {
2853
+ description: "Propose a new field on an existing type. Used for additive schema evolution AND for declaring edges (propose a crossRef field to model a relationship, including cross-namespace edges). Idempotent on exact spec match; rejects with `destructive_change_required` if a field of the same name exists with a different spec. Requires the `substrate.propose` capability.",
2854
+ inputSchema: {
2855
+ namespace: z.string().min(1).describe("Namespace containing the target type (must be in ownedNamespaces)."),
2856
+ targetType: z.string().min(1).describe("Existing type to extend. May be code-declared or previously proposed."),
2857
+ fieldName: z.string().min(1).describe("camelCase field name to add."),
2858
+ fieldSpec: z.record(z.string(), z.unknown()).describe("Single FieldSpecJson: { kind: \"scalar\" | \"crossRef\" | \"struct\" | \"list\", ... }. For an edge: { \"kind\": \"crossRef\", \"ns\": \"<target-ns>\", \"type\": \"<TargetType>\", \"onDelete\": \"set_null\" }."),
2859
+ proposedReason: z.string().min(1).describe("Short human-readable justification.")
2860
+ }
2861
+ },
2862
+ handler: createProposeFieldHandler(endpoint)
2863
+ },
2864
+ {
2865
+ name: "propose_index",
2866
+ config: {
2867
+ description: "Apply or dismiss an index recommendation (query `_system/IndexRecommendation`), or change indexes directly. `add` / `orderedBy` work on proposed types only (`index_on_code_defined_type` otherwise); `remove` drops an engine-owned, non-unique index the engine no longer wants, on any type (`not_engine_owned`, `unique_index`, `still_desired`, `unknown_index`). A referenced recommendation moves to accepted or dismissed; a closed one is refused (`recommendation_closed`), one whose evidence no longer holds is superseded (`recommendation_stale`). Requires the `substrate.index` capability in the target namespace.",
2868
+ inputSchema: {
2869
+ namespace: z.string().min(1).describe("Namespace of the type whose indexes change."),
2870
+ type: z.string().min(1).describe("Type name, e.g. \"Sneaker\"."),
2871
+ action: z.enum([
2872
+ "add",
2873
+ "remove",
2874
+ "dismiss",
2875
+ "orderedBy"
2876
+ ]),
2877
+ reason: z.string().min(1).describe("Short human-readable justification."),
2878
+ recommendationId: z.string().min(1).optional().describe("The IndexRecommendation row id; required for dismiss."),
2879
+ declaration: z.record(z.string(), z.unknown()).optional().describe("add: an index declaration, e.g. { \"fields\": [\"brand\", { \"field\": \"size\", \"dir\": \"desc\" }] }. Defaults to the recommendation's."),
2880
+ orderedBy: z.record(z.string(), z.enum(["asc", "desc"])).optional().describe("orderedBy: the natural order, one key, e.g. { \"releasedAt\": \"desc\" }."),
2881
+ indexName: z.string().min(1).optional().describe("remove: the index to drop. Defaults to the recommendation's.")
2882
+ }
2883
+ },
2884
+ handler: createProposeIndexHandler(endpoint)
2885
+ },
2886
+ {
2887
+ name: "drop_namespace",
2888
+ config: {
2889
+ description: "Admin: physically delete every row + short-id for a given namespace. Refuses by default if any edge references the namespace; pass cascade=\"delete\" to drop those edges too. Dry-run mode reports counts without mutating. Emits a AuditEvent { kind: \"namespace_dropped\" }. Requires the `admin` capability on the server side. DESTRUCTIVE — data cannot be recovered after a non-dry-run call.",
2890
+ inputSchema: {
2891
+ namespace: z.string().min(1).describe("Namespace to drop."),
2892
+ confirm: z.string().min(1).describe("Must equal `namespace` exactly (confirmation gate)."),
2893
+ dryRun: z.boolean().optional().describe("If true, report counts and roll back — no actual deletion."),
2894
+ cascade: z.enum(["refuse", "delete"]).optional().describe("Behaviour when edges reference the namespace. Default \"refuse\" — aborts if any edges exist.")
2895
+ }
2896
+ },
2897
+ handler: createDropNamespaceHandler(endpoint)
2898
+ },
2899
+ {
2900
+ name: "drop_type",
2901
+ config: {
2902
+ description: "Admin: physically delete every row + short-id for a given (namespace, type). Same cascade + dry-run semantics as drop_namespace. Emits a AuditEvent { kind: \"type_dropped\" }. Requires the `admin` capability. DESTRUCTIVE — data cannot be recovered after a non-dry-run call.",
2903
+ inputSchema: {
2904
+ namespace: z.string().min(1).describe("Namespace containing the type to drop."),
2905
+ type: z.string().min(1).describe("Type name to drop, e.g. \"Todo\"."),
2906
+ confirm: z.string().min(1).describe("Must equal \"<namespace>/<type>\" exactly (confirmation gate)."),
2907
+ dryRun: z.boolean().optional().describe("If true, report counts and roll back — no actual deletion."),
2908
+ cascade: z.enum(["refuse", "delete"]).optional().describe("Behaviour when edges reference the type. Default \"refuse\" — aborts if any edges exist.")
2909
+ }
2910
+ },
2911
+ handler: createDropTypeHandler(endpoint)
2912
+ },
2913
+ {
2914
+ name: "whoami",
2915
+ config: {
2916
+ description: "Ask the server who this MCP session is authenticated as. Returns { authEnabled, identity }, where `identity` is null for an anonymous caller and otherwise carries { id, grants } — a namespace -> capabilities map, AS RECORDED, so a wildcard stays a `'*'` key rather than expanding into every namespace. USE THIS BEFORE CONCLUDING A CREDENTIAL WORKS: on a reads-open stack an authenticated read and an anonymous one return byte-identical results, so a successful query is not evidence of identity. `authEnabled: false` means the deployment verifies nothing (a posture you cannot fix from here); `authEnabled: true` with `identity: null` means your own credential never arrived (SUBSTRATE_AGENT_KEY_ID / SUBSTRATE_AGENT_KEY_PATH). Those need different fixes, which is why they are separate fields.",
2917
+ inputSchema: {}
2918
+ },
2919
+ handler: async () => {
2920
+ try {
2921
+ const answer = await getSubstrate(endpoint, "/substrate/v1/whoami");
2922
+ const claimed = resolveAgentCapabilities(process.env);
2923
+ return okResult({
2924
+ ...answer,
2925
+ client: {
2926
+ claimedCapabilities: claimed,
2927
+ note: "What this MCP client ASKED for. The effective identity is this claim intersected with the registry row, so a capability absent here is unreachable however the row is granted. Widen with SUBSTRATE_AGENT_CAPABILITIES (csv)."
2928
+ }
2929
+ });
2930
+ } catch (err) {
2931
+ return errorResult(toMessage(err));
2932
+ }
2933
+ }
2934
+ },
2935
+ {
2936
+ name: "recall",
2937
+ config: {
2938
+ description: "Semantic recall over embedded Substrate records. Returns top-K records by cosine similarity to the NL query. Use for finding prior context by meaning when structural `where`/`contains` queries miss. WHICH TYPES ARE EMBEDDED IS A SERVER FACT — ask it (`GET /substrate/v1/embed-stats` returns `embeddedTypes`) rather than assuming; a type is embedded iff its namespace definition declares an `embed.source`. The same operation is also reachable as `POST /substrate/v1/recall` (body param `query`) and as the frame key `recall/Hit` through query — where the search text is `params.to`, not `params.query` and not a `where` clause. See docs/surface-parity.md.",
2939
+ inputSchema: {
2940
+ query: z.string().min(1).describe("Natural-language query to embed and match against."),
2941
+ k: z.number().int().min(1).max(100).optional().describe("Max results. Default 10."),
2942
+ namespace: z.string().optional().describe("Namespace to search. Pass it: there is no default. Omitted, the server falls back to ITS OWN SUBSTRATE_NAMESPACE and refuses with `missing_namespace` if that is unset."),
2943
+ type: z.string().min(1).describe("Type to search, e.g. \"Note\". Required."),
2944
+ threshold: z.number().optional().describe("Minimum similarity (0..1). Default 0."),
2945
+ lexicalThreshold: z.number().optional().describe("Cosine floor for hits only the lexical (keyword) arm found. Default: same as threshold. 0 keeps them unfloored, so keyword matches survive a high threshold."),
2946
+ where: z.record(z.string(), z.unknown()).optional().describe("Row-field filter applied inside every candidate source, so k fills with matching rows: field -> { eq: scalar | null } or { in: [scalar | null, ...] }, every field must match; eq null matches a missing or null field. Example: { \"project\": { \"in\": [\"substrate\", null] } }."),
2947
+ rowFields: z.union([z.record(z.string(), z.literal(true)), z.literal(true)]).optional().describe("Row-body projection. Omitted, each hit's `row` carries `id` plus its handle fields (name, title, topic, synopsis, description), which is enough to decide on. Ask for more only when you need it: field -> true keeps just those fields plus `id`, e.g. { \"synopsis\": true, \"body\": true }; true returns the whole body.")
2948
+ }
2949
+ },
2950
+ handler: async (input) => {
2951
+ try {
2952
+ return okResult(await recall(endpoint, input));
2953
+ } catch (err) {
2954
+ return errorResult(toMessage(err));
2955
+ }
2956
+ }
2957
+ }
2958
+ ];
2959
+ const allowed = resolveToolAllowlist(options.tools, TOOLS.map((t) => t.name));
2960
+ for (const t of TOOLS) {
2961
+ if (allowed !== null && !allowed.has(t.name)) continue;
2962
+ server.registerTool(t.name, t.config, t.handler);
2963
+ }
2964
+ return server;
2965
+ }
2966
+ /**
2967
+ * Parse SUBSTRATE_MCP_TOOLS. `null` means register everything. An unknown name
2968
+ * throws: a typo that silently registered nothing would read as "this server
2969
+ * has no such tool", which is a worse failure than refusing to start.
2970
+ */
2971
+ function resolveToolAllowlist(raw, known) {
2972
+ if (raw === void 0 || raw.trim() === "") return null;
2973
+ const names = raw.split(",").map((n) => n.trim()).filter((n) => n !== "");
2974
+ for (const n of names) if (!known.includes(n)) throw new Error(`SUBSTRATE_MCP_TOOLS: unknown tool '${n}'. Valid names: ${[...known].sort().join(", ")}`);
2975
+ return new Set(names);
2976
+ }
2977
+ /** The overview for the session's instructions, or null when the server is slow or down. */
2978
+ async function fetchOverview(endpoint) {
2979
+ const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 5e3).unref());
2980
+ const fetched = getSubstrate(endpoint, "/substrate/v1/federated-schema").then(schemaOverview, () => null);
2981
+ return Promise.race([fetched, timeout]);
2982
+ }
2983
+ /**
2984
+ * Boot the stdio MCP server. Resolves once the transport is connected; the
2985
+ * process keeps running until the host (Claude Code, etc.) closes stdio.
2986
+ */
2987
+ async function runMcp() {
2988
+ const endpoint = process.env.SUBSTRATE_URL ?? "http://localhost:3100";
2989
+ configureAgentAuth(process.env, endpoint);
2990
+ const server = createMcpServer(endpoint, {
2991
+ ...process.env.SUBSTRATE_MCP_TOOLS === void 0 ? {} : { tools: process.env.SUBSTRATE_MCP_TOOLS },
2992
+ instructions: buildInstructions(await fetchOverview(endpoint))
2993
+ });
2994
+ const transport = new StdioServerTransport();
2995
+ await server.connect(transport);
2996
+ }
2997
+
2998
+ //#endregion
2999
+ //#region src/cli.ts
3000
+ /**
3001
+ * Substrate CLI dispatcher. The unified `substrate` binary dispatches on argv[2]:
3002
+ *
3003
+ * substrate serve — boot the HTTP/WS server (./main.ts)
3004
+ * substrate mcp — boot the stdio MCP transport (./mcp/server.ts)
3005
+ * substrate init — scaffold a runtime directory (./cli/init)
3006
+ * substrate check-enums — report stored values outside declared enums
3007
+ * substrate normalise-vocab — rewrite stored vocabulary aliases to canonical values
3008
+ * substrate backfill-field — write per-row values of one field, metadata preserved
3009
+ * substrate ask — ask a natural-language question (./cli/ask)
3010
+ * substrate run — run a script against a signed, guarded client (./cli/run)
3011
+ * substrate federate — enroll / join / check bridges (./cli/federate)
3012
+ *
3013
+ * No flags-vs-subcommand ambiguity: subcommands are always argv[2].
3014
+ * Unknown / missing subcommand prints help and exits non-zero.
3015
+ */
3016
+ const HELP = `substrate — the Substrate CLI
3017
+
3018
+ Usage:
3019
+ substrate <subcommand> [args...]
3020
+ substrate --version Print this binary's package version (also -v, version).
3021
+ substrate <subcommand> --help Print this help.
3022
+
3023
+ Subcommands:
3024
+ serve Boot the Substrate HTTP/WS server (default port 3100).
3025
+ mcp Boot the stdio MCP server. Reads SUBSTRATE_URL, and
3026
+ SUBSTRATE_MCP_TOOLS (csv) to register only those tools.
3027
+ init [dir] [flags] Scaffold a new Substrate runtime directory. Interactive by
3028
+ default; pass --yes for non-interactive scripted use.
3029
+ federate <verb> Federation onboarding: enroll / join / check.
3030
+ Run \`substrate federate\` for the verb list.
3031
+ ask <question> Ask a natural-language question (needs the substrate-nl plugin).
3032
+ Flags: --ns, --project, --json. Reads SUBSTRATE_URL.
3033
+ run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]
3034
+ Run a script's default export (s) => result against a client
3035
+ signed from SUBSTRATE_URL + SUBSTRATE_AGENT_KEY_ID/_PATH, and
3036
+ print one JSON report. --args is a JSON object, read as
3037
+ s.args. Read-only unless --dry-run (records mutations) or
3038
+ --write (sends up to --max-writes frames, 50).
3039
+ check-enums [--json] [--record]
3040
+ Report stored values outside a field's declared enum.
3041
+ Read-only over HTTP (--record writes verdict rows); reads
3042
+ SUBSTRATE_URL and SUBSTRATE_ENUM_CHECK_TOKEN. Exit 1 on
3043
+ drift, so it works as a CI/cron gate.
3044
+ normalise-vocab <ns> <Type> <field> [--apply] [--reject a,b] [--json]
3045
+ Rewrite stored aliases to their canonical value. Dry run
3046
+ unless --apply. Admin: reads SUBSTRATE_URL and
3047
+ SUBSTRATE_ADMIN_TOKEN.
3048
+ backfill-field <ns> <Type> <field> --values <file.json> [--apply] [--overwrite] [--json]
3049
+ Write per-row values of one field, metadata preserved. Dry
3050
+ run unless --apply. Admin: reads SUBSTRATE_URL and
3051
+ SUBSTRATE_ADMIN_TOKEN.
3052
+
3053
+ Environment for \`serve\` (the load-bearing ones; the full reference is in the docs):
3054
+ SUBSTRATE_DATABASE_URL 'memory' (default) or 'postgres://...'
3055
+ SUBSTRATE_PLUGIN_DIR Abs path to plugin install root (manifest-driven loader)
3056
+ PORT Listen port (default 3100)
3057
+ HOST Listen address (default 0.0.0.0, or 127.0.0.1 when
3058
+ auth is off). A non-loopback HOST with auth off fails
3059
+ boot unless SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST=1.
3060
+ SUBSTRATE_AUTH_MODE 'attribute' or 'required'. Setting this or
3061
+ SUBSTRATE_AUTH_KEY_REGISTRY enables auth; with
3062
+ neither, every request is anonymous.
3063
+ SUBSTRATE_STREAM_TICKET_SECRET HMAC key signing the SSE stream tickets. REQUIRED when
3064
+ auth is enabled — boot fails without it. Minimum 16
3065
+ characters after trimming. The ticket signature is the
3066
+ ONLY authentication on GET /substrate/v1/stream and
3067
+ GET /substrate/v1/subscribe (EventSource can send no
3068
+ header or body). Rotating it invalidates every
3069
+ outstanding ticket, which is the only revocation
3070
+ mechanism.
3071
+ SUBSTRATE_PUBLIC_ORIGIN This server's origins, comma-separated (e.g.
3072
+ https://host:3100,https://alias). A token must carry
3073
+ 'aud' naming one; a token with no 'aud' is refused.
3074
+ Required with auth on a non-loopback
3075
+ HOST; on loopback it defaults to the loopback origins.
3076
+ SUBSTRATE_TLS_KEY_PATH Serve HTTPS. Both are required together — setting one
3077
+ SUBSTRATE_TLS_CERT_PATH without the other refuses to boot.
3078
+ SUBSTRATE_NAMESPACE Default namespace for recall requests that omit one.
3079
+ Without it such requests are refused rather than
3080
+ guessing a namespace that may not exist.
3081
+
3082
+ Natural-language query and the recall embedder are configured by plugin config
3083
+ files under SUBSTRATE_PLUGIN_DIR (substrate-nl.config.json,
3084
+ substrate-recall.config.json), not by environment variables.
3085
+
3086
+ See https://github.com/mnmal-ai/substrate for the full env reference.
3087
+ `;
3088
+ async function runCli(argv) {
3089
+ const [subcommand, ...rest] = argv;
3090
+ if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
3091
+ process.stdout.write(HELP);
3092
+ return subcommand === void 0 ? 1 : 0;
3093
+ }
3094
+ if (subcommand === "--version" || subcommand === "-v" || subcommand === "version") {
3095
+ process.stdout.write(`${version}\n`);
3096
+ return 0;
3097
+ }
3098
+ if (subcommand !== "federate" && (rest.includes("--help") || rest.includes("-h"))) {
3099
+ process.stdout.write(HELP);
3100
+ return 0;
3101
+ }
3102
+ switch (subcommand) {
3103
+ case "serve":
3104
+ await runServe();
3105
+ await new Promise(() => {});
3106
+ return 0;
3107
+ case "mcp":
3108
+ await runMcp();
3109
+ await new Promise(() => {});
3110
+ return 0;
3111
+ case "init": return await runInit(rest);
3112
+ case "check-enums": return await runCheckEnums(rest);
3113
+ case "normalise-vocab": return await runNormaliseVocab(rest);
3114
+ case "backfill-field": return await runBackfillField(rest);
3115
+ case "ask": return await runAsk(rest);
3116
+ case "run": return await runRun(rest);
3117
+ case "federate": return await runFederate(rest, process.env, (s) => process.stdout.write(s), (s) => process.stderr.write(s));
3118
+ default:
3119
+ process.stderr.write(`substrate: unknown subcommand '${subcommand}'\n\n`);
3120
+ process.stderr.write(HELP);
3121
+ return 1;
3122
+ }
3123
+ }
3124
+
3125
+ //#endregion
3126
+ export { parsePositive as a, DEFAULT_SIZING as i, defaultPluginsForPersona as n, parsePort as r, runCli, KNOWN_PLUGINS as t };