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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +32 -14
  2. package/dist/boot-store-BMQUbHKv.js +4086 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
  4. package/dist/cli-DModIbnN.js +3390 -0
  5. package/dist/client.browser.js +2507 -0
  6. package/dist/client.d.ts +222 -171
  7. package/dist/client.js +6 -7
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-Cmkp1qxf.d.ts} +44 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/{plugin-B3NxUCVn.js → plugin-CEOhrEme.js} +149 -6
  19. package/dist/proposals-bootstrap.js +6 -5
  20. package/dist/proposals.config.schema.json +5 -0
  21. package/dist/proposals.d.ts +17 -5
  22. package/dist/proposals.default-config.json +2 -1
  23. package/dist/proposals.js +2 -3
  24. package/dist/recall-bootstrap.js +5 -4
  25. package/dist/recall.config.schema.json +6 -0
  26. package/dist/recall.d.ts +27 -6
  27. package/dist/recall.js +2 -3
  28. package/dist/{repl-DeKzfvNV.js → repl-BvDZy-Ut.js} +52 -26
  29. package/dist/{row-ByLFE2Wx.d.ts → row-D0If4qif.d.ts} +92 -12
  30. package/dist/run-BT123RV1.js +2443 -0
  31. package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
  32. package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
  33. package/dist/script-runner.js +78 -0
  34. package/dist/sdk.d.ts +236 -38
  35. package/dist/sdk.js +5 -110
  36. package/dist/semver-D_zdq0hi.js +17 -0
  37. package/dist/src-BMD2OE--.js +8289 -0
  38. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  39. package/dist/{src-DjIuRjzF.js → src-CKSJ13p8.js} +10231 -4237
  40. package/dist/{src-CkZw6xVD.js → src-CW7eRDss.js} +188 -87
  41. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  42. package/dist/{src-DCy7Iy2l.js → src-DmjwFMu8.js} +900 -77
  43. package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
  44. package/dist/substrate-admin.js +17 -782
  45. package/dist/substrate.js +4 -5206
  46. package/dist/testing.d.ts +473 -96
  47. package/dist/testing.js +19 -165
  48. package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
  49. package/package.json +26 -26
  50. package/dist/dataset-jZS_4ci4.js +0 -1535
  51. package/dist/pg-edges-store-KH_FQCxx.js +0 -381
  52. package/dist/schema-g4FQLr0V.d.ts +0 -433
  53. package/dist/src-BD27zeGF.js +0 -2339
