@ultimat3/db 24.0.0 → 25.0.0

package/src/errors.ts

@@ -41,6 +41,8 @@ export const DB_OWNED_ERROR_CODES = [
   'X_DB_TRANSACTION_ABORTED',
   'X_DB_COMMIT_UNKNOWN',
   'X_DB_SIBLING_SCOPE_TIMEOUT',
+  'X_APPEND_ONLY_TRIGGER_MISSING',
+  'X_MIGRATION_APPEND_ONLY_BACKFILL',
 ] as const;
 
 /**
@@ -89,6 +91,9 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_TRANSACTION_ABORTED: 'the server rolled the transaction back',
   X_DB_COMMIT_UNKNOWN: 'the connection was lost while COMMIT was in flight',
   X_DB_SIBLING_SCOPE_TIMEOUT: 'a nested transaction scope waited too long for its sibling',
+  X_APPEND_ONLY_TRIGGER_MISSING: 'an append-only table has lost its refusing trigger',
+  X_MIGRATION_APPEND_ONLY_BACKFILL:
+    'a NOT NULL column added to an append-only table needs a default',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -285,7 +290,7 @@ export const drainTimeout = (ms: number, role: string): DbError =>
   new DbError({
     code: 'X_DB_DRAIN_TIMEOUT',
     cause: `the ${role} pool still held connections after ${String(ms)}ms, so close() stopped waiting`,
-    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in createPostgresClient({ profile }) for the ${role} role`,
+    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in postgresClient({ profile }) for the ${role} role`,
     meta: { drainTimeoutMs: ms, role },
   });
 

package/src/fake.ts

@@ -49,7 +49,7 @@ const DEFAULT_STUBS: readonly Stub[] = [
   { match: /pg_try_advisory_lock/, response: { rows: [{ locked: true }] } },
 ];
 
-export function createRecordingClient(): RecordingClient {
+export function recordingClient(): RecordingClient {
   const statements: RecordedStatement[] = [];
   const stubs: Stub[] = [...DEFAULT_STUBS];
 

package/src/generate-append-only.ts

@@ -0,0 +1,146 @@
+// Single responsibility: the trigger an `entity({ appendOnly: true })` table carries, emitted once.
+// The repository refuses update and delete above the driver; this is the same guarantee held by the
+// DATABASE, so raw SQL, a second app on the same schema and a hand-written driver are refused too.
+// Recorded on the snapshot (`appendOnly: true`), which is what stops it being re-emitted.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
+import { DbError } from './errors';
+import type { Plan } from './foreign-key-plan';
+import { findTable, type SchemaDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * The trigger's name — the SAME on every table, because a trigger name is unique per table, never
+ * per schema. A per-table name (`<table>_append_only`) would pass 63 bytes on a long table name,
+ * Postgres would truncate it in silence, and drift would compare the untruncated name forever.
+ */
+export const APPEND_ONLY_TRIGGER = 'ultimate_append_only';
+
+/**
+ * One function for every append-only table: `tg_table_name` says which table refused. Not `x_`
+ * prefixed — that namespace is framework bookkeeping created at boot (`FRAMEWORK_TABLE_PREFIX`), and
+ * this function is created by the app's own migrations, so the schema dump files it with them.
+ */
+export const APPEND_ONLY_FUNCTION = 'ultimate_refuse_append_only';
+
+/**
+ * `create or replace`, so every migration that adds a trigger may define it again: no migration has
+ * to know whether an earlier one already did, and a database where it was dropped by hand gets it
+ * back on the next one. One line, because the drift repair (`drift-append-only.ts`) is the same
+ * text as one `psql -c` word.
+ *
+ * The message LEADS with the code an app searches for, and the SQLSTATE is `23001`
+ * (`restrict_violation`): class 23 is "an integrity constraint refused this", which is what an
+ * append-only table is — so a caller that already treats class 23 as terminal, never retried,
+ * treats this the same. These bytes are in migrations on disk; changing them changes nothing that
+ * already shipped.
+ */
+export const APPEND_ONLY_FUNCTION_SQL =
+  `create or replace function ${identifier(APPEND_ONLY_FUNCTION).text}() returns trigger ` +
+  'language plpgsql as $append_only$ begin raise exception ' +
+  "'X_ENTITY_APPEND_ONLY: % on %.% is refused, the table is append-only', " +
+  "tg_op, tg_table_schema, tg_table_name using errcode = '23001', hint = 'insert a new row " +
+  "instead; to allow rewrites, remove appendOnly from the entity and run x db gen'; end; " +
+  '$append_only$;';
+
+/**
+ * `before update or delete … for each row`: a row-level BEFORE trigger raises before the row moves,
+ * and it covers `insert … on conflict do update` too — the conflict arm IS an update. `truncate` is
+ * deliberately not refused: it is no row-level write, `destructive.ts` already gates it in a
+ * migration, and the testing package's reusable database empties every table with it.
+ */
+export const appendOnlyTriggerSql = (table: string): string =>
+  `create trigger ${identifier(APPEND_ONLY_TRIGGER).text} before update or delete on ` +
+  `${identifier(table).text} for each row execute function ` +
+  `${identifier(APPEND_ONLY_FUNCTION).text}();`;
+
+/** `if exists`: a revert must not fail on a database where the trigger was already dropped by hand. */
+export const dropAppendOnlyTriggerSql = (table: string): string =>
+  `drop trigger if exists ${identifier(APPEND_ONLY_TRIGGER).text} on ${identifier(table).text};`;
+
+/**
+ * Installing it on a table that may already hold one: drop-if-exists, then create. A DISABLED
+ * trigger of this name is drift (`drift-append-only.ts`) yet still exists, so a bare `create
+ * trigger` would fail on it (`42710`) and leave the table unprotected. Idempotent for both a
+ * missing and a disabled trigger — the drift repair and an existing table's migration both use it.
+ */
+export const installAppendOnlyTriggerSql = (table: string): readonly string[] => [
+  dropAppendOnlyTriggerSql(table),
+  appendOnlyTriggerSql(table),
+];
+
+/** Whether the recorded schema says this table carries the trigger. Absent is "not recorded". */
+const recorded = (current: SchemaDescription, table: string): boolean =>
+  findTable(current, table)?.appendOnly === true;
+
+/**
+ * Both directions. Declared and not recorded: define the function (once per migration) and add the
+ * trigger; its `down` drops the trigger, except on a table this migration creates, whose `down` is
+ * already `drop table`. Recorded and no longer declared: drop it, and `down` puts it back.
+ *
+ * A table dropped outright needs nothing — the trigger goes with it, and the snapshot stops naming
+ * the table. The function is never dropped: other tables may still call it, and a function left with
+ * no trigger refuses nothing.
+ */
+export function appendOnlyPlan(
+  plan: Plan,
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+  created: ReadonlySet<string>,
+): void {
+  const changed = entities.filter(
+    (entity) => (entity.appendOnly === true) !== recorded(current, entity.table),
+  );
+  const added = changed.filter((entity) => entity.appendOnly === true).map((e) => e.table);
+  const removed = changed.filter((entity) => entity.appendOnly !== true).map((e) => e.table);
+  if (added.length > 0) plan.up.push(APPEND_ONLY_FUNCTION_SQL);
+  for (const table of added) {
+    // A table this migration creates holds no trigger yet, and its `down` is `drop table`.
+    if (created.has(table)) {
+      plan.up.push(appendOnlyTriggerSql(table));
+      continue;
+    }
+    plan.up.push(...installAppendOnlyTriggerSql(table));
+    plan.down.push(dropAppendOnlyTriggerSql(table));
+  }
+  for (const table of removed) {
+    plan.up.push(dropAppendOnlyTriggerSql(table));
+    // Reversed whole: pushed create-then-drop so `down` runs drop-if-exists, then create.
+    plan.down.push(...[...installAppendOnlyTriggerSql(table)].reverse());
+  }
+  // `down` is reversed whole, so the function pushed LAST here runs FIRST there — before the
+  // triggers that call it are re-created.
+  if (removed.length > 0) plan.down.push(APPEND_ONLY_FUNCTION_SQL);
+}
+
+/** Which arm met the column: a new one, or an existing one turned NOT NULL. */
+export type AppendOnlyBackfillArm = 'added' | 'made-not-null';
+
+/**
+ * A column an append-only table must hold NOT NULL with no default to fill it. Both arms of the
+ * diff would emit `-- backfill …, then: set not null` — `diffTable` for a new column,
+ * `alterColumnInPlace` for an existing one — and on this table that backfill is an UPDATE the
+ * trigger refuses: an instruction nobody can carry out, leaving the column nullable forever.
+ * Refused at generation instead; a default is the one way every row gets a value with no UPDATE.
+ */
+export const appendOnlyBackfillRefused = (
+  entity: EntityDescriptionLike,
+  column: ColumnDescriptionLike,
+  arm: AppendOnlyBackfillArm,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_APPEND_ONLY_BACKFILL',
+    cause:
+      `${identifier(entity.table).text} is append-only and ` +
+      `${arm === 'added' ? 'gains NOT NULL column' : 'turns NOT NULL its column'} ` +
+      `${identifier(column.column).text} with no default: existing rows could only be given a ` +
+      'value by an UPDATE, which the append-only trigger refuses, so x db gen cannot write a ' +
+      'migration that ends with the column NOT NULL',
+    // A default fills a column as it is ADDED; it fills no NULL an existing column already holds.
+    fix:
+      arm === 'added'
+        ? `entity(${renderFixLiteral(entity.name, "'<name>'")}, { columns: { ${renderFixLiteral(column.property, "'<col>'")}: <builder>.default(<value>) } })   # then re-run x db gen`
+        : `entity(${renderFixLiteral(entity.name, "'<name>'")}, { columns: { ${renderFixLiteral(column.property, "'<col>'")}: <builder>.nullable() } })   # keep it nullable, or add a NEW column with .default(<value>); then re-run x db gen`,
+    meta: { table: entity.table, column: column.column, arm },
+  });

