@ultimat3/db 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -100,14 +100,14 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`expected-loop.ts` is the ONLY suppression**: `expectedQueryLoop(reason, fn)`, innermost reason,
   blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement.
   The framework's own loops declare themselves (`migrate()`, `rollback()`, admin's `search.ts`).
-- `@ultimat3/jobs` never imports this package; its statements pass the observer only because
-  `packages/cli/src/dev-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
+- `@ultimat3/jobs` never imports this package; its statements pass the observer only as
+  `packages/cli/src/runtime-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
 
 ## Migrations
 
 - **The migration lock is polled** (`pg_try_advisory_lock` every `MIGRATION_LOCK_POLL_MS` until
   `MIGRATION_LOCK_WAIT_MS`, then `X_MIGRATE_CONCURRENT`), declared with `expectedQueryLoop`;
-  `createRecordingClient` stubs the lock as `locked: true`.
+  `recordingClient` stubs the lock as `locked: true`.
 - **`lock_timeout` is the migration's** (`SET LOCAL` inside each migration's transaction, from the
   `migrate` profile's 3 s).
 - **The advisory lock is held by one pinned session, and `migrate()`/`rollback()` run every statement
@@ -141,7 +141,7 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   declared is CLOSED, live is OPEN (`indexMethodOf` passes the catalog through; `declaredMethod`
   refuses); absent is `btree` through one function; `snapshotOf` records `using` only when declared;
   `indexMethodSql` re-derives the literal (`X_SQL_UNSAFE` default); a unique or ordered GIN is
-  `X_INVARIANT`. `introspect()` reads `pg_am` (`introspect-embedded.test.ts`).
+  `X_INVARIANT`. `introspectSchema()` reads `pg_am` (`introspect-embedded.test.ts`).
 - **`index-plan.ts` walks both directions** (declared first, removed last). `dropRecordedIndex` emits
   `alter table … drop constraint if exists` then `drop index` for a shape a constraint could back
   (`mayBeConstraintBacked`); four names are skipped (primary, moved aside, rebuilt, over a dropped
@@ -170,29 +170,30 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   in `preAlters` at the top of `up`, re-adding is `foreignKeyPlan`'s, both `breaksOn` ends are needed
   (`generate-retype-key.live.test.ts`). `sql-type.ts` reads `SQL_TYPES` with `Object.hasOwn`.
 - **A generated column** (`generated-column.ts`): the clause right after the type; generated-and-
-  defaulted refused; an expression change is `set expression as (…)`; a retype carries no `using`; a NOT
-  NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds the
-  column (`regenerate` answers `rebuilt`) and moves its dependents aside; a generated column's own type
-  change deliberately does not. `introspect` never reads `generation_expression` back.
+  defaulted refused; an expression change is `set expression as (…)`; a retype has no `using`; a NOT
+  NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds
+  (`rebuilt`) and moves dependents aside, its own type change does not. `introspectSchema` never reads
+  `generation_expression`.
   `generate-generated-{column,rebuild}.live.test.ts`.
-- **`REPLICA IDENTITY FULL` is emitted by a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from
-  `@ultimat3/cli`'s `db-generate.ts`), in `replica-identity.ts`: recorded `true` or absent; the
-  snapshot records the union; dead last in `up`; never destructive; an undeclared name is skipped;
-  `down` is `replica identity default` except on a table this migration creates.
+- **`REPLICA IDENTITY FULL` is a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from the CLI's
+  `db-generate.ts`; `replica-identity.ts`): recorded `true` or absent, as a union; last in `up`; an
+  undeclared name skipped; `down` reverts it unless this migration created the table.
+- **`appendOnly: true` is a trigger** (`generate-append-only.ts`): one `create or replace` function
+  (SQLSTATE `23001`, message leads `X_ENTITY_APPEND_ONLY`) and a fixed-name `ultimate_append_only`
+  `before update or delete … for each row`; recorded `true` or absent; no `truncate`. Drift:
+  enabled `triggerNames` (`drift-append-only.ts`, `X_APPEND_ONLY_TRIGGER_MISSING`).
 - **A foreign key is `alter table … add constraint`**, collected into a bucket merged after every table
   statement (`foreign-key-plan.ts`); **dropping a table has its own bucket emitted BEFORE the table
   statements** (`preDrops`), ordered children-first by `drop-order.ts`, which breaks a two-table cycle
   by dropping one key first. `foreignKeyPlan` walks both directions, drops the name the previous
   snapshot recorded, and rebuilds a key whose `onDelete` moved. **`on delete` reaches the SQL**
   (`onDeleteRule`, `foreign-key.ts`; an unknown rule is `X_INVARIANT`).