@@ -0,0 +1,2443 @@
1
+ import { _ as AUDIT_EVENT_TYPE, g as buildAuditRow } from "./src-CKSJ13p8.js";
2
+ import { n as trimTrailingSlashes } from "./env-utils-s25Z1YSA.js";
3
+ import { I as decodeList, L as encodeList, M as grantEntryError, g as checkUpdatable, h as checkRevocable, y as newlyGranted } from "./src-DmiUWOLp.js";
4
+ import "./src-B_kHkbsr.js";
5
+ import { A as REVOKE_EXIT_CODES, B as listActiveAdminKeys, C as runRegisterViaRoute, D as formatBootstrapOutput, E as formatDoctorReport, F as BootstrapError, G as ARGV_SPEC, H as describeAdminTarget, I as CLI_ACTOR_KID, J as USAGE, K as validateArgv, L as base64Url, M as runKeyListViaRoute, N as runKeyPatchViaRoute, O as parseBootstrapArgs, P as ACTOR_HINT, R as forUpdate, S as runRegister, T as doctorCommand, U as resolveAdminAuth, V as readKeyById, W as resolveAdminTarget, X as AdminCliError, Y as argvError, Z as pgNoticeOptions, _ as version, b as formatRegisterOutput, c as parseEnv, f as registeredTypes, g as loadPluginsFromDir, i as EnvConfigError, j as UPDATE_EXIT_CODES, k as runBootstrap, l as refuseContractViolation, n as resolvePluginDir, q as RESTART_NOTE, r as BINARY_CONTRACT_VERSION, t as bootStore, u as buildDeferredIndexes, v as openPgDataset, w as grantLines, x as parseRegisterArgs, y as onboardCommand, z as generateAdminKeypair } from "./boot-store-BMQUbHKv.js";
6
+ import { T as substrateFetch } from "./src-FXO5JPyk.js";
7
+ import { C as detectLayout, E as parseSourceBody, S as UUID_REGEX, T as copyRows, _ as isDerivedMigration, a as seqName, c as loadTypeTable, d as MIGRATE_STORE_MARKER_TABLE, f as PLAIN_SCHEMA_NAME, l as typeTableRef, m as assertStoreSchema, o as ensureTypeTable, x as UUID_CHECK_MIGRATION } from "./src-BMD2OE--.js";
8
+ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
9
+ import { dirname } from "node:path";
10
+ import { createHash, randomUUID } from "node:crypto";
11
+ import { statfs } from "node:fs/promises";
12
+ import postgres from "postgres";
13
+ import { PassThrough, Transform } from "node:stream";
14
+ import { pipeline } from "node:stream/promises";
15
+ import { createInterface } from "node:readline";
16
+
17
+ //#region src/admin/commands/list.ts
18
+ /**
19
+ * `list` — print the active Key rows.
20
+ *
21
+ * Without `--url`: read-only, direct-to-postgres, and it DOES NOT
22
+ * AUTHENTICATE, so an admin row here is no evidence admin auth works — that is
23
+ * `doctor`'s question. With `--url`: an authenticated read through the server.
24
+ */
25
+ /**
26
+ * Parse `list`'s arguments. Returns the `--url` base when one was given.
27
+ */
28
+ function parseListArgs(argv) {
29
+ try {
30
+ return parseListArgsInner(argv);
31
+ } catch (err) {
32
+ if (err instanceof AdminCliError) throw argvError("list", err.message, err.exitCode);
33
+ throw err;
34
+ }
35
+ }
36
+ function parseListArgsInner(argv) {
37
+ validateArgv("list", argv);
38
+ const out = {};
39
+ for (let i = 0; i < argv.length; i++) {
40
+ const tok = argv[i] ?? "";
41
+ if (tok === "--url") {
42
+ const value = argv[i + 1];
43
+ if (value === void 0 || value.startsWith("-")) throw new AdminCliError("list: --url requires a base URL, e.g. --url https://host:3100", 1);
44
+ out.url = value;
45
+ i += 1;
46
+ continue;
47
+ }
48
+ if (tok.startsWith("--url=")) {
49
+ const value = tok.slice(6);
50
+ if (value === "") throw new AdminCliError("list: --url requires a base URL, e.g. --url https://host:3100", 1);
51
+ out.url = value;
52
+ }
53
+ }
54
+ return out;
55
+ }
56
+ async function runList(env, openDataset = openPgDataset) {
57
+ const { dataset, close } = await openDataset(env);
58
+ try {
59
+ const { rows } = await dataset.read("Key", { where: { revokedAt: { eq: null } } });
60
+ const out = [];
61
+ for (const row of rows) {
62
+ const kid = typeof row.kid === "string" ? row.kid : "";
63
+ if (kid.length === 0) continue;
64
+ if (row.revokedAt != null) continue;
65
+ const createdAt = row._metadata?.createdAt ?? "";
66
+ out.push({
67
+ kid,
68
+ name: typeof row.name === "string" ? row.name : "",
69
+ capabilities: typeof row.capabilities === "string" ? row.capabilities : "",
70
+ namespaces: typeof row.namespaces === "string" ? row.namespaces : "",
71
+ createdAt
72
+ });
73
+ }
74
+ return out;
75
+ } finally {
76
+ await close();
77
+ }
78
+ }
79
+ /**
80
+ * Provenance line, printed with every result including the empty one, so an
81
+ * unauthenticated direct read is not mistaken for proof that admin auth works
82
+ * — or, when empty, for proof that the right store is empty.
83
+ */
84
+ const PROVENANCE = "read directly from SUBSTRATE_DATABASE_URL — NOT authenticated, and not a check that any credential works.\nTo ask a running server whether admin auth actually works: substrate-admin doctor --url <base>\n";
85
+ function formatListOutput(rows) {
86
+ if (rows.length === 0) return `no active Key rows\n${PROVENANCE}`;
87
+ return `${formatTable(rows)}${PROVENANCE}`;
88
+ }
89
+ /** The aligned table, shared by both modes so they cannot drift apart. */
90
+ function formatTable(rows) {
91
+ const header = {
92
+ kid: "kid",
93
+ name: "name",
94
+ capabilities: "capabilities",
95
+ namespaces: "namespaces",
96
+ createdAt: "createdAt"
97
+ };
98
+ const all = [header, ...rows];
99
+ const widths = {
100
+ kid: Math.max(...all.map((r) => r.kid.length)),
101
+ name: Math.max(...all.map((r) => r.name.length)),
102
+ capabilities: Math.max(...all.map((r) => r.capabilities.length)),
103
+ namespaces: Math.max(...all.map((r) => r.namespaces.length)),
104
+ createdAt: Math.max(...all.map((r) => r.createdAt.length))
105
+ };
106
+ const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
107
+ const divider = [
108
+ "-".repeat(widths.kid),
109
+ "-".repeat(widths.name),
110
+ "-".repeat(widths.capabilities),
111
+ "-".repeat(widths.namespaces),
112
+ "-".repeat(widths.createdAt)
113
+ ].join(" ");
114
+ const lines = [[
115
+ pad(header.kid, widths.kid),
116
+ pad(header.name, widths.name),
117
+ pad(header.capabilities, widths.capabilities),
118
+ pad(header.namespaces, widths.namespaces),
119
+ pad(header.createdAt, widths.createdAt)
120
+ ].join(" "), divider];
121
+ for (const r of rows) lines.push([
122
+ pad(r.kid, widths.kid),
123
+ pad(r.name, widths.name),
124
+ pad(r.capabilities, widths.capabilities),
125
+ pad(r.namespaces, widths.namespaces),
126
+ pad(r.createdAt, widths.createdAt)
127
+ ].join(" "));
128
+ return `${lines.join("\n")}\n`;
129
+ }
130
+ /**
131
+ * Render the AUTHENTICATED read, naming the target and stating that the
132
+ * server verified the credential before answering.
133
+ */
134
+ function formatRemoteListOutput(rows, baseUrl) {
135
+ const mapped = rows.map((r) => ({
136
+ kid: typeof r.kid === "string" ? r.kid : "",
137
+ name: typeof r.name === "string" ? r.name : "",
138
+ capabilities: typeof r.capabilities === "string" ? r.capabilities : "",
139
+ namespaces: typeof r.namespaces === "string" ? r.namespaces : "",
140
+ createdAt: typeof r.createdAt === "string" ? r.createdAt : ""
141
+ }));
142
+ const provenance = `read from ${baseUrl} over the admin-gated route — AUTHENTICATED, and the server accepted this credential.\n`;
143
+ if (mapped.length === 0) return `no active Key rows\n${provenance}`;
144
+ return `${formatTable(mapped)}${provenance}`;
145
+ }
146
+
147
+ //#endregion
148
+ //#region src/admin/migrate-store/progress.ts
149
+ /** Progress of a migrate-store copy, counted off the COPY text stream as it passes, or per converted batch. */
150
+ /**
151
+ * A pass-through that counts rows (one newline each: COPY text escapes the
152
+ * newlines inside values) and reports every `batchRows` rows. A throw from
153
+ * `onProgress` fails the stream, which aborts the copy.
154
+ */
155
+ var RowCounter = class extends Transform {
156
+ table;
157
+ batchRows;
158
+ onProgress;
159
+ rows = 0;
160
+ bytes = 0;
161
+ #next;
162
+ constructor(table, batchRows, onProgress, from = {
163
+ rows: 0,
164
+ bytes: 0
165
+ }) {
166
+ super();
167
+ this.table = table;
168
+ this.batchRows = batchRows;
169
+ this.onProgress = onProgress;
170
+ if (!Number.isInteger(batchRows) || batchRows < 1) throw new Error(`batchRows must be a positive integer (got ${batchRows})`);
171
+ this.rows = from.rows;
172
+ this.bytes = from.bytes;
173
+ this.#next = from.rows - from.rows % batchRows + batchRows;
174
+ }
175
+ /** Counts `rows` converted rows of `bytes` body text, reporting as `_transform` does. */
176
+ add(rows, bytes) {
177
+ this.rows += rows;
178
+ this.bytes += bytes;
179
+ this.#report();
180
+ }
181
+ #report() {
182
+ if (this.rows < this.#next) return;
183
+ this.#next = this.rows - this.rows % this.batchRows + this.batchRows;
184
+ this.onProgress({
185
+ table: this.table,
186
+ rows: this.rows,
187
+ bytes: this.bytes,
188
+ done: false
189
+ });
190
+ }
191
+ _transform(chunk, _enc, cb) {
192
+ try {
193
+ this.bytes += chunk.length;
194
+ for (let i = chunk.indexOf(10); i !== -1; i = chunk.indexOf(10, i + 1)) this.rows++;
195
+ this.#report();
196
+ this.push(chunk);
197
+ cb(null);
198
+ } catch (err) {
199
+ cb(err);
200
+ }
201
+ }
202
+ };
203
+
204
+ //#endregion
205
+ //#region src/admin/migrate-store/source.ts
206
+ /**
207
+ * Read-only inventory of a migrate-store source. Every read runs in one
208
+ * REPEATABLE READ, READ ONLY transaction, so the inventory is one snapshot and
209
+ * nothing here can write to the source. It never runs migrations and never
210
+ * goes through `assertServerVersion`: the source may be PG 17.
211
+ */
212
+ async function inspectSource(sql) {
213
+ return await sql.begin("isolation level repeatable read read only", async (tx) => {
214
+ await assertStoreSchema(tx);
215
+ const layout = await detectLayout(tx);
216
+ if (layout === "absent") throw new Error("the source schema holds no rows table");
217
+ if (layout === "tables") throw new Error("the source is already in the tables layout; migrate-store copies a legacy or partitioned store");
218
+ const [version] = await tx`SELECT current_setting('server_version_num')::int AS v`;
219
+ const [ledger] = await tx`SELECT to_regclass('migrations') IS NOT NULL AS present`;
220
+ const appliedMigrations = ledger?.present ? (await tx`SELECT version FROM migrations ORDER BY version`).map((r) => r.version) : [];
221
+ const tableRows = await tx`
222
+ SELECT c.relname AS name,
223
+ -- pg_partition_tree is empty for an ordinary table.
224
+ (CASE WHEN c.relkind = 'p'
225
+ THEN (SELECT coalesce(sum(pg_table_size(t.relid)), 0) FROM pg_partition_tree(c.oid) t WHERE t.isleaf)
226
+ ELSE pg_table_size(c.oid) END)::text AS bytes
227
+ FROM pg_class c
228
+ WHERE c.relnamespace = current_schema()::regnamespace
229
+ AND c.relkind IN ('r', 'p') AND NOT c.relispartition
230
+ ORDER BY c.relname`;
231
+ const colRows = await tx`
232
+ SELECT c.relname AS "table", a.attname AS col
233
+ FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid
234
+ WHERE c.relnamespace = current_schema()::regnamespace
235
+ AND c.relkind IN ('r', 'p') AND NOT c.relispartition
236
+ AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''
237
+ ORDER BY c.relname, a.attnum`;
238
+ const columns = {};
239
+ for (const r of colRows) {
240
+ const list = columns[r.table] ?? [];
241
+ list.push(r.col);
242
+ columns[r.table] = list;
243
+ }
244
+ const types = await tx`
245
+ SELECT namespace, type,
246
+ count(*) FILTER (WHERE deleted_at IS NULL)::text AS live,
247
+ count(*) FILTER (WHERE deleted_at IS NOT NULL)::text AS deleted,
248
+ coalesce(sum(pg_column_size(r.*)), 0)::text AS bytes
249
+ FROM rows r GROUP BY namespace, type ORDER BY namespace, type`;
250
+ const nonUuid = (table, column, nsCol, typeCol) => tx`
251
+ SELECT ${tx(nsCol)} AS namespace, ${tx(typeCol)} AS type, ${tx(column)} AS id
252
+ FROM ${tx(table)} WHERE ${tx(column)} !~ ${UUID_REGEX}
253
+ ORDER BY 1, 2, 3 LIMIT 20`.then((rs) => rs.map((r) => ({
254
+ table,
255
+ column,
256
+ ...r
257
+ })));
258
+ const nonUuidIds = appliedMigrations.includes("0002_uuid_format_check") ? [] : [
259
+ ...await nonUuid("rows", "id", "namespace", "type"),
260
+ ...columns.short_ids ? await nonUuid("short_ids", "row_id", "namespace", "type") : [],
261
+ ...columns.edges ? await nonUuid("edges", "from_id", "from_ns", "from_type") : [],
262
+ ...columns.edges ? await nonUuid("edges", "to_id", "to_ns", "to_type") : []
263
+ ];
264
+ const [dims] = columns.embeddings ? await tx`
265
+ SELECT a.atttypmod AS dims FROM pg_attribute a
266
+ WHERE a.attrelid = to_regclass('embeddings') AND a.attname = 'embedding' AND NOT a.attisdropped` : [];
267
+ const extensions = await tx`SELECT extname, extversion FROM pg_extension ORDER BY extname`;
268
+ const sessions = await tx`
269
+ SELECT pid, extract(epoch FROM backend_start)::text AS start, usename,
270
+ application_name AS "applicationName", client_addr::text AS "clientAddr",
271
+ backend_type AS "backendType", state
272
+ FROM pg_stat_activity
273
+ WHERE datname = current_database() AND pid <> pg_backend_pid()
274
+ -- Another role's session shows a NULL backend_type to a non-monitoring role.
275
+ AND (backend_type = 'client backend' OR (backend_type IS NULL AND usesysid IS NOT NULL))
276
+ ORDER BY pid`;
277
+ return {
278
+ serverVersionNum: version?.v ?? 0,
279
+ layout,
280
+ appliedMigrations,
281
+ hasSeq: columns.rows?.includes("seq") ?? false,
282
+ hasVisibleSeqs: columns.visible_seqs !== void 0,
283
+ types: types.map((t) => ({
284
+ ...t,
285
+ live: Number(t.live),
286
+ deleted: Number(t.deleted),
287
+ bytes: Number(t.bytes)
288
+ })),
289
+ tables: tableRows.map((t) => t.name),
290
+ columns,
291
+ tableBytes: Object.fromEntries(tableRows.map((t) => [t.name, Number(t.bytes)])),
292
+ nonUuidIds,
293
+ vectorDims: dims !== void 0 && dims.dims > 0 ? dims.dims : null,
294
+ extensions: Object.fromEntries(extensions.map((e) => [e.extname, e.extversion])),
295
+ otherSessions: sessions.length,
296
+ sessions
297
+ };
298
+ });
299
+ }
300
+ /** The `rows` columns the engine itself defined in the legacy and partitioned layouts. */
301
+ const ENGINE_ROWS_COLUMNS = /* @__PURE__ */ new Set([
302
+ "namespace",
303
+ "type",
304
+ "id",
305
+ "body",
306
+ "deleted_at",
307
+ "created_at",
308
+ "updated_at",
309
+ "created_by_kind",
310
+ "created_by_id",
311
+ "updated_by_kind",
312
+ "updated_by_id",
313
+ "seq"
314
+ ]);
315
+ /** The fields a target type table declares, orphaned columns excluded. */
316
+ function declaredFields(table) {
317
+ if (table === void 0) return [];
318
+ return [...table.columns().filter((c) => c.state !== "orphaned").map((c) => c.field), ...table.pending];
319
+ }
320
+ /**
321
+ * SQL for a source row's body as the old engine read it. A plugin migration could add a `rows`
322
+ * column mirroring a body field (cortext's `archived boolean NOT NULL DEFAULT false`), and old
323
+ * filters read that column, so a body lacking the key still matched `archived eq false`. A
324
+ * non-null mirror column named after a declared field fills that field when the body lacks it;
325
+ * where the body has the key, the body wins.
326
+ * shortcut: matches a mirror column to its field by name only (every known plugin uses the field
327
+ * name); a plugin that renamed its column would need its promotedColumns map read here.
328
+ */
329
+ function sourceBodySql(rowsColumns, declared) {
330
+ const mirrored = rowsColumns.filter((c) => !ENGINE_ROWS_COLUMNS.has(c) && declared.includes(c));
331
+ if (mirrored.length === 0) return "body";
332
+ return `(jsonb_strip_nulls(jsonb_build_object(${mirrored.map((c) => `'${c.replace(/'/g, "''")}', "${c.replace(/"/g, "\"\"")}"`).join(", ")})) || body)`;
333
+ }
334
+
335
+ //#endregion
336
+ //#region src/admin/migrate-store/copy.ts
337
+ /**
338
+ * The migrate-store copy: converts a legacy or partitioned source into a
339
+ * target `bootStore` prepared in the `tables` layout, all from one REPEATABLE
340
+ * READ, READ ONLY source snapshot. `rows` is converted: each source type is
341
+ * streamed with a cursor, in `batchRows` batches, into its type table by
342
+ * `copyRows` (columns plus `extra`, ids into `row_ids`). Every other table
343
+ * moves with `COPY … TO STDOUT` piped into `COPY … FROM STDIN`. Nothing here
344
+ * writes to the source.
345
+ *
346
+ * Two phases around a re-boot, on one source snapshot. Phase 1 copies the
347
+ * rows (and their shortIds) that declare storage: `_system`,
348
+ * `_system_proposals` and every TypeProposal and FieldProposal. The second
349
+ * boot replays those proposals as serve does, so every proposed type is
350
+ * registered, with its table and declared fields, before phase 2 copies
351
+ * everything else. A source type nothing declares gets a table with no
352
+ * columns, so its fields all go to `extra`, and is reported `defaulted`.
353
+ * Last, one promotion sweep moves the values of fields declared only by the
354
+ * replay (phase 1 converted them into `extra`) into their columns.
355
+ *
356
+ * Progress lives in the marker table on the target. A rerun after an
357
+ * interruption restarts cleanly: it empties the planned tables, keeps the
358
+ * seed rows the first run recorded, and copies again.
359
+ */
360
+ /** The misfits listed per type, beside the full count. */
361
+ const MISFITS_LISTED = 100;
362
+ /** A source table or column with nowhere to go on the target. Thrown before any data moves. */
363
+ var MigrateStoreColumnError = class extends Error {
364
+ table;
365
+ column;
366
+ name = "MigrateStoreColumnError";
367
+ constructor(table, column) {
368
+ super(column === null ? `the target has no table "${table}" to copy into` : `the target's "${table}" has no column "${column}", which the source has`);
369
+ this.table = table;
370
+ this.column = column;
371
+ }
372
+ };
373
+ const STARTED = "copy:started";
374
+ const SEED = "seed:";
375
+ /** The `rows` / `short_ids` predicate phase 1 copies; phase 2 copies its complement. Both columns are NOT NULL. */
376
+ const PHASE1_ROWS = "namespace IN ('_system', '_system_proposals') OR type IN ('TypeProposal', 'FieldProposal')";
377
+ const PHASED = /* @__PURE__ */ new Set(["rows", "short_ids"]);
378
+ /** Converted rather than copied: the target has no `rows`. */
379
+ const CONVERTED = "rows";
380
+ async function copyStore(source, boot, plan, opts) {
381
+ let target = await boot();
382
+ let open = target;
383
+ try {
384
+ let tsql = sqlOf(target);
385
+ await tsql`CREATE TABLE IF NOT EXISTS ${tsql(MIGRATE_STORE_MARKER_TABLE)} (step text PRIMARY KEY, done_at timestamptz)`;
386
+ const identity = await checkColumns(tsql, plan);
387
+ if (await restartIfStarted(tsql, plan)) {
388
+ open = void 0;
389
+ await target.close();
390
+ target = await boot();
391
+ open = target;
392
+ tsql = sqlOf(target);
393
+ }
394
+ const src = await source.reserve();
395
+ let streaming = false;
396
+ let snapshotOpen = true;
397
+ try {
398
+ await src.unsafe("BEGIN ISOLATION LEVEL REPEATABLE READ, READ ONLY");
399
+ await src.unsafe("SET LOCAL DateStyle = 'ISO, YMD'");
400
+ await src.unsafe("SET LOCAL TimeZone = 'UTC'");
401
+ const keptSeeds = await reconcileSeeds(src, tsql, target);
402
+ const rowsPlan = plan.tables.find((t) => t.name === CONVERTED);
403
+ const misfits = {};
404
+ const totals = /* @__PURE__ */ new Map();
405
+ const copy = async (t, filter, tables) => {
406
+ const start = performance.now();
407
+ const prev = totals.get(t.name) ?? {
408
+ rows: 0,
409
+ bytes: 0,
410
+ ms: 0
411
+ };
412
+ const counter = new RowCounter(t.name, opts.batchRows, opts.onProgress, prev);
413
+ streaming = true;
414
+ if (t.name === CONVERTED) await convertRows(src, tsql, t, filter, tables, counter, opts.batchRows, misfits);
415
+ else await copyTable(src, tsql, t, identity.get(t.name) ?? [], counter, filter);
416
+ streaming = false;
417
+ totals.set(t.name, {
418
+ rows: counter.rows,
419
+ bytes: counter.bytes,
420
+ ms: prev.ms + Math.round(performance.now() - start)
421
+ });
422
+ };
423
+ const phase1 = await prepareTables(src, target, PHASE1_ROWS, false);
424
+ for (const t of plan.tables.filter((p) => PHASED.has(p.name))) await copy(t, PHASE1_ROWS, phase1.tables);
425
+ await markStep(tsql, "copy:phase1");
426
+ await snapshotRows(tsql);
427
+ open = void 0;
428
+ await target.close();
429
+ target = await boot();
430
+ open = target;
431
+ tsql = sqlOf(target);
432
+ await assertRebootWroteNothing(tsql);
433
+ const phase2 = await prepareTables(src, target, null, true);
434
+ const tables = [];
435
+ for (const t of plan.tables) {
436
+ await copy(t, PHASED.has(t.name) ? `NOT (${PHASE1_ROWS})` : null, phase2.tables);
437
+ await markStep(tsql, `copy:${t.name}`);
438
+ const done = totals.get(t.name);
439
+ tables.push({
440
+ name: t.name,
441
+ ...done
442
+ });
443
+ opts.onProgress({
444
+ table: t.name,
445
+ rows: done.rows,
446
+ bytes: done.bytes,
447
+ done: true
448
+ });
449
+ }
450
+ await markStep(tsql, "copy:phase2");
451
+ await advanceSequences(tsql, identity);
452
+ await src.unsafe("COMMIT");
453
+ snapshotOpen = false;
454
+ src.release();
455
+ if (rowsPlan !== void 0) await settleFields(target, opts.batchRows);
456
+ await markStep(tsql, "copy:done");
457
+ return {
458
+ tables,
459
+ keptSeeds,
460
+ defaulted: phase2.defaulted,
461
+ misfits,
462
+ target
463
+ };
464
+ } catch (err) {
465
+ if (!snapshotOpen) throw err;
466
+ const released = src.unsafe("ROLLBACK").catch(() => void 0).then(() => src.release()).catch(() => void 0);
467
+ if (!streaming) await released;
468
+ throw err;
469
+ }
470
+ } catch (err) {
471
+ await open?.close().catch(() => void 0);
472
+ throw err;
473
+ }
474
+ }
475
+ function sqlOf(target) {
476
+ if (target.sql === null) throw new Error("migrate-store copies into a postgres target only");
477
+ return target.sql;
478
+ }
479
+ const quoteIdent = (name) => `"${name.replace(/"/g, "\"\"")}"`;
480
+ /** The target's type tables, each with its (quoted) relation. */
481
+ async function typeTablesOf(tsql) {
482
+ return (await tsql`
483
+ SELECT namespace, type, table_name FROM substrate_type_tables ORDER BY namespace, type`).map((r) => ({
484
+ namespace: r.namespace,
485
+ type: r.type,
486
+ rel: quoteIdent(r.table_name)
487
+ }));
488
+ }
489
+ /**
490
+ * SQL over every target row: `(namespace, type, id, h)`, `h` an md5 of the
491
+ * stored row with its null columns dropped, so a column added by a re-boot
492
+ * changes no row's hash. `null` when there are no type tables.
493
+ */
494
+ async function targetRowsSql(tsql) {
495
+ const tables = await typeTablesOf(tsql);
496
+ if (tables.length === 0) return null;
497
+ const lit = (s) => `'${s.replace(/'/g, "''")}'`;
498
+ return tables.map((t) => `SELECT ${lit(t.namespace)}::text AS namespace, ${lit(t.type)}::text AS type, x.id, md5(jsonb_strip_nulls(to_jsonb(x))::text) AS h FROM ${t.rel} x`).join(" UNION ALL ");
499
+ }
500
+ const SNAPSHOT = "substrate_migrate_store_reboot_rows";
501
+ /** Records every target row's key and content hash, for `assertRebootWroteNothing`. */
502
+ async function snapshotRows(tsql) {
503
+ await tsql`DROP TABLE IF EXISTS ${tsql(SNAPSHOT)}`;
504
+ const all = await targetRowsSql(tsql);
505
+ await tsql.unsafe(`CREATE UNLOGGED TABLE ${quoteIdent(SNAPSHOT)} AS ${all ?? "SELECT NULL::text AS namespace, NULL::text AS type, NULL::text AS id, NULL::text AS h WHERE false"}`);
506
+ }
507
+ /** Refuses a re-boot that added, removed or changed a row, naming up to ten of each. */
508
+ async function assertRebootWroteNothing(tsql) {
509
+ const all = await targetRowsSql(tsql) ?? "SELECT NULL::text AS namespace, NULL::text AS type, NULL::text AS id, NULL::text AS h WHERE false";
510
+ const diff = await tsql.unsafe(`
511
+ SELECT CASE WHEN s.id IS NULL THEN 'added' WHEN r.id IS NULL THEN 'removed' ELSE 'changed' END AS change,
512
+ coalesce(r.namespace, s.namespace) AS namespace, coalesce(r.type, s.type) AS type,
513
+ coalesce(r.id, s.id) AS id
514
+ FROM (${all}) r
515
+ FULL JOIN ${quoteIdent(SNAPSHOT)} s USING (namespace, type, id)
516
+ WHERE s.id IS NULL OR r.id IS NULL OR r.h <> s.h
517
+ ORDER BY 1, 2, 3, 4 LIMIT 30`);
518
+ await tsql`DROP TABLE ${tsql(SNAPSHOT)}`;
519
+ if (diff.length === 0) return;
520
+ const named = [
521
+ "added",
522
+ "changed",
523
+ "removed"
524
+ ].map((c) => {
525
+ const rows = diff.filter((d) => d.change === c).slice(0, 10);
526
+ return rows.length === 0 ? "" : `${c}: ${rows.map((d) => `${d.namespace}/${d.type}/${d.id}`).join(", ")}`;
527
+ }).filter((s) => s !== "").join("; ");
528
+ throw new Error(`the target's re-boot wrote rows the source does not have (${named}). The boot writes them because the source lacks them, usually the _system/AuditEvent of kind 'bootstrap' that serve records on a store's first boot with keys. Boot the source once with substrate serve so it records them itself, stop it, then rerun migrate-store, which restarts cleanly.`);
529
+ }
530
+ /** Refuses a plan column the target lacks; returns each table's identity-always columns among the planned ones. */
531
+ async function checkColumns(tsql, plan) {
532
+ const copied = plan.tables.filter((t) => t.name !== CONVERTED);
533
+ const rows = await tsql`
534
+ SELECT c.relname AS "table", a.attname AS col, a.attidentity AS ident
535
+ FROM pg_attribute a
536
+ JOIN pg_class c ON c.oid = a.attrelid
537
+ JOIN pg_namespace n ON n.oid = c.relnamespace
538
+ WHERE n.nspname = current_schema() AND c.relname = ANY(${copied.map((t) => t.name)}::text[])
539
+ AND c.relkind IN ('r', 'p') AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''`;
540
+ const identity = /* @__PURE__ */ new Map();
541
+ for (const t of copied) {
542
+ const cols = rows.filter((r) => r.table === t.name);
543
+ if (cols.length === 0) throw new MigrateStoreColumnError(t.name, null);
544
+ const have = new Set(cols.map((c) => c.col));
545
+ const missing = t.columns.find((c) => !have.has(c));
546
+ if (missing !== void 0) throw new MigrateStoreColumnError(t.name, missing);
547
+ const always = cols.filter((c) => c.ident === "a" && t.columns.includes(c.col));
548
+ if (always.length > 0) identity.set(t.name, always.map((c) => c.col));
549
+ }
550
+ return identity;
551
+ }
552
+ const keyOf = (r) => JSON.stringify([
553
+ r.namespace,
554
+ r.type,
555
+ r.id
556
+ ]);
557
+ /** `(namespace, type, id) IN (…)` over `keys`, as three bound arrays. */
558
+ function inKeys(sql, keys) {
559
+ return sql`(namespace, type, id) IN (SELECT * FROM unnest(
560
+ ${keys.map((k) => k.namespace)}::text[], ${keys.map((k) => k.type)}::text[], ${keys.map((k) => k.id)}::text[]))`;
561
+ }
562
+ /**
563
+ * Deletes target rows: those in `keys`, or (`except`) all but those. From each
564
+ * type table and from `row_ids`, whose delete cascades to `short_ids`.
565
+ */
566
+ async function deleteTargetRows(t, keys, except) {
567
+ for (const table of await typeTablesOf(t)) {
568
+ const ids = keys.filter((k) => k.namespace === table.namespace && k.type === table.type).map((k) => k.id);
569
+ if (!except && ids.length === 0) continue;
570
+ await t.unsafe(`DELETE FROM ${table.rel} WHERE ${except ? "NOT " : ""}(id = ANY($1::text[]))`, [ids]);
571
+ }
572
+ await t`DELETE FROM row_ids WHERE ${except ? t`NOT` : t``} ${inKeys(t, keys)}`;
573
+ }
574
+ /** After an interrupted run: empties every planned table but the seed rows that run recorded. True when it did. */
575
+ async function restartIfStarted(tsql, plan) {
576
+ const marker = tsql(MIGRATE_STORE_MARKER_TABLE);
577
+ const [started] = await tsql`SELECT 1 FROM ${marker} WHERE step = ${STARTED}`;
578
+ if (started === void 0) return false;
579
+ const seeds = (await tsql`SELECT step FROM ${marker} WHERE starts_with(step, ${SEED})`).map((r) => {
580
+ const [namespace, type, id] = JSON.parse(r.step.slice(5));
581
+ return {
582
+ namespace,
583
+ type,
584
+ id
585
+ };
586
+ });
587
+ const others = plan.tables.map((p) => p.name).filter((n) => !PHASED.has(n));
588
+ await tsql.begin(async (tx) => {
589
+ const t = tx;
590
+ await deleteTargetRows(t, seeds, true);
591
+ if (others.length > 0) await t`TRUNCATE ${t(others)}`;
592
+ });
593
+ return true;
594
+ }
595
+ /**
596
+ * Deletes each target row the source also holds, so the source row replaces
597
+ * it, and records the rest as seeds. Every row still on the target must be of
598
+ * a type the target registers, as everything the prepare step writes is.
599
+ */
600
+ async function reconcileSeeds(src, tsql, target) {
601
+ const present = await tsql`SELECT namespace, type, id FROM row_ids ORDER BY namespace, type, id`;
602
+ const inSource = present.length === 0 ? [] : await src`SELECT namespace, type, id FROM rows WHERE ${inKeys(src, [...present])}`;
603
+ const replaced = new Set(inSource.map(keyOf));
604
+ const kept = present.filter((r) => !replaced.has(keyOf(r))).map(({ namespace, type, id }) => ({
605
+ namespace,
606
+ type,
607
+ id
608
+ }));
609
+ for (const r of kept) if (registeredDataset(target, r.namespace, r.type) === void 0) throw new Error(`target row ${r.namespace}/${r.type}/${r.id} is not one the prepare step wrote; refusing to copy alongside it`);
610
+ const marker = tsql(MIGRATE_STORE_MARKER_TABLE);
611
+ await tsql.begin(async (tx) => {
612
+ const t = tx;
613
+ if (inSource.length > 0) await deleteTargetRows(t, inSource.map(({ namespace, type, id }) => ({
614
+ namespace,
615
+ type,
616
+ id
617
+ })), false);
618
+ await t`DELETE FROM ${marker} WHERE starts_with(step, ${SEED}) OR starts_with(step, 'copy:')`;
619
+ const steps = [STARTED, ...kept.map((k) => SEED + keyOf(k))];
620
+ await t`INSERT INTO ${marker} ${t(steps.map((step) => ({
621
+ step,
622
+ done_at: /* @__PURE__ */ new Date()
623
+ })))}`;
624
+ });
625
+ return kept;
626
+ }
627
+ function registeredDataset(target, ns, type) {
628
+ if (!target.datasets.has(ns)) return void 0;
629
+ if (target.engine.registryFor(ns)?.get(type)?.kind !== "type") return void 0;
630
+ return target.datasets.get(ns);
631
+ }
632
+ /**
633
+ * Gives every source type `filter` picks its table and returns their
634
+ * descriptors: a registered type's through its dataset, with its declared
635
+ * fields and unique indexes; any other's with no field columns (its fields
636
+ * all go to `extra`), listed in `defaulted` when `report` is set.
637
+ */
638
+ async function prepareTables(src, target, filter, report) {
639
+ const tsql = sqlOf(target);
640
+ const pairs = await src`SELECT DISTINCT namespace, type FROM rows ${filter === null ? src`` : src`WHERE ${src.unsafe(filter)}`} ORDER BY namespace, type`;
641
+ const tables = /* @__PURE__ */ new Map();
642
+ const defaulted = [];
643
+ const [uuid] = await tsql`
644
+ SELECT EXISTS (SELECT 1 FROM migrations WHERE version = ${UUID_CHECK_MIGRATION}) AS on`;
645
+ for (const { namespace, type } of pairs) {
646
+ const key = `${namespace}/${type}`;
647
+ const dataset = registeredDataset(target, namespace, type);
648
+ if (dataset === void 0 && report) defaulted.push(key);
649
+ try {
650
+ if (dataset !== void 0) await dataset.ensureTypeStorage?.(type, { indexes: "unique" });
651
+ else await ensureTypeTable(tsql, {
652
+ namespace,
653
+ type,
654
+ fields: {},
655
+ newFields: "column",
656
+ enforceUuidCheck: uuid?.on === true,
657
+ createOnly: true
658
+ });
659
+ } catch (err) {
660
+ throw new Error(`preparing storage for ${key} failed: ${err.message}`, { cause: err });
661
+ }
662
+ const table = await loadTypeTable(tsql, namespace, type);
663
+ if (table === void 0) throw new Error(`preparing storage for ${key} made no table`);
664
+ tables.set(key, table);
665
+ }
666
+ return {
667
+ tables,
668
+ defaulted
669
+ };
670
+ }
671
+ /**
672
+ * Converts the source rows `filter` picks, type by type, each streamed with a
673
+ * cursor in `batchRows` batches into its type table. A row the table already
674
+ * holds, or a refusal (a declared unique index), fails the copy loudly.
675
+ */
676
+ async function convertRows(src, tsql, t, filter, tables, counter, batchRows, misfits) {
677
+ const where = filter === null ? src`` : src`AND (${src.unsafe(filter)})`;
678
+ const seq = t.columns.includes("seq") ? src`seq::text` : src`NULL::text`;
679
+ const pairs = await src`
680
+ SELECT DISTINCT namespace, type FROM rows WHERE true ${where} ORDER BY namespace, type`;
681
+ for (const { namespace, type } of pairs) {
682
+ const key = `${namespace}/${type}`;
683
+ const table = tables.get(key);
684
+ if (table === void 0) throw new Error(`internal: no table prepared for ${key}`);
685
+ const cursor = src`
686
+ SELECT id, ${src.unsafe(sourceBodySql(t.columns, declaredFields(table)))}::text AS body, deleted_at::text, created_at::text, updated_at::text,
687
+ created_by_kind, created_by_id, updated_by_kind, updated_by_id,
688
+ ${seq} AS seq
689
+ FROM rows WHERE namespace = ${namespace} AND type = ${type} ${where}
690
+ ORDER BY id`.cursor(batchRows);
691
+ for await (const batch of cursor) {
692
+ let result;
693
+ try {
694
+ result = await copyRows(tsql, table, batch.map((r) => ({
695
+ ...r,
696
+ body: parseSourceBody(r.body)
697
+ })));
698
+ } catch (err) {
699
+ throw rowsError(key, err);
700
+ }
701
+ if (result.inserted !== batch.length) throw new Error(`copying rows failed: ${key}: ${batch.length - result.inserted} source row(s) were already on the target`);
702
+ if (result.misfits.length > 0) {
703
+ const listed = misfits[key] ?? {
704
+ count: 0,
705
+ first: []
706
+ };
707
+ listed.count += result.misfits.length;
708
+ listed.first.push(...result.misfits.slice(0, 100 - listed.first.length));
709
+ misfits[key] = listed;
710
+ }
711
+ counter.add(batch.length, batch.reduce((n, r) => n + Buffer.byteLength(r.body), 0));
712
+ }
713
+ }
714
+ }
715
+ /** A conversion failure as one line naming the type; a unique refusal names the declared index and the key. */
716
+ function rowsError(key, err) {
717
+ const pg = err;
718
+ if (pg?.code === "23505" && typeof pg.constraint_name === "string") return new Error(`copying rows failed: ${key}: unique index ${pg.constraint_name} refuses a source row whose key another row already holds${typeof pg.detail === "string" ? ` (${pg.detail})` : ""}. Resolve the duplicate in the source, then rerun migrate-store, which restarts cleanly.`, { cause: err });
719
+ const detail = typeof pg?.detail === "string" ? ` (${pg.detail})` : "";
720
+ return new Error(`copying rows failed: ${key}: ${err.message ?? String(err)}${detail}`, { cause: err });
721
+ }
722
+ /**
723
+ * One promotion sweep over the target: a field declared only once the re-boot
724
+ * replayed its proposal had its phase-1 values converted into `extra`, so it
725
+ * is `promoting` (or `pending`) until moved into its column. Fails loudly,
726
+ * naming each field, when one is not promoted.
727
+ */
728
+ async function settleFields(target, batchRows) {
729
+ const stuck = (await target.dataset.promotePendingFields?.({
730
+ lockTimeoutMs: 6e4,
731
+ batchRows,
732
+ noWriters: true
733
+ }) ?? []).filter((e) => e.kind !== "promoted");
734
+ if (stuck.length > 0) throw new Error(`settling declared fields failed: ${stuck.map((e) => `${e.namespace}/${e.type}.${e.field} ${e.kind}${e.error ? ` (${e.error})` : ""}`).join("; ")}. Rerun migrate-store, which restarts cleanly.`);
735
+ }
736
+ async function copyTable(src, tsql, t, identityCols, counter, filter) {
737
+ const where = filter === null ? src`` : src`WHERE ${src.unsafe(filter)}`;
738
+ const out = await src`COPY (SELECT ${src(t.columns)} FROM ${src(t.name)} ${where}) TO STDOUT`.readable();
739
+ const feed = new PassThrough();
740
+ out.on("error", (err) => feed.destroy(err));
741
+ out.pipe(feed);
742
+ try {
743
+ if (identityCols.length === 0) {
744
+ await copyIn(tsql`COPY ${tsql(t.name)} (${tsql(t.columns)}) FROM STDIN`, feed, counter);
745
+ return;
746
+ }
747
+ await tsql.begin(async (tx) => {
748
+ const x = tx;
749
+ const stage = x(`migrate_stage_${t.name}`);
750
+ await x`CREATE TEMP TABLE ${stage} (LIKE ${x(t.name)} INCLUDING DEFAULTS) ON COMMIT DROP`;
751
+ await copyIn(x`COPY ${stage} (${x(t.columns)}) FROM STDIN`, feed, counter);
752
+ await x`INSERT INTO ${x(t.name)} (${x(t.columns)}) OVERRIDING SYSTEM VALUE SELECT ${x(t.columns)} FROM ${stage}`;
753
+ });
754
+ } catch (err) {
755
+ out.unpipe(feed);
756
+ feed.destroy();
757
+ out.resume();
758
+ const detail = err.detail;
759
+ throw new Error(`copying ${t.name} failed: ${err.message}${detail ? ` (${detail})` : ""}`, { cause: err });
760
+ }
761
+ }
762
+ /**
763
+ * Pipes `feed` through `counter` into a `COPY … FROM STDIN`. postgres.js 3.4.9
764
+ * never finishes the writable when the server rejects the COPY, so the
765
+ * query's own reject is raced as the failure signal.
766
+ */
767
+ async function copyIn(query, feed, counter) {
768
+ const q = query;
769
+ const reject = q.reject;
770
+ const failed = new Promise((_, fail) => {
771
+ q.reject = (err) => {
772
+ fail(err);
773
+ reject(err);
774
+ };
775
+ });
776
+ failed.catch(() => void 0);
777
+ const into = await query.writable();
778
+ await Promise.race([pipeline(feed, counter, into), failed]);
779
+ }
780
+ /**
781
+ * Moves every shortId sequence to the highest copied shortId of the
782
+ * (namespace, type) pairs sharing its name, creating it if missing, and every
783
+ * copied identity column's sequence to its column's maximum.
784
+ */
785
+ async function advanceSequences(tsql, identity) {
786
+ const maxes = await tsql`SELECT namespace, type, max(short_id)::text AS max FROM short_ids GROUP BY namespace, type`;
787
+ const byName = /* @__PURE__ */ new Map();
788
+ for (const m of maxes) {
789
+ const name = seqName(m.namespace, m.type);
790
+ const max = BigInt(m.max);
791
+ if ((byName.get(name) ?? 0n) < max) byName.set(name, max);
792
+ }
793
+ for (const [name, max] of byName) {
794
+ await tsql`CREATE SEQUENCE IF NOT EXISTS ${tsql(name)}`;
795
+ await tsql`SELECT setval(${`"${name}"`}::regclass, ${max.toString()}::bigint)`;
796
+ }
797
+ for (const [table, cols] of identity) for (const col of cols) await tsql`
798
+ SELECT setval(pg_get_serial_sequence(quote_ident(${table}), ${col}), m)
799
+ FROM (SELECT max(${tsql(col)}) AS m FROM ${tsql(table)}) s WHERE m IS NOT NULL`;
800
+ }
801
+ async function markStep(tsql, step) {
802
+ await tsql`
803
+ INSERT INTO ${tsql(MIGRATE_STORE_MARKER_TABLE)} (step, done_at) VALUES (${step}, now())
804
+ ON CONFLICT (step) DO UPDATE SET done_at = excluded.done_at`;
805
+ }
806
+
807
+ //#endregion
808
+ //#region src/admin/migrate-store/preflight.ts
809
+ /** Pure preflight: turns a source inventory plus target facts into refusals, warnings and a copy plan. */
810
+ /** Each old layout's baseline ledger version, as the last release that booted it recorded it. */
811
+ const OLD_BASELINES = {
812
+ legacy: "0001_baseline",
813
+ partitioned: "0001p_partitioned_baseline"
814
+ };
815
+ /** Every static ledger version an old-layout store can hold. */
816
+ const OLD_MIGRATIONS = /* @__PURE__ */ new Set([
817
+ ...Object.values(OLD_BASELINES),
818
+ UUID_CHECK_MIGRATION,
819
+ "0003_safe_casts",
820
+ "0004_visible_seq"
821
+ ]);
822
+ /** `rows` is converted into type tables, which writes `row_ids` too; the rest are copied as they are. */
823
+ const ENGINE_COPIED = [
824
+ "rows",
825
+ "short_ids",
826
+ "edges",
827
+ "visible_seqs"
828
+ ];
829
+ const NOT_COPIED = [
830
+ "idempotency",
831
+ "migrations",
832
+ "migrations_audit",
833
+ "kernel_migrations",
834
+ MIGRATE_STORE_MARKER_TABLE
835
+ ];
836
+ /** The extension a copied table depends on. shortcut: recall's only, upgrade when another plugin table needs one. */
837
+ const TABLE_EXTENSION = { embeddings: "vector" };
838
+ const PG17 = 17e4;
839
+ const PG18 = 18e4;
840
+ function preflight(source, target, opts) {
841
+ const refusals = [];
842
+ const warnings = [];
843
+ if (source.serverVersionNum < PG17) refusals.push(`source is PostgreSQL ${source.serverVersionNum} (server_version_num); 170000 or later is required`);
844
+ if (target.serverVersionNum < PG18) refusals.push(`target is PostgreSQL ${target.serverVersionNum} (server_version_num); 180000 or later is required`);
845
+ const baselines = Object.values(OLD_BASELINES);
846
+ const unknownVersions = source.appliedMigrations.filter((v) => !OLD_MIGRATIONS.has(v) && !isDerivedMigration(v));
847
+ if (unknownVersions.length > 0) refusals.push(`source ledger holds migrations this binary does not know: ${unknownVersions.join(", ")}`);
848
+ if (!source.appliedMigrations.some((v) => baselines.includes(v))) refusals.push(`source ledger lacks ${baselines.join(" / ")}; found: ${source.appliedMigrations.join(", ") || "no migrations"}`);
849
+ if (target.layout === "legacy" || target.layout === "partitioned") refusals.push(`target is a ${target.layout} store; migrate-store copies into the tables layout, so point it at an empty database or schema`);
850
+ if (!target.empty && !target.createdByUs) refusals.push("target already holds data and was not created by migrate-store");
851
+ const otherBaseline = baselines.find((b) => b !== OLD_BASELINES[source.layout]);
852
+ if (otherBaseline !== void 0 && source.appliedMigrations.includes(otherBaseline)) refusals.push(`source ledger records ${otherBaseline} but rows is ${source.layout}`);
853
+ if (source.appliedMigrations.includes("0002_uuid_format_check") && !target.enforceUuidCheck) refusals.push(`source enforces the UUID check (${UUID_CHECK_MIGRATION}) but the target would not: run migrate-store with the service's environment, which sets SUBSTRATE_ENFORCE_UUID_CHECK=true`);
854
+ if (target.enforceUuidCheck && source.nonUuidIds.length > 0) {
855
+ const sample = source.nonUuidIds.slice(0, 5).map((r) => `${r.table}.${r.column}=${r.id}`).join(", ");
856
+ refusals.push(`source has ${source.nonUuidIds.length} non-UUID id(s) while the target enforces the UUID check (first 5 shown): ${sample}`);
857
+ }
858
+ const skip = new Set(opts.skipTables);
859
+ const knownTables = /* @__PURE__ */ new Set([
860
+ ...ENGINE_COPIED,
861
+ ...NOT_COPIED,
862
+ ...opts.pluginTables
863
+ ]);
864
+ const unknownTables = source.tables.filter((t) => !knownTables.has(t) && !skip.has(t));
865
+ for (const t of unknownTables) refusals.push(`source table "${t}" is not known to migrate-store; load the plugin that owns it, or pass --skip-table ${t}`);
866
+ const copied = /* @__PURE__ */ new Set([...ENGINE_COPIED, ...opts.pluginTables]);
867
+ for (const t of skip) if (copied.has(t)) refusals.push(`--skip-table ${t} names a table migrate-store copies; it cannot be skipped. --skip-table is for tables migrate-store does not know`);
868
+ else if (!source.tables.includes(t)) warnings.push(`--skip-table ${t} matches no source table`);
869
+ if (source.vectorDims !== null && target.recallDims !== null && source.vectorDims !== target.recallDims) refusals.push(`recall embedding dimensions differ: source ${source.vectorDims}, target ${target.recallDims}`);
870
+ const present = new Set(source.tables);
871
+ const plan = {
872
+ tables: [...ENGINE_COPIED, ...opts.pluginTables].filter((t, i, all) => present.has(t) && all.indexOf(t) === i).map((name) => ({
873
+ name,
874
+ columns: source.columns[name] ?? [],
875
+ bytes: source.tableBytes[name] ?? 0
876
+ })),
877
+ estimatedBytes: 0,
878
+ skipped: [...skip].filter((t) => present.has(t) && !copied.has(t))
879
+ };
880
+ plan.estimatedBytes = 2 * plan.tables.reduce((n, t) => n + t.bytes, 0);
881
+ for (const t of plan.tables) {
882
+ const ext = TABLE_EXTENSION[t.name];
883
+ if (ext === void 0) continue;
884
+ const [from, to] = [source.extensions[ext], target.extensions[ext]];
885
+ if (to === void 0) refusals.push(`table "${t.name}" needs extension "${ext}", which is not installed in a schema on the target's search_path; run CREATE EXTENSION ${ext}; in the target database as a superuser, in public or the target schema`);
886
+ else if (from !== void 0 && from !== to) warnings.push(`extension "${ext}" is version ${from} on the source and ${to} on the target, so verification of ${t.name} may fail; match the versions`);
887
+ }
888
+ if (target.freeBytes !== null && target.freeBytes < plan.estimatedBytes) {
889
+ const msg = `free disk ${target.freeBytes} bytes is below the estimated need of ${plan.estimatedBytes} bytes`;
890
+ (opts.dryRun ? warnings : refusals).push(msg);
891
+ }
892
+ if (source.otherSessions > 0) {
893
+ const named = source.sessions.slice(0, 10).map((s) => `usename=${s.usename ?? "hidden"} application_name=${s.applicationName ?? "hidden"} client_addr=${s.clientAddr ?? "local"} backend_type=${s.backendType ?? "hidden"} state=${s.state ?? "hidden"}`);
894
+ const more = source.sessions.length - named.length;
895
+ const list = named.length > 0 ? `: ${named.join("; ")}${more > 0 ? `; +${more} more` : ""}` : "";
896
+ (opts.dryRun ? warnings : refusals).push(`source has ${source.otherSessions} other active session(s) on its database; writes after the snapshot are not copied, so stop the service first${list}`);
897
+ }
898
+ return {
899
+ refusals,
900
+ warnings,
901
+ plan
902
+ };
903
+ }
904
+
905
+ //#endregion
906
+ //#region src/admin/migrate-store/verify.ts
907
+ /**
908
+ * The migrate-store verification: compares the source with its conversion
909
+ * per (namespace, type) and, only when everything agrees and the target holds
910
+ * every declared index, drops the in-progress marker so `serve` will boot the
911
+ * target. Both sides are read in their own REPEATABLE READ, READ ONLY
912
+ * transaction; nothing here writes to the source.
913
+ *
914
+ * Target rows the prepare step seeded and the source lacks (`keptSeeds`) are
915
+ * subtracted from the target side before every comparison.
916
+ *
917
+ * Every set is fingerprinted as `count(*)` plus the sum of a 64-bit prefix of
918
+ * each row's md5. That is independent of row order, of either cluster's
919
+ * collation, and of any join separator, and it builds no string. Row content
920
+ * is compared as the dataset reads it: the target's row as `decodeRow` builds
921
+ * it, the source's body under the same read rule (an explicit null on a
922
+ * declared column field reads absent), both as jsonb text, so a number's
923
+ * stored text counts, plus every metadata column.
924
+ */
925
+ const quote = (cols) => cols.map((c) => `"${c.replace(/"/g, "\"\"")}"`).join(", ");
926
+ /** SQL for a set's fingerprint: its size and an order-independent sum of per-row hashes of `expr`. */
927
+ const fp = (expr) => `count(*)::text || ' ' || coalesce(sum(('x' || substr(md5(${expr}), 1, 16))::bit(64)::bigint::numeric), 0)::text`;
928
+ /**
929
+ * The declared indexes of every registered type that are not valid on the
930
+ * target: missing, invalid, building, failed, or built over a field that is
931
+ * not yet in its column. `uniqueOnly` leaves out the non-unique ones, which
932
+ * `--skip-index-build` defers to serve.
933
+ */
934
+ async function missingIndexes(target, uniqueOnly) {
935
+ const out = [];
936
+ for (const { ns, type, dataset } of registeredTypes(target.engine, target.datasets)) {
937
+ const report = await dataset?.describeStorage?.(type);
938
+ for (const i of report?.indexes ?? []) if (i.state !== "valid" && (i.unique || !uniqueOnly)) out.push({
939
+ type: `${ns}/${type}`,
940
+ index: i.name
941
+ });
942
+ }
943
+ return out;
944
+ }
945
+ async function verifyStore(source, target, opts) {
946
+ const readOnly = "isolation level repeatable read read only";
947
+ const types = await target.begin(readOnly, (tx) => typeTables(tx));
948
+ const src = await source.begin(readOnly, (tx) => snapshot(tx, "source", [], null, opts, types));
949
+ const tgt = await target.begin(readOnly, (tx) => snapshot(tx, "target", opts.keptSeeds, src, opts, types));
950
+ const mismatches = [];
951
+ const keys = [.../* @__PURE__ */ new Set([...src.entries.keys(), ...tgt.entries.keys()])].sort();
952
+ for (const k of keys) {
953
+ const a = src.entries.get(k);
954
+ const b = tgt.entries.get(k);
955
+ if (a?.value === b?.value) continue;
956
+ const e = a ?? b;
957
+ mismatches.push({
958
+ check: e.check,
959
+ ...e.namespace !== void 0 ? { namespace: e.namespace } : {},
960
+ ...e.type !== void 0 ? { type: e.type } : {},
961
+ detail: `${e.what}: source ${a?.value ?? "absent"}, target ${b?.value ?? "absent"}`
962
+ });
963
+ }
964
+ for (const [key, table] of types) {
965
+ const [namespace, type] = [table.namespace, table.type];
966
+ const unsettled = [...table.pending.map((field) => ({
967
+ field,
968
+ state: "pending"
969
+ })), ...table.columns().filter((c) => c.state === "promoting")];
970
+ for (const f of unsettled) mismatches.push({
971
+ check: "fields",
972
+ namespace,
973
+ type,
974
+ detail: `field ${f.field} of ${key} is ${f.state}, so its values are not all in its column`
975
+ });
976
+ }
977
+ for (const w of (await opts.storageReport({ partitionBudget: opts.partitionBudget })).warnings) mismatches.push({
978
+ check: "storage",
979
+ detail: w
980
+ });
981
+ const missing = await opts.missingIndexes();
982
+ const ok = mismatches.length === 0 && missing.length === 0;
983
+ if (ok) await target`DROP TABLE IF EXISTS ${target(MIGRATE_STORE_MARKER_TABLE)}`;
984
+ return {
985
+ ok,
986
+ mismatches,
987
+ missingIndexes: missing
988
+ };
989
+ }
990
+ const COPY_MILESTONES = /* @__PURE__ */ new Set([
991
+ "copy:started",
992
+ "copy:phase1",
993
+ "copy:phase2",
994
+ "copy:done"
995
+ ]);
996
+ /**
997
+ * What a finished copy left behind, for a verification that has no
998
+ * `CopyResult`: the kept seeds from the marker table, the types the target
999
+ * does not register (their fields all sit in `extra`), and the copied tables,
1000
+ * which are the marker's `copy:<table>` steps.
1001
+ */
1002
+ async function readCopyState(target) {
1003
+ const sql = target.sql;
1004
+ if (sql === null) throw new Error("migrate-store verifies a postgres target only");
1005
+ const steps = await sql`
1006
+ SELECT step FROM ${sql(MIGRATE_STORE_MARKER_TABLE)}`.catch((err) => {
1007
+ if (err.code === "42P01") return [];
1008
+ throw err;
1009
+ });
1010
+ if (!steps.some((s) => s.step === "copy:done")) throw new Error("the target has no completed migrate-store copy to verify (its in-progress marker is missing or the copy did not finish)");
1011
+ return {
1012
+ keptSeeds: steps.filter((s) => s.step.startsWith(SEED)).map((s) => {
1013
+ const [namespace, type, id] = JSON.parse(s.step.slice(SEED.length));
1014
+ return {
1015
+ namespace,
1016
+ type,
1017
+ id
1018
+ };
1019
+ }).sort((a, b) => (a.namespace + a.type + a.id).localeCompare(b.namespace + b.type + b.id)),
1020
+ defaulted: (await sql`
1021
+ SELECT DISTINCT namespace, type FROM row_ids ORDER BY namespace, type`).filter((p) => registeredDataset(target, p.namespace, p.type) === void 0).map((p) => `${p.namespace}/${p.type}`),
1022
+ tables: steps.map((s) => s.step).filter((s) => s.startsWith("copy:") && !COPY_MILESTONES.has(s)).map((s) => s.slice(5)).sort()
1023
+ };
1024
+ }
1025
+ /** The target's type tables, by `<ns>/<Type>`. */
1026
+ async function typeTables(tx) {
1027
+ const types = /* @__PURE__ */ new Map();
1028
+ const listed = await tx`
1029
+ SELECT namespace, type FROM substrate_type_tables ORDER BY namespace, type`;
1030
+ for (const { namespace, type } of listed) {
1031
+ const table = await loadTypeTable(tx, namespace, type);
1032
+ if (table !== void 0) types.set(`${namespace}/${type}`, table);
1033
+ }
1034
+ return types;
1035
+ }
1036
+ /** Each row's id with its versions: a row updated or deleted after the copy's snapshot changes it, wherever the sample falls. */
1037
+ const VERSIONS = `id || E'\n' || coalesce(updated_at::text, '') || E'\n' || coalesce(deleted_at::text, '')`;
1038
+ const META = `deleted_at::text, created_at::text, updated_at::text, created_by_kind, created_by_id, updated_by_kind, updated_by_id`;
1039
+ /**
1040
+ * Every comparable fact about one side, keyed so the two sides diff by key.
1041
+ * `other` is the source's snapshot when this is the target; `types` are the
1042
+ * target's type tables, which give the source its read rule.
1043
+ */
1044
+ async function snapshot(tx, side, seeds, other, opts, types) {
1045
+ await tx`SET LOCAL TimeZone = 'UTC'`;
1046
+ await tx`SET LOCAL DateStyle = 'ISO, YMD'`;
1047
+ await tx`SET LOCAL extra_float_digits = 3`;
1048
+ const entries = /* @__PURE__ */ new Map();
1049
+ const columns = /* @__PURE__ */ new Map();
1050
+ const add = (e) => entries.set(`${e.check}\0${e.namespace ?? ""}\0${e.type ?? ""}\0${e.what}`, e);
1051
+ const notSeed = (ns, ty, id) => tx`(${tx(ns)}, ${tx(ty)}, ${tx(id)}) NOT IN (SELECT * FROM unnest(
1052
+ ${seeds.map((k) => k.namespace)}::text[], ${seeds.map((k) => k.type)}::text[], ${seeds.map((k) => k.id)}::text[]))`;
1053
+ const seedIds = (ns, ty) => seeds.filter((k) => k.namespace === ns && k.type === ty).map((k) => k.id);
1054
+ const colsOf = async (table) => {
1055
+ const have = await tx`
1056
+ SELECT a.attname AS col FROM pg_attribute a
1057
+ WHERE a.attrelid = to_regclass(${table}) AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''
1058
+ ORDER BY a.attname`;
1059
+ if (have.length === 0) return null;
1060
+ const theirs = other?.columns.get(table);
1061
+ const cols = have.map((c) => c.col).filter((c) => theirs === void 0 || theirs.includes(c));
1062
+ columns.set(table, cols);
1063
+ return cols;
1064
+ };
1065
+ const limit = opts.fullChecksum ? Number.MAX_SAFE_INTEGER : opts.sampleRows;
1066
+ const counted = [];
1067
+ if (side === "source") {
1068
+ const counts = await tx`
1069
+ SELECT namespace, type,
1070
+ count(*) FILTER (WHERE deleted_at IS NULL)::text AS live,
1071
+ count(*) FILTER (WHERE deleted_at IS NOT NULL)::text AS deleted,
1072
+ ${tx.unsafe(fp("id"))} AS ids,
1073
+ ${tx.unsafe(fp(VERSIONS))} AS versions
1074
+ FROM rows GROUP BY namespace, type`;
1075
+ for (const r of counts) {
1076
+ const at = {
1077
+ namespace: r.namespace,
1078
+ type: r.type
1079
+ };
1080
+ add({
1081
+ check: "count",
1082
+ ...at,
1083
+ what: "live rows",
1084
+ value: r.live
1085
+ });
1086
+ add({
1087
+ check: "count",
1088
+ ...at,
1089
+ what: "deleted rows",
1090
+ value: r.deleted
1091
+ });
1092
+ add({
1093
+ check: "ids",
1094
+ ...at,
1095
+ what: "id set",
1096
+ value: r.ids
1097
+ });
1098
+ add({
1099
+ check: "ids",
1100
+ ...at,
1101
+ what: "registered ids (row_ids)",
1102
+ value: r.ids
1103
+ });
1104
+ add({
1105
+ check: "versions",
1106
+ ...at,
1107
+ what: "row versions (updated_at, deleted_at)",
1108
+ value: r.versions
1109
+ });
1110
+ counted.push(at);
1111
+ }
1112
+ } else {
1113
+ for (const table of types.values()) {
1114
+ const { namespace, type } = table;
1115
+ const skip = seedIds(namespace, type);
1116
+ const [r] = await tx.unsafe(`SELECT count(*) FILTER (WHERE deleted_at IS NULL)::text AS live,
1117
+ count(*) FILTER (WHERE deleted_at IS NOT NULL)::text AS deleted,
1118
+ ${fp("id")} AS ids, ${fp(VERSIONS)} AS versions
1119
+ FROM ${table.from} WHERE NOT (id = ANY($1::text[]))`, [skip]);
1120
+ const at = {
1121
+ namespace,
1122
+ type
1123
+ };
1124
+ if (r !== void 0 && Number(r.live) + Number(r.deleted) > 0) {
1125
+ add({
1126
+ check: "count",
1127
+ ...at,
1128
+ what: "live rows",
1129
+ value: r.live
1130
+ });
1131
+ add({
1132
+ check: "count",
1133
+ ...at,
1134
+ what: "deleted rows",
1135
+ value: r.deleted
1136
+ });
1137
+ add({
1138
+ check: "ids",
1139
+ ...at,
1140
+ what: "id set",
1141
+ value: r.ids
1142
+ });
1143
+ add({
1144
+ check: "versions",
1145
+ ...at,
1146
+ what: "row versions (updated_at, deleted_at)",
1147
+ value: r.versions
1148
+ });
1149
+ counted.push(at);
1150
+ }
1151
+ }
1152
+ const registered = await tx`
1153
+ SELECT namespace, type, ${tx.unsafe(fp("id"))} AS ids
1154
+ FROM row_ids WHERE ${notSeed("namespace", "type", "id")} GROUP BY namespace, type`;
1155
+ for (const r of registered) add({
1156
+ check: "ids",
1157
+ namespace: r.namespace,
1158
+ type: r.type,
1159
+ what: "registered ids (row_ids)",
1160
+ value: r.ids
1161
+ });
1162
+ }
1163
+ const shorts = await tx`
1164
+ SELECT namespace, type, ${tx.unsafe(fp("row(short_id, row_id)::text"))} AS f
1165
+ FROM short_ids WHERE ${notSeed("namespace", "type", "row_id")} GROUP BY namespace, type`;
1166
+ for (const r of shorts) add({
1167
+ check: "short_ids",
1168
+ namespace: r.namespace,
1169
+ type: r.type,
1170
+ what: "shortIds",
1171
+ value: r.f
1172
+ });
1173
+ const edgeCols = await colsOf("edges");
1174
+ if (edgeCols !== null) {
1175
+ const edges = await tx`
1176
+ SELECT from_ns AS namespace, from_type AS type, field_name AS field,
1177
+ ${tx.unsafe(fp(`row(${quote(edgeCols)})::text`))} AS f
1178
+ FROM edges WHERE ${notSeed("from_ns", "from_type", "from_id")} GROUP BY from_ns, from_type, field_name`;
1179
+ for (const r of edges) add({
1180
+ check: "edges",
1181
+ namespace: r.namespace,
1182
+ type: r.type,
1183
+ what: `edges of ${r.field}`,
1184
+ value: r.f
1185
+ });
1186
+ }
1187
+ const hasSeq = side === "source" ? (await colsOf("rows"))?.includes("seq") === true : other?.columns.get("rows")?.includes("seq") !== false;
1188
+ const meta = `row(${META}, ${hasSeq ? "seq::text" : "NULL::text"})::text`;
1189
+ const rowsColumns = side === "source" ? (await tx`
1190
+ SELECT attname AS col FROM pg_attribute
1191
+ WHERE attrelid = to_regclass('rows') AND attnum > 0 AND NOT attisdropped AND attgenerated = ''`).map((r) => r.col) : [];
1192
+ for (const { namespace, type } of counted) {
1193
+ let rows;
1194
+ let params;
1195
+ if (side === "source") {
1196
+ const declared = declaredFields(types.get(`${namespace}/${type}`));
1197
+ rows = `SELECT id || E'\n' || (SELECT coalesce(jsonb_object_agg(k, v), '{}'::jsonb) FROM jsonb_each(${sourceBodySql(rowsColumns, declared)}) e(k, v)
1198
+ WHERE NOT (v = 'null'::jsonb AND k = ANY($3::text[])))::text || E'\n' || ${meta} AS h
1199
+ FROM rows WHERE namespace = $1 AND type = $2 ORDER BY md5(id) COLLATE "C" LIMIT ${limit}`;
1200
+ params = [
1201
+ namespace,
1202
+ type,
1203
+ declared
1204
+ ];
1205
+ } else {
1206
+ const ref = await typeTableRef(tx, namespace, type);
1207
+ if (ref === void 0) continue;
1208
+ rows = `SELECT x.id || E'\n' || ${ref.rowJson("x")}::text || E'\n' || ${meta} AS h FROM ${ref.from} x
1209
+ WHERE NOT (x.id = ANY($1::text[])) ORDER BY md5(x.id) COLLATE "C" LIMIT ${limit}`;
1210
+ params = [seedIds(namespace, type)];
1211
+ }
1212
+ const [r] = await tx.unsafe(`SELECT ${fp("h")} AS f FROM (${rows}) s`, params);
1213
+ add({
1214
+ check: "sample",
1215
+ namespace,
1216
+ type,
1217
+ what: "content",
1218
+ value: String(r?.f)
1219
+ });
1220
+ }
1221
+ const skip = /* @__PURE__ */ new Set([
1222
+ "rows",
1223
+ "short_ids",
1224
+ "edges"
1225
+ ]);
1226
+ for (const name of opts.tables.filter((t) => !skip.has(t))) {
1227
+ if (other !== null && !other.columns.has(name)) continue;
1228
+ const cols = await colsOf(name);
1229
+ if (cols === null) continue;
1230
+ const where = [
1231
+ "row_namespace",
1232
+ "row_type",
1233
+ "row_id"
1234
+ ].every((c) => cols.includes(c)) ? notSeed("row_namespace", "row_type", "row_id") : tx`true`;
1235
+ const [r] = await tx`
1236
+ SELECT ${tx.unsafe(fp(`row(${quote(cols)})::text`))} AS f FROM ${tx(name)} WHERE ${where}`;
1237
+ add({
1238
+ check: "table",
1239
+ what: name,
1240
+ value: String(r?.f)
1241
+ });
1242
+ }
1243
+ return {
1244
+ entries,
1245
+ columns
1246
+ };
1247
+ }
1248
+
1249
+ //#endregion
1250
+ //#region src/admin/commands/migrate-store.ts
1251
+ /**
1252
+ * `substrate-admin migrate-store`: converts a legacy or partitioned store into
1253
+ * a fresh, empty PostgreSQL 18 store in the `tables` layout. Preflight,
1254
+ * prepare and copy, index builds, verification, report. Connection strings come from named environment
1255
+ * variables only, and nothing this command prints carries one.
1256
+ */
1257
+ const DEFAULT_FROM_ENV = "SUBSTRATE_MIGRATE_FROM_URL";
1258
+ const DEFAULT_TO_ENV = "SUBSTRATE_MIGRATE_TO_URL";
1259
+ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
1260
+ const IDENT = PLAIN_SCHEMA_NAME;
1261
+ const SAFE_VALUE = (flag) => `migrate-store: ${flag} takes a plain name (a value that does not fit is not echoed)`;
1262
+ /** Parses the argv tail after `migrate-store`. Usage errors exit 2. */
1263
+ function parseMigrateStoreArgs(tail) {
1264
+ validateArgv("migrate-store", tail);
1265
+ const seen = /* @__PURE__ */ new Map();
1266
+ const args = {
1267
+ fromEnv: DEFAULT_FROM_ENV,
1268
+ toEnv: DEFAULT_TO_ENV,
1269
+ fromSchema: null,
1270
+ toSchema: null,
1271
+ batchRows: 1e4,
1272
+ skipTables: [],
1273
+ dryRun: false,
1274
+ verifyOnly: false,
1275
+ json: false,
1276
+ skipIndexBuild: false,
1277
+ fullChecksum: false
1278
+ };
1279
+ const fail = (msg) => argvError("migrate-store", msg, 2);
1280
+ for (let i = 0; i < tail.length; i++) {
1281
+ const tok = tail[i];
1282
+ switch (tok) {
1283
+ case "--dry-run":
1284
+ args.dryRun = true;
1285
+ continue;
1286
+ case "--verify-only":
1287
+ args.verifyOnly = true;
1288
+ continue;
1289
+ case "--json":
1290
+ args.json = true;
1291
+ continue;
1292
+ case "--skip-index-build":
1293
+ args.skipIndexBuild = true;
1294
+ continue;
1295
+ case "--full-checksum":
1296
+ args.fullChecksum = true;
1297
+ continue;
1298
+ }
1299
+ const value = tail[i + 1];
1300
+ if (value === void 0 || value.startsWith("--")) throw fail(`migrate-store: ${tok} needs a value`);
1301
+ i += 1;
1302
+ if (tok !== "--skip-table") {
1303
+ if (seen.has(tok)) throw fail(`migrate-store: ${tok} given more than once`);
1304
+ seen.set(tok, value);
1305
+ }
1306
+ switch (tok) {
1307
+ case "--from-env":
1308
+ case "--to-env":
1309
+ if (!ENV_NAME.test(value)) throw fail(`migrate-store: ${tok} takes the NAME of an environment variable that holds the connection string, never the string itself`);
1310
+ args[tok === "--from-env" ? "fromEnv" : "toEnv"] = value;
1311
+ break;
1312
+ case "--from-schema":
1313
+ case "--to-schema":
1314
+ if (!IDENT.test(value)) throw fail(SAFE_VALUE(tok));
1315
+ args[tok === "--from-schema" ? "fromSchema" : "toSchema"] = value;
1316
+ break;
1317
+ case "--skip-table":
1318
+ if (!IDENT.test(value)) throw fail(SAFE_VALUE(tok));
1319
+ args.skipTables.push(value);
1320
+ break;
1321
+ case "--batch-rows": {
1322
+ const n = Number(value);
1323
+ if (!/^\d+$/.test(value) || !Number.isSafeInteger(n) || n < 1) throw fail("migrate-store: --batch-rows takes a positive integer");
1324
+ args.batchRows = n;
1325
+ break;
1326
+ }
1327
+ }
1328
+ }
1329
+ if (args.dryRun && args.verifyOnly) throw fail("migrate-store: --dry-run and --verify-only are mutually exclusive");
1330
+ return args;
1331
+ }
1332
+ /** Replaces every URL, and each given secret, in `s`. */
1333
+ function redactor(secrets) {
1334
+ const literals = [...new Set(secrets.filter((x) => x.length >= 3))].sort((a, b) => b.length - a.length);
1335
+ return (s) => {
1336
+ let r = s.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s'"`]+/gi, "<redacted url>");
1337
+ for (const l of literals) r = r.split(l).join("<redacted>");
1338
+ return r;
1339
+ };
1340
+ }
1341
+ /** The connection string, its password both as written and decoded, for `redactor`. */
1342
+ function secretsOf(url) {
1343
+ if (url === void 0 || url.length === 0) return [];
1344
+ const out = [url];
1345
+ let pw = "";
1346
+ try {
1347
+ pw = new URL(url).password;
1348
+ } catch {}
1349
+ if (pw.length === 0) return out;
1350
+ out.push(pw);
1351
+ try {
1352
+ out.push(decodeURIComponent(pw));
1353
+ } catch {}
1354
+ return out;
1355
+ }
1356
+ /** `url` with `search_path` pinned to `schema`, as a startup option so every pooled connection has it. */
1357
+ function withSchema(url, schema) {
1358
+ return schema === null ? url : withSettings(url, [`search_path=${schema},public`]);
1359
+ }
1360
+ /** `url` with each `name=value` in `settings` as a startup option (`-c`). */
1361
+ function withSettings(url, settings) {
1362
+ const u = new URL(url);
1363
+ const prior = u.searchParams.get("options");
1364
+ const params = [...u.searchParams.entries()].filter(([k]) => k !== "options");
1365
+ const added = settings.map((s) => `-c ${s}`).join(" ");
1366
+ params.push(["options", `${prior !== null ? `${prior} ` : ""}${added}`]);
1367
+ u.search = params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
1368
+ return u.toString();
1369
+ }
1370
+ const DISK_PATH_UNSET = "SUBSTRATE_INDEX_DISK_PATH is unset, so the target cannot check free disk before index builds and its storage check fails verification: set it to the target database volume mount, or to off when the database has no local volume";
1371
+ const PENDING_INDEX = /^index \S+ on \S+ is pending( \(.*\))?: filters it would serve scan until it is valid$/;
1372
+ async function runMigrateStore(args, env, deps) {
1373
+ const started = performance.now();
1374
+ const vars = env;
1375
+ const urlOf = (name, side) => {
1376
+ const v = vars[name]?.trim();
1377
+ if (v === void 0 || v.length === 0) throw new AdminCliError(`migrate-store: ${name} (the ${side} connection string) is not set`, 2);
1378
+ if (!/^postgres(ql)?:\/\//.test(v)) throw new AdminCliError(`migrate-store: ${name} does not hold a postgres:// connection string`, 2);
1379
+ return v;
1380
+ };
1381
+ const fromUrl = withSchema(urlOf(args.fromEnv, "source"), args.fromSchema);
1382
+ const toStore = withSchema(urlOf(args.toEnv, "target"), args.toSchema);
1383
+ if (fromUrl === toStore) throw new AdminCliError("migrate-store: the source and the target are the same store", 2);
1384
+ const toUrl = withSettings(toStore, ["statement_timeout=0"]);
1385
+ const report = {
1386
+ mode: args.dryRun ? "dry-run" : args.verifyOnly ? "verify-only" : "migrate",
1387
+ ok: false,
1388
+ exitCode: 2,
1389
+ refusals: [],
1390
+ warnings: [],
1391
+ tables: [],
1392
+ phases: {},
1393
+ totalMs: 0,
1394
+ keptSeeds: [],
1395
+ defaulted: [],
1396
+ misfits: null,
1397
+ missingIndexes: [],
1398
+ pendingIndexes: [],
1399
+ mismatches: [],
1400
+ switchOver: null
1401
+ };
1402
+ const finish = (exitCode) => {
1403
+ report.exitCode = exitCode;
1404
+ report.ok = exitCode === 0;
1405
+ report.totalMs = Math.round(performance.now() - started);
1406
+ return report;
1407
+ };
1408
+ let running;
1409
+ const phase = async (name, fn) => {
1410
+ deps.progress(`migrate-store: ${name}`);
1411
+ const t = performance.now();
1412
+ running = name;
1413
+ try {
1414
+ const out = await fn();
1415
+ running = void 0;
1416
+ return out;
1417
+ } finally {
1418
+ report.phases[name] = Math.round(performance.now() - t);
1419
+ }
1420
+ };
1421
+ const diskPath = vars.SUBSTRATE_INDEX_DISK_PATH?.trim();
1422
+ if (diskPath === void 0 || diskPath.length === 0) (args.dryRun ? report.warnings : report.refusals).push(DISK_PATH_UNSET);
1423
+ if (report.refusals.length > 0) return finish(2);
1424
+ const targetEnv = {
1425
+ ...vars,
1426
+ SUBSTRATE_DATABASE_URL: toUrl,
1427
+ HOST: "127.0.0.1",
1428
+ SUBSTRATE_SYSTEM_ACTOR: vars.SUBSTRATE_SYSTEM_ACTOR?.trim() || "migrate-store"
1429
+ };
1430
+ let config;
1431
+ try {
1432
+ config = parseEnv(targetEnv);
1433
+ } catch (err) {
1434
+ if (!(err instanceof EnvConfigError)) throw err;
1435
+ report.refusals.push(`the target's serve env is invalid: ${err.message}`);
1436
+ return finish(2);
1437
+ }
1438
+ const pluginDir = resolvePluginDir(targetEnv);
1439
+ const boot = () => bootStore({
1440
+ config,
1441
+ pluginDir,
1442
+ allowMigrating: true,
1443
+ background: false
1444
+ });
1445
+ const notices = pgNoticeOptions(deps.notice ?? ((line) => deps.progress(line.trimEnd())));
1446
+ const openFacts = () => postgres(toUrl, {
1447
+ ...notices,
1448
+ max: 1
1449
+ });
1450
+ const endFacts = (facts) => facts.end({ timeout: 5 }).catch(() => void 0);
1451
+ const src = postgres(fromUrl, {
1452
+ ...notices,
1453
+ max: 1,
1454
+ connection: {
1455
+ default_transaction_read_only: true,
1456
+ statement_timeout: 0,
1457
+ idle_in_transaction_session_timeout: 0,
1458
+ transaction_timeout: 0
1459
+ }
1460
+ });
1461
+ let target;
1462
+ try {
1463
+ let keptSeeds;
1464
+ let defaulted;
1465
+ let tables;
1466
+ if (args.verifyOnly) {
1467
+ const facts = openFacts();
1468
+ try {
1469
+ await assertSchema(src, args.fromSchema, "source");
1470
+ await assertSchema(facts, args.toSchema, "target");
1471
+ await assertDistinct(src, facts);
1472
+ await assertCopyDone(facts);
1473
+ } finally {
1474
+ await endFacts(facts);
1475
+ }
1476
+ target = await phase("prepare", boot);
1477
+ const state = await readCopyState(target);
1478
+ ({keptSeeds, defaulted, tables} = state);
1479
+ } else {
1480
+ const pre = await phase("preflight", async () => {
1481
+ const facts = openFacts();
1482
+ try {
1483
+ const own = await ownSession(facts);
1484
+ await assertSchema(src, args.fromSchema, "source");
1485
+ await assertSchema(facts, args.toSchema, "target");
1486
+ await assertDistinct(src, facts);
1487
+ const source = await inspectSource(src);
1488
+ source.sessions = source.sessions.filter((s) => !(s.pid === own.pid && s.start === own.start));
1489
+ source.otherSessions = deps.otherSessions ?? source.sessions.length;
1490
+ const target = await targetFacts(facts, env, diskPath);
1491
+ const pluginTables = await storeTables(pluginDir);
1492
+ return {
1493
+ source,
1494
+ ...preflight(source, target, {
1495
+ skipTables: args.skipTables,
1496
+ pluginTables,
1497
+ dryRun: args.dryRun
1498
+ })
1499
+ };
1500
+ } finally {
1501
+ await endFacts(facts);
1502
+ }
1503
+ });
1504
+ report.refusals.push(...pre.refusals);
1505
+ report.warnings.push(...pre.warnings);
1506
+ report.plan = planOf(pre.plan);
1507
+ if (report.refusals.length > 0) return finish(2);
1508
+ if (args.dryRun) {
1509
+ report.types = pre.source.types;
1510
+ return finish(0);
1511
+ }
1512
+ const copied = await phase("prepare-and-copy", () => copyStore(src, boot, pre.plan, {
1513
+ batchRows: args.batchRows,
1514
+ onProgress: (e) => deps.progress(` ${e.table}: ${e.rows} rows, ${e.bytes} bytes${e.done ? ", done" : ""}`)
1515
+ }));
1516
+ target = copied.target;
1517
+ report.tables = copied.tables;
1518
+ report.misfits = copied.misfits;
1519
+ ({keptSeeds, defaulted} = copied);
1520
+ tables = pre.plan.tables.map((t) => t.name);
1521
+ }
1522
+ const booted = target;
1523
+ const indexFailures = args.skipIndexBuild ? [] : await phase("indexes", () => (deps.buildIndexes ?? buildDeferredIndexes)(booted.engine, booted.datasets));
1524
+ report.keptSeeds = keptSeeds.map((k) => `${k.namespace}/${k.type}/${k.id}`);
1525
+ report.defaulted = defaulted;
1526
+ const tsql = booted.sql;
1527
+ await deps.beforeVerify?.(tsql);
1528
+ const verified = await phase("verify", () => verifyStore(src, tsql, {
1529
+ keptSeeds,
1530
+ tables,
1531
+ missingIndexes: () => missingIndexes(booted, args.skipIndexBuild),
1532
+ fullChecksum: args.fullChecksum,
1533
+ sampleRows: 1e3,
1534
+ partitionBudget: parseEnv(targetEnv).typeTableBudget,
1535
+ storageReport: async (r) => {
1536
+ const { warnings } = await booted.dataset.storageReport(r);
1537
+ const failed = [...indexFailures, ...await invalidIndexes(tsql)];
1538
+ if (!args.skipIndexBuild) return { warnings: [...warnings, ...failed] };
1539
+ report.pendingIndexes = warnings.filter((w) => PENDING_INDEX.test(w));
1540
+ return { warnings: [...warnings.filter((w) => !PENDING_INDEX.test(w)), ...failed] };
1541
+ }
1542
+ }));
1543
+ report.mismatches = verified.mismatches;
1544
+ report.missingIndexes = verified.missingIndexes;
1545
+ if (!verified.ok) return finish(3);
1546
+ report.switchOver = `stop serve, set SUBSTRATE_DATABASE_URL to the value of ${args.toEnv}${args.toSchema !== null ? ` with search_path ${args.toSchema},public (options=-c search_path=${args.toSchema},public)` : ""}, then start serve. The source is untouched: pointing back at it is the rollback.`;
1547
+ return finish(0);
1548
+ } catch (e) {
1549
+ const message = e instanceof Error ? e.message : String(e);
1550
+ if (e instanceof AdminCliError && (e.exitCode === 2 || e.exitCode === 3)) {
1551
+ report.refusals.push(message);
1552
+ return finish(e.exitCode);
1553
+ }
1554
+ report.error = message;
1555
+ if (running !== void 0) report.failedPhase = running;
1556
+ return finish(1);
1557
+ } finally {
1558
+ await target?.close().catch(() => void 0);
1559
+ await src.end({ timeout: 5 }).catch(() => void 0);
1560
+ }
1561
+ }
1562
+ function planOf(plan) {
1563
+ return {
1564
+ tables: plan.tables.map((t) => ({
1565
+ name: t.name,
1566
+ bytes: t.bytes
1567
+ })),
1568
+ estimatedBytes: plan.estimatedBytes,
1569
+ skipped: plan.skipped
1570
+ };
1571
+ }
1572
+ /** The target schema's INVALID indexes, which a failed CREATE INDEX CONCURRENTLY leaves behind. */
1573
+ async function invalidIndexes(sql) {
1574
+ return (await sql`
1575
+ SELECT c.relname AS name, t.relname AS tbl
1576
+ FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid JOIN pg_class t ON t.oid = i.indrelid
1577
+ WHERE c.relnamespace = current_schema()::regnamespace AND NOT i.indisvalid
1578
+ ORDER BY c.relname`).map((r) => `index ${r.name} on ${r.tbl} is INVALID: rerun with --verify-only (without --skip-index-build), which rebuilds an engine index; drop or REINDEX any other INVALID index by hand`);
1579
+ }
1580
+ /** Refuses a named schema the connection did not land in: an unknown name on search_path falls through to public. */
1581
+ async function assertSchema(sql, schema, side) {
1582
+ const [r] = await sql`SELECT current_schema() AS s`;
1583
+ if (schema !== null && r?.s !== schema) throw new AdminCliError(`migrate-store: the ${side} has no schema ${schema}`, 2);
1584
+ }
1585
+ const storeId = async (sql) => {
1586
+ const [r] = await sql`
1587
+ SELECT concat_ws('/', (SELECT system_identifier FROM pg_control_system())::text,
1588
+ current_database(), current_schema()) AS id`;
1589
+ return r?.id;
1590
+ };
1591
+ /** Refuses a source and target that are one store: same cluster, database and schema. */
1592
+ async function assertDistinct(src, tgt) {
1593
+ if (await storeId(src) === await storeId(tgt)) throw new AdminCliError("migrate-store: the source and the target are the same store", 2);
1594
+ }
1595
+ /** Refuses `--verify-only` on a target with no finished migrate-store copy. */
1596
+ async function assertCopyDone(sql) {
1597
+ const [r] = await sql`
1598
+ SELECT to_regclass(quote_ident(current_schema()) || '.' || quote_ident(${MIGRATE_STORE_MARKER_TABLE}))::text AS marker`;
1599
+ if (r?.marker == null) throw new AdminCliError("migrate-store: the target is already verified, or not a migrate-store target (no marker)", 2);
1600
+ if ((await sql`SELECT 1 FROM ${sql(r.marker)} WHERE step = 'copy:done'`).length === 0) throw new AdminCliError("migrate-store: the target holds no finished migrate-store copy to verify (no in-progress marker with a completed copy)", 2);
1601
+ }
1602
+ async function ownSession(sql) {
1603
+ const [r] = await sql`
1604
+ SELECT pid, extract(epoch FROM backend_start)::text AS start
1605
+ FROM pg_stat_activity WHERE pid = pg_backend_pid()`;
1606
+ return r;
1607
+ }
1608
+ async function targetFacts(sql, env, diskPath) {
1609
+ const [r] = await sql`
1610
+ SELECT current_setting('server_version_num')::int AS v, current_schema() AS schema,
1611
+ to_regclass(quote_ident(current_schema()) || '.rows') IS NOT NULL AS rows,
1612
+ to_regclass(quote_ident(current_schema()) || '.row_ids') IS NOT NULL AS ids,
1613
+ to_regclass(quote_ident(current_schema()) || '.' || quote_ident(${MIGRATE_STORE_MARKER_TABLE})) IS NOT NULL AS marker,
1614
+ to_regclass(quote_ident(current_schema()) || '.embeddings') IS NOT NULL AS embeddings`;
1615
+ const facts = r;
1616
+ const holds = async (table) => (await sql`SELECT 1 FROM ${sql(facts.schema)}.${sql(table)} LIMIT 1`).length > 0;
1617
+ const empty = !(facts.rows && await holds("rows")) && !(facts.ids && await holds("row_ids"));
1618
+ const [dims] = facts.embeddings ? await sql`
1619
+ SELECT atttypmod AS d FROM pg_attribute
1620
+ WHERE attrelid = to_regclass(quote_ident(${facts.schema}) || '.embeddings')
1621
+ AND attname = 'embedding' AND NOT attisdropped` : [];
1622
+ const extensions = await sql`
1623
+ SELECT e.extname AS name, e.extversion AS version
1624
+ FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
1625
+ WHERE n.nspname = ANY (current_schemas(true))`;
1626
+ let freeBytes = null;
1627
+ if (diskPath !== void 0 && diskPath.length > 0 && diskPath !== "off") {
1628
+ const s = await statfs(diskPath).catch((err) => {
1629
+ if (err.code !== "ENOENT") throw err;
1630
+ throw new AdminCliError(`migrate-store: SUBSTRATE_INDEX_DISK_PATH names a path that does not exist; set it to the target database volume mount, or to off`, 2);
1631
+ });
1632
+ freeBytes = s.bavail * s.bsize;
1633
+ }
1634
+ return {
1635
+ serverVersionNum: facts.v,
1636
+ layout: await detectLayout(sql),
1637
+ empty,
1638
+ createdByUs: facts.marker,
1639
+ enforceUuidCheck: env.SUBSTRATE_ENFORCE_UUID_CHECK === "true",
1640
+ recallDims: dims !== void 0 && dims.d > 0 ? dims.d : null,
1641
+ extensions: Object.fromEntries(extensions.map((e) => [e.name, e.version])),
1642
+ freeBytes
1643
+ };
1644
+ }
1645
+ /** The loaded kernel plugins' `storeTables`, loaded as serve loads them but never composed. */
1646
+ async function storeTables(pluginDir) {
1647
+ if (pluginDir === null) return [];
1648
+ const { kernel } = await loadPluginsFromDir({
1649
+ pluginDir,
1650
+ kernelHostDeps: {},
1651
+ contractCheck: {
1652
+ hostVersion: BINARY_CONTRACT_VERSION,
1653
+ onViolation: refuseContractViolation
1654
+ }
1655
+ });
1656
+ return kernel.flatMap((p) => p.storeTables ?? []);
1657
+ }
1658
+ function formatMigrateStoreOutput(r, json) {
1659
+ if (json) return `${JSON.stringify(r)}\n`;
1660
+ const lines = [];
1661
+ const verdict = r.exitCode === 0 ? r.mode === "dry-run" ? "dry run: nothing written" : "copied and verified" : r.exitCode === 3 ? "VERIFICATION FAILED: the target keeps its in-progress marker, so serve will not boot it" : r.exitCode === 1 ? `FAILED${r.failedPhase !== void 0 ? ` in ${r.failedPhase}` : ""}: ${r.error ?? "unknown error"}` : "REFUSED: nothing was written to the target";
1662
+ lines.push(`migrate-store (${r.mode}): ${verdict}`);
1663
+ for (const x of r.refusals) lines.push(` refused: ${x}`);
1664
+ for (const x of r.warnings) lines.push(` warning: ${x}`);
1665
+ if (r.types !== void 0) {
1666
+ lines.push("source types (live / deleted / bytes):");
1667
+ for (const t of r.types) lines.push(` ${t.namespace}/${t.type}: ${t.live} / ${t.deleted} / ${t.bytes}`);
1668
+ }
1669
+ if (r.plan !== void 0) {
1670
+ lines.push(`plan (estimated target need ${r.plan.estimatedBytes} bytes):`);
1671
+ for (const t of r.plan.tables) lines.push(` ${t.name}: ${t.bytes} bytes`);
1672
+ if (r.plan.skipped.length > 0) lines.push(` skipped: ${r.plan.skipped.join(", ")}`);
1673
+ }
1674
+ if (r.tables.length > 0) {
1675
+ lines.push("copied (rows / bytes / ms):");
1676
+ for (const t of r.tables) lines.push(` ${t.name}: ${t.rows} / ${t.bytes} / ${t.ms}`);
1677
+ }
1678
+ if (r.keptSeeds.length > 0) lines.push(`kept seeds: ${r.keptSeeds.join(", ")}`);
1679
+ if (r.defaulted.length > 0) lines.push(`declared by no definition, every field in extra: ${r.defaulted.join(", ")}`);
1680
+ if (r.misfits === null) lines.push("misfits: not counted (only a copy run counts them)");
1681
+ for (const [type, m] of Object.entries(r.misfits ?? {})) {
1682
+ const more = m.count > 10 ? ` (first 10 shown; --json lists ${m.first.length})` : "";
1683
+ lines.push(`misfits in ${type}: ${m.count}, kept unchanged under $raw${more}: ${m.first.slice(0, 10).map((x) => `${x.id}.${x.field}`).join(", ")}`);
1684
+ }
1685
+ for (const m of r.missingIndexes) lines.push(` missing index [${m.type}]: ${m.index}`);
1686
+ if (r.pendingIndexes.length > 0) {
1687
+ lines.push(`${r.pendingIndexes.length} index build(s) left pending for serve (--skip-index-build; --json lists them all):`);
1688
+ for (const w of r.pendingIndexes.slice(0, 10)) lines.push(` ${w}`);
1689
+ }
1690
+ for (const m of r.mismatches) {
1691
+ const at = m.namespace !== void 0 ? ` ${m.namespace}/${m.type}` : "";
1692
+ lines.push(` mismatch [${m.check}]${at}: ${m.detail}`);
1693
+ }
1694
+ const phases = Object.entries(r.phases).map(([k, v]) => `${k} ${v}`);
1695
+ lines.push(`ms: ${[...phases, `total ${r.totalMs}`].join(", ")}`);
1696
+ if (r.switchOver !== null) lines.push(`switch over: ${r.switchOver}`);
1697
+ return `${lines.join("\n")}\n`;
1698
+ }
1699
+ /**
1700
+ * The CLI door: parse, run, print, exit code. Every string bound for stdout or
1701
+ * stderr passes one redactor, so no connection string reaches either.
1702
+ */
1703
+ async function migrateStoreCommand(tail, env, out, errOut, hooks = {}) {
1704
+ const vars = env;
1705
+ const names = /* @__PURE__ */ new Set([
1706
+ DEFAULT_FROM_ENV,
1707
+ DEFAULT_TO_ENV,
1708
+ "SUBSTRATE_DATABASE_URL"
1709
+ ]);
1710
+ for (let i = 0; i < tail.length - 1; i++) if (tail[i] === "--from-env" || tail[i] === "--to-env") names.add(tail[i + 1]);
1711
+ const redact = redactor([...names].flatMap((n) => secretsOf(vars[n])));
1712
+ const err = (s) => errOut(redact(s));
1713
+ const stdoutWrite = process.stdout.write;
1714
+ const stderrWrite = process.stderr.write;
1715
+ const realStderr = stderrWrite.bind(process.stderr);
1716
+ process.stdout.write = shim((s) => err(s));
1717
+ process.stderr.write = shim((s) => realStderr(redact(s)));
1718
+ let report;
1719
+ let json = false;
1720
+ try {
1721
+ const args = parseMigrateStoreArgs(tail);
1722
+ json = args.json;
1723
+ report = await runMigrateStore(args, env, {
1724
+ progress: (line) => err(`${line}\n`),
1725
+ ...hooks
1726
+ });
1727
+ } catch (e) {
1728
+ err(`${e instanceof Error ? e.message : String(e)}\n`);
1729
+ return e instanceof AdminCliError ? e.exitCode : 1;
1730
+ } finally {
1731
+ process.stdout.write = stdoutWrite;
1732
+ process.stderr.write = stderrWrite;
1733
+ }
1734
+ out(redact(formatMigrateStoreOutput(report, json)));
1735
+ return report.exitCode;
1736
+ }
1737
+ /** A `stream.write` stand-in that hands decoded text to `sink`, honouring `encoding` and `callback`. */
1738
+ function shim(sink) {
1739
+ return ((chunk, encoding, callback) => {
1740
+ const cb = typeof encoding === "function" ? encoding : callback;
1741
+ const enc = typeof encoding === "string" ? encoding : void 0;
1742
+ sink(typeof chunk === "string" ? enc === void 0 || enc === "utf8" || enc === "utf-8" ? chunk : Buffer.from(chunk, enc).toString("utf8") : Buffer.from(chunk).toString("utf8"));
1743
+ if (cb !== void 0) process.nextTick(cb, null);
1744
+ return true;
1745
+ });
1746
+ }
1747
+
1748
+ //#endregion
1749
+ //#region src/admin/commands/promote-fields.ts
1750
+ /**
1751
+ * `substrate-admin promote-fields [--url <base>]` — run the promotion sweep
1752
+ * now, through the running server's admin-gated
1753
+ * `POST /substrate/v1/_system/promote-fields`, rather than waiting for
1754
+ * `SUBSTRATE_PROMOTE_INTERVAL_MS`. It goes through the server because the
1755
+ * sweep's audit events must reach its subscribers; there is no `--direct`.
1756
+ * Unlike the timed sweep, it retries a field a unique conflict holds back,
1757
+ * so an operator who has fixed the data can finish its promotion.
1758
+ */
1759
+ /** Parses `argv` (after the subcommand), resolves the server, and runs one sweep there. */
1760
+ async function promoteFieldsCommand(argv, env, fetchImpl = substrateFetch) {
1761
+ validateArgv("promote-fields", argv);
1762
+ let url;
1763
+ for (let i = 0; i < argv.length; i++) {
1764
+ if (argv[i] !== "--url") continue;
1765
+ if (url !== void 0) throw argvError("promote-fields", "promote-fields: --url specified more than once");
1766
+ url = argv[i + 1] ?? "";
1767
+ i += 1;
1768
+ }
1769
+ if (url === "") throw argvError("promote-fields", "promote-fields: --url requires a base URL");
1770
+ const target = resolveAdminTarget(url ?? null, env);
1771
+ if (target.kind !== "route") throw new AdminCliError("promote-fields runs on a running server: pass --url <base> or set SUBSTRATE_URL", 1);
1772
+ const auth = resolveAdminAuth(env, target.baseUrl);
1773
+ if ("error" in auth) throw new AdminCliError(`promote-fields: ${auth.error}`, 1);
1774
+ const endpoint = `${trimTrailingSlashes(target.baseUrl)}/substrate/v1/_system/promote-fields`;
1775
+ let res;
1776
+ try {
1777
+ res = await fetchImpl(endpoint, {
1778
+ method: "POST",
1779
+ headers: {
1780
+ authorization: auth.ok,
1781
+ "content-type": "application/json"
1782
+ },
1783
+ body: "{}",
1784
+ redirect: "error"
1785
+ });
1786
+ } catch (err) {
1787
+ throw new AdminCliError(`could not reach ${endpoint}: ${err instanceof Error ? err.message : String(err)}`, 1);
1788
+ }
1789
+ const payload = await res.json().catch(() => ({}));
1790
+ if (!res.ok) {
1791
+ const reason = typeof payload.message === "string" ? payload.message : typeof payload.code === "string" ? payload.code : `HTTP ${res.status}`;
1792
+ throw new AdminCliError(`promote-fields: ${reason}`, res.status === 403 ? 5 : 1);
1793
+ }
1794
+ if (!Array.isArray(payload.events)) throw new AdminCliError("promote-fields: response carried no `events` array", 1);
1795
+ return {
1796
+ target: describeAdminTarget("promote-fields", target),
1797
+ events: payload.events
1798
+ };
1799
+ }
1800
+ /** One line per field, after the target line. */
1801
+ function formatPromoteFieldsOutput(result) {
1802
+ const lines = [result.target];
1803
+ if (result.events.length === 0) lines.push("no pending fields");
1804
+ for (const e of result.events) {
1805
+ const outcome = e.kind === "busy" && e.error !== void 0 ? `busy (${e.error})` : `${e.kind} (attempt ${e.attempts})${e.error !== void 0 ? ` — ${e.error}` : ""}`;
1806
+ lines.push(`${e.namespace}/${e.type}.${e.field}: ${outcome}`);
1807
+ }
1808
+ return `${lines.join("\n")}\n`;
1809
+ }
1810
+
1811
+ //#endregion
1812
+ //#region src/admin/commands/revoke.ts
1813
+ /**
1814
+ * `revoke` — soft-delete a Key by stamping `revokedAt`.
1815
+ *
1816
+ * Refuses the last active admin. `checkRevocable` is shared with the route so
1817
+ * both transports enforce the same floor.
1818
+ */
1819
+ async function runRevoke(kid, env, openDataset = openPgDataset) {
1820
+ if (kid === void 0 || kid.length === 0) throw argvError("revoke", "revoke requires a <kid> positional arg");
1821
+ const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : "admin";
1822
+ const { dataset, close } = await openDataset(env);
1823
+ try {
1824
+ return await dataset.withTransaction(async (tx) => {
1825
+ const existing = await readKeyById(tx, kid);
1826
+ const refusal = checkRevocable({
1827
+ kid,
1828
+ exists: existing !== null,
1829
+ existingRevokedAt: existing?.revokedAt,
1830
+ activeAdminKids: (await listActiveAdminKeys(tx, adminCapability)).map((a) => a.kid)
1831
+ });
1832
+ if (refusal !== null) throw new AdminCliError(refusal.message, REVOKE_EXIT_CODES[refusal.code]);
1833
+ const now = /* @__PURE__ */ new Date();
1834
+ const mergedRow = forUpdate({
1835
+ ...existing.row,
1836
+ revokedAt: now
1837
+ });
1838
+ await tx.write("Key", [mergedRow], ACTOR_HINT);
1839
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1840
+ actorKid: CLI_ACTOR_KID,
1841
+ kind: "key_revoked",
1842
+ targetKid: kid,
1843
+ details: {
1844
+ revokedAt: now.toISOString(),
1845
+ cliSubcommand: "revoke"
1846
+ },
1847
+ now
1848
+ })], ACTOR_HINT);
1849
+ return {
1850
+ kid,
1851
+ revokedAt: now.toISOString()
1852
+ };
1853
+ });
1854
+ } finally {
1855
+ await close();
1856
+ }
1857
+ }
1858
+ function formatRevokeOutput(result) {
1859
+ return [
1860
+ `Key ${result.kid} revoked at ${result.revokedAt}`,
1861
+ "",
1862
+ RESTART_NOTE,
1863
+ ""
1864
+ ].join("\n");
1865
+ }
1866
+
1867
+ //#endregion
1868
+ //#region src/admin/commands/rotate.ts
1869
+ /**
1870
+ * `rotate` — mint a fresh keypair for an existing kid and retire the old row,
1871
+ * in one transaction.
1872
+ *
1873
+ * `--out` is required and must not already exist. An admin tool that silently
1874
+ * clobbers an operator's private key destroys the only copy of a credential.
1875
+ */
1876
+ function parseRotateArgs(argv) {
1877
+ try {
1878
+ return parseRotateArgsInner(argv);
1879
+ } catch (err) {
1880
+ if (err instanceof AdminCliError) throw argvError("rotate", err.message, err.exitCode);
1881
+ throw err;
1882
+ }
1883
+ }
1884
+ function parseRotateArgsInner(argv) {
1885
+ const rest = argv.slice(1);
1886
+ validateArgv("rotate", rest);
1887
+ let kid;
1888
+ let outPath;
1889
+ let wantsEncrypt = false;
1890
+ for (let i = 0; i < rest.length; i++) {
1891
+ const tok = rest[i];
1892
+ if (tok === void 0) continue;
1893
+ if (tok === "--out") {
1894
+ if (outPath !== void 0) throw new AdminCliError("rotate: --out specified more than once", 1);
1895
+ const val = rest[i + 1];
1896
+ if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError("rotate: --out requires a path argument", 1);
1897
+ outPath = val;
1898
+ i += 1;
1899
+ } else if (tok === "--encrypt") {
1900
+ if (wantsEncrypt) throw new AdminCliError("rotate: --encrypt specified more than once", 1);
1901
+ wantsEncrypt = true;
1902
+ } else kid = tok;
1903
+ }
1904
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("rotate requires a <kid> positional arg", 1);
1905
+ if (outPath === void 0 || outPath.length === 0) throw new AdminCliError("rotate requires --out <path>", 1);
1906
+ return {
1907
+ kid,
1908
+ outPath,
1909
+ wantsEncrypt
1910
+ };
1911
+ }
1912
+ async function runRotate(kid, outPath, env, wantsEncrypt = false, openDataset = openPgDataset) {
1913
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("rotate requires a <kid> positional arg");
1914
+ if (outPath === void 0 || outPath.length === 0) throw new AdminCliError("rotate requires --out <path>");
1915
+ if (existsSync(outPath)) throw new AdminCliError(`--out path already exists: ${outPath} (move it aside and retry)`, 2);
1916
+ const { publicKeyPem, privateKeyPem, encrypted } = generateAdminKeypair(env, wantsEncrypt);
1917
+ try {
1918
+ mkdirSync(dirname(outPath), {
1919
+ recursive: true,
1920
+ mode: 448
1921
+ });
1922
+ writeFileSync(outPath, privateKeyPem, {
1923
+ mode: 384,
1924
+ flag: "wx"
1925
+ });
1926
+ } catch (err) {
1927
+ const msg = err instanceof Error ? err.message : String(err);
1928
+ throw new AdminCliError(`failed to write private key to '${outPath}': ${msg}. Nothing was changed.`, 5);
1929
+ }
1930
+ let committed = false;
1931
+ const { dataset, close } = await openDataset(env).catch((err) => {
1932
+ rmSync(outPath, { force: true });
1933
+ throw err;
1934
+ });
1935
+ try {
1936
+ const newKid = randomUUID();
1937
+ const shaFull = createHash("sha256").update(publicKeyPem).digest();
1938
+ const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
1939
+ const { name, namespaces, capabilities } = await dataset.withTransaction(async (tx) => {
1940
+ const existing = await readKeyById(tx, kid);
1941
+ if (existing === null) throw new AdminCliError(`no Key with kid ${kid}`, 3);
1942
+ if (existing.revokedAt != null) throw new AdminCliError(`cannot rotate revoked Key ${kid}`, 4);
1943
+ const preservedName = typeof existing.row.name === "string" ? existing.row.name : "";
1944
+ const preservedAlgorithm = typeof existing.row.algorithm === "string" ? existing.row.algorithm : "EdDSA";
1945
+ if (preservedAlgorithm !== "EdDSA") throw new AdminCliError(`cannot rotate Key with algorithm '${preservedAlgorithm}' — only EdDSA is currently supported by the CLI`, 5);
1946
+ const preservedNamespaces = typeof existing.row.namespaces === "string" ? existing.row.namespaces : "";
1947
+ const preservedCapabilities = typeof existing.row.capabilities === "string" ? existing.row.capabilities : "";
1948
+ const preservedKid = existing.row.kid;
1949
+ const now = /* @__PURE__ */ new Date();
1950
+ await tx.write("Key", [forUpdate({
1951
+ ...existing.row,
1952
+ revokedAt: now
1953
+ })], ACTOR_HINT);
1954
+ await tx.write("Key", [{
1955
+ id: newKid,
1956
+ kid: preservedKid,
1957
+ name: preservedName,
1958
+ algorithm: preservedAlgorithm,
1959
+ publicKey: publicKeyPem,
1960
+ namespaces: preservedNamespaces,
1961
+ capabilities: preservedCapabilities,
1962
+ revokedAt: null
1963
+ }], ACTOR_HINT);
1964
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1965
+ actorKid: CLI_ACTOR_KID,
1966
+ kind: "key_rotated",
1967
+ targetKid: kid,
1968
+ details: {
1969
+ oldKid: kid,
1970
+ newKid,
1971
+ name: preservedName
1972
+ },
1973
+ now
1974
+ })], ACTOR_HINT);
1975
+ return {
1976
+ name: preservedName,
1977
+ namespaces: preservedNamespaces,
1978
+ capabilities: preservedCapabilities
1979
+ };
1980
+ });
1981
+ committed = true;
1982
+ return {
1983
+ oldKid: kid,
1984
+ newKid,
1985
+ fingerprint,
1986
+ privateKeyPath: outPath,
1987
+ name,
1988
+ namespaces,
1989
+ capabilities,
1990
+ encrypted
1991
+ };
1992
+ } finally {
1993
+ if (!committed) rmSync(outPath, { force: true });
1994
+ await close();
1995
+ }
1996
+ }
1997
+ function formatRotateOutput(result) {
1998
+ const encLabel = result.encrypted ? "encrypted: aes-256-cbc+pbes2" : "unencrypted";
1999
+ return [
2000
+ "substrate-admin rotate complete.",
2001
+ `old kid: ${result.oldKid}`,
2002
+ `new kid: ${result.newKid}`,
2003
+ `fingerprint: ${result.fingerprint}`,
2004
+ `private key: ${result.privateKeyPath} (mode 0600, ${encLabel})`,
2005
+ `namespaces: ${result.namespaces}`,
2006
+ `capabilities: ${result.capabilities}`,
2007
+ "",
2008
+ `Use the new private key to sign JWTs with kid=${result.newKid} to authenticate. The old key is revoked and no longer valid.`,
2009
+ "",
2010
+ RESTART_NOTE,
2011
+ ""
2012
+ ].join("\n");
2013
+ }
2014
+
2015
+ //#endregion
2016
+ //#region src/admin/commands/update.ts
2017
+ /**
2018
+ * `update` — change a live key's grant in place, leaving the keypair alone.
2019
+ *
2020
+ * An omitted flag leaves that field unchanged; `--ns` REPLACES rather than
2021
+ * merges. Widening authority needs `--widen`, narrowing does not, and the audit
2022
+ * event carries before AND after so a grant change is reconstructable from the
2023
+ * trail rather than from whoever remembers running it.
2024
+ */
2025
+ /**
2026
+ * Parse `update <kid> [--ns <csv>] [--caps <csv>] [--name <n>] [--widen]
2027
+ * [--allow-admin]`.
2028
+ *
2029
+ * Unlike `parseRegisterArgs`, an omitted flag means LEAVE UNCHANGED: the
2030
+ * defaulting `register` does at parse time (caps → read,mutate, name → kid)
2031
+ * is deliberately not repeated, so `update <kid> --name foo` cannot change
2032
+ * the grant.
2033
+ */
2034
+ function parseUpdateArgs(argv) {
2035
+ try {
2036
+ return parseUpdateArgsInner(argv);
2037
+ } catch (err) {
2038
+ if (err instanceof AdminCliError) throw argvError("update", err.message, err.exitCode);
2039
+ throw err;
2040
+ }
2041
+ }
2042
+ function parseUpdateArgsInner(argv) {
2043
+ const rest = argv.slice(1);
2044
+ validateArgv("update", rest);
2045
+ let kid;
2046
+ let name;
2047
+ let nsCsv;
2048
+ let capsCsv;
2049
+ let widen = false;
2050
+ let allowAdmin = false;
2051
+ let allowUnknownNs = false;
2052
+ let url = null;
2053
+ const takeValue = (flag, i) => {
2054
+ const val = rest[i + 1];
2055
+ if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError(`update: ${flag} requires a value`, 1);
2056
+ return val;
2057
+ };
2058
+ for (let i = 0; i < rest.length; i++) {
2059
+ const tok = rest[i];
2060
+ if (tok === void 0) continue;
2061
+ if (tok === "--name") {
2062
+ if (name !== void 0) throw new AdminCliError("update: --name specified more than once", 1);
2063
+ name = takeValue("--name", i);
2064
+ i += 1;
2065
+ } else if (tok === "--ns") {
2066
+ if (nsCsv !== void 0) throw new AdminCliError("update: --ns specified more than once", 1);
2067
+ nsCsv = takeValue("--ns", i);
2068
+ i += 1;
2069
+ } else if (tok === "--caps") {
2070
+ if (capsCsv !== void 0) throw new AdminCliError("update: --caps specified more than once", 1);
2071
+ capsCsv = takeValue("--caps", i);
2072
+ i += 1;
2073
+ } else if (tok === "--url") {
2074
+ if (url === "") throw new AdminCliError("update: --direct and --url are mutually exclusive", 1);
2075
+ if (url !== null) throw new AdminCliError("update: --url specified more than once", 1);
2076
+ url = takeValue("--url", i);
2077
+ i += 1;
2078
+ } else if (tok === "--direct") {
2079
+ if (url !== null && url !== "") throw new AdminCliError("update: --direct and --url are mutually exclusive", 1);
2080
+ url = "";
2081
+ } else if (tok === "--allow-unknown-ns") allowUnknownNs = true;
2082
+ else if (tok === "--widen") {
2083
+ if (widen) throw new AdminCliError("update: --widen specified more than once", 1);
2084
+ widen = true;
2085
+ } else if (tok === "--allow-admin") {
2086
+ if (allowAdmin) throw new AdminCliError("update: --allow-admin specified more than once", 1);
2087
+ allowAdmin = true;
2088
+ } else kid = tok;
2089
+ }
2090
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("update requires a <kid> positional arg", 1);
2091
+ const splitCsv = (csv) => csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
2092
+ const namespaces = nsCsv === void 0 ? void 0 : splitCsv(nsCsv);
2093
+ if (namespaces !== void 0) {
2094
+ const nsError = grantEntryError(namespaces, ["read", "mutate"]);
2095
+ if (nsError !== null) throw new AdminCliError(`update: ${nsError} — e.g. --ns inventory:read,notes:read+mutate`, 1);
2096
+ }
2097
+ return {
2098
+ kid,
2099
+ name,
2100
+ namespaces,
2101
+ capabilities: capsCsv === void 0 ? void 0 : splitCsv(capsCsv),
2102
+ widen,
2103
+ allowAdmin,
2104
+ allowUnknownNs,
2105
+ url
2106
+ };
2107
+ }
2108
+ /**
2109
+ * NOTE on `--allow-unknown-ns`: the unhosted-namespace check is ROUTE-SIDE
2110
+ * only, because it needs the engine's federated schema. A `--direct` update
2111
+ * can still write a grant naming a namespace nobody hosts.
2112
+ */
2113
+ async function runUpdate(args, env, openDataset = openPgDataset) {
2114
+ if (args.name === void 0 && args.namespaces === void 0 && args.capabilities === void 0) throw new AdminCliError("update requires at least one of --ns, --caps or --name — there is nothing to change", 1);
2115
+ const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : "admin";
2116
+ const { dataset, close } = await openDataset(env);
2117
+ try {
2118
+ return await dataset.withTransaction(async (tx) => {
2119
+ const existing = await readKeyById(tx, args.kid);
2120
+ const prevNs = decodeList(existing?.row.namespaces);
2121
+ const prevCaps = decodeList(existing?.row.capabilities);
2122
+ const prevName = typeof existing?.row.name === "string" ? existing.row.name : "";
2123
+ const nextNs = args.namespaces ?? prevNs;
2124
+ const nextCaps = args.capabilities ?? prevCaps;
2125
+ const nextName = args.name ?? prevName;
2126
+ const refusal = checkUpdatable({
2127
+ kid: args.kid,
2128
+ exists: existing !== null,
2129
+ existingRevokedAt: existing?.revokedAt,
2130
+ prevNamespaces: prevNs,
2131
+ prevCapabilities: prevCaps,
2132
+ nextNamespaces: nextNs,
2133
+ nextCapabilities: nextCaps,
2134
+ activeAdminKids: (await listActiveAdminKeys(tx, adminCapability)).map((a) => a.kid),
2135
+ adminCapability,
2136
+ widen: args.widen === true,
2137
+ allowAdmin: args.allowAdmin === true
2138
+ });
2139
+ if (refusal !== null) {
2140
+ const suffix = refusal.code === "requires_widen" ? " Pass --widen to confirm it is deliberate. Narrowing a grant needs no flag." : refusal.code === "requires_allow_admin" ? "" : "";
2141
+ const message = refusal.code === "requires_allow_admin" ? "update: granting the 'admin' capability requires --allow-admin" : `${refusal.message}${suffix}`;
2142
+ throw new AdminCliError(message, UPDATE_EXIT_CODES[refusal.code]);
2143
+ }
2144
+ const nsGranted = newlyGranted(prevNs, nextNs);
2145
+ const capsGranted = newlyGranted(prevCaps, nextCaps);
2146
+ const before = {
2147
+ name: prevName,
2148
+ namespaces: encodeList(prevNs),
2149
+ capabilities: encodeList(prevCaps)
2150
+ };
2151
+ const after = {
2152
+ name: nextName,
2153
+ namespaces: encodeList(nextNs),
2154
+ capabilities: encodeList(nextCaps)
2155
+ };
2156
+ if (!(after.name !== before.name || after.namespaces !== before.namespaces || after.capabilities !== before.capabilities)) return {
2157
+ kid: args.kid,
2158
+ before,
2159
+ after,
2160
+ changed: false
2161
+ };
2162
+ const now = /* @__PURE__ */ new Date();
2163
+ await tx.write("Key", [forUpdate({
2164
+ ...existing.row,
2165
+ name: after.name,
2166
+ namespaces: after.namespaces,
2167
+ capabilities: after.capabilities
2168
+ })], ACTOR_HINT);
2169
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
2170
+ actorKid: CLI_ACTOR_KID,
2171
+ kind: "key_authority_updated",
2172
+ targetKid: args.kid,
2173
+ details: {
2174
+ before,
2175
+ after,
2176
+ namespacesGranted: nsGranted,
2177
+ capabilitiesGranted: capsGranted,
2178
+ widened: nsGranted.length > 0 || capsGranted.length > 0,
2179
+ cliSubcommand: "update"
2180
+ },
2181
+ now
2182
+ })], ACTOR_HINT);
2183
+ return {
2184
+ kid: args.kid,
2185
+ before,
2186
+ after,
2187
+ changed: true
2188
+ };
2189
+ });
2190
+ } finally {
2191
+ await close();
2192
+ }
2193
+ }
2194
+ function formatUpdateOutput(result) {
2195
+ if (!result.changed) return [
2196
+ `substrate-admin update: no change — ${result.kid} already carries this authority.`,
2197
+ `name: ${result.before.name}`,
2198
+ ...grantLines("grant: ", result.before.namespaces, result.before.capabilities),
2199
+ ` (stored as: namespaces='${result.before.namespaces}' capabilities='${result.before.capabilities}')`,
2200
+ "",
2201
+ "Nothing was written and no audit row was emitted.",
2202
+ ""
2203
+ ].join("\n");
2204
+ const row = (label, b, a) => b === a ? `${label}${b === "" ? "(empty)" : b} (unchanged)` : `${label}${b} -> ${a}`;
2205
+ const beforeGrant = grantLines("grant before: ", result.before.namespaces, result.before.capabilities);
2206
+ const afterGrant = grantLines(" after: ", result.after.namespaces, result.after.capabilities);
2207
+ return [
2208
+ "substrate-admin update complete.",
2209
+ `kid: ${result.kid}`,
2210
+ row("name: ", result.before.name, result.after.name),
2211
+ ...beforeGrant,
2212
+ ...afterGrant,
2213
+ ` (stored as: namespaces='${result.after.namespaces}' capabilities='${result.after.capabilities}')`,
2214
+ "",
2215
+ RESTART_NOTE,
2216
+ ""
2217
+ ].join("\n");
2218
+ }
2219
+
2220
+ //#endregion
2221
+ //#region src/admin/main.ts
2222
+ /**
2223
+ * Argv -> subcommand dispatch.
2224
+ *
2225
+ * Every case here is thin on purpose: parse, resolve the target, call the
2226
+ * command module, format. The logic lives in `./commands/`, so this file stays
2227
+ * readable as the map of what the CLI can do.
2228
+ */
2229
+ /**
2230
+ * CLI entry point. Parses `process.argv`, dispatches to the requested
2231
+ * sub-command, and writes human-readable output. Returns the exit code so the
2232
+ * top-level runner can call `process.exit` once.
2233
+ */
2234
+ async function main(argv, env, out, errOut, openDataset = openPgDataset, prompt = {
2235
+ ask: async () => null,
2236
+ interactive: false
2237
+ }) {
2238
+ const command = argv[0];
2239
+ if (command === void 0) {
2240
+ errOut(`${USAGE}\n`);
2241
+ return 1;
2242
+ }
2243
+ if (command === "--version" || command === "-v" || command === "version") {
2244
+ out(`${version}\n`);
2245
+ return 0;
2246
+ }
2247
+ if (command === "help" || argv.some((a) => a === "--help" || a === "-h")) {
2248
+ out(`${USAGE}\n`);
2249
+ return 0;
2250
+ }
2251
+ try {
2252
+ if (ARGV_SPEC[command] === void 0) {
2253
+ errOut(`unknown command: ${command}\n${USAGE}\n`);
2254
+ return 1;
2255
+ }
2256
+ if (command !== "migrate-store") validateArgv(command, argv.slice(1));
2257
+ switch (command) {
2258
+ case "bootstrap": {
2259
+ const parsed = parseBootstrapArgs(argv);
2260
+ const result = await runBootstrap(env, parsed.wantsEncrypt);
2261
+ out(formatBootstrapOutput(result));
2262
+ return 0;
2263
+ }
2264
+ case "doctor": {
2265
+ const report = await doctorCommand(argv.slice(1), env);
2266
+ out(formatDoctorReport(report));
2267
+ return report.exitCode;
2268
+ }
2269
+ case "onboard": return onboardCommand(argv.slice(1), env, {
2270
+ out,
2271
+ ask: prompt.ask
2272
+ }, prompt.interactive);
2273
+ case "list": {
2274
+ const args = parseListArgs(argv.slice(1));
2275
+ if (args.url !== void 0) {
2276
+ const remote = await runKeyListViaRoute(args.url, env);
2277
+ out(formatRemoteListOutput(remote, args.url));
2278
+ return 0;
2279
+ }
2280
+ const rows = await runList(env, openDataset);
2281
+ out(formatListOutput(rows));
2282
+ return 0;
2283
+ }
2284
+ case "revoke": {
2285
+ const rest = argv.slice(1);
2286
+ let kid;
2287
+ let url;
2288
+ let direct = false;
2289
+ for (let i = 0; i < rest.length; i++) {
2290
+ const tok = rest[i];
2291
+ if (tok === void 0) continue;
2292
+ if (tok === "--url") {
2293
+ if (url !== void 0) throw argvError("revoke", "revoke: --url specified more than once", 1);
2294
+ url = rest[i + 1] ?? "";
2295
+ i += 1;
2296
+ continue;
2297
+ }
2298
+ if (tok === "--direct") {
2299
+ direct = true;
2300
+ continue;
2301
+ }
2302
+ kid = tok;
2303
+ }
2304
+ if (kid === void 0 || kid.length === 0) {
2305
+ errOut(`revoke requires a <kid> positional arg\n${USAGE}\n`);
2306
+ return 1;
2307
+ }
2308
+ if (direct && url !== void 0) throw argvError("revoke", "revoke: --direct and --url are mutually exclusive", 1);
2309
+ const target = resolveAdminTarget(direct ? "" : url ?? null, env);
2310
+ errOut(`${describeAdminTarget("revoke", target)}\n`);
2311
+ if (target.kind === "route") {
2312
+ const payload = await runKeyPatchViaRoute({
2313
+ kid,
2314
+ revoke: true
2315
+ }, target.baseUrl, env, REVOKE_EXIT_CODES);
2316
+ out(`Key ${String(payload.kid)} revoked at ${String(payload.revokedAt)} — the running server saw it.
2317
+ `);
2318
+ return 0;
2319
+ }
2320
+ const result = await runRevoke(kid, env, openDataset);
2321
+ out(formatRevokeOutput(result));
2322
+ return 0;
2323
+ }
2324
+ case "rotate": {
2325
+ const parsed = parseRotateArgs(argv);
2326
+ const result = await runRotate(parsed.kid, parsed.outPath, env, parsed.wantsEncrypt, openDataset);
2327
+ out(formatRotateOutput(result));
2328
+ return 0;
2329
+ }
2330
+ case "register": {
2331
+ const parsed = parseRegisterArgs(argv);
2332
+ const target = resolveAdminTarget(parsed.url, env);
2333
+ errOut(`${describeAdminTarget("register", target)}\n`);
2334
+ const result = target.kind === "route" ? await runRegisterViaRoute(parsed, target.baseUrl, env) : await runRegister(parsed, env, openDataset);
2335
+ out(formatRegisterOutput(result));
2336
+ return 0;
2337
+ }
2338
+ case "update": {
2339
+ const parsed = parseUpdateArgs(argv);
2340
+ const target = resolveAdminTarget(parsed.url, env);
2341
+ errOut(`${describeAdminTarget("update", target)}\n`);
2342
+ if (target.kind === "route") {
2343
+ const payload = await runKeyPatchViaRoute({
2344
+ kid: parsed.kid,
2345
+ ...parsed.name !== void 0 ? { name: parsed.name } : {},
2346
+ ...parsed.namespaces !== void 0 ? { namespaces: parsed.namespaces } : {},
2347
+ ...parsed.capabilities !== void 0 ? { capabilities: parsed.capabilities } : {},
2348
+ widen: parsed.widen === true,
2349
+ allowAdmin: parsed.allowAdmin === true,
2350
+ allowUnknownNs: parsed.allowUnknownNs
2351
+ }, target.baseUrl, env, UPDATE_EXIT_CODES);
2352
+ out(`Key ${String(payload.kid)} updated via the route — the running server saw it.\n`);
2353
+ return 0;
2354
+ }
2355
+ const result = await runUpdate(parsed, env, openDataset);
2356
+ out(formatUpdateOutput(result));
2357
+ return 0;
2358
+ }
2359
+ case "migrate-store": return migrateStoreCommand(argv.slice(1), env, out, errOut);
2360
+ case "promote-fields": {
2361
+ const result = await promoteFieldsCommand(argv.slice(1), env);
2362
+ out(formatPromoteFieldsOutput(result));
2363
+ return result.events.some((e) => e.kind === "failed") ? 1 : 0;
2364
+ }
2365
+ default:
2366
+ errOut(`unknown command: ${command}\n${USAGE}\n`);
2367
+ return 1;
2368
+ }
2369
+ } catch (err) {
2370
+ const exitCode = err instanceof BootstrapError || err instanceof AdminCliError ? err.exitCode : 1;
2371
+ errOut(`${err instanceof Error ? err.message : String(err)}\n`);
2372
+ return exitCode;
2373
+ }
2374
+ }
2375
+
2376
+ //#endregion
2377
+ //#region src/admin/stdin-ask.ts
2378
+ /**
2379
+ * The line reader behind an interactive `substrate-admin onboard`.
2380
+ *
2381
+ * - End of input (Ctrl-D, a closed pipe) resolves the open question, and every later
2382
+ * one, with null — the loop turns that into a quit with its summary.
2383
+ * - Ctrl-C at a prompt does the same. Ctrl-C with no prompt open (an action or a fetch in
2384
+ * flight) calls `onInterrupt`, because no prompt will come back to notice a close.
2385
+ * - `terminal` is set from the INPUT, so redirecting stderr cannot turn Ctrl-C back into
2386
+ * a process-killing SIGINT.
2387
+ * - One pending resolver and one permanent close listener, so nothing accumulates per
2388
+ * question.
2389
+ */
2390
+ function createAsk(streams) {
2391
+ const rl = createInterface({
2392
+ input: streams.input,
2393
+ output: streams.output,
2394
+ terminal: streams.terminal
2395
+ });
2396
+ let closed = false;
2397
+ let pending = null;
2398
+ const settle = (line) => {
2399
+ const resolve = pending;
2400
+ pending = null;
2401
+ resolve?.(line);
2402
+ };
2403
+ rl.on("close", () => {
2404
+ closed = true;
2405
+ settle(null);
2406
+ });
2407
+ rl.on("SIGINT", () => {
2408
+ if (pending !== null) rl.close();
2409
+ else streams.onInterrupt();
2410
+ });
2411
+ return (prompt) => {
2412
+ if (closed) return Promise.resolve(null);
2413
+ return new Promise((resolve) => {
2414
+ pending = resolve;
2415
+ rl.question(prompt, (line) => settle(line));
2416
+ });
2417
+ };
2418
+ }
2419
+
2420
+ //#endregion
2421
+ //#region src/admin/run.ts
2422
+ /** Runs `substrate-admin` on this process's argv, then exits with its code. */
2423
+ function runAdminCli() {
2424
+ const interactive = process.stdin.isTTY === true && process.argv[2] === "onboard";
2425
+ main(process.argv.slice(2), process.env, (s) => process.stdout.write(s), (s) => process.stderr.write(s), openPgDataset, interactive ? {
2426
+ ask: createAsk({
2427
+ input: process.stdin,
2428
+ output: process.stderr,
2429
+ terminal: true,
2430
+ onInterrupt: () => {
2431
+ process.stderr.write("\ninterrupted.\n");
2432
+ process.exit(130);
2433
+ }
2434
+ }),
2435
+ interactive: true
2436
+ } : {
2437
+ ask: async () => null,
2438
+ interactive: false
2439
+ }).then((exitCode) => process.exit(exitCode));
2440
+ }
2441
+
2442
+ //#endregion
2443
+ export { runAdminCli };