@substrat-run/cli 0.44.0 → 0.45.0

package/dist/data-loss-check.js

@@ -0,0 +1,260 @@
+/**
+ * The data-loss check a push makes before upload (#2321): the vertical's authored migrations,
+ * replayed against an in-memory scope that holds data, through the data-loss fence (#115).
+ *
+ * The fence refuses, at apply, a migration that would lose data a scope holds and does not
+ * declare it — which closes every populated scope until a fixed version ships. In this repository
+ * `lint:migration-fence` asks the question in the pull request; a vertical built anywhere else
+ * has only this, the push, as the earlier and cheaper place to hear no.
+ *
+ * The replay is the VERTICAL's own kernel's (`replayMigrations`), reached at run time the way
+ * `moduleMigrations` is (#1677): it is the copy of the fence the vertical's scopes run at apply,
+ * so it is the one whose answer matters, and this CLI stays Apache-2.0 with no kernel dependency.
+ * What this module supplies is only what the kernel does not import: an empty in-memory SQLite
+ * (`node:sqlite`), and the platform's spine tables from the vertical's own
+ * `@substrat-run/adapter-sqlite`, when it has one, for an authored migration that reads them.
+ *
+ * It runs in a process of its own (`data-loss-replay-child.ts`), with an empty environment and a
+ * time limit per migration, because a runaway statement — a recursive CTE with no end — runs in
+ * native code nothing in this process could interrupt. The fence refuses ATTACH, so the replay
+ * never reaches a file; it opens no network connection and reads none of the vertical's data.
+ *
+ * Three outcomes, never confused:
+ * - REFUSED — the fence would refuse a migration. The push stops, with the fence's own message
+ *   naming the declaration (`moves` / `discards`) to add. There is no flag past it: a `discards`
+ *   entry with its reason is the reviewed way to lose data on purpose.
+ * - INCOMPLETE — a migration could not be run on synthetic rows at all (its SQL needs real input,
+ *   reads a spine table this CLI could not build, or did not finish in time). The replay stops
+ *   there, so the migrations after it go unchecked, and the warning says how many.
+ * - SKIPPED — nothing could be replayed: no `node:sqlite` (Node before 22.13), or a kernel with
+ *   no replay this CLI knows how to call.
+ * The last two do not refuse by default — promote is the hard gate, and the fence still refuses
+ * there — unless the caller asks for the guarantee (`--require-data-loss-check`).
+ */
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+/** The replay API this CLI calls — `MIGRATION_REPLAY_API` in `@substrat-run/kernel`. */
+const REPLAY_API = 1;
+/**
+ * How long one migration may run. A Durable Object would stop a migration that ran this long
+ * on its own CPU limit, so a replay that has not finished by then is not one worth waiting for.
+ */
+export const MIGRATION_TIMEOUT_MS = 30_000;
+const isOutcome = (o) => {
+    const r = o;
+    const stop = (s) => s === undefined || (typeof s.key === 'string' && typeof s.message === 'string');
+    return (typeof r === 'object' && r !== null &&
+        typeof r.authored === 'number' && typeof r.passed === 'number' &&
+        Array.isArray(r.declared) && r.declared.every((d) => typeof d === 'string') &&
+        stop(r.refused) && stop(r.failed));
+};
+/** The built child, beside this module in `dist`. */
+const CHILD = fileURLToPath(new URL('./data-loss-replay-child.js', import.meta.url));
+/**
+ * Run the replay in its own process, killing it when one migration runs past `timeoutMs`. Each
+ * `started` line restarts the clock, so the limit is per migration, and says which one was
+ * running when it fired and how many authored migrations had passed before it.
+ */
+export function replayInChild(request, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? MIGRATION_TIMEOUT_MS;
+    // The child's stderr is kept, never forwarded: node's notice that `node:sqlite` is experimental
+    // stays out of the push log, and only a process that dies without answering is shown it.
+    const child = spawn(process.execPath, [opts.childPath ?? CHILD], {
+        cwd: tmpdir(),
+        // Nothing of the pusher's environment: the replay needs none of it.
+        env: process.platform === 'win32' && process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {},
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return new Promise((resolveResult) => {
+        let settled = false;
+        let key;
+        let authoredStarted = 0;
+        let runningAuthored = false;
+        let stdout = '';
+        let stderr = '';
+        let timer;
+        // A push that ends any other way — it exits, throws, or is killed by a signal, SIGKILL
+        // included — takes the replay with it through the child's own watchdog
+        // (`data-loss-replay-child.ts`), which no handler here could do for SIGKILL. On POSIX; on
+        // Windows, where an orphan is not re-parented, only the child's hard deadline stops it.
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode !== null || child.signalCode !== null) {
+                resolveResult(result);
+                return;
+            }
+            // Answered only once the process is gone, so nothing the replay started outlives it.
+            child.once('exit', () => resolveResult(result));
+            child.kill('SIGKILL');
+        };
+        const arm = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => settle({ kind: 'timeout', key, passed: authoredStarted - (runningAuthored ? 1 : 0) }), timeoutMs);
+        };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+            let nl;
+            while ((nl = stdout.indexOf('\n')) >= 0) {
+                const line = stdout.slice(0, nl);
+                stdout = stdout.slice(nl + 1);
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (message.type === 'started') {
+                    key = message.key;
+                    runningAuthored = message.authored;
+                    if (message.authored)
+                        authoredStarted += 1;
+                    arm();
+                }
+                else if (message.type === 'done') {
+                    settle(message.result);
+                }
+            }
+        });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            stderr = (stderr + chunk).slice(-2000);
+        });
+        child.on('error', (e) => settle({ kind: 'error', message: e.message }));
+        // `close`, not `exit`: it fires once stdout has drained, so a last `done` line is never lost.
+        child.on('close', (code, signal) => settle({ kind: 'error', message: `the replay process ended (${signal ?? `exit ${code}`}) without an answer${stderr ? `: ${stderr.trim()}` : ''}` }));
+        arm();
+        child.stdin.on('error', () => { });
+        child.stdin.end(JSON.stringify(request));
+    });
+}
+const DOCS = 'see https://substrat.net/concepts/deploying ("A migration cannot quietly lose data")';
+const TRUTHY = /^(1|true|yes)$/i;
+const FALSY = /^(0|false|no)?$/i;
+/**
+ * Is the check required to have run: the flag, or `SUBSTRAT_REQUIRE_DATA_LOSS_CHECK` set to `1`,
+ * `true` or `yes` (any case). Any other non-empty value is warned about rather than read as no,
+ * because a CI job that meant yes would otherwise get the permissive default without a word.
+ */
+export function dataLossCheckRequired(argv, env = process.env, warn = console.error) {
+    if (argv.includes('--require-data-loss-check'))
+        return true;
+    const value = (env.SUBSTRAT_REQUIRE_DATA_LOSS_CHECK ?? '').trim();
+    if (TRUTHY.test(value))
+        return true;
+    if (!FALSY.test(value)) {
+        warn(`⚠ SUBSTRAT_REQUIRE_DATA_LOSS_CHECK=${value} is not one of 1/true/yes or 0/false/no — read as no, so the data-loss check stays optional`);
+    }
+    return false;
+}
+/** The one summary line, the same in the check's own output and the push's last line. */
+export function formatDataLossCheck(check) {
+    switch (check.status) {
+        case 'passed':
+            return `data-loss check: PASSED (${check.authored} authored migration(s) replayed against a populated scope)`;
+        case 'skipped':
+            return `data-loss check: SKIPPED (${check.why}) — the fence still refuses at promote`;
+        case 'incomplete':
+            return (`data-loss check: INCOMPLETE (${check.notReplayed} of ${check.authored} authored migration(s) were not replayed ` +
+                `after ${check.key} failed) — the fence still refuses at promote`);
+    }
+}
+/**
+ * Replay the vertical's migrations through its own kernel's fence. Throws when the fence would
+ * refuse one, and — with `require` — when the check was skipped or incomplete. Otherwise returns
+ * the outcome, having printed each declared move and discard with its reason (`log`) and the
+ * summary (`log` when passed, `warn` — stderr — when it is not).
+ */
+export async function checkMigrationDataLoss(inputs, opts = {}) {
+    const log = opts.log ?? console.log;
+    const warn = opts.warn ?? console.error;
+    const check = await replay(inputs, opts, log);
+    const line = formatDataLossCheck(check);
+    if (check.status === 'passed') {
+        log(line);
+        return check;
+    }
+    if (check.status === 'incomplete') {
+        warn(`⚠ ${check.key} could not be replayed on synthetic data: ${check.message}`);
+        if (/no such table: _substrat_/i.test(check.message)) {
+            warn('  it reads a platform table this CLI could not build: add @substrat-run/adapter-sqlite as a devDependency ' +
+                'so the replay can create them.');
+        }
+    }
+    if (opts.require) {
+        throw new Error(`${line}.\n--require-data-loss-check (or SUBSTRAT_REQUIRE_DATA_LOSS_CHECK=1) refuses a push it could not fully check.`);
+    }
+    warn(`⚠ ${line}`);
+    return check;
+}
+async function replay(inputs, opts, log) {
+    const kernel = inputs.kernel;
+    const authoredCount = inputs.modules.reduce((n, m) => {
+        const migrations = m.migrations;
+        return n + (Array.isArray(migrations) ? migrations.length : 0);
+    }, 0);
+    // Nothing authored, nothing the fence judges — and no reason to need SQLite.
+    if (authoredCount === 0)
+        return { status: 'passed', authored: 0 };
+    if (!kernel || !inputs.kernelUrl)
+        return { status: 'skipped', why: 'no @substrat-run/kernel resolves from the vertical' };
+    if (typeof kernel.replayMigrations !== 'function') {
+        return { status: 'skipped', why: "the vertical's @substrat-run/kernel has no migration replay (upgrade it)" };
+    }
+    if (kernel.MIGRATION_REPLAY_API !== REPLAY_API) {
+        return {
+            status: 'skipped',
+            why: `the vertical's @substrat-run/kernel has migration replay API ${String(kernel.MIGRATION_REPLAY_API)}, this CLI calls ${REPLAY_API} (upgrade the CLI)`,
+        };
+    }
+    // The registrations as data — what the replay reads of them, without the handlers no
+    // process boundary can carry.
+    const modules = JSON.parse(JSON.stringify(inputs.modules.map((m) => ({ manifest: m.manifest, migrations: m.migrations }))));
+    const timeoutMs = opts.timeoutMs ?? MIGRATION_TIMEOUT_MS;
+    // The child's own backstop, far past anything the per-migration limit allows: every authored
+    // migration and up to three derived ones per module (search, entity state, list), each at the
+    // limit, plus one for the start.
+    const deadlineMs = timeoutMs * (authoredCount + 3 * modules.length + 1);
+    const result = await replayInChild({ kernelUrl: inputs.kernelUrl, modules, spineDdl: await inputs.spineDdl(), deadlineMs }, { ...opts, timeoutMs });
+    if (result.kind === 'no-sqlite') {
+        return { status: 'skipped', why: `node:sqlite unavailable on Node ${process.versions.node}; it needs 22.13 or later` };
+    }
+    if (result.kind === 'error')
+        return { status: 'skipped', why: `the replay itself failed: ${result.message}` };
+    if (result.kind === 'timeout') {
+        return {
+            status: 'incomplete',
+            authored: authoredCount,
+            notReplayed: authoredCount - result.passed,
+            key: result.key ?? 'the replay',
+            message: `it did not finish within ${timeoutMs / 1000} s and was stopped — a statement with no end, such as a recursive CTE ` +
+                "without a limit? A Durable Object's own CPU limit would stop it at promote too",
+        };
+    }
+    const outcome = result.outcome;
+    if (!isOutcome(outcome))
+        return { status: 'skipped', why: "the vertical's kernel returned a replay outcome this CLI does not recognise" };
+    for (const line of outcome.declared)
+        log(`declared  ${line}`);
+    if (outcome.refused) {
+        throw new Error(`data-loss check: REFUSED — ${outcome.refused.message}\n` +
+            'A scope holding that data would refuse this migration at promote and fail closed. Fix the migration, or ' +
+            `declare the loss on it (\`moves\` / \`discards\`, with its reason) for review — ${DOCS}.`);
+    }
+    if (outcome.failed) {
+        return {
+            status: 'incomplete',
+            authored: outcome.authored,
+            notReplayed: outcome.authored - outcome.passed,
+            key: outcome.failed.key,
+            message: outcome.failed.message,
+        };
+    }
+    return { status: 'passed', authored: outcome.authored };
+}
+//# sourceMappingURL=data-loss-check.js.map