package/src/generate.ts

@@ -7,10 +7,11 @@ import { systemClock } from '@ultimat3/core';
 import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
 import { alterColumnInPlace } from './column-alter';
 import { defaultExpression } from './column-default';
-import { isDestructive } from './destructive';
+import { isDestructiveMigration } from './destructive';
 import { dropOrder } from './drop-order';
 import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
+import { appendOnlyBackfillRefused, appendOnlyPlan } from './generate-append-only';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
 import { createIndex, impliedByColumnClause } from './index-ddl';
@@ -23,7 +24,7 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
-import { addChangedKey, dropChangedKey } from './primary-key';
+import { addChangedKey, dropChangedKey, migrationNameArg } from './primary-key';
 import type { ReplicaIdentityInput } from './replica-identity';
 import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
 import type { MovedAside } from './retype-dependents';
@@ -112,6 +113,8 @@ export function snapshotOf(
         // The same rule once more: `true` or absent, never `false`. This is what makes the ALTER
         // beside it a one-time statement rather than a line every `x db gen` writes again.
         ...(replicaIdentityFull.has(entity.table) ? { replicaIdentityFull: true as const } : {}),
+        // `true` or absent once more — the record that makes the trigger a one-time statement.
+        ...(entity.appendOnly === true ? { appendOnly: true as const } : {}),
       };
     });
   return { tables };
