@ultimat3/db 14.0.0 → 16.0.0

package/CLAUDE.md

@@ -9,11 +9,11 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 |---|---|
 | Deps | none. `@electric-sql/pglite` is an **optional peer**, imported by variable specifier inside `loadPgliteDriver()` so no consumer's `tsc` or bundler resolves it. **No ORM** — `entity`'s hand-written `postgresDriver()` is the production backing |
 | SQL | `sql` binds `$n`; anything non-scalar and non-fragment throws `X_SQL_UNSAFE` |
-| Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point |
+| Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point. `literal()` is the tree's ONE SQL-string-literal escape (`scripts/sql-literal-copies.ts`, pinned at zero) and it emits `E'…'` when the value carries a backslash |
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
 | Reading a caught value | `renderThrowable()` from core; never `error instanceof Error ? error.message : String(error)` — both halves RUN app code (a `Proxy` trap, `Symbol.toPrimitive`) and `checkDb` backs `/readyz`, where a render that throws is an exception in place of the report the kubelet asked for |
 | Errors | subclass `DbError`; never `throw new Error` **in source**. A test simulating a *database* failure throws `dbUnavailable()`; a test simulating the *caller's body* failing throws a bare `Error` on purpose — an arbitrary throw is exactly what rollback and disposal must survive, and a `DbError` there would prove the narrower thing |
-| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` |
+| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` — always there, whichever file the CONSTRUCTOR lives in. `errors.ts` reached the 500-line ceiling on 2026-08-25, so a migration's constructors are `migration-errors.ts` and an invariant's are `invariant-errors.ts`; both import `DbError` from `errors.ts` and neither is imported back, and `src/index.ts` re-exports every one of them so no consumer can tell |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from `@ultimat3/core` — never `new AsyncLocalStorage`. Three scopes here use it: `transaction.ts`, `attribution.ts`, `expected-loop.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
 | Files | < 200 LOC, one responsibility, `kebab-case.ts`, test beside source |
@@ -511,7 +511,10 @@ migration ever generated and a marker on all of them marks none. **A closed list
 `drop table`, `drop column`, `truncate`, `alter column … type`; a rail enumerating every Postgres
 foot-gun is a second SQL parser competing with the server's, and every one of these four is a
 statement `generateMigration` emits, so each has a generated case holding it honest. `drop
-constraint`/`default`/`not null` and `drop index` are excluded by name: the database rebuilds them.
+constraint`/`default`/`not null` and `drop index` are excluded by name — a `drop index` holds no
+rows of its own, its `down` recreates the recorded definition, and `redefineIndex` has emitted one
+on every index rename since it existed, so classifying it marks nearly every migration and a marker
+on all is none.
 **Decide on blanked text, report the original** — `statementsOf` + `stripSqlNoise` before a keyword
 is looked for, so `-- drop table users` is prose and `values ('drop table users')` is data; but the
 excerpt in the error keeps its identifiers, because `drop table ""` names nothing an author can act
@@ -653,6 +656,257 @@ right database, and `x db gen`'s `retypeColumn` owns that question where both si
 The `fix:` is the `alter table … set not null` itself and deliberately not `x db gen`, which has
 never emitted one and would answer with an empty migration.
 