package/dist/data-loss-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-loss-check.js","sourceRoot":"","sources":["../src/data-loss-check.ts"],"names":[],"mappings":"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"}

package/dist/data-loss-replay-child.d.ts

@@ -0,0 +1,27 @@
+export interface ReplayRequest {
+    readonly kernelUrl: string;
+    readonly modules: readonly unknown[];
+    readonly spineDdl?: string;
+    /** Wall-clock limit for the whole replay, after which the child kills itself — a backstop. */
+    readonly deadlineMs: number;
+}
+/** How often the watchdog looks at its parent. */
+export declare const WATCHDOG_POLL_MS = 200;
+/** Each stdout line, in order: zero or more `started`, then one `done`. */
+export type ChildMessage = {
+    readonly type: 'started';
+    readonly key: string;
+    readonly authored: boolean;
+} | {
+    readonly type: 'done';
+    readonly result: {
+        readonly kind: 'outcome';
+        readonly outcome: unknown;
+    } | {
+        readonly kind: 'no-sqlite';
+    } | {
+        readonly kind: 'error';
+        readonly message: string;
+    };
+};
+//# sourceMappingURL=data-loss-replay-child.d.ts.map

package/dist/data-loss-replay-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-loss-replay-child.d.ts","sourceRoot":"","sources":["../src/data-loss-replay-child.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAepC,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC9E;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GACvD;QAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;KAAE,GAC9B;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D,CAAC"}

