@everystack/cli 0.4.81 → 0.4.83

package/src/cli/plain-output.ts

@@ -0,0 +1,521 @@
+/**
+ * plain-output — what db:plan, db:apply and db:check say by DEFAULT.
+ *
+ * A developer at a consumer ran the reconcile check and got 38 lines for 3 real changes.
+ * Nineteen of them were no-op notes printed at the same visual weight as the real ones, in
+ * a vocabulary only this repo understands (`≈ rebaseline`, `≠ regrant`, `= 19 up to date`).
+ * He read it as 38 things about to happen to his database and stopped. That is the output
+ * this module replaces.
+ *
+ * The whole vocabulary is three marks:
+ *
+ *   +               something is now true — added OR updated. A rebuild (drop + create of the
+ *                   same object) is ONE `+ update …` line, never a drop/create pair.
+ *   -               something is no longer true — dropped, revoked.
+ *   ⚠ DESTRUCTIVE   real data can be lost. Orthogonal to the other two: its own line, never
+ *                   combined with + or -.
+ *
+ * And a banned list (BANNED_DEFAULT_WORDS): words that mean something to us and nothing to the
+ * reader. Nothing is deleted — the full internal report is exactly as it was, behind --verbose.
+ *
+ * Everything here is PURE. It describes statements; it never decides what they are. The
+ * destructive set is computed upstream (state-apply's classifyDestructive — the same
+ * classification that gates --confirm, the snapshot and the approver set) and passed in, so
+ * this module cannot disagree with the gate about what destroys. Reading a statement — which of
+ * its lines are SQL and which are the emitter's `-- WARNING:` prologue — is shared with that gate
+ * too, in sql-statement.ts, so the two paths cannot disagree about what they are looking at
+ * before either one has decided anything.
+ */
+
+import { statementBody } from './sql-statement';
+
+// ---------------------------------------------------------------------------
+// The banned vocabulary.
+// ---------------------------------------------------------------------------
+
+/** Words and marks that may not appear in default output. Verbose keeps every one of them. */
+export const BANNED_DEFAULT_WORDS: readonly string[] = [
+  'state', 'derived', 'provenance', 'fingerprint', 'phase', '≈', '≠', 'rebaseline', 'regrant',
+];
+
+const WORD_RE = /^[a-z]+$/;
+
+/**
+ * Which banned words appear in these lines, in BANNED_DEFAULT_WORDS order.
+ *
+ * Whole words for the alphabetic entries — `statement` is not `state`, and failing on it would
+ * make the rule unusable rather than strict.
+ */
+export function bannedVocabulary(lines: readonly string[]): string[] {
+  const text = lines.join('\n');
+  return BANNED_DEFAULT_WORDS.filter((word) =>
+    WORD_RE.test(word) ? new RegExp(`\\b${word}\\b`, 'i').test(text) : text.includes(word),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Reading a statement.
+// ---------------------------------------------------------------------------
+
+/**
+ * The whole statement as ONE line, comments and blank lines dropped, whitespace collapsed.
+ *
+ * Two things it has to survive. A `-- WARNING:` prologue must not hide the verb — so comment
+ * lines go. And a statement is NOT single-line: the reconcile emits formatted DDL, so a trigger,
+ * a policy, a grant or an `ALTER TABLE` can arrive broken across lines. Reading only the FIRST
+ * line left `ALTER TABLE public.foo\n  DROP COLUMN bar;` matching nothing — it fell through to
+ * the raw fallback and printed with a `+`, the wrong sign on a statement that removes a column.
+ * Sign is the whole vocabulary here, so getting it backwards is the one unacceptable outcome.
+ *
+ * The reading itself is sql-statement's {@link statementBody}, shared with the destructive gate.
+ * All this adds is the fallback: a statement with nothing but comments in it still shows the
+ * operator its own text rather than an empty line. The result is MATCHED against, never executed,
+ * so collapsing a function body's own formatting costs the reader nothing.
+ */
+function head(statement: string): string {
+  const body = statementBody(statement);
+  return body === '' ? statement.replace(/\s+/g, ' ').trim() : body;
+}
+
+/** The whole statement as one line, comments stripped and truncated — for the fallback description. */
+function oneLine(statement: string): string {
+  const body = head(statement).replace(/;$/, '');
+  return body.length > 120 ? `${body.slice(0, 119)}…` : body;
+}
+
+const unquote = (name: string): string => name.replace(/"/g, '').trim();
+
+/** `public.events` → `events`; `stats.runs` → `stats.runs`. The default schema is noise. */
+function rel(name: string): string {
+  const clean = unquote(name).replace(/;$/, '');
+  return clean.startsWith('public.') ? clean.slice('public.'.length) : clean;
+}
+
+/** A grant/revoke target: drop the object-kind keyword and any argument list. */
+function grantObject(raw: string): string {
+  const stripped = raw
+    .trim()
+    .replace(/;$/, '')
+    .replace(/^(ALL\s+(TABLES|SEQUENCES|FUNCTIONS|ROUTINES|PROCEDURES)\s+IN\s+SCHEMA|TABLE|FUNCTION|PROCEDURE|ROUTINE|SEQUENCE|SCHEMA|TYPE|DOMAIN|DATABASE)\s+/i, '')
+    .replace(/\s*\([\s\S]*\)\s*$/, '');
+  return rel(stripped);
+}
+
+/** `SELECT, INSERT` → `select, insert`. */
+const privileges = (raw: string): string => raw.trim().replace(/\s+/g, ' ').toLowerCase();
+
+// ---------------------------------------------------------------------------
+// One statement → one plain line.
+// ---------------------------------------------------------------------------
+
+export interface PlainChange {
+  symbol: '+' | '-';
+  text: string;
+}
+
+/** Options for {@link describeChange}. */
+export interface DescribeOptions {
+  /**
+   * This CREATE is the second half of a rebuild — the batch dropped the same object first.
+   * A bare `CREATE FUNCTION` after its own `DROP FUNCTION` is not an addition; the object was
+   * already there and its definition changed. Reads exactly as `CREATE OR REPLACE` does.
+   */
+  rebuilt?: boolean;
+}
+
+/** Statement shapes that only ever take something away. Used for the fallback's sign. */
+const REMOVAL_HEAD_RE = /^(DROP|REVOKE)\b/i;
+
+/**
+ * Describe ONE non-destructive statement in plain words.
+ *
+ * Deliberately not exhaustive over PostgreSQL: an unrecognised statement falls back to itself
+ * on one line, which is honest, rather than to an invented summary that could be wrong. The
+ * sign still comes out right for the shapes that matter (a DROP or REVOKE nobody matched is
+ * still a removal).
+ */
+export function describeChange(statement: string, opts: DescribeOptions = {}): PlainChange {
+  const s = head(statement);
+  const rebuilt = opts.rebuilt === true;
+  let m: RegExpExecArray | null;
+
+  // ALTER TABLE …
+  if ((m = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+([\s\S]+)$/i.exec(s))) {
+    const table = rel(m[1]);
+    const rest = m[2].trim();
+    let a: RegExpExecArray | null;
+
+    if ((a = /^ADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(rest))) {
+      return { symbol: '+', text: `add column ${table}.${unquote(a[1])}` };
+    }
+    if ((a = /^DROP\s+COLUMN\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(rest))) {
+      return { symbol: '-', text: `remove column ${table}.${unquote(a[1])}` };
+    }
+    if ((a = /^ADD\s+CONSTRAINT\s+("[^"]+"|[\w$]+)/i.exec(rest))) {
+      return { symbol: '+', text: `add constraint ${unquote(a[1])} on ${table}` };
+    }
+    if ((a = /^DROP\s+CONSTRAINT\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(rest))) {
+      return { symbol: '-', text: `remove constraint ${unquote(a[1])} on ${table}` };
+    }
+    if ((a = /^ALTER\s+COLUMN\s+("[^"]+"|[\w$]+)\s+([\s\S]+)$/i.exec(rest))) {
+      const column = `${table}.${unquote(a[1])}`;
+      const what = a[2].trim();
+      if (/^SET\s+NOT\s+NULL/i.test(what)) return { symbol: '+', text: `require a value in column ${column}` };
+      if (/^DROP\s+NOT\s+NULL/i.test(what)) return { symbol: '+', text: `allow an empty value in column ${column}` };
+      if (/^SET\s+DEFAULT/i.test(what)) return { symbol: '+', text: `set a default for column ${column}` };
+      if (/^DROP\s+DEFAULT/i.test(what)) return { symbol: '-', text: `remove the default from column ${column}` };
+      const type = /^SET\s+DATA\s+TYPE\s+([^\s;]+)/i.exec(what);
+      if (type) return { symbol: '+', text: `change column ${column} to ${type[1].replace(/;$/, '')}` };
+    }
+    if (/^(ENABLE|FORCE)\s+ROW\s+LEVEL\s+SECURITY/i.test(rest)) {
+      return { symbol: '+', text: `turn on row security for ${table}` };
+    }
+    if (/^(DISABLE|NO\s+FORCE)\s+ROW\s+LEVEL\s+SECURITY/i.test(rest)) {
+      return { symbol: '-', text: `turn off row security for ${table}` };
+    }
+  }
+
+  if ((m = /^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([^\s(]+)/i.exec(s))) {
+    return { symbol: '+', text: `add table ${rel(m[1])}` };
+  }
+  if ((m = /^DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove table ${rel(m[1])}` };
+  }
+  if ((m = /^CREATE\s+POLICY\s+("[^"]+"|[\w$]+)\s+ON\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add policy ${unquote(m[1])} on ${rel(m[2])}` };
+  }
+  if ((m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)\s+ON\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove policy ${unquote(m[1])} on ${rel(m[2])}` };
+  }
+  if ((m = /^GRANT\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+TO\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `grant ${unquote(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
+  }
+  if ((m = /^REVOKE\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+FROM\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `revoke ${unquote(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
+  }
+  // A "rebuild" — the same function coming back with a new body — is ONE update line. The
+  // drop half is never shown: the object does not go away, its definition changes.
+  if ((m = /^CREATE\s+(OR\s+REPLACE\s+)?(FUNCTION|PROCEDURE)\s+([^\s(]+)/i.exec(s))) {
+    const what = m[2].toLowerCase();
+    return m[1] || rebuilt
+      ? { symbol: '+', text: `update ${what} ${rel(m[3])}(...): definition updated` }
+      : { symbol: '+', text: `add ${what} ${rel(m[3])}(...)` };
+  }
+  if ((m = /^DROP\s+(FUNCTION|PROCEDURE)\s+(?:IF\s+EXISTS\s+)?([^\s(;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove ${m[1].toLowerCase()} ${rel(m[2])}(...)` };
+  }
+  if ((m = /^CREATE\s+(OR\s+REPLACE\s+)?(?:MATERIALIZED\s+)?VIEW\s+([^\s(;]+)/i.exec(s))) {
+    return m[1] || rebuilt
+      ? { symbol: '+', text: `update view ${rel(m[2])}: definition updated` }
+      : { symbol: '+', text: `add view ${rel(m[2])}` };
+  }
+  if ((m = /^REFRESH\s+MATERIALIZED\s+VIEW\s+(?:CONCURRENTLY\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `refresh view ${rel(m[1])}` };
+  }
+  if ((m = /^DROP\s+(?:MATERIALIZED\s+)?VIEW\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove view ${rel(m[1])}` };
+  }
+  if ((m = /^CREATE\s+(?:CONSTRAINT\s+)?TRIGGER\s+("[^"]+"|[\w$]+)[\s\S]*?\sON\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add trigger ${unquote(m[1])} on ${rel(m[2])}` };
+  }
+  if ((m = /^DROP\s+TRIGGER\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)\s+ON\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove trigger ${unquote(m[1])} on ${rel(m[2])}` };
+  }
+  if ((m = /^CREATE\s+(UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?("[^"]+"|[\w$]+)\s+ON\s+([^\s(;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add index ${unquote(m[2])} on ${rel(m[3])}` };
+  }
+  if ((m = /^DROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove index ${rel(m[1])}` };
+  }
+  if ((m = /^CREATE\s+TYPE\s+([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add type ${rel(m[1])}` };
+  }
+  if ((m = /^DROP\s+TYPE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove type ${rel(m[1])}` };
+  }
+  if ((m = /^CREATE\s+SCHEMA\s+(?:IF\s+NOT\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add schema ${unquote(m[1])}` };
+  }
+  if ((m = /^CREATE\s+EXTENSION\s+(?:IF\s+NOT\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add extension ${unquote(m[1])}` };
+  }
+  if ((m = /^CREATE\s+SEQUENCE\s+(?:IF\s+NOT\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '+', text: `add sequence ${rel(m[1])}` };
+  }
+  if ((m = /^DROP\s+SEQUENCE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { symbol: '-', text: `remove sequence ${rel(m[1])}` };
+  }
+  if ((m = /^COMMENT\s+ON\s+\w+(?:\s+\w+)?\s+([^\s;]+)\s+IS\b/i.exec(s))) {
+    return { symbol: '+', text: `update the comment on ${rel(m[1])}` };
+  }
+
+  return { symbol: REMOVAL_HEAD_RE.test(s) ? '-' : '+', text: oneLine(statement) };
+}
+
+/**
+ * Describe ONE destructive statement — the wording says what is LOST, because that is the
+ * only question the reader has. No sign: the ⚠ line stands alone.
+ */
+export function describeDestructive(statement: string): string {
+  const s = head(statement);
+  let m: RegExpExecArray | null;
+
+  if ((m = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+DROP\s+COLUMN\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(s))) {
+    return `drops column ${rel(m[1])}.${unquote(m[2])}`;
+  }
+  if ((m = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ALTER\s+COLUMN\s+("[^"]+"|[\w$]+)\s+DROP\s+IDENTITY/i.exec(s))) {
+    return `drops the auto-value on column ${rel(m[1])}.${unquote(m[2])} (its counter is not recoverable)`;
+  }
+  if ((m = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ALTER\s+COLUMN\s+("[^"]+"|[\w$]+)\s+SET\s+DATA\s+TYPE\s+([^\s;]+)/i.exec(s))) {
+    return `changes the type of column ${rel(m[1])}.${unquote(m[2])} to ${m[3].replace(/;$/, '')} (values that do not fit are lost)`;
+  }
+  if ((m = /^DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return `drops table ${rel(m[1])}`;
+  }
+  if ((m = /^DROP\s+TYPE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return `drops type ${rel(m[1])}`;
+  }
+  if ((m = /^REVOKE\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+FROM\s+([^\s;]+)/i.exec(s))) {
+    return `revokes ${privileges(m[1])} on ${grantObject(m[2])} from ${unquote(m[3])} — nothing declares it, so it cannot be put back`;
+  }
+  return oneLine(statement);
+}
+
+// ---------------------------------------------------------------------------
+// Rebuilds: a drop and a create of the same object are ONE change.
+// ---------------------------------------------------------------------------
+
+/**
+ * The object a statement drops or creates, as `kind:name`, or null for a statement that does
+ * neither. A matview and a view share the `view` kind because the reader does too.
+ *
+ * A function's key deliberately omits its argument list: the DROP carries catalog argument
+ * TYPES and the CREATE carries declared argument NAMES, and the two never match textually. The
+ * cost is that dropping one overload while creating another would read as one update line
+ * instead of two — a display difference on a rare shape, in exchange for every ordinary
+ * function rebuild reading correctly.
+ */
+function objectKey(s: string): { verb: 'drop' | 'create'; key: string } | null {
+  let m: RegExpExecArray | null;
+  if ((m = /^DROP\s+TRIGGER\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)\s+ON\s+([^\s;]+)/i.exec(s))) {
+    return { verb: 'drop', key: `trigger:${rel(m[2])}.${unquote(m[1])}` };
+  }
+  if ((m = /^CREATE\s+(?:CONSTRAINT\s+)?TRIGGER\s+("[^"]+"|[\w$]+)[\s\S]*?\sON\s+([^\s;]+)/i.exec(s))) {
+    return { verb: 'create', key: `trigger:${rel(m[2])}.${unquote(m[1])}` };
+  }
+  if ((m = /^DROP\s+(?:MATERIALIZED\s+)?VIEW\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
+    return { verb: 'drop', key: `view:${rel(m[1])}` };
+  }
+  if ((m = /^CREATE\s+(?:OR\s+REPLACE\s+)?(?:MATERIALIZED\s+)?VIEW\s+([^\s(;]+)/i.exec(s))) {
+    return { verb: 'create', key: `view:${rel(m[1])}` };
+  }
+  if ((m = /^DROP\s+(FUNCTION|PROCEDURE)\s+(?:IF\s+EXISTS\s+)?([^\s(;]+)/i.exec(s))) {
+    return { verb: 'drop', key: `${m[1].toLowerCase()}:${rel(m[2])}` };
+  }
+  if ((m = /^CREATE\s+(?:OR\s+REPLACE\s+)?(FUNCTION|PROCEDURE)\s+([^\s(;]+)/i.exec(s))) {
+    return { verb: 'create', key: `${m[1].toLowerCase()}:${rel(m[2])}` };
+  }
+  return null;
+}
+
+/**
+ * Drop the DROP half of every rebuild in a batch.
+ *
+ * The function/view reconcile rebuilds an object by dropping it and creating it again. That is
+ * how the DDL has to be written; it is not what happened to the database. Shown raw, one
+ * changed view reads as a removal AND an addition — two lines, one of them frightening, for a
+ * definition edit. So the drop is removed and its create is marked `rebuilt`, which renders as
+ * the update line it always was.
+ *
+ * Statements this does not recognise pass through untouched, in order.
+ */
+export function collapseRebuilds(statements: readonly string[]): {
+  statements: string[];
+  rebuilt: ReadonlySet<string>;
+} {
+  const created = new Map<string, string>();
+  for (const s of statements) {
+    const k = objectKey(head(s));
+    if (k?.verb === 'create') created.set(k.key, s);
+  }
+  const kept: string[] = [];
+  const rebuilt = new Set<string>();
+  for (const s of statements) {
+    const k = objectKey(head(s));
+    if (k?.verb === 'drop' && created.has(k.key)) {
+      rebuilt.add(created.get(k.key)!);
+      continue;
+    }
+    kept.push(s);
+  }
+  return { statements: kept, rebuilt };
+}
+
+// ---------------------------------------------------------------------------
+// The reports.
+// ---------------------------------------------------------------------------
+
+/** How many change lines a report prints before it collapses to a count. */
+const MAX_LISTED_CHANGES = 50;
+/** Above this, db:apply's receipt is a count rather than a list — "not per object if there are many". */
+const MAX_RECEIPT_CHANGES = 20;
+
+const DESTRUCTIVE_MARK = '⚠ DESTRUCTIVE';
+
+const plural = (n: number, one: string, many: string): string => (n === 1 ? one : many);
+
+/** One change line, indented, already carrying its mark. */
+function changeLine(statement: string, destructive: ReadonlySet<string>, rebuilt?: ReadonlySet<string>): string {
+  if (destructive.has(statement)) return `  ${DESTRUCTIVE_MARK} — ${describeDestructive(statement)}`;
+  const { symbol, text } = describeChange(statement, { rebuilt: rebuilt?.has(statement) === true });
+  return `  ${symbol} ${text}`;
+}
+
+function changeLines(
+  executable: readonly string[],
+  destructive: ReadonlySet<string>,
+  limit: number,
+  rebuilt?: ReadonlySet<string>,
+): string[] {
+  const shown = executable.slice(0, limit).map((s) => changeLine(s, destructive, rebuilt));
+  const hidden = executable.length - shown.length;
+  if (hidden > 0) shown.push(`  … and ${hidden} more (--verbose for the full list)`);
+  return shown;
+}
+
+export interface PlanReportInput {
+  /** The real DDL the plan will run — notices and held drops are not changes. */
+  executable: readonly string[];
+  /** The destructive subset, as the apply gate classifies it. Must be members of `executable`. */
+  destructive: readonly string[];
+  /** What the plan is aimed at, in the reader's words: a stage name, or `local`. */
+  target: string;
+  /** The stage flag to repeat in the Run line, when there is one. */
+  stage?: string | null;
+  /** The plan file to name in the Run line; null when the plan went to stdout. */
+  planPath: string | null;
+}
+
+/** db:plan's default output — the whole thing. */
+export function renderPlanReport(input: PlanReportInput): string[] {
+  const { executable, target, stage, planPath } = input;
+  if (executable.length === 0) return ['Up to date. Nothing to plan.'];
+
+  const destructive = new Set(input.destructive);
+  const lines: string[] = [
+    `Plan: ${executable.length} ${plural(executable.length, 'change', 'changes')} (${target})`,
+    '',
+    ...changeLines(executable, destructive, MAX_LISTED_CHANGES),
+    '',
+  ];
+
+  lines.push(
+    destructive.size > 0
+      ? `Verify the destructive ${plural(destructive.size, 'change', 'changes')}, then run db:backup before applying.`
+      : 'Non-destructive. Safe to apply.',
+  );
+
+  // No file, no command to give — `--out -` piped the plan somewhere only the caller knows.
+  if (planPath !== null) {
+    const confirm = destructive.size > 0 ? ' --confirm' : '';
+    const stageFlag = stage ? ` --stage ${stage}` : '';
+    lines.push('', `Run: db:apply --plan ${planPath}${confirm}${stageFlag}`);
+  }
+  return lines;
+}
+
+export interface ApplyReceiptInput {
+  executable: readonly string[];
+  destructive: readonly string[];
+  /** The target was already where the plan ends — an idempotent re-apply. */
+  alreadyApplied?: boolean;
+  /**
+   * The function/view/trigger DDL db:apply ran after the plan, on the same target.
+   *
+   * It joins the SAME list and the SAME count: the operator ran one command, so they read one
+   * receipt. Rebuild pairs collapse to a single update line on the way in.
+   */
+  catchUp?: readonly string[];
+}
+
+/** db:apply's default output: the plan's change list back as a receipt, then the count. */
+export function renderApplyReceipt(input: ApplyReceiptInput): string[] {
+  const { statements: caughtUp, rebuilt } = collapseRebuilds(input.catchUp ?? []);
+  // An idempotent re-apply ran no plan statements; only the catch-up can have done anything.
+  const executable = input.alreadyApplied ? caughtUp : [...input.executable, ...caughtUp];
+  if (input.alreadyApplied && executable.length === 0) return ['Up to date. Nothing to apply.'];
+  const n = executable.length;
+  const tally = `Applied ${n} ${plural(n, 'change', 'changes')}.`;
+  if (n === 0 || n > MAX_RECEIPT_CHANGES) return [tally];
+  return [...changeLines(executable, new Set(input.destructive), MAX_RECEIPT_CHANGES, rebuilt), '', tally];
+}
+
+export interface CatchUpFailureInput {
+  /** How many table/column changes are already committed. */
+  applied: number;
+  /** The exact command that retries ONLY the functions and views. */
+  rerun: string;
+  /** Why it did not finish, as the failure itself said it. Its first line rides line 1. */
+  reason?: string;
+}
+
+/**
+ * The whole default output when the plan landed and the functions/views then did not.
+ *
+ * LINE 1 IS ALWAYS ONE LINE, and it names TWO subjects explicitly — the table and column
+ * changes, then the functions and views — because the reader's one question is "is my
+ * database half-changed and what do I type now", and a single sentence covering both halves
+ * at once reads as self-contradictory ("nothing was sent" inside "applied and safe").
+ * Two subjects, two verdicts, then the rerun. Nothing else may precede it.
+ *
+ * The cause does not get folded onto that line. A real refusal is structured and
+ * copy-pasteable — four lines of prose and then `CREATE ROLE app_owner NOLOGIN;` — and
+ * flattening it ran past 900 characters and pushed `Rerun:` off the end of the screen. So
+ * line 1 takes the HEADLINE only (the cause's first line), and a multi-line cause is
+ * reprinted verbatim below, indented, ALWAYS — not behind --verbose, because an operator who
+ * cannot see the cause reruns the command that just failed and fails the same way. It appears
+ * exactly once, in exactly one place, at every verbosity.
+ */
+export function renderCatchUpFailure(input: CatchUpFailureInput): string[] {
+  const n = input.applied;
+  const state = n === 0
+    ? 'Table and column changes: none applied.'
+    : `Table and column changes: applied ${n} ${plural(n, 'change', 'changes')}, committed.`;
+  const cause = causeLines(input.reason);
+  const head = cause.length === 0
+    ? 'Functions and views: not finished.'
+    : `Functions and views: not finished — ${sentence(headline(cause[0]))}`;
+  const line = `${state} ${head} Rerun: ${input.rerun}`;
+  if (cause.length <= 1) return [line];
+  return [line, '', ...cause.map((text) => (text.trim() === '' ? '' : `  ${text}`))];
+}
+
+/** The cause as it was written — its own line breaks kept, its blank top and tail dropped. */
+function causeLines(reason: string | undefined): string[] {
+  const lines = (reason ?? '').split('\n').map((l) => l.replace(/\s+$/, ''));
+  while (lines.length > 0 && lines[0].trim() === '') lines.shift();
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+  return lines;
+}
+
+/** The cause's first line as a headline: whitespace tidied, its own full stop dropped. */
+function headline(first: string): string {
+  return first.replace(/\s+/g, ' ').trim().replace(/\.+$/, '');
+}
+
+/**
+ * End the headline with a stop — unless it already ends in one of its own.
+ *
+ * A refusal's first line can end in a SQL statement, and `;` is that statement's terminator.
+ * Appending ours produced `SET TRUE;.`, which reads as corruption. So `.` closes a headline
+ * that has no terminator, and a headline that has one keeps it.
+ */
+function sentence(text: string): string {
+  return /[;:!?]$/.test(text) ? text : `${text}.`;
+}
+
+/** db:check's default output: one line, always. */
+export function renderCheckVerdict(pending: number): string[] {
+  if (pending === 0) return ['Up to date.'];
+  return [`${pending} ${plural(pending, 'change', 'changes')} pending. Run db:plan to review.`];
+}

package/src/cli/schema-diff.ts

@@ -143,6 +143,12 @@ export type TableMoveMap = Record<string, string>;
 
 // ---------------------------------------------------------------------------
 // Normalization — so semantically-equal expressions don't read as drift.
+//
+// These normalizers are LEAF PRIMITIVES the frozen retained canons reuse (schema-fingerprint-v10,
+// -v11). Changing what any of them return moves EVERY recorded fingerprint, current and retained,
+// and would corrupt descent. It is not free to tweak: the golden-hash tests
+// (schema-fingerprint-v11-freeze.test.ts) will fail first, by design — treat that as the signal
+// that the change needs its own FINGERPRINT_VERSION bump, not a test to update.
 // ---------------------------------------------------------------------------
 
 /**