@ultimat3/db 23.0.0 → 25.0.0

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,6 +24,7 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
+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';
@@ -111,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 };
@@ -198,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;
     }
@@ -211,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) {
@@ -324,6 +331,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       created.add(entity.table);
       continue;
     }
+    // The key first and last, around every column statement of the table (`primary-key.ts`): the
+    // snapshot below records `entity.primaryKey`, and until this arm existed nothing produced it.
+    dropChangedKey(entity, live, current, plan, options.name);
     diffTable(entity, live, plan, retypedIn(retyped, entity.table));
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
@@ -331,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(
@@ -343,6 +353,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
           ' -- data is not restored',
       );
     }
+    addChangedKey(entity, live, plan, options.name);
   }
 
   const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));
@@ -350,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`,
       );
     }
   }
@@ -368,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
@@ -383,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
@@ -406,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,
@@ -72,7 +72,6 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbNotImplemented,
   dbUnavailable,
   driverError,
   identifierUnsafe,
@@ -84,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';
@@ -104,7 +103,7 @@ export type {
   SchemaDescription,
   TableDescription,
 } from './introspect';
-export { buildSchema, findTable, introspect } from './introspect';
+export { buildSchema, findTable, introspectSchema } from './introspect';
 export {
   constraintNameFor,
   declaredIndexes,
@@ -158,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';
@@ -185,6 +184,7 @@ export { BREAKER_COOLDOWN_MS, BREAKER_FAILURES, replicatedClient } from './repli
 export { type DbNode, isPlainRead } from './replica-route';
 export type { ReplicaScope } from './replica-scope';
 export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope';
+export { SIBLING_SCOPE_WAIT_MS } from './sibling-turn';
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
@@ -203,8 +203,10 @@ export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode }
 export { statementFingerprint, statementKind, statementVerb } from './statement-shape';
 export { STATEMENT_ATTRIBUTE } from './statement-span';
 export { statementsOf } from './statement-split';
-export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
-export { beginStatement, currentTx, withTransaction } from './transaction';
+export { currentTx, liveTxConnection, withTransaction } from './transaction';
+export { commitUnknown, siblingScopeTimeout, transactionAborted } from './transaction-errors';
+export type { DbTx, IsolationLevel, TransactionOptions } from './transaction-options';
+export { beginStatement } from './transaction-options';
 export type { GeneratableForm } from './ungeneratable';
 export { GENERATABLE_FORMS, ungeneratableStatements } from './ungeneratable';
 export type { UnrenderedDeclaration } from './unrendered';

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.
 
@@ -79,6 +79,12 @@ export async function introspectCatalog(
   const unrendered = await unrenderedRows(client, schema);
   const known = new Set(tables.map((table) => table.name));
   const materialized = new Set(views.filter((view) => view.kind === 'm').map((view) => view.name));
+  // A trigger loads only onto a relation the dump creates: a plain table, or a view (`instead
+  // of`). One on a partitioned table or a partition was filed under `09_triggers/` for a table no
+  // file creates, and the load refused the whole dump with `X_SCHEMA_DUMP_DRIFT`.
+  const viewNames = new Set(views.map((view) => view.name));
+  const loadable = (trigger: { readonly table_name: string }): boolean =>
+    known.has(trigger.table_name) || viewNames.has(trigger.table_name);
 
   return {
     schema,
@@ -129,6 +135,7 @@ export async function introspectCatalog(
         ),
       ),
     triggers: triggers