package/dist/data-loss-replay-child.js

@@ -0,0 +1,71 @@
+/**
+ * The data-loss replay's own process (#2321): what `checkMigrationDataLoss` runs the vertical's
+ * migrations in, so a runaway one can be stopped. A SQLite statement runs in native code that no
+ * JavaScript timer and no `worker.terminate()` can interrupt, and this Node's `node:sqlite` has no
+ * progress handler; a process can always be killed. See `replayInChild` for the parent's half.
+ *
+ * Reads one request as JSON on stdin — the vertical's kernel URL, its modules as data, the spine
+ * DDL — and writes one JSON line per message to stdout, synchronously, so the line naming the
+ * migration about to run is out before that migration can block the process. Started with an empty
+ * environment, in the temp directory, against an in-memory database.
+ *
+ * It must not outlive the push that started it, however that push ends. The parent kills it on a
+ * timeout, but a parent killed by a signal runs no handler at all, and an orphaned replay blocked
+ * in a SQLite step would spin forever. So the child carries a watchdog of
+ * its own: a worker thread — which a blocked main thread cannot starve — that kills this process
+ * when its parent is gone (the parent pid changes as the OS re-parents it) or the request's hard
+ * deadline passes. Covered: the parent exiting, crashing, or being killed by any signal, SIGKILL
+ * included, within the watchdog's poll interval. Not covered: a parent that is alive but stopped
+ * (SIGSTOP) — the replay then runs until the deadline — and, because the parent check relies on
+ * POSIX re-parenting an orphan, Windows, where only the deadline stops an orphaned replay.
+ */
+import { writeSync } from 'node:fs';
+import { Worker } from 'node:worker_threads';
+/** How often the watchdog looks at its parent. */
+export const WATCHDOG_POLL_MS = 200;
+/** Kill this process when the parent that started it is gone, or `deadlineMs` has passed. */
+function watchdog(deadlineMs) {
+    const worker = new Worker(`const { workerData: { parent, until, every } } = require('node:worker_threads');
+     setInterval(() => {
+       if (process.ppid !== parent || Date.now() > until) process.kill(process.pid, 'SIGKILL');
+     }, every);`, { eval: true, workerData: { parent: process.ppid, until: Date.now() + deadlineMs, every: WATCHDOG_POLL_MS } });
+    // The watchdog never keeps a finished replay alive.
+    worker.unref();
+}
+const send = (message) => {
+    writeSync(1, `${JSON.stringify(message)}\n`);
+};
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const request = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    watchdog(request.deadlineMs);
+    let open;
+    try {
+        const { DatabaseSync } = (await import('node:sqlite'));
+        open = () => new DatabaseSync(':memory:');
+    }
+    catch {
+        send({ type: 'done', result: { kind: 'no-sqlite' } });
+        return;
+    }
+    try {
+        const kernel = (await import(request.kernelUrl));
+        const db = open();
+        const outcome = kernel.replayMigrations({
+            exec: (q) => db.exec(q),
+            query: (q, p = []) => db.prepare(q).all(...p),
+            run: (q, p = []) => ({ changes: Number(db.prepare(q).run(...p).changes) }),
+        }, request.modules, {
+            spineDdl: request.spineDdl,
+            onMigration: (key, authored) => send({ type: 'started', key, authored }),
+        });
+        send({ type: 'done', result: { kind: 'outcome', outcome } });
+    }
+    catch (e) {
+        send({ type: 'done', result: { kind: 'error', message: e instanceof Error ? e.message : String(e) } });
+    }
+}
+await main();
+//# sourceMappingURL=data-loss-replay-child.js.map