-- **`entity-shape.ts` holds the three `*Like` interfaces** (optional `onDelete` / `generated`).
-- **`snapshot-json.ts` writes bytes that are a fixed point of Biome** (arrays collapse when they fit at
-  `<= 100` counting the trailing comma); `snapshot-json.test.ts` runs the repo's own `biome format`.
-- **`declaredSchema()` answers the NEWEST migration's snapshot or `undefined`**; `checkDrift` turns
-  that into `unknown-schema`, and `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING`. Both lead
-  with the same two remedies in order: restore the sidecar (`git checkout --`), or delete the
-  migration's files FIRST and then run `x db gen`. Both commands are screened (`shellInertIdentifier`
-  / `renderFixShellArg`), degrading the whole line to prose.
+- **`entity-shape.ts` holds the `*Like` interfaces** (every later field optional).
+- **`snapshot-json.ts` writes a fixed point of Biome** (an array collapses when it fits at `<= 100`
+  with its trailing comma); `snapshot-json.test.ts` runs `biome format`.
+- **`declaredSchema()` answers the NEWEST migration's snapshot or `undefined`** (`checkDrift`:
+  `unknown-schema`; `x db gen`: `X_MIGRATION_SNAPSHOT_MISSING`). Both fixes: restore the sidecar
+  (`git checkout --`), else delete the migration's files FIRST, then `x db gen`; both screened.
 
 ## Drift and introspection
 