+**A CHECK that went missing is drift, `As of 2026-08-25`, and it is compared by NAME because it
+cannot be compared any other way.** `pg_get_constraintdef` answers Postgres' own rewriting —
+`status in ('draft', 'published')` reads back as
+`CHECK ((status = ANY (ARRAY['draft'::text, 'published'::text])))`, measured on 18.4
+(`drift-check.live.test.ts`) — so a catalog value could never equal a generated one and a text
+comparison reports a correct database as wrong forever. That is why nothing here read
+`pg_constraint` for CHECKs at all, and why `alter table … drop constraint` in a psql session was
+`ok: true` on every check that followed it.
+
+**The two readings do not share a field, and that split is the whole design.**
+`TableDescription.checks` is the DECLARED side — name **and** expression, `snapshotOf`'s own
+spelling, the value `checkPlan` diffs. `TableDescription.checkNames` is the CATALOG side — `conname`
+for `contype = 'c'`, names and nothing else, written only by `introspect()`. Filling `checks` from
+the catalog instead would put a rewritten expression where `checkPlan` expects a generated one, and
+every `x db gen` in every app would then drop and re-add every constraint it has, forever, because
+the two strings can never be equal. Split, the TYPE says which reading a value came from and
+`checkPlan` cannot be handed a catalog value by accident.
+
+Three rules ride with it. **Absent and `[]` are different on both sides** — an absent `checks` is a
+sidecar written before the field existed (declares nothing, so nothing can be missing), and an
+absent `checkNames` is a description that never asked the catalog, which reading as "the database
+holds none" is one finding per declared constraint against a database nobody looked at.
+`introspect()` therefore always writes `checkNames`, `[]` included. **Only the declared side is
+judged**, the rule `compareIndexes` and `compareForeignKeys` already state: a NOT NULL (`contype =
+'n'` from Postgres 17 on), an `enumerated()` column's old anonymous form and every constraint an
+extension brought would each be a finding against a database that is exactly right. **There is no
+`changed-check` and there never will be** — presence is a boolean, the predicate is text, and
+normalising the text is an expression parser competing with the server's. `missing-check`'s `fix:`
+is the `add constraint` statement itself, not `x db migrate`: the migration declaring it is already
+in the ledger, so the migrator applies nothing, and the declared side carries the predicate that
+makes an executable fix possible at all.
+
+**`literal()` DOES receive caller input, and this file's own source said otherwise until
+2026-08-25.** `column-default.ts:43` renders `ColumnDefaultLike` through it — an app's own
+`.default('C:\\logs')`, crossing the tier seam from `@ultimat3/entity`, validated by nothing and
+guarded by no `identifier()`. Measured through `generateMigration` on 18.4: the emitted
+`default 'C:\logs'` stores `C:\logs` with `standard_conforming_strings` on and **`C:logs`** with it
+off. A declaration that type-checks, a migration that applies, a column defaulting to a value nobody
+wrote, and no error anywhere. A value ENDING in a backslash is worse — the escaped quote leaves the
+literal unterminated.
+
+The rule is `E'…'` **only** when the value actually carries a backslash: without one there is no
+escape mechanism for the two GUC settings to disagree about, so every migration already on disk
+stays byte for byte what it was and nothing regenerates spuriously. That property is load-bearing —
+both tracked apps hold applied migrations whose `.hash` covers this text — and
+`generate-default.live.test.ts` pins both halves against a real server, applying the same generated
+migration under `on` and under `off` and reading the stored default back. `sql.test.ts` pins the
+five shapes; the round trip through `statementsOf` is there too, because this package's own lexer
+has to read back what its escape writes or `migrate()` starts miscounting statements
+(`sql-scan.ts`'s `escapesAt` already knew the `E''` prefix).
+
+**The other two callers here are safe by CONSTRUCTION, never by input, and the difference matters
+if either is refactored.** `readonly-role.ts:71` sits in the same `sql` template as
+`identifier(role)`, which throws on a backslash before the tag function runs; `branch.ts:85` runs
+after an already-awaited `identifier(base)`. Neither is validating the value it passes to
+`literal()` — a caller moved out of that ordering loses the guard silently.
+
+`literal()` is now the tree's ONE answer, enforced: `scripts/sql-literal-copies.ts` refuses a
+`replace`/`replaceAll` whose replacement is `''` anywhere but `packages/db/src/sql.ts`, matched on
+the TRANSFORMATION rather than on a name — the three copies were called `literal`, `literalText`
+and an unnamed inline template. Pinned at zero.
+
+**A retype takes the objects written against the column out of its way first, `As of 2026-08-25`,
+and `retype-dependents.ts` decides which those are.** Postgres compiles a partial index's predicate
+and a CHECK's expression against the column's type at creation and cannot recompile either:
+`alter table "posts" alter column "status" type text using "status"::text` answered
+`42883 operator does not exist: text = post_status` and the migration aborted mid-run — inside
+`ROLE=migrate`, with the ledger recording nothing. It is what blocked `examples/dummy` from
+regenerating at all.
+
+**Which objects are dependent is measured, never assumed** (`generate-retype.live.test.ts`, one
+shape at a time on 18.4):
+
+| recorded object | survives the ALTER |
+|---|---|
+| btree over the column — plain, unique or composite | **yes**, Postgres rebuilds it itself |
+| partial index whose predicate names the column | **no — 42883** |
+| partial index naming another column | yes |
+| CHECK whose expression names the column | **no — 42883** |
+| a view over the column | no, `0A000`; no snapshot records a view, so `migrate()` refuses it instead (`dependent-view.ts`) |
+
+So only an expression that MENTIONS the column is moved, and a plain btree is left alone — dropping
+it is a table scan to rebuild for nothing.
+
+**The reference test over-approximates on purpose, and it cannot be narrowed by type name.**
+Measured: `char(1)` → `char(3)`, `varchar(80)` → `text` and `numeric` → `integer` all re-derive
+their predicates cleanly, while `integer` → `text` under `check (c >= 0)` is `42883` — both sides
+built-ins. Whether an expression re-resolves depends on operator resolution, which is exactly the
+knowledge a generator with no database cannot have, so every ambiguous case answers "dependent":
+a miss is `42883` in the release phase, a false positive is a rebuild on a statement that is
+already rewriting the whole table under ACCESS EXCLUSIVE. `referencesColumn` walks `sql-scan.ts`
+rather than matching a substring — a name inside a literal or a comment is not a reference,
+`status_code` is not `status`, and a **quoted** identifier IS one, which is the one span the lexer
+calls noise and this reader must not skip.
+
+**What is moved aside is put back by the ORDINARY diff, never twice.** `up` drops the dependents
+before the ALTER and `MovedAside` carries their names to the two arms that would otherwise act on a
+thing that is no longer there: the index loop CREATES a declared name instead of comparing it
+(`redefineIndex` is silent on a definition that never moved, which here means the table comes out
+with no index at all), and `checkPlan` neither drops nor re-adds a predropped name — a declared one
+takes the bare `add constraint` because the name is provably free, and a recorded one the entity no
+longer declares is simply gone, which is what `checkPlan` would have done to it anyway. `down`
+pushes the restores forwards and is reversed as a whole, so it reads: drop the new objects, retype
+back, then recreate the ones compiled against the old type — restoring first is `42883` in the
+other direction. What it restores is what the snapshot RECORDED, never what the entity declares.
+
+**A FOREIGN KEY over the retyped column is moved too, `As of 2026-08-25`, and `retype-keys.ts`
+decides which — above `diffTable`, which is the whole point.** Postgres re-checks a key's two ends
+against each other on every `alter column … type`: measured on 18.4, `42804 foreign key constraint
+"rk_posts_org_code_fkey" cannot be implemented — Key columns "org_code" … and "code" … are of
+incompatible types: integer and text`, thrown by the ALTER itself, inside `ROLE=migrate`, with the
+ledger recording nothing.
+
+**It could not be answered from inside `diffTable` and that is not an implementation detail.** The
+constraint that breaks is recorded on the table that OWNS it, so for a retype of the key's TARGET it
+is a different entity's row — `diffTable(orgs)` is handed `orgs`'s record and can never see
+`posts.foreignKeys`. So `retypedColumns(entities, current)` derives the whole schema's retype set
+once, before the entity loop, and `retypeColumn` READS it instead of asking
+`recorded.dataType === wanted` a second time: two answers to "is this column being retyped" is the
+axiom-1 split this package has spent the week closing.
+
+Four rules ride with it.
+
+| Rule | Why |
+|---|---|
+| the drop goes in a `preAlters` bucket merged at the TOP of `up` and at the FRONT of `down` | both ends of one key can move in two different entities' diffs, so the drop must precede every ALTER in the migration and the restore must follow every one of them. `down` is reversed at assembly, so the front becomes the end: drop the new key, retype both ends back, then add the recorded one. Restoring any earlier is `42804` in the other direction |
+| what comes back in `up` is written by `foreignKeyPlan`, never here | `moveKeysAside` answers a set of `keyId`s and `ConstraintPlans.predropped` reads it as "the schema does not record this key" — the same reading `checkPlan` gives its own `predropped`. That is what makes the three outcomes fall out of code that already exists: still declared (added back in the `constraints` bucket that already runs after every table statement), no longer declared (gone, exactly as the removal arm would have left it), `on delete` moved (added back carrying the new rule). Three branches restating them here is the collision this was deferred over |
+| **both** ends of `breaksOn` earn their line, and they do not overlap | the OWNER arm catches a key whose table is retyped while its TARGET's table is being dropped; the TARGET arm catches the mirror — the key's own table is doomed, so nothing retypes its column and `foreignKeyPlan` is never called for it at all, while `drop table` is emitted at the END of `up`, long after the ALTER it would have unblocked. Both are pinned live (`generate-retype-key.live.test.ts`), because when both tables survive either arm alone would do |
+| a key whose own table or whose target is doomed gets a `--` note in `down` | `add constraint` against a table no `down` can restore is a rollback that cannot run — the rule `unrestorableDrop` already states |
+
+**Re-adding the key is still the SERVER's judgement, deliberately.** An entity that retypes one end
+and not the other declares a pairing Postgres has no operator for, and the `add constraint` at the
+end of `up` is where that is said. Refusing it at generation would need to know whether two types
+share an equality operator — `varchar(80)` and `text` do, `integer` and `text` do not — which is the
+operator-resolution knowledge a generator with no database cannot have, and the same reason
+`referencesColumn` over-approximates. What it cannot see at all is a key the recorded schema does
+not hold: a hand-written migration's, or a sidecar written before `foreignKeys` was recorded.
+
+`sql-type.ts` holds `SQL_TYPES`/`sqlType`, split out of `generate.ts` so the pre-pass can ask what a
+kind renders to without importing the module that imports it. The read is **guarded** with
+`Object.hasOwn`, and db's `proto-index` pin dropped 5 → 4 in the same commit — the ratchet reports a
+count that drops as `stale`, so the two could not land apart. `kind` is data: unguarded,
+`SQL_TYPES['constructor']` answered the `Object` function and its source went into the type position
+of an `alter` statement, and `'__proto__'` answered `[object Object]`. Guarded, both pass through as
+themselves like any other unknown kind, and no other input's answer moves.
+
+**A generated column's REBUILD moves its dependents aside too, `As of 2026-08-25`, and it reuses
+`retypeDependents` rather than answering again.** Plain → generated has no `set expression`, so
+`regenerate` drops the column and adds it back — and `drop column` silently takes every partial
+index whose PREDICATE names it and every CHECK whose expression does (measured, 18.4). The `rebuilt`
+set `diffTable` carries into its index loop is keyed on an index's COLUMNS, so neither is a name it
+can find: the table came back without them, the snapshot still recording both, and `down` unable to
+restore either. `regenerate` therefore takes `live` and `moved` and calls `moveDependentsAside`,
+which drops each explicitly, restores it in `down`, and puts the name where the ordinary diff will
+CREATE it. `generate-generated-rebuild.live.test.ts` applies it both ways.
+
+**A generated column's own `alter … type` deliberately does NOT move them, and the reason is
+measured.** It trips the same `42883` (`operator does not exist: text > integer`, on a generated
+`integer` column under `where (doubled > 0)`) — but moving the index aside only relocates the
+failure to the `create index` that puts it back, because a predicate whose operator the NEW type has
+no resolution for cannot be written either. The plain path's dependents survive precisely because an
+untyped literal re-resolves (`status = 'published'` under an enum and under `text`), and a generated
+column reaching that shape needs its EXPRESSION changed in the same migration, which `regenerate`
+emits AFTER the type statement. Left open with the failure named in the source rather than closed
+with a change no test could fail on.
+
+And **what no migration wrote down** is still invisible to the generator by construction — `x db gen`
+runs with no database open, so a hand-added expression index over the column is `42883` whatever
+this does, since `SchemaDescription` has a field for it nowhere.
+
+**A VIEW is NOT discoverable from anything this generator reads, and the honest ceiling is a
+refusal one statement earlier, `As of 2026-08-25`.** `SchemaDescription` has no field for a view,
+`introspect()` reads none by construction (`app-relation.ts` excludes every non-table relation), and
+no `entity()` can declare one — so a `GenerateOptions.views` with no caller to fill it would be the
+declared-and-never-wired defect this release exists to eliminate, and the caller is
+`@ultimat3/cli`'s. What DOES have a connection is `migrate()`. `dependent-view.ts` is the preflight:
+`refuseDependentViews(tx, script)` runs inside each migration's own transaction, before its first
+statement, and both `migrate()` and `rollback()` call it.
+
+It repairs nothing and does not claim to — the deploy still stops. What it replaces is
+`X_DB_UNAVAILABLE: cannot reach the database`, whose registered `fix:` is "set `DATABASE_URL` to a
+reachable Postgres url", on a database the migrator is connected to and mid-transaction on. The
+server's own words name the view in a **DETAIL** field nothing printed:
+`0A000 cannot alter type of a column used by a view or rule` /
+`rule _RETURN on view dv_docs_published depends on column "rank"`. `X_MIGRATION_VIEW_DEPENDS` names
+the view, the table and the column, and its `fix:` is the `drop view` plus the `create view` built
+from `pg_get_viewdef(oid, true)` — a paste, not an archaeology.
+
+Four rules.
+
+| Rule | Why |
+|---|---|
+| `retypeTargets` is a WORD scan over `sql-scan.ts`, never a regex | a retype inside a `--` comment is prose and one inside a literal is data, and both reach the scan when they sit inside an `alter table` statement — read as code either invents a target on a column the statement never touches. A **quoted** name is never a keyword: `alter table "t" alter "column" type text` retypes a column called `column`, and read as the keyword it names `type` and matches nothing |
+| the matcher is **narrow on purpose** | a miss costs exactly what happens today — the server's own `0A000`, one statement later — while a false positive refuses a migration that would have applied. Every retype `generateMigration` emits is `alter table <t> … alter [column] <c> type`; a hand-written `ALTER TABLE ONLY t …` is not, and is left to the server |
+| one catalog round trip, and the PAIR is filtered in JS | the query asks every retyped table against every retyped column, so it answers pairs nobody retypes — `dv_notes.rank` out of `dv_docs.rank` and `dv_notes.mark`. Refusing on one is a deploy stopped over a view standing in nobody's way, which is worse than the message this exists to improve. Pinned live |
+| the `fix:` is built through `identifier()` **inside a `try`** | `identifier()` refuses a name holding a quote, a space or a backslash, all three legal inside a quoted Postgres name, and a `fix:` may not throw — the rule `rebuildForeignKey` already states, with the same shape. `errors.ts` takes the finished string rather than importing `sql.ts`: that module imports `identifierUnsafe` from it, and an import cycle around the module whose evaluation REGISTERS every code is not one worth having for a quoted name |
+
+A script that retypes nothing costs one text scan and no round trip, which is nearly every migration
+an app writes.
+
+**`index-ddl.ts` holds `createIndex`, `redefineIndex`, `indexShape`, `dropIndex`,
+`dropRecordedIndex`, `mayBeConstraintBacked` and `asDeclared`**, split out of `generate.ts` at the
+500-line ceiling along the seam `check-ddl.ts` and `generated-column.ts` already drew —
+`generate.ts` assembles a plan, `index-plan.ts` decides which index statements go in it, and
+`index-ddl.ts` writes them. `drift-findings.ts` is the same split on the other file: every `DriftDifference`
+constructor and the `DriftKind` union, with `drift.ts` keeping the comparisons and re-exporting both
+types explicitly so the public surface does not move.
+
+**`index-plan.ts` walks both directions, `As of 2026-08-25`** — the third arm to learn it, after
+`checkPlan` and `foreignKeyPlan`. `diffTable`'s index loop walked `declaredIndexes(entity)` and
+matched by name with **no reverse pass**, so an index the entities stopped declaring stayed on the
+database forever while the sidecar beside it stopped recording it: measured on `examples/dummy`,
+`member_unique_per_org`, `members_tz_idx` and `post_slug_unique_per_org` all survived a regeneration
+that recorded none of them, and the `drift` gate step was green over all three because drift judges
+the declared side. `indexPlan(entity, live, plan, context)` is the whole question now — declared
+first and removed last, the order `checkPlan` uses — and `generate.ts` calls it.
+
+**A recorded UNIQUE index cannot be told from a UNIQUE CONSTRAINT's, and it never will be.**
+`TableDescription` carries no discriminator and cannot usefully be given one: the *same*
+declaration reaches the server as either, depending on which migration created it. A `unique` column
+on a table `createTable` writes goes out as `create table … slug text unique`, which Postgres backs
+with a **constraint** named `posts_slug_key`; the same column gaining `unique` later takes
+`diffTable`'s `create unique index "posts_slug_key"` and is a plain index. `snapshotOf` records both
+as `{ unique: true, primary: false }`, and every sidecar already on disk was written that way, so a
+new field could not classify one retroactively. Measured on 18.4
+(`index-removal.live.test.ts`):
+
+| statement | on a constraint's index | on a plain index |
+|---|---|---|
+| `drop index "n"` | **2BP01** | ok |
+| `drop index if exists "n"` | **2BP01** — `if exists` does not suppress it | ok |
+| `alter table … drop constraint if exists "n"` | drops it, index and all | notice, no-op |
+
+So `dropRecordedIndex` emits the **pair**, constraint first — reversed, the `drop index` reaches a
+constraint's index and is the 2BP01 this exists to avoid — and only for the shape a constraint could
+be backing: `mayBeConstraintBacked` is unique, non-primary, total, unordered and btree, because
+`add constraint … unique` and a `unique` column clause can produce nothing else. A partial or
+ordered or GIN index takes the bare `drop index`. The asymmetry that remains is named rather than
+hidden: `down` recreates it with `create unique index`, so a constraint comes back as an index. That
+is the one statement this generator has, and it restores what the record described.
+
+Four names are skipped by the removal arm, and each is a statement Postgres would refuse or repeat:
+a `primary` index (2BP01, and the key is `TableDescription.primaryKey`), one already in
+`MovedAside.indexes` (a retype dropped it ahead of the ALTER — 42704), one over a column
+`regenerate` rebuilt (it went with the `drop column` — 42704), and one over a column this migration
+DROPS (`alter table … drop column` takes it, the rule `foreignKeyPlan` already applies to a
+constraint on a dropped column). A doomed **table** needs no arm at all: `generate.ts` only reaches
+a diff for a table an entity still declares. The known limit is written in the file header — a
+unique index a foreign key on ANOTHER table still references cannot be dropped (2BP01), and this arm
+sees one table at a time.
+
 **An entity's INVARIANTS reach the DDL, `As of 2026-08-25`, and `invariant-ddl.ts` is what they
 become.** `EntityDescriptionLike` had no `invariants` field at all — the same seam gap
 `onDelete` carried until 3.0 — so a regenerated migration held **none** of them: measured on
@@ -866,8 +1120,10 @@ module's vocabulary; `snapshotOf` imports `foreignKeysOf` back, one direction on
 **`foreignKeyPlan` walks both directions, `As of 2026-08-19`.** A *removed* `references()` used to
 emit nothing while the snapshot beside it recorded `foreignKeys: []` — so the orphan constraint
 stayed on the database **and** the record denied one the catalog holds, which `compareForeignKeys`
-can never see because it judges the declared side. That is not parity with a removed index: a
-removed index leaves the snapshot correct by omission, and this snapshot lied. The drop names the
+can never see because it judges the declared side. **This paragraph said "that is not parity with a
+removed index: a removed index leaves the snapshot correct by omission", and that was wrong** — see
+`index-plan.ts` below: a removed index's snapshot lied in exactly the same way, and the arm to fix
+it did not land until 2026-08-25. The drop names the
 constraint **the previous snapshot recorded**, never the one this generator would have chosen — a
 hand-written `fk_legacy` is `42704` under the generated spelling — and a key whose columns this
 migration is dropping is skipped, because `drop column` takes the constraint with it. A key whose

package/README.md

@@ -36,13 +36,13 @@ 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) 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()` / `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` |
 | `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 |
 | `isLedgerMissing()` | `As of 2026-08`: whether an error is Postgres' `undefined_table` for `x_migrations` — the one condition a caller may read as "nothing applied" |
 | `appTables()` / `FRAMEWORK_TABLE_PREFIX` | `As of 2026-08`: the live schema minus the `x_` namespace — no migration declares the ledger, the queue, the outbox or an auth table, so none of them is drift |
-| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all |
+| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all. `As of 2026-08-25` a **retype** drops the partial indexes and CHECK constraints written against that column first and restores them in `down`: Postgres compiles both predicates against the old type and cannot recompile either, so `alter column … type text using …::text` was `42883 operator does not exist: text = post_status` and the migration aborted mid-run. A plain btree over the column is left alone — measured, Postgres rebuilds that one itself |
 | `declaredIndexes()` / `invariantChecks()` / `constraintNameFor()` | `As of 2026-08-25`: the DDL an entity **invariant** becomes — a `check` as a named `CONSTRAINT`, a `unique` as a partial-capable unique INDEX, an `assert` as nothing. `EntityDescriptionLike` had no `invariants` field for three majors, so a regenerated migration silently held **none** of them, including the composite UNIQUE `upsertAll`'s `on conflict` is inferred against |
 | `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` |
@@ -185,6 +185,17 @@ table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox a
 snapshot, so `appTables()` drops them before the diff. `introspect()` 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.**
+`pg_get_constraintdef` answers Postgres' own rewriting (`status in ('draft', 'published')` reads
+back as `CHECK ((status = ANY (ARRAY['draft'::text, 'published'::text])))`), so the catalog side is
+read as `conname` alone and lands on `TableDescription.checkNames`, a **separate field** from the
+declaration's `checks`. Only the declared side is judged, so a NOT NULL, an `enumerated()` column's
+old anonymous form and an extension's own constraint are all silent; a declared one the catalog
+does not hold is `missing-check`, whose `fix:` is the `add constraint` statement itself, because the
+migration that declares it is already in the ledger and `x db migrate` would apply nothing. There is
+no `changed-check`: presence is a boolean, a predicate is text, and normalising the text is an
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "14.0.0",
+  "version": "16.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "14.0.0"
+    "@ultimat3/core": "16.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/check-ddl.ts