package/dist/data-loss-replay-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-loss-replay-child.js","sourceRoot":"","sources":["../src/data-loss-replay-child.ts"],"names":[],"mappings":"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"}

package/dist/promote.d.ts

@@ -12,9 +12,14 @@
  * #1705 PR 3: a promote that drops or re-versions an exported event an installed app imports
  * is refused too (409), and the refusal lists the apps it would break: the caller's own tenant's
  * by name, any other tenant only as a count. `--ack-export-break` passes it once that is read.
+ *
+ * #2333: an acknowledgement answers ONE review — the diffs printed against the version prod served
+ * when they were read. Every refusal that prints them also prints the `--review` token they were
+ * read with, and the control plane refuses a token whose base or stored rows have moved since
+ * (and a `--ack-migrations` sent with none), so a person never acknowledges a diff they were not shown.
  */
 import { type MigrationDiff, type PermissionRegistry } from '@substrat-run/contracts';
-import { type ExportBreaks, type MintedStore, type PromoteResult } from '@substrat-run/control-plane-client';
+import { type ExportBreaks, type MintedStore, type PromoteResult, type PromoteReviewBinding } from '@substrat-run/control-plane-client';
 export interface PromoteOptions {
     controlPlaneUrl: string;
     header: Record<string, string>;
@@ -25,8 +30,13 @@ export interface PromoteOptions {
         permissionChange?: boolean;
         migrationChange?: boolean;
         exportBreak?: boolean;
+        review?: PromoteReviewBinding;
     };
 }