@@ -199,7 +202,7 @@ function diffTable(
       } else {
         // After any retype, so a new default is set against the column's new type. A rebuilt
         // column was re-added carrying its whole clause, so it has nothing left to move.
-        alterColumnInPlace(entity.table, column, recorded, plan);
+        alterColumnInPlace(entity, column, recorded, plan);
       }
       continue;
     }
@@ -212,6 +215,9 @@ function diffTable(
     // one statement — measured. Emitting it nullable would leave a `-- backfill` comment naming a
     // step nobody can perform, since a generated column cannot be written to.
     const nullable = column.notNull && !isGenerated(column) && defaultExpression(column) === null;
+    // That follow-up is an UPDATE, and an append-only table's trigger refuses every one.
+    if (nullable && entity.appendOnly === true)
+      throw appendOnlyBackfillRefused(entity, column, 'added');
     const clause = nullable ? columnClause({ ...column, notNull: false }) : columnClause(column);
     plan.up.push(`alter table ${identifier(entity.table).text} add column ${clause};`);
     if (nullable) {
@@ -335,7 +341,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       if (options.allowDestructive !== true) {
         throw migrationIrreversible(
           `dropping "${entity.table}"."${column.name}" discards its rows and cannot be undone`,
-          `x db gen "${options.name}" --allow-destructive   # or keep the column and deprecate it`,
+          `x db gen ${migrationNameArg(options.name)} --allow-destructive   # or keep the column and deprecate it`,
         );
       }
       plan.up.push(
@@ -355,7 +361,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     if (options.allowDestructive !== true) {
       throw migrationIrreversible(
         `dropping table "${table.name}" discards every row and cannot be undone`,
-        `x db gen "${options.name}" --allow-destructive   # or delete the entity in two releases`,
+        `x db gen ${migrationNameArg(options.name)} --allow-destructive   # or delete the entity in two releases`,
       );
     }
   }
@@ -373,6 +379,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   plan.up.push(...constraints.up);
   plan.down.push(...constraints.down);
 
+  // After every table exists, so a `create table` in this same migration is already above it.
+  appendOnlyPlan(plan, options.entities, current, created);
+
   // Dead last in `up`, and it is the only placement that is right for every arm: the table has to
   // exist, and a `create table` in this same migration is the reason it might not. It is ordered
   // against nothing else — replica identity constrains no column, no index and no constraint — so
@@ -388,7 +397,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
   // At the TOP of `up`, so what is MISSING is the first thing read — and a line comment, so it is
   // noise to every reader that matters: `statementsOf` drops a chunk of comments alone,
-  // `stripSqlNoise` blanks it before `isDestructive` looks for a verb, and the server ignores it.
+  // `stripSqlNoise` blanks it before `isDestructiveMigration` looks for a verb, and the server ignores it.
   //
   // Never onto an EMPTY diff. `@ultimat3/cli`'s `generateAppMigration` reads `up.trim().length` as
   // "nothing changed" and re-records the hash sidecar instead of writing a file; a comment there
@@ -411,7 +420,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     // ends have been retyped back, which is every other statement in the script.
     down: [...preAlters.down, ...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities, replicaIdentityFullAfter(replicaIdentity)),
-    destructive: isDestructive(up),
+    destructive: isDestructiveMigration(up),
     unrendered,
   };
 }