@@ -204,16 +205,16 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   holds `x db gen`'s arm, its `drop not null`s, its two refusals). The type is not compared.
 - **A missing CHECK is drift, compared by NAME**: `TableDescription.checks` (declared: name and
   expression) vs `TableDescription.checkNames` (catalog: `conname` for `contype = 'c'`, always written
-  by `introspect()`, `[]` included). Only the declared side is judged; no `changed-check`, ever.
+  by `introspectSchema()`, `[]` included). Only the declared side is judged; never a `changed-check`.
   `drift-check.live.test.ts`.
 - `compareTable` judges declared indexes (`missing-index`, `changed-index` over method, column list,
   uniqueness, predicate presence and direction; `asc` normalises to `null`); never the predicate text.
 - `compareForeignKeys` matches on where a key points (`foreignKeyTarget`, the one copy) and compares
   `onDelete` through `onDeleteRule` (`changed-foreign-key`; its fix, `changed-column`'s and
   `missing-check`'s are one `psql -c` too — `repair()`, schema-scoped off `public`).
-- `introspect()` reads index columns in key order (`indkey`) and a foreign key's two column lists
+- `introspectSchema()` reads index columns in key order (`indkey`) and a foreign key's two column lists
   together (`unnest(a, b) with ordinality`), pinned by `introspect-embedded.test.ts`.
-- **`appTables()`** excludes the whole `x_` namespace for drift; `introspect()` alone excludes
+- **`appTables()`** excludes all of `x_` for drift; `introspectSchema()` alone excludes
   `x_migrations` by default. **`app-relation.ts`**: `nonAppRelations(client, schema)` — extension
   ownership from `pg_depend` (`deptype = 'e'`) plus views, materialised views and foreign tables —
   merged into `excluded` unconditionally.
@@ -228,9 +229,9 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 
 - **Its own entry: `@ultimat3/db/schema-dump`** (`schema-dump-entry.ts`). The barrel is in every
   role's boot graph and must evaluate none of this family — `schema-dump-entry.test.ts`.
-- **Two readings of one catalog, never mixed.** `introspect()` → `SchemaDescription`, the entity
-  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries in `catalog-relations.ts` and
-  `catalog-objects.ts`; the pure fold in `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
+- **Two readings of one catalog, never mixed.** `introspectSchema()` → `SchemaDescription`, the entity
+  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries: `catalog-relations.ts`,
+  `catalog-objects.ts`; pure fold: `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
   itself. A catalog spelling on a `SchemaDescription` field is the `checks`/`checkNames` mistake.
 - **Sorted in JS** (`byCodeUnit`), never `order by` and never `localeCompare`: collations differ.
 - **`renderSchemaDump()` is pure**; `schema-dump-table.ts` spells one table. `quoted()` escapes any
@@ -284,7 +285,7 @@ Gotchas:
 
 - `exactOptionalPropertyTypes` — declare optional fields as `x?: T | undefined`.
 - `noUncheckedIndexedAccess` — array reads are `T | undefined`; `chunks[i] ?? ''` everywhere.
-- Tests use `createRecordingClient()` + `setDbClient()`; no test may need a live database.
+- Tests use `recordingClient()` + `setDbClient()`; no test needs a live database.
 - A test that must prove a pin came back uses `reservableOver()` (`fake-reservable.ts`), never a copy.
 - `ALTER DEFAULT PRIVILEGES` is scoped to an object's creator, so layer 1 covers future tables only for
   the roles in `creators` (default: the connected user).

package/README.md

@@ -38,7 +38,7 @@ await withTransaction(async (tx) => {
 | `replicatedClient()` / `ReplicaStats` / `REPLICA_URL_ENV` | `As of 2026-08-24`: one `DbClient` over a primary and a standby. `baseClient()` builds one when `DATABASE_REPLICA_URL` is set and the single-pool client when it is not |
 | `INDEX_METHODS` / `IndexMethod` / `indexMethodOf()` / `indexMethodSql()` / `declaredMethod()` / `isIndexMethod()` | `As of 2026-08-24`: an index's access method — `btree` or `gin`, closed. Absent is `btree`, the live side is read open (whatever `pg_am` said), and the DDL literal is re-derived from the set rather than spliced from the input |
 | `isPlainRead()` | `As of 2026-08-24`: whether a statement may leave the primary. An allow-list — everything it cannot vouch for is the primary's |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text), declared CHECK constraints by NAME (`missing-check`, `As of 2026-08-25` — never a predicate, which the catalog answers rewritten) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
+| `checkDrift()` / `diffSchema()` / `assertNoSchemaDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text), declared CHECK constraints by NAME (`missing-check`, `As of 2026-08-25` — never a predicate, which the catalog answers rewritten) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
 | `declaredSchema()` / `expectedSchema()` | `As of 2026-08`: the schema the migrations write down, or `undefined` when the newest one carries no snapshot — never an older snapshot standing in for it |
 | `parseSnapshot()` | `As of 2026-08`: a `<id>.snapshot.json` sidecar validated to the last nested field, or `undefined`. `{"tables":[null]}` is valid JSON and is not a schema |
 | `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
@@ -49,10 +49,10 @@ await withTransaction(async (tx) => {
 | `declaredChecks()` / `checkClauses()` / `checkPlan()` / `columnChecks()` / `columnCheckName()` / `columnNamesConstraint()` | `As of 2026-08-25`: **every** CHECK a table declares — a column's own (`enumerated()`'s value set, `tz()`'s IANA whitelist, `locale()`'s tags, money's currency pattern and scale bound) and an invariant's — on ONE list, so `createTable`, `diffTable` and `snapshotOf` agree about what exists. A column's check reached `create table` **inline and anonymous** and nothing else: the snapshot recorded none and the diff had no arm, so a value added to `enumerated()` generated no migration and a regenerated ENUM column came back as bare `text`. The name is `<table>_<column>_check` because that is the name **Postgres itself mints** for the old anonymous form — measured — so the repair lands on the constraint an already-generated database is holding; `checkPlan` emits `drop constraint if exists` before the `add` for exactly that column, because a bare add is `42710` there and a no-op everywhere else |
 | `defaultExpression()` / `ColumnDefaultLike` | `As of 2026-08-25`: a column's `default` as SQL. A DECLARED default (`{ kind: 'value', value }`) wins; `gen_random_uuid()` and `now()` stay as the inference for a description that carries only `hasDefault` |
 | `unrenderedOf()` / `unrenderedComment()` / `UnrenderedDeclaration` | `As of 2026-08-25`: what the generator could **not** write, on `GeneratedMigration.unrendered` and as a `-- UNRENDERED` block at the top of a non-empty `up`. A generator that emits less than the declaration in silence is the defect the whole file exists against, and `x verify`'s `drift` step reads a source hash — it never reads the SQL, so the loss was green. **`unrenderedOf(entities, current)` takes the recorded schema**, required and nullable: a rule declared as an `assert` reaches no SQL by design and is no loss on its own, but one whose CHECK a previous migration RECORDED is dropped by this run and reported by nothing — five in `examples/dummy`, and `@ultimat3/cli`'s `repairFix` then offered `x db gen "drop <name>"` as the repair for the loss that command performs |
-| `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
+| `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructiveMigration()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
-| `introspect()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
-| `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspect()` stays the entity-vocabulary reading a snapshot is diffed in |
+| `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
+| `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspectSchema()` stays the entity-vocabulary reading a snapshot is diffed in |
 | `renderSchemaDump()` / `SchemaDumpFile` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: a catalog → the schema dump's files. Pure and byte-deterministic. [The schema dump](#the-schema-dump) |
 | `loadSchemaDump()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: build a schema from those files, in one transaction, retrying a file that names something not created yet |
 | `compareSchemaDump()` / `reloadDifferences()` / `schemaDumpDrift()` / `schemaDumpDifferenceOf()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: `X_SCHEMA_DUMP_DRIFT` — committed files against rendered ones in both directions, and load-equals-replay as a comparison |
@@ -60,7 +60,7 @@ await withTransaction(async (tx) => {
 | `PgliteOptions.extensions` / `linkPgliteExtensions()` | `As of 2026-10`: Postgres extensions to link at boot, by name — a list, or a function for a caller whose list is read from disk. `linkPgliteExtensions(names)` answers `{ linked, missing }` without booting anything: `missing` is what the installed PGlite ships no bundle for, which is how `@ultimat3/cli` decides a replay needs a real Postgres. A missing name is skipped at boot and refused by `create extension` itself |
 | `PgliteOptions.snapshotDir` | `As of 2026-10`: a directory for the post-`initdb` snapshot, so an in-memory boot is a restore (~0.4 s against ~2.7 s). Keyed on the PGlite version alone — `initdb` never sees a linked extension, so one snapshot serves every set; checksummed, never trusted, written by temp-name-then-rename. Ignored for a data directory on disk |
 | `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases. `As of 2026-08-19` the marker comment records the **base** as well as the instant (`ultimate:branch:<base>:<iso>`, on `BranchInfo.base`), and `reapBranches()` sweeps only branches of the database it is connected to — one Postgres hosting two Ultimate apps used to mean one app's nightly reap dropped the other's branches. A pre-3.x marker records no base and is skipped, never dropped |
-| `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
+| `pgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
 | `readOnlyQuery()` / `READONLY_TIMEOUT_MS` | one statement inside `BEGIN READ ONLY` with a statement timeout — layer 2 |
 | `setStatementObserver()` / `statementObserver()` | `As of 2026-08`: one event **and one `db.<verb>` span** per settled statement, both drivers; uninstalled is one branch |
@@ -68,7 +68,7 @@ await withTransaction(async (tx) => {
 | `withStatementAttribution()` / `statementAttribution()` | `As of 2026-08`: the `{ entity, op }` pair on `StatementEvent.attribution`, scoped exactly like `expectedQueryLoop()` — `@ultimat3/entity`'s `postgresRepo` is the one producer |
 | `STATEMENT_ATTRIBUTE` | `As of 2026-08`: `db.statement`, the OTel attribute each span carries its text under — declared here, read by `x dev`'s timeline |
 | `statementFingerprint()` / `statementKind()` / `statementVerb()` | `As of 2026-08`: what shape a statement is — `entity.op` when attributed else its own collapsed text, read or write from the leading verb. One rule, so two detectors group identically |
-| `createRecordingClient()` | in-memory `DbClient` that records SQL, for tests |
+| `recordingClient()` | in-memory `DbClient` that records SQL, for tests |
 
 ## `sql` is parameters-only
 
@@ -197,7 +197,7 @@ production traffic is routed.
 
 ## The drift contract
 
-`checkDrift()` compares `introspect()` against the snapshot the newest applied migration carries —
+`checkDrift()` compares `introspectSchema()` against the snapshot the newest applied migration carries —
 `expectedSchema(migrations, ledger)`. `declaredSchema(migrations)` is the same read with the ledger
 left out: the schema the files *declare*, applied or not, which is what `x db gen` diffs the app's
 entities against so generation needs no database at all. One implementation, two callers — a
@@ -215,7 +215,7 @@ A migration the ledger has not recorded is **not** drift: `expectedSchema` reads
 subset, so a database that simply has not migrated yet is pending, not divergent. Neither is a
 table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox and every
 `@ultimat3/auth` table are created by `create table if not exists` at boot and appear in no
-snapshot, so `appTables()` drops them before the diff. `introspect()` keeps its own narrower
+snapshot, so `appTables()` drops them before the diff. `introspectSchema()` keeps its own narrower
 exclusion (the ledger alone), reserving `x_users` for a schema view that wants it.
 
 **A CHECK the catalog no longer holds is drift, `As of 2026-08-25` — by NAME.**
@@ -233,7 +233,7 @@ expression parser competing with the server's.
 **Nor is a relation an extension owns, `As of 2026-08-24`.** `create extension pg_stat_statements`
 in `public` is the CNPG, RDS, Supabase and Neon default, and its view read as `unexpected-table`
 with `x db gen "add pg_stat_statements"` as the fix — so every deploy failed terminally and the fix
-would have written an extension's internal view into the app's migration set. `introspect()` now
+would have written an extension's internal view into the app's migration set. `introspectSchema()` now
 excludes every relation Postgres records as extension-owned (`pg_depend`, `deptype = 'e'`), which is
 ownership rather than a name: a `pg_*` prefix rule covers that view and misses `postgis`'
 `spatial_ref_sys`. Views, materialised views and foreign tables go with them — no snapshot records
@@ -257,15 +257,36 @@ X_DB_DRIFT: schema differs from migrations
 | index rebuilt differently | `index "I" on "T" covers (…)` / `is unique` / `is descending` / `is partial`, `not what migrations declare` | `x db migrate` |
 | foreign key, rule moved | `foreign key "K" on "T" (C) to "R" is on delete cascade, not what migrations declare` — `K` is the constraint the database holds | `psql "$DATABASE_URL" -c '<the drop constraint + add constraint pair>'` — one command, against the drifted database — then `x db migrate` |
 | column nullability differs (`changed-column`) | `table "T" allows NULL in column "C" that migrations declare not null` / `forbids NULL in column "C" that migrations declare nullable` | `psql "$DATABASE_URL" -c 'alter table "T" alter column "C" set not null;'` (or `drop not null`) — one command, then `x db migrate`. A table read from a schema other than `public` gets `set search_path = "<schema>";` ahead of the statement, in the same `psql -c` word, so it and every table it references resolve there. A name `shellInertIdentifier()` refuses degrades every one of these three to `psql "$DATABASE_URL"   # <the steps>`: still a command that runs, with no name in it |
+| append-only trigger gone (`missing-append-only-trigger`, `As of 2026-10-06`) — raised as `X_APPEND_ONLY_TRIGGER_MISSING`, the one kind with its own code | `table "T" is declared appendOnly, and its trigger ultimate_append_only is missing or disabled` — a disabled (`D`) or replica-only (`R`) trigger counts as missing, because an ordinary session fires neither | `psql "$DATABASE_URL" -c '<create or replace function …; drop trigger if exists "ultimate_append_only" on "T"; create trigger "ultimate_append_only" …>'` against the drifted database, then `x db migrate`. Drop-if-exists first: a disabled trigger still exists, and a bare `create trigger` would fail on it (`42710`) |
 | primary key differs (`changed-primary-key`, `As of 2026-10-02`) | `table "T" has primary key (id) as constraint "T_pkey", and migrations declare (slug)` — the constraint named is the one the DATABASE holds — compared in column ORDER; `has no primary key` when the database holds none | `psql "$DATABASE_URL" -c '<drop constraint "<the live key>"; add constraint "T_pkey" primary key (…)>'` — one command, against the drifted database — then `x db migrate`. Nullability is skipped for the DECLARED key's columns only |
 
-`checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x db migrate` renders
+`checkDrift()` returns every difference; `assertNoSchemaDrift()` throws the first. `x db migrate` renders
 them all as findings and exits non-zero; a `ROLE=migrate` container throws the first one
-(`assertNoDrift`, in `runRole`) and exits non-zero too, because the release phase has one channel —
+(`assertNoSchemaDrift`, in `runRole`) and exits non-zero too, because the release phase has one channel —
 the exit code — and a deploy that rolled on past a schema nobody can reconstruct is the failure
 drift exists to catch. There is no `x db drift`, and `x verify`'s `drift` step is the *source*
 detector (`checkSourceDrift`), which needs no database and never calls this.
 
+## Append-only tables
+
+`EntityDescriptionLike.appendOnly` (from `entity({ appendOnly: true })`) is a trigger, written by
+`x db gen` (`generate-append-only.ts`) and recorded on the snapshot as `appendOnly: true`:
+
+```sql
+create or replace function "ultimate_refuse_append_only"() 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 = '…'; end; $append_only$;
+create trigger "ultimate_append_only" before update or delete on "ledger" for each row execute function "ultimate_refuse_append_only"();
+```
+
+| | |
+|---|---|
+| Names | fixed: the trigger is `ultimate_append_only` on every table (a trigger name is per table, so no 63-byte truncation), the function one shared `ultimate_refuse_append_only()` |
+| Refuses | UPDATE, DELETE, and the update arm of `insert … on conflict do update`. Not `truncate` — no row write, and `destructive.ts` already gates it |
+| The error | message leads with `X_ENTITY_APPEND_ONLY`, SQLSTATE `23001` (`restrict_violation`, class 23: an integrity rule refused it, so never retried) |
+| On / off | adding `appendOnly` emits the function (once per migration) and the trigger (drop-if-exists first on an existing table), `down` drops the trigger; removing it drops the trigger, `down` restores both. A dropped table takes its trigger with it; the function is never dropped |
+| NOT NULL with no backfill | a NEW NOT NULL column needs a default (or `.nullable()`), and an EXISTING column cannot be turned NOT NULL: `x db gen` refuses both (`X_MIGRATION_APPEND_ONLY_BACKFILL`) rather than emit the usual `-- backfill …, then: set not null` note — that backfill is an UPDATE the trigger refuses, and a default fills no NULL already stored (`generate-append-only-column.test.ts`) |
+| Engines | Postgres and PGlite alike (`generate-append-only.live.test.ts`, `generate-append-only-embedded.test.ts`) |
+| Drift | `introspectSchema()` writes `triggerNames` (enabled, non-internal) on every table — the catalog half; `appendOnly` is the snapshot half, never read from the catalog |
+
 ## The schema dump
 
 **Imported from `@ultimat3/db/schema-dump`, never from the barrel** (23.0.0): `introspectCatalog`,
@@ -317,17 +338,17 @@ Which engine, where the files live, when they are written and what holds them is
 
 ## The embedded database
 
-No `DATABASE_URL` means no Docker: `createPgliteClient()` runs Postgres as WASM inside this
+No `DATABASE_URL` means no Docker: `pgliteClient()` runs Postgres as WASM inside this
 process. The module is resolved on the first statement, never at import, so an image that only
 ever talks to a managed Postgres never loads it.
 
 ```ts
-const dev = createPgliteClient({ dataDir: pgliteDataDir(services.db.url) });  // or memory://
+const dev = pgliteClient({ dataDir: pgliteDataDir(services.db.url) });  // or memory://
 await dev.ping();                                       // pay the ~3s boot before serving
 setDbClient(dev);
 
 const branch = await branchPglite('feature_x', { from: '.x/pgdata' });
-setDbClient(createPgliteClient({ dataDir: branch.dataDir }));
+setDbClient(pgliteClient({ dataDir: branch.dataDir }));
 ```
 
 PGlite has no `CREATE DATABASE ... TEMPLATE`, so `branchPglite()` copies the data directory —
@@ -337,7 +358,7 @@ lands in a filesystem path, so an unvalidated one is traversal rather than a typ
 
 ### One session, so callers take turns
 
-Embedded Postgres is a single session, not a pool. `createPgliteClient()` is therefore
+Embedded Postgres is a single session, not a pool. `pgliteClient()` is therefore
 `ReservableClient`: `withTransaction()` and `readOnlyQuery()` pin it, and every other statement
 waits for its turn. Without that pin two concurrent units of work each run `BEGIN` on the same
 connection — the second `COMMIT` commits the first's rows and the first `ROLLBACK` finds no
@@ -402,9 +423,9 @@ A pooled statement cannot hold a subscription: the next one runs on another conn
 clients hold ONE session beside the pool for it.
 
 ```ts
-import { createPostgresClient } from '@ultimat3/db';
+import { postgresClient } from '@ultimat3/db';
 
-const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const client = postgresClient({ url: 'postgres://localhost:5432/app_test' });
 const subscription = await client.listen(
   'x_jobs_wake',
   (payload) => console.log('notified', payload),
@@ -438,7 +459,13 @@ migration inside its own transaction. It refuses **before applying anything** wh
   the running one — another version owns the database; or
 - an applied migration's `up` SQL no longer matches its recorded checksum.
 
-Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion }`.
+**Except a rollback** (`As of 2026-10-05`, `migrate-rollback.ts`): when every unknown ledger row
+sorts after the newest migration this build ships, and this build has nothing left to apply, the
+ledger is an older image rolled back onto a newer build's schema. Nothing is applied, the rows are
+reported in `ahead` and logged as `ultimate migrate ledger ahead of build`; any other unknown row is
+still `X_MIGRATION_CONFLICT`.
+
+Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion, ahead: [id] }`.
 
 ## A loop of queries that is deliberate says so
 
@@ -533,7 +560,7 @@ job the moment Postgres fails over.
 | `X_DB_LOCK_TIMEOUT` | `55P03` — it waited past `lock_timeout` for a lock it never got |
 | `X_DB_POOL_EXHAUSTED` | `53300` / `53200`, or `reserve()` past `acquireTimeoutMs` |
 | `X_DB_DRIFT` | live schema differs from migrations |
-| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch |
+| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch — never for rows that are all newer than the build (a rollback) |
 | `X_MIGRATE_CONCURRENT` | another migrator still held the lock when the wait ran out |
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -26,14 +26,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/client.ts

@@ -69,7 +69,7 @@ export interface PostgresClient extends ReservableClient, ListeningClient {
 }
 
 /** Lazily connects: the pool opens on the first statement, never at import. */
-export function createPostgresClient(options: PostgresClientOptions = {}): PostgresClient {
+export function postgresClient(options: PostgresClientOptions = {}): PostgresClient {
   const role = options.role ?? resolveRole();
   const profile: PoolProfile = assertPoolProfile({
     ...poolProfileFor(role),
@@ -247,7 +247,7 @@ export function setDbClient(client: DbClient | undefined): void {
  *
  * The role default is layered under `DATABASE_POOL_MAX`, because this is the one place the process
  * builds its own client and therefore the only place an operator's value can reach one:
- * `createPostgresClient` has always taken a `profile` override and nothing in a running app passed
+ * `postgresClient` has always taken a `profile` override and nothing in a running app passed
  * it, so `POOL_PROFILES` was the last word in a deployed image. `default-client.ts` owns what gets
  * built — one pool, or a primary and a replica when `DATABASE_REPLICA_URL` names one.
  */

package/src/column-alter.ts

@@ -6,8 +6,9 @@
 
 import { defaultExpression, hasUnrenderedDefault } from './column-default';
 import { columnDefaultUnsafe } from './ddl-errors';
-import type { ColumnDescriptionLike } from './entity-shape';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
+import { appendOnlyBackfillRefused } from './generate-append-only';
 import type { ColumnDescription } from './introspect';
 import { identifier } from './sql';
 import { statementsOf } from './statement-split';
@@ -29,18 +30,20 @@ function screened(column: string, expression: string): string {
  * `set default` / `drop default` and `drop not null`, each with its reverse in `down` — the shape
  * `redefineIndex` (`index-ddl.ts`) gives a moved index. Becoming NOT NULL is deliberately NOT a
  * bare `set not null`: rows already holding `NULL` make it fail inside `ROLE=migrate`, so it gets
- * the expand/contract note `diffTable` writes for a NOT NULL column added to a populated table.
+ * the expand/contract note `diffTable` writes for a NOT NULL column added to a populated table —
+ * refused on an append-only table, whose backfill the trigger would refuse.
  *
  * A default this generator cannot render (`hasUnrenderedDefault`) moves nothing: dropping the one
  * the database holds would lose a rule the entity still states, and `unrenderedOf` already reports
  * it at the top of `up`.
  */
 export function alterColumnInPlace(
-  table: string,
+  entity: EntityDescriptionLike,
   column: ColumnDescriptionLike,
   recorded: ColumnDescription,
   plan: Plan,
 ): void {
+  const { table } = entity;
   const alter = `alter table ${identifier(table).text} alter column ${identifier(column.column).text}`;
   const wanted = hasUnrenderedDefault(column) ? recorded.default : defaultExpression(column);
   const held = recorded.default;
@@ -59,6 +62,9 @@ export function alterColumnInPlace(
     plan.down.push(`${alter} set not null;`);
     return;
   }
+  // That backfill is an UPDATE, and an append-only table's trigger refuses every one. Refused even
+  // with a default now declared: `set default` fills no row that already holds NULL.
+  if (entity.appendOnly === true) throw appendOnlyBackfillRefused(entity, column, 'made-not-null');
   // `drop not null` in `down` is a no-op on a column that never became NOT NULL, so the reverse is
   // right whether or not the backfill and its `set not null` were ever run.
   plan.up.push(`-- backfill ${identifier(column.column).text}, then: ${alter} set not null;`);

package/src/default-client.ts

@@ -3,7 +3,7 @@
 // framework decides a process's database topology from the environment, and `client.ts` is at the
 // line ceiling.
 
-import { createPostgresClient, type DbClient } from './client';
+import { type DbClient, postgresClient } from './client';
 import { poolMaxFromEnv } from './pool-profile';
 import { replicatedClient } from './replica-client';
 
@@ -18,7 +18,7 @@ import { replicatedClient } from './replica-client';
 export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
 
 /**
- * Composed rather than folded into `createPostgresClient`, on purpose: `migrate`, `x db branch` and
+ * Composed rather than folded into `postgresClient`, on purpose: `migrate`, `x db branch` and
  * every test build a client that must be exactly one pool, and a second pool reachable through the
  * same factory would be a second thing `reserve()`, `close()` and `ping()` each have to mean two
  * ways.
@@ -29,8 +29,8 @@ export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
  */
 export function defaultClient(): DbClient {
   const profile = poolMaxFromEnv();
-  const primary = createPostgresClient({ profile });
+  const primary = postgresClient({ profile });
   const replicaUrl = process.env[REPLICA_URL_ENV];
   if (replicaUrl === undefined || replicaUrl.trim() === '') return primary;
-  return replicatedClient(primary, createPostgresClient({ url: replicaUrl, profile }));
+  return replicatedClient(primary, postgresClient({ url: replicaUrl, profile }));
 }

package/src/dependent-view.ts

@@ -2,7 +2,7 @@
 // before the statement is sent — and name the view, the column and the statement that recreates it.
 //
 // **This is the honest ceiling for views, and the reason it is not in the generator.** `x db gen`
-// runs with no database open; `SchemaDescription` has no field for a view; `introspect()` reads
+// runs with no database open; `SchemaDescription` has no field for a view; `introspectSchema()` reads
 // none by construction (`app-relation.ts` excludes every non-table relation); and no `entity()` can
 // declare one. So nothing the generator reads knows a view exists, and a `GenerateOptions.views`
 // with no caller to fill it is the declared-and-never-wired defect this release exists to

package/src/destructive.ts

@@ -112,4 +112,4 @@ export function destructiveStatements(up: string): readonly DestructiveStatement
 }
 
 /** Whether `up` destroys data at all — what `x db gen` writes the marker from. */
-export const isDestructive = (up: string): boolean => destructiveStatements(up).length > 0;
+export const isDestructiveMigration = (up: string): boolean => destructiveStatements(up).length > 0;

package/src/drift-append-only.ts

@@ -0,0 +1,53 @@
+// Single responsibility: whether an `appendOnly` table still carries the trigger that refuses UPDATE
+// and DELETE, and what to say when it does not. The repository refuses above the driver whatever
+// the database holds, so a dropped trigger is invisible to every test — only the catalog can say.
+
+import { byHand, type DriftDifference, pathTo, repair } from './drift-findings';
+import {
+  APPEND_ONLY_FUNCTION_SQL,
+  APPEND_ONLY_TRIGGER,
+  installAppendOnlyTriggerSql,
+} from './generate-append-only';
+import type { TableDescription } from './introspect';
+import { shellInertIdentifier } from './sql';
+
+/** The code `driftError` raises for this kind, exported so the tests assert the one literal. */
+export const APPEND_ONLY_DRIFT_CODE = 'X_APPEND_ONLY_TRIGGER_MISSING';
+
+/**
+ * The constructor. The fix is the two statements `x db gen` wrote, run against THIS database:
+ * the migration that added the trigger is already in the ledger, so `x db migrate` applies nothing
+ * (`repair`'s argument). Drop-if-exists before create, because a DISABLED trigger counts as missing
+ * here yet still exists, and a bare `create trigger` would fail on it. The function is redefined too — `create or replace` — because a hand that
+ * dropped the trigger may have dropped the function with it.
+ */
+export function missingAppendOnlyTrigger(schema: string, table: string): DriftDifference {
+  const path = pathTo(schema);
+  const spellable = shellInertIdentifier(table) !== null;
+  return {
+    kind: 'missing-append-only-trigger',
+    table,
+    column: null,
+    cause:
+      `table "${table}" is declared appendOnly, and its trigger ${APPEND_ONLY_TRIGGER} is missing ` +
+      'or disabled — raw SQL can UPDATE and DELETE its rows; only the repository still refuses',
+    fix:
+      path === null || !spellable
+        ? byHand('re-create the append-only function and trigger this difference names')
+        : repair(path, [APPEND_ONLY_FUNCTION_SQL, ...installAppendOnlyTriggerSql(table)].join(' ')),
+  };
+}
+
+/**
+ * Judged only where both halves were asked: the snapshot declares the table append-only AND the
+ * catalog was read (`triggerNames` present). Either absent says nothing — a sidecar that predates
+ * the field, or a description nobody introspected — exactly as `compareChecks` reads its pair.
+ */
+export function compareAppendOnly(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  if (expected.appendOnly !== true || live.triggerNames === undefined) return [];
+  if (live.triggerNames.includes(APPEND_ONLY_TRIGGER)) return [];
+  return [missingAppendOnlyTrigger(live.schema, live.name)];
+}

package/src/drift-findings.ts

@@ -23,6 +23,8 @@ export type DriftKind =
   | 'missing-check'
   | 'missing-foreign-key'
   | 'changed-foreign-key'
+  // Constructed in `drift-append-only.ts`: an `appendOnly` table whose refusing trigger is gone.
+  | 'missing-append-only-trigger'
   // Constructed in `object-drift.ts`: a trigger, function, view, type or sequence in the live
   // database that replaying the migrations does not create.
   | 'unexpected-object';
@@ -59,7 +61,7 @@ const UNSPELLABLE = `${CARRIES}, so no statement here can spell it`;
  * this database and never "in a new migration": drift means this database left the migrations,
  * and a migration would re-apply the repair to every database that is already right.
  */
-const repair = (path: string, statements: string, note = RE_CHECK): string =>
+export const repair = (path: string, statements: string, note = RE_CHECK): string =>
   `${psqlCommand(`${path}${statements}`)}   # ${note}`;
 
 /**
@@ -81,7 +83,7 @@ const DEFAULT_SCHEMA = 'public';
  * `tenant_a` fails, or lands on a same-named table in `public`. `null` for a schema no statement
  * can spell.
  */
-const pathTo = (schema: string): string | null => {
+export const pathTo = (schema: string): string | null => {
   if (schema === DEFAULT_SCHEMA) return '';
   const name = shellInertIdentifier(schema);
   return name === null ? null : `set search_path = ${name}; `;

package/src/drift.ts

@@ -4,6 +4,7 @@
 // by the framework contract; `x verify` fails on it and `--json` carries every difference.
 
 import { baseClient, type DbClient } from './client';
+import { APPEND_ONLY_DRIFT_CODE, compareAppendOnly } from './drift-append-only';
 import type { DriftDifference } from './drift-findings';
 import {
   changedColumn,
@@ -22,7 +23,12 @@ import {
 import { DbError } from './errors';
 import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
-import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
+import {
+  findTable,
+  introspectSchema,
+  type SchemaDescription,
+  type TableDescription,
+} from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
 import { sameColumns } from './primary-key';
 
@@ -162,7 +168,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
  * before constraints were recorded: it declares nothing, so nothing can be missing. `live.checkNames`
  * absent is a description that never asked the catalog — a stub, a fake client's rows, a
  * `TableDescription` built by hand — and reading that as "the database holds none" is one finding
- * per declared constraint against a database nobody looked at. `introspect()` always answers with
+ * per declared constraint against a database nobody looked at. `introspectSchema()` always answers with
  * the field, `[]` included, so a real read is never mistaken for an unread one.
  *
  * Only the declared side is judged, the rule `compareIndexes` and `compareForeignKeys` both state:
@@ -222,6 +228,7 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
+  differences.push(...compareAppendOnly(live, expected));
   return differences;
 }
 
@@ -246,7 +253,8 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
 
 export function driftError(difference: DriftDifference): DbError {
   return new DbError({
-    code: 'X_DB_DRIFT',
+    // One kind carries its own code — the guarantee it names is the entity's, not a column's.
+    code: difference.kind === 'missing-append-only-trigger' ? APPEND_ONLY_DRIFT_CODE : 'X_DB_DRIFT',
     cause: difference.cause,
     fix: difference.fix,
     meta: { kind: difference.kind, table: difference.table, column: difference.column },
@@ -260,7 +268,7 @@ export function driftError(difference: DriftDifference): DbError {
  * (`driftFindings`), and `x verify`'s `drift` step is the *source* detector (`checkSourceDrift`),
  * which never reaches this function. There is no `x db drift` command.
  */
-export function assertNoDrift(report: DriftReport): void {
+export function assertNoSchemaDrift(report: DriftReport): void {
   const first = report.differences[0];
   if (first !== undefined) throw driftError(first);
 }
@@ -311,7 +319,7 @@ export function expectedSchema(
  * schema that is in fact correct. The `x_` prefix is the convention every framework table already
  * follows, so a table a future package adds needs no second list here.
  *
- * `introspect()` keeps its own narrower default (`x_migrations` alone) on purpose: the admin
+ * `introspectSchema()` keeps its own narrower default (`x_migrations` alone) on purpose: the admin
  * dashboard's schema view and the MCP `schema.describe` tool legitimately show `x_users`. Only
  * drift wants the whole namespace gone, so only drift declares it.
  */
@@ -348,7 +356,7 @@ export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
   // and a wrong `ok: true` is the failure this check exists to prevent.
   if (expected === undefined)
     return { ok: false, differences: [unknownSchema(options.migrations)] };
-  const live = await introspect({
+  const live = await introspectSchema({
     client,
     ...(options.schema === undefined ? {} : { schema: options.schema }),
   });

package/src/entity-shape.ts

@@ -112,4 +112,9 @@ export interface EntityDescriptionLike {
    * none", which is what every hand-built description in this package's own tests is.
    */
   readonly invariants?: readonly InvariantDescriptionLike[] | undefined;
+  /**
+   * `entity({ appendOnly: true })`: the table refuses UPDATE and DELETE (`generate-append-only.ts`).
+   * Optional for the reason `invariants` is, and absent reads as "rows may change".
+   */
+  readonly appendOnly?: boolean | undefined;
 }