+      .filter(loadable)
       .map((row) => ({
         table: row.table_name,
         name: row.name,
@@ -141,7 +148,17 @@ export async function introspectCatalog(
           (trigger) => trigger.name,
         ),
       ),
-    unrendered: unrendered
+    unrendered: [
+      ...unrendered,
+      // Named rather than dropped, the rule `CatalogUnrendered` states.
+      ...triggers
+        .filter((trigger) => !loadable(trigger))
+        .map((trigger) => ({
+          kind: 'trigger',
+          name: trigger.name,
+          table_name: trigger.table_name,
+        })),
+    ]
       .map((row) => ({ kind: row.kind, name: row.name, table: row.table_name }))
       .sort(
         by(

package/src/introspect.ts

@@ -27,7 +27,11 @@ export interface ColumnDescription {
 
 export interface IndexDescription {
   readonly name: string;
-  /** Physical columns in **index key order** — the order the planner sorts by, never `attnum`. */
+  /**
+   * Key columns in **index key order** — the order the planner sorts by, never `attnum`. An
+   * EXPRESSION key read from the catalog is its definition in parentheses (`(lower(title))`), in
+   * its own position: marked, so it can never be taken for a column, and never dropped.
+   */
   readonly columns: readonly string[];
   readonly unique: boolean;
   readonly primary: boolean;
@@ -100,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.
    */
@@ -115,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 {
@@ -175,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
@@ -188,17 +213,45 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     ...(await nonAppRelations(client, schema)),
   ];
 
+  // The type is `format_type`, as `catalog-relations.ts` reads it: `information_schema.data_type`
+  // answers `numeric` for `numeric(12,2)`, `ARRAY` for `text[]` and `USER-DEFINED` for an enum, and
+  // `ColumnDescription.dataType` has always been documented as the first of each pair. Still FROM
+  // the view, which decides which columns this role may see.
   const columns = await client.query<ColumnRow>(sql`
-    select table_name, column_name, data_type, is_nullable, column_default, ordinal_position
-    from information_schema.columns
-    where table_schema = ${schema}
-    order by table_name, ordinal_position
+    select
+      c.table_name,
+      c.column_name,
+      coalesce(
+        (
+          select format_type(a.atttypid, a.atttypmod)
+          from pg_attribute a
+          join pg_class r on r.oid = a.attrelid
+          join pg_namespace n on n.oid = r.relnamespace
+          where n.nspname = c.table_schema
+            and r.relname = c.table_name
+            and a.attname = c.column_name
+            and a.attnum > 0
+            and not a.attisdropped
+        ),
+        c.data_type
+      ) as data_type,
+      c.is_nullable,
+      c.column_default,
+      c.ordinal_position
+    from information_schema.columns c
+    where c.table_schema = ${schema}
+    order by c.table_name, c.ordinal_position
   `);
 
   // Ordered by the index's own key position, never by `attnum`: `indkey` IS the order the planner
   // sorts by, and a composite index on `(created_at, org_id)` whose columns were declared the
   // other way round came back reversed — a description that reads correct and compares wrong.
   // `indnkeyatts` drops INCLUDE payload columns, which are stored, not keyed.
+  //
+  // A LEFT join on `pg_attribute`: an expression key has `attnum = 0` and no attribute row, so an
+  // inner join dropped it and `(id, lower(title))` read back as `(id)` — an index rebuilt by hand
+  // with an extra expression key compared equal to the declared one. It is kept in its position
+  // and MARKED by its parentheses, which no declared column name carries.
   const indexes = await client.query<IndexRow>(sql`
     select
       t.relname as table_name,
@@ -207,7 +260,10 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
       ix.indisprimary as is_primary,
       pg_get_expr(ix.indpred, ix.indrelid) as predicate,
       am.amname as method,
-      array_agg(a.attname order by k.ord) as columns,
+      array_agg(
+        coalesce(a.attname::text, '(' || pg_get_indexdef(ix.indexrelid, k.ord::int, false) || ')')
+        order by k.ord
+      ) as columns,
       bool_and((ix.indoption[k.ord - 1] & 1) = 1) as descending
     from pg_class t
     join pg_namespace n on n.oid = t.relnamespace
@@ -215,9 +271,11 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     join pg_class i on i.oid = ix.indexrelid
     join pg_am am on am.oid = i.relam
     cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
-    join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum
+    left join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum and k.attnum > 0
     where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
-    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid, am.amname
+    group by
+      t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid,
+      ix.indexrelid, am.amname
     order by t.relname, i.relname
   `);
 
@@ -260,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. */
@@ -271,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))
@@ -322,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 };
+}