package/src/index.ts

@@ -27,7 +27,7 @@ export type {
   PostgresClientOptions,
   ReservableClient,
 } from './client';
-export { baseClient, createPostgresClient, db, isReservable, setDbClient } from './client';
+export { baseClient, db, isReservable, postgresClient, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
 export type { DbHealthReport } from './db-health';
@@ -44,12 +44,12 @@ export {
   DESTRUCTIVE_MARKER,
   destructiveStatements,
   hasDestructiveMarker,
-  isDestructive,
+  isDestructiveMigration,
 } from './destructive';
 export type { DriftDifference, DriftKind, DriftOptions, DriftReport } from './drift';
 export {
   appTables,
-  assertNoDrift,
+  assertNoSchemaDrift,
   checkDrift,
   declaredSchema,
   diffSchema,
@@ -83,7 +83,7 @@ export {
 } from './errors';
 export { expectedQueryLoop, expectedQueryLoopReason } from './expected-loop';
 export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
-export { createRecordingClient } from './fake';
+export { recordingClient } from './fake';
 export type { GeneratedMigration, GenerateOptions } from './generate';
 export { generateMigration, migrationStamp, slugify, snapshotOf } from './generate';
 export type { IndexMethod } from './index-method';
@@ -103,7 +103,7 @@ export type {
   SchemaDescription,
   TableDescription,
 } from './introspect';
-export { buildSchema, findTable, introspect } from './introspect';
+export { buildSchema, findTable, introspectSchema } from './introspect';
 export {
   constraintNameFor,
   declaredIndexes,
@@ -157,12 +157,12 @@ export type {
   PgliteResult,
 } from './pglite';
 export {
-  createPgliteClient,
   loadPgliteDriver,
   PGLITE_FIX,
   PGLITE_MEMORY,
   PGLITE_MISSING,
   PGLITE_PACKAGE,
+  pgliteClient,
   pgliteDataDir,
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';

package/src/introspect-catalog.ts

@@ -1,5 +1,5 @@
 // Single responsibility: read the WHOLE schema out of `pg_catalog` — tables and everything that is
-// not a table — into one `CatalogDescription`, sorted in JS. `introspect()` beside it stays the
+// not a table — into one `CatalogDescription`, sorted in JS. `introspectSchema()` beside it stays the
 // entity-vocabulary reading drift compares to a snapshot; this is the catalog's own spelling, the
 // input of the schema dump, and comparable only to another reading of itself.
 

package/src/introspect.ts

@@ -104,7 +104,7 @@ export interface TableDescription {
    * handed a catalog value by accident.
    *
    * `snapshotOf` never writes it and `parseSnapshot` never reads it, so a sidecar carries `checks`
-   * alone. `introspect()` always answers with it, `[]` included: absent therefore means "nobody
+   * alone. `introspectSchema()` always answers with it, `[]` included: absent therefore means "nobody
    * asked the catalog", which is what keeps `compareChecks` silent on a description that never
    * read one instead of reporting every declared constraint as missing.
    */
@@ -119,12 +119,25 @@ export interface TableDescription {
    * table an app has would rewrite every sidecar in the tree on the next `x db gen` for a fact that
    * was already true — the argument `IndexDescription.using` makes about `btree`.
    *
-   * `introspect()` never answers it. The catalog's half is `pg_class.relreplident`, which
+   * `introspectSchema()` never answers it. The catalog's half is `pg_class.relreplident`, which
    * `@ultimat3/realtime`'s preflight already reads at the only moment it matters; a second reader
    * here would let a `diffSchema` compare a declaration against a catalog value, which is the
    * mistake `checks` and `checkNames` exist as two fields to prevent.
    */
   readonly replicaIdentityFull?: true | undefined;
+  /**
+   * That a migration gave this table the append-only trigger (`generate-append-only.ts`). The
+   * SNAPSHOT's half: `true` or absent, never `false`, for the reason `replicaIdentityFull` gives.
+   * `introspectSchema()` never writes it — the catalog's half is `triggerNames`.
+   */
+  readonly appendOnly?: true | undefined;
+  /**
+   * The CATALOG's half of `appendOnly`: the names of the ENABLED, non-internal triggers on the
+   * table (`tgenabled` `O` or `A` — a disabled or replica-only trigger refuses nothing in an
+   * ordinary session, so it is not held). A separate field for the reason `checkNames` is one.
+   * Written by `introspectSchema()` always, `[]` included; absent means nobody asked the catalog.
+   */
+  readonly triggerNames?: readonly string[] | undefined;
 }
 
 export interface SchemaDescription {
@@ -179,9 +192,17 @@ interface CheckRow {
   readonly constraint_name: string;
 }
 
+/** An enabled trigger's NAME — the half of `appendOnly` the catalog can answer. */
+interface TriggerNameRow {
+  readonly table_name: string;
+  readonly trigger_name: string;
+}
+
 const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
 
-export async function introspect(options: IntrospectOptions = {}): Promise<SchemaDescription> {
+export async function introspectSchema(
+  options: IntrospectOptions = {},
+): Promise<SchemaDescription> {
   const client = options.client ?? db();
   const schema = options.schema ?? 'public';
   // Asked first, and unconditionally: everything below reads `information_schema`, which admits a
@@ -297,7 +318,19 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     order by src.relname, c.conname
   `);
 
-  return buildSchema(schema, excluded, columns, indexes, foreignKeys, checks);
+  // Names only, as `checks` above: an append-only table is judged by whether its trigger is THERE
+  // and firing, never by `pg_get_triggerdef`'s text. `tgisinternal` is a foreign key's own.
+  const triggers = await client.query<TriggerNameRow>(sql`
+    select src.relname as table_name, t.tgname as trigger_name
+    from pg_trigger t
+    join pg_class src on src.oid = t.tgrelid
+    join pg_namespace n on n.oid = src.relnamespace
+    where not t.tgisinternal and t.tgenabled in ('O', 'A')
+      and n.nspname = ${schema} and src.relkind = 'r'
+    order by src.relname, t.tgname
+  `);
+
+  return buildSchema(schema, excluded, columns, indexes, foreignKeys, checks, triggers);
 }
 
 /** Pure, so the row -> description mapping is testable without a database. */
@@ -308,6 +341,8 @@ export function buildSchema(
   indexes: readonly IndexRow[],
   foreignKeys: readonly ForeignKeyRow[],
   checks: readonly CheckRow[] = [],
+  /** Absent leaves `triggerNames` off every table: nobody asked the catalog. */
+  triggers?: readonly TriggerNameRow[],
 ): SchemaDescription {
   const names = [...new Set(columns.map((row) => row.table_name))]
     .filter((name) => !excluded.includes(name))
@@ -359,6 +394,14 @@ export function buildSchema(
         .filter((row) => row.table_name === name)
         .map((row) => row.constraint_name)
         .sort(),
+      ...(triggers === undefined
+        ? {}
+        : {
+            triggerNames: triggers
+              .filter((row) => row.table_name === name)
+              .map((row) => row.trigger_name)
+              .sort(),
+          }),
     };
   });
 

package/src/migrate-rollback.ts

@@ -0,0 +1,44 @@
+// Single responsibility: recognise a ledger an OLDER build is being rolled back onto — rows the
+// newer build applied, every one of them newer than anything this build ships — so the migrate
+// role lets a rollback through instead of failing the deploy that is trying to undo a bad one.
+
+import type { LedgerRow, Migration } from './migration-ledger';
+import { pendingMigrations } from './migration-ledger';
+
+/** A rollback: the rows this build does not know (all newer), and the ledger it does. */
+export interface LedgerAhead {
+  /** The rows a newer build applied, oldest first. Never empty. */
+  readonly ahead: readonly LedgerRow[];
+  /** Every other row — the part this build's own audit still runs over. */
+  readonly known: readonly LedgerRow[];
+}
+
+/**
+ * The ledger split, when it is exactly a rollback, else `undefined` and the caller's audit refuses
+ * the unknown rows as it always has. Three conditions, all required:
+ *
+ * - every row this build does not ship sorts AFTER the newest migration it does ship — the ids are
+ *   `<stamp>_<name>`, the order `pendingMigrations` applies them in. One unknown row between two
+ *   shipped ones is a deleted or renamed migration, not a newer build's work;
+ * - this build has nothing left to apply. A pending migration beside newer rows means the database
+ *   never held this build's schema: two branches, not a rollback;
+ * - the build ships at least one migration. An image that lost its migrations directory is not
+ *   "older than every row", and reading it as one would wave through the image that is broken.
+ *
+ * Nothing is applied either way: the schema the newer build left is additive over this one when
+ * the release followed expand/contract (docs/ops/06-runbooks.md), and when it did not, no
+ * migration this build ships could put it back.
+ */
+export function ledgerAheadOfBuild(
+  ledger: readonly LedgerRow[],
+  migrations: readonly Migration[],
+): LedgerAhead | undefined {
+  if (migrations.length === 0) return undefined;
+  const shipped = new Set(migrations.map((migration) => migration.id));
+  const newest = [...shipped].sort().at(-1) ?? '';
+  const unknown = ledger.filter((row) => !shipped.has(row.id));
+  if (unknown.length === 0 || unknown.some((row) => row.id <= newest)) return undefined;
+  const known = ledger.filter((row) => shipped.has(row.id));
+  if (pendingMigrations(known, migrations).length > 0) return undefined;
+  return { ahead: [...unknown].sort((a, b) => (a.id < b.id ? -1 : 1)), known };
+}