+/** How a review binding is written on the command line: `<base>:<digest>`, `-` for no base. */
+export declare function reviewToken(review: PromoteReviewBinding): string;
+/** `reviewToken` read back, or null when it is not one. The digest is hex, so the last `:` splits it. */
+export declare function parseReviewToken(token: string): PromoteReviewBinding | null;
 /** The listing a refused (or acknowledged) export break carries, one line per affected app. */
 export declare function exportBreakLines(b: ExportBreaks): string[];
 /** The listing a refusal prints, and how to answer it once it has been read. */
@@ -53,6 +63,11 @@ export declare function explainRefusal(opts: PromoteOptions, refused: {
  * "none" is never the answer, because the gate has just said there is a change.
  */
 export declare function formatRegistryDiff(from: PermissionRegistry | null, to: PermissionRegistry | null, digestMoved: boolean): string[];
+/**
+ * A module id or migration version on the listing's header line: bare when it is a plain id, as
+ * every id the push boundary admits is, and `quoted` otherwise, so nothing in it can break the line.
+ */
+export declare const idOf: (text: string) => string;
 /**
  * The migrations a promote adds, each with its SQL. `null` is a version whose manifest carries
  * none. `digestMoved` is whether the gate refused on the migration digest.

package/dist/promote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../src/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,oCAAoC,CAAC;AAI5C,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChG;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAQ1D;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAE1D;AAED,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAEzD,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAkC1E;AAOD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACnD,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,EAAE,EAAE,EAAE,kBAAkB,GAAG,IAAI,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,CA0BjI;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,CAyB9F"}
+{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../src/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAUL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,oCAAoC,CAAC;AAI5C,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC;CAC/H;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAEhE;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM3E;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAQ1D;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAE1D;AAED,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAEzD,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqC1E;AAOD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACnD,OAAO,CAAC,MAAM,EAAE,CAAC,CAmCnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,EAAE,EAAE,EAAE,kBAAkB,GAAG,IAAI,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,CA0BjI;AAYD;;;GAGG;AACH,eAAO,MAAM,IAAI,SAAU,MAAM,KAAG,MAAqD,CAAC;AAwB1F;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,CA8C9F"}

package/dist/promote.js

@@ -12,11 +12,29 @@
  * #1705 PR 3: a promote that drops or re-versions an exported event an installed app imports
  * is refused too (409), and the refusal lists the apps it would break: the caller's own tenant's
  * by name, any other tenant only as a count. `--ack-export-break` passes it once that is read.
+ *
+ * #2333: an acknowledgement answers ONE review — the diffs printed against the version prod served
+ * when they were read. Every refusal that prints them also prints the `--review` token they were
+ * read with, and the control plane refuses a token whose base or stored rows have moved since
+ * (and a `--ack-migrations` sent with none), so a person never acknowledges a diff they were not shown.
  */
-import { diffRegistries, grantShapeHolderNotes, unitemisedRegistryChanges, } from '@substrat-run/contracts';
+import { diffRegistries, grantShapeHolderNotes, promoteReviewReasonIn, clipReviewText, discardTally, reviewSql, reviewText, unitemisedRegistryChanges, } from '@substrat-run/contracts';
 import { ControlPlaneError, } from '@substrat-run/control-plane-client';
 import { planeFor, viaPlane, walkAll } from './plane.js';
 import { failureMessage, readRefused } from './problem.js';
+/** How a review binding is written on the command line: `<base>:<digest>`, `-` for no base. */
+export function reviewToken(review) {
+    return `${review.base ?? '-'}:${review.digest}`;
+}
+/** `reviewToken` read back, or null when it is not one. The digest is hex, so the last `:` splits it. */
+export function parseReviewToken(token) {
+    const at = token.lastIndexOf(':');
+    const base = token.slice(0, at);
+    const digest = token.slice(at + 1);
+    if (at <= 0 || !/^[0-9a-f]{64}$/.test(digest))
+        return null;
+    return { base: base === '-' ? null : base, digest };
+}
 /** The listing a refused (or acknowledged) export break carries, one line per affected app. */
 export function exportBreakLines(b) {
     const lines = b.affected.map((r) => `  ${r.vertical} (scope ${r.scopeId}) imports ${r.type} v${r.schemaVersion} — ` +
@@ -59,11 +77,14 @@ export async function promote(opts) {
                 ? `\n  (${parsed.exportBreaksUnavailable}; re-run with --ack-export-break to promote anyway)`
                 : '';
         const message = failureMessage('promote failed', e.status, body);
-        if (!message.includes(NEEDS_ACK))
+        // A review that moved under the acknowledgement, or a migration acknowledgement sent with none
+        // (#2333), is answered like a digest refusal: by the diffs as they stand now, and their token.
+        const review = promoteReviewReasonIn(parsed);
+        if (!message.includes(NEEDS_ACK) && review === undefined)
             throw new Error(message + listing);
         const lines = await explainRefusal(opts, {
             permission: message.includes('changes the permission surface'),
-            migration: message.includes('changes migrations'),
+            migration: message.includes('changes migrations') || review === 'promote_review_unbound',
         });
         throw new Error(`${message}${listing}\n\n${lines.join('\n')}`);
     }
@@ -89,21 +110,26 @@ export async function explainRefusal(opts, refused) {
         if (!serving)
             return ['(nothing serves this channel yet, so there is nothing to diff against)'];
         const registry = (id) => get(() => client.getVersionRegistry(opts.slug, id)).then((r) => r.registry);
-        const [from, to, migrations] = await Promise.all([
+        const [from, to, read] = await Promise.all([
             registry(serving),
             registry(opts.versionId),
-            get(() => client.getVersionMigrations(opts.slug, opts.versionId, serving)).then((r) => r.migrations),
+            get(() => client.getVersionMigrations(opts.slug, opts.versionId, serving)),
         ]);
+        // The token is the one the migrations read answered beside the diff printed here, never one
+        // put together from separate reads: the two must describe the same review.
+        const token = read.review ? reviewToken(read.review) : null;
         return [
-            `${opts.channel} serves ${serving}; promoting ${opts.versionId}.`,
+            `${opts.channel} serves ${idOf(serving)}; promoting ${idOf(opts.versionId)}.`,
             '',
             'permission changes:',
             ...formatRegistryDiff(from, to, refused.permission).map((l) => `  ${l}`),
             '',
             'migration changes:',
-            ...formatMigrationDiff(migrations, refused.migration).map((l) => `  ${l}`),
+            ...formatMigrationDiff(read.migrations, refused.migration).map((l) => `  ${l}`),
             '',
-            'note: the registry does not yet require --ack-migrations for a change to SQL migrations alone (#1754).',
+            token === null
+                ? '(this control plane hands out no review token, so --review cannot be given)'
+                : `to acknowledge exactly what is shown above, re-run with the --ack-* flags it needs and --review ${idOf(token)}`,
         ];
     }
     catch (e) {
@@ -146,6 +172,40 @@ export function formatRegistryDiff(from, to, digestMoved) {
         ? ["the permission digest changed, but the two stored registries read the same here — compare them in the repository"]
         : ['none'];
 }
+/**
+ * Pusher-supplied text on one terminal line (#2322): every control, format and bidi character
+ * made visible (`reviewText`), then quoted, which escapes the newlines and tabs it keeps. So no
+ * reason, table name or id prints as a terminal command, a reordered word or a forged line.
+ */
+const quoted = (text) => JSON.stringify(reviewText(text));
+/** What an id may hold to print bare in the listing's one-line header. */
+const PLAIN_ID = /^[A-Za-z0-9@/._~:+-]+$/;
+/**
+ * A module id or migration version on the listing's header line: bare when it is a plain id, as
+ * every id the push boundary admits is, and `quoted` otherwise, so nothing in it can break the line.
+ */
+export const idOf = (text) => (PLAIN_ID.test(text) ? text : quoted(text));
+/**
+ * A discard's reason as the listing shows it: quoted, and cut where the review cuts it
+ * (`clipReviewText`: 280 characters or 6 lines), saying where the rest is. A terminal has no
+ * expander, and the listing must stay readable down to the acknowledgement.
+ */
+function reasonOf(why) {
+    const { shown, clipped } = clipReviewText(why);
+    return clipped ? `${JSON.stringify(shown)}… (cut; the whole reason is in the dashboard's promote dialog and the migration's source)` : quoted(why);
+}
+/**
+ * What one migration declares it moves and discards (#2322), one line each under its id.
+ * Every target and reason is the pusher's text, so each goes through `quoted`.
+ */
+function declarationLines(m) {
+    if (m.declarationsLeftOut)
+        return ['    (declares moves or discards, left out: past the size bound of this answer; read them in the repository)'];
+    return [
+        ...Object.entries(m.discards ?? {}).map(([target, why]) => `    discards ${quoted(target)}: ${reasonOf(why)}`),
+        ...Object.entries(m.moves ?? {}).map(([from, to]) => `    moves ${quoted(from)} → ${quoted(to)} (verified at apply)`),
+    ];
+}
 /**
  * The migrations a promote adds, each with its SQL. `null` is a version whose manifest carries
  * none. `digestMoved` is whether the gate refused on the migration digest.
@@ -157,15 +217,31 @@ export function formatMigrationDiff(diff, digestMoved) {
                 'older than migrations in the manifest, or its migrations were over the size a manifest carries. Read them in the repository.',
         ];
     }
+    // The id and the SQL are the pusher's text too. The header is one line, so the module and the
+    // version print bare only when they are plain ids and are quoted otherwise (`idOf`): a newline
+    // in either would forge another entry above the real one. The SQL is split into its lines after
+    // `reviewSql`, so a control or bidi character in it prints as `<U+XXXX>`, not as itself.
     const entry = (mark, m) => [
-        `${mark} ${m.moduleId} ${m.version}`,
-        ...(m.sql === null ? ['    (SQL left out: past the size bound of this answer)'] : m.sql.split('\n').map((l) => `    ${l}`)),
+        `${mark} ${idOf(m.moduleId)} ${idOf(m.version)}`,
+        ...declarationLines(m),
+        ...(m.sql === null ? ['    (SQL left out: past the size bound of this answer)'] : reviewSql(m.sql).split('\n').map((l) => `    ${l}`)),
     ];
+    const discards = discardTally(diff);
     const lines = [
+        ...(discards.count > 0
+            ? [
+                `! this promote deliberately discards data in ${discards.atLeast ? 'at least ' : ''}${discards.count} place${discards.count === 1 ? '' : 's'}; ` +
+                    "each reason is the migration author's own",
+            ]
+            : discards.atLeast
+                ? ["! this list is cut, so it cannot show whether a migration left out of it discards data; read the rest in the repository"]
+                : []),
         ...(diff.baseline === 'unavailable'
             ? ['(the serving version predates carried migrations, so every migration this version ships is listed)']
             : []),
-        ...diff.changed.flatMap((m) => entry('~ (edited after shipping; a scope that already ran it will not run it again)', m)),
+        ...diff.changed.flatMap((m) => entry(m.edited === 'declarations'
+            ? '~ (declarations edited after shipping; a scope that already ran it is unaffected, one that has not is held to these)'
+            : '~ (edited after shipping; a scope that already ran it will not run it again)', m)),
         ...diff.added.flatMap((m) => entry('+', m)),
     ];
     if (diff.total === 0) {