@@ -125,11 +125,13 @@ export function checkClauses(entity: EntityDescriptionLike): readonly string[] {
   );
 }
 
-const addCheck = (table: string, check: CheckDescription): string =>
+/** Exported for `retype-dependents.ts`: a constraint moved out of a retype's way is put back by
+ * the same statement that would have added it, never by a second spelling of `add constraint`. */
+export const addCheck = (table: string, check: CheckDescription): string =>
   `alter table ${identifier(table).text} add constraint ${identifier(check.name).text} ` +
   `check (${check.expression});`;
 
-const dropCheck = (table: string, name: string): string =>
+export const dropCheck = (table: string, name: string): string =>
   `alter table ${identifier(table).text} drop constraint ${identifier(name).text};`;
 
 /**
@@ -161,12 +163,21 @@ const rebuildCheck = (table: string, check: CheckDescription): readonly string[]
  * plain -> generated path). The constraint went with the column and the snapshot still records it,
  * so without this the check would be silently gone — the defect class this file exists against,
  * one level in.
+ *
+ * `predropped` names the CONSTRAINTS this plan already dropped, ahead of a retype whose predicate
+ * they were compiled against (`retype-dependents.ts`). Two arms read it and both are about a name
+ * that is provably free: a declared one takes the bare `add constraint` rather than the
+ * drop-if-exists pair, and a recorded one the entity no longer declares is left alone entirely —
+ * `drop constraint` on it a second time is `42704`, and its `down` belongs to the retype that
+ * moved it. Keyed by name and not by column because an INVARIANT's check reads a column without
+ * being derived from one, which is exactly the constraint `examples/dummy` retypes under.
  */
 export function checkPlan(
   entity: EntityDescriptionLike,
   live: TableDescription,
   plan: { up: string[]; down: string[] },
   rebuilt: ReadonlySet<string> = new Set(),
+  predropped: ReadonlySet<string> = new Set(),
 ): void {
   const recorded = new Map((live.checks ?? []).map((check) => [check.name, check]));
   const present = new Set(live.columns.map((column) => column.name));
@@ -189,10 +200,11 @@ export function checkPlan(
   );
   const wanted = declaredChecks(entity);
   for (const check of wanted) {
-    const held = dropped.has(check.name) ? undefined : recorded.get(check.name);
+    const gone = dropped.has(check.name) || predropped.has(check.name);
+    const held = gone ? undefined : recorded.get(check.name);
     if (held === undefined) {
       plan.up.push(
-        ...(exposed.has(check.name)
+        ...(exposed.has(check.name) && !predropped.has(check.name)
           ? rebuildCheck(entity.table, check)
           : [addCheck(entity.table, check)]),
       );
@@ -205,7 +217,7 @@ export function checkPlan(
   }
   const declared = new Set(wanted.map((check) => check.name));
   for (const check of live.checks ?? []) {
-    if (declared.has(check.name)) continue;
+    if (declared.has(check.name) || predropped.has(check.name)) continue;
     plan.up.push(dropCheck(entity.table, check.name));
     plan.down.push(addCheck(entity.table, check));
   }