@ultimat3/db 13.0.0 → 15.0.0

package/CLAUDE.md

@@ -653,6 +653,208 @@ 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.
+
+**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`, and no snapshot records a view |
+
+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.
+
+**Three things it does not move, and each is measured rather than assumed.** A **foreign key** over
+the retyped column is `ERROR: foreign key constraint "c_k_fkey" cannot be implemented` — the
+dependents are in `live.foreignKeys` *and* in every OTHER table's, which `diffTable` cannot see from
+one entity, and the statements belong to `foreign-key-plan.ts`'s own buckets, so half a fix here
+would collide with it. Neither tracked app can reach it (every key is `uuid` on both sides) and it
+is the next thing to close. A **generated column's** own retype (`regenerate`) does not move
+dependents either: it emits `set expression` and `alter … type` with no `using`, and nothing covers
+a partial index over one. And **what no migration wrote down** is invisible by construction —
+`x db gen` runs with no database open, so a hand-added expression index over the column is still
+`42883` and a VIEW over it is `0A000` whatever this does, since `SchemaDescription` has a field for
+neither.
+
+**`index-ddl.ts` holds `createIndex`, `redefineIndex`, `indexShape`, `dropIndex` 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-ddl.ts` writes the index
+statements in it. `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.
+
+**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
+`examples/dummy`, nine database-expressible rules across six tables, including
+`member_unique_per_org UNIQUE(org_id, user_id)`, which is the constraint `upsertAll`'s inferred
+`on conflict` rests on, and `post_slug_unique`. The `drift` gate step hashes entity SOURCE against a
+sidecar and never reads the SQL, so the squash that lost them would have been **green**.
+
+Four rules, none optional.
+
+| Rule | Why |
+|---|---|
+| a `check` is a named `CONSTRAINT`, a `unique` is a unique **INDEX**, an `assert` is nothing | a soft-deleting entity stamps `deleted_at is null` onto a unique invariant and Postgres has no partial unique CONSTRAINT — only a partial unique index. An `assert` declares itself as a rule only the app can judge (`sql: null`), which is what `hasJsOnlyInvariant` already reads it as, so on its own it is not an unrendered loss — see the next paragraph for the case where it is |
+| a `unique` invariant joins the ONE declared index list (`declaredIndexes`) | `createTable`, `diffTable` and `snapshotOf` must agree about what exists. A `create unique index` emitted and not recorded is `42P07` on the very next `x db gen` — worse than the silent drop |
+| a `check` is recorded on `TableDescription.checks`, **absent** and never `[]` | a sidecar that predates the field must read as "nothing recorded" so the next generation ADDS the constraints the database is genuinely missing. `[]` would mean "declares none" and leave every already-generated app's invariants unenforced forever. That absence is the repair path, and `parseSnapshot` preserves it |
+| the constraint name is `<table>_<name>_<check\|key>`, re-derived, bounded at 63 bytes, and **validated as an identifier** | nothing validates an invariant name at declaration, so `invariant('x" ); drop table t; --', …)` type-checks all the way to `create table` — the identical hole `columnName` carried. `identifier()` is the one rule; `constraintNameUnsafe` (`invariant-errors.ts`) exists only for its `fix:`, which names the `invariant()` call an author edits, and `generate-invariant.test.ts` pins that line because a guard whose value is its message is proven by nothing else |
+
+**An `assert` IS an unrendered loss the moment a migration recorded its CHECK, `As of 2026-08-25`,
+and that is the half `unrenderedOf` could not see.** `checkPlan` drops a recorded check nothing
+declares — "a snapshot may not lie" — and an `assert` declares nothing in SQL, so regenerating
+**deletes the database's half of a rule the entity still states**, with nothing added back and no
+`-- destructive:` marker (`destructive.ts` excludes `drop constraint` by name, on the argument that
+the database rebuilds it; here nothing does). Measured on `examples/dummy`: `x db gen` emitted
+`alter table "posts" drop constraint "post_slug_shape"` and four more, and `unrenderedOf` answered
+`[]` — so `@ultimat3/cli`'s `repairFix`, whose whole job is to refuse `x db gen` as the instruction
+when the generator would lose something, read the empty list and handed out
+`x db gen "drop post_slug_shape"`: the command that performs the loss, offered as the repair for it.
+
+**The discriminator is what the recorded schema holds, never the kind.** An `assert` with nothing
+recorded behind it loses nothing and is reported by nothing — the previous reading was right about
+that, and a marker on nearly every app's every migration marks none. `unrenderedOf(entities,
+current)` therefore takes the recorded schema, **required and nullable**: a caller with no sidecar
+(the first migration) has to say `undefined`, because an argument nobody passes is a blind answer
+nobody notices, which is exactly how the five drops shipped. `namesConstraint` (`invariant-ddl.ts`)
+is the match, under **both** spellings — this generator's `<table>_<name>_check` and the rule's own
+name, which is what a hand-written `0001_init.sql` calls it — and it never throws, because its
+caller is a reporter reached by the `drift` gate step where a throw replaces a finding with a crash.
+Self-clearing: once the drop is applied and the new sidecar written, nothing records the check and
+the next generation reports nothing.
+
+**A COLUMN declares a CHECK too, and until 2026-08-25 it reached `create table` and nothing else.**
+`check-ddl.ts` is what it becomes. `columnClause` wrote `check (…)` **inline and anonymous**,
+`snapshotOf` recorded no check for a column and `diffTable` had no arm for one — so the constraint
+existed only in the statement that created the table and was invisible to every generation after it.
+Neither `drift` nor `unrendered` could see the loss: the gate's `drift` step hashes entity SOURCE
+against a sidecar and never reads the SQL, and `unrenderedOf` keys on declared **invariants**, which
+these are not — they are minted by the column builder (`enumerated()`'s value set,
+`tz()`'s IANA whitelist, `locale()`'s tags, money's currency pattern and scale bound;
+`packages/entity/src/enum-column.ts` implements `enumerated(V)` as `kind: 'text'` plus
+`check: oneOf(V)`). Three consequences, measured on `examples/dummy`: a value added to
+`enumerated()` generated **no migration at all**, so the app accepted `'archived'` and the database
+answered `23514`; a regenerated migration retyped every Postgres-ENUM column to bare `text` with no
+CHECK beside it; and the sidecar claimed a schema the database did not have, so `down` and every
+later diff reasoned off a lie.
+
+Four rules, none optional.
+
+| Rule | Why |
+|---|---|
+| every CHECK is a **named** constraint on ONE list (`declaredChecks` = `columnChecks` then `invariantChecks`) | `createTable`, `diffTable` and `snapshotOf` must agree about what exists, the rule `declaredIndexes` already states. An anonymous constraint is not diffable at all — there is nothing to match a recorded name against |
+| the name is `<table>_<column>_check`, and it is **not a convention chosen here** | it is the name Postgres itself mints for an anonymous single-column CHECK — measured, `check-ddl.live.test.ts`, including for a multi-clause predicate like `scaleCheck`'s. Any other spelling makes the repair add a SECOND constraint beside the one an already-generated database is holding |
+| an ADD onto a column the recorded schema already had is `drop constraint if exists` **then** `add constraint` | the two databases the generator cannot tell apart read identically in the snapshot — one is holding the old anonymous form under exactly this name, one is holding nothing because the old `diffTable` emitted nothing. A bare `add constraint` is `42710` on the first (measured), inside `ROLE=migrate`, with the server's words and none of the entity's. A column this migration ADDS, or one `regenerate` rebuilt, takes the bare add: the name provably cannot be taken |
+| two declarations naming one constraint are **refused**, never deduped | `invariant('status', …)` on a table whose `status` is an `enumerated()` derives the same `posts_status_check` the column owns, and two `add constraint` under one name is `42710` — a migration nobody can apply, which is worse than either declaration being dropped. `X_INVARIANT` through core's `assert`, the refusal `createIndex` already gives a unique GIN. Unlike two identical index definitions there is nothing to dedup: the predicates differ |
+
+**What an app with an existing sidecar sees on its first `x db gen` after this.** One
+`drop constraint if exists` / `add constraint` pair per checked column, on every table it already
+has — the same absent-never-`[]` discipline `checks` was given for invariants, read the other way
+round: the sidecar says nothing, so the generator emits the pair that is correct whether the
+database is holding the constraint or not. Self-clearing — the new sidecar records the check and the
+next generation emits nothing. It is not free: `add constraint … check` takes `ACCESS EXCLUSIVE` and
+scans the table, under `migrate`'s 3s `lock_timeout`. Validating is deliberate over `NOT VALID`,
+which would accept the rows already in the table — and a database holding the identical constraint
+has none that can fail.
+
+**`checkPlan` takes the `rebuilt` set for the same reason `diffTable`'s index loop does.**
+`regenerate`'s plain -> generated path is `drop column` + `add column`, which takes the constraint
+with it while the snapshot still records it — so without the set the check is silently gone, which
+is this file's own defect one level in.
+
+`rebuildCheck` is NOT `destructive.ts`'s concern: `drop constraint` is excluded there by name on
+the argument that the database rebuilds it, and here the very next statement does.
+
+
+**A default's VALUE crosses the seam too.** `ColumnDescriptionLike.default` carries
+`ColumnDefaultLike` and `defaultExpression` renders it; `hasDefault` stays beside it as the older,
+narrower fact `generatedClause` reads. `@ultimat3/entity` projects the value beside the flag
+(`packages/entity/src/describe.ts:175`), so the nine defaults in `examples/dummy` — `plan_code`,
+`billing_currency`, `role`, `tz`, `locale`, `theme`, `digest_opt_in`, `status`, `like_count` — do
+reach the SQL. A description whose producer does not project it still reads `hasDefault` alone, and
+that half **is not silent**: `unrenderedOf` reports each one on `GeneratedMigration.unrendered` and
+`unrenderedComment` writes a `-- UNRENDERED` block at the top of the emitted `up`.
+
+Comments, never a refusal, and never onto an EMPTY diff. A refusal would be a generator no app with
+a `.default('draft')` could run at all until tier 2 ships one line, and a migration nobody can
+generate repairs nothing. The empty-diff exclusion is `@ultimat3/cli`'s
+`generateAppMigration`, which reads `up.trim().length === 0` as "nothing changed": a comment there
+makes every `x db gen` write a file holding no statement — a ledger row, a checksum and a place in
+the apply order for nothing.
+
+**`REPLICA IDENTITY FULL` is still emitted by nothing, and it does not belong here.** Which tables
+need it is derived from the `live: true` queries in the manifest, not from any entity — this package
+is tier 1 and can see neither. An `EntityDescriptionLike.replicaIdentity` field would be a
+declared-and-never-wired key, which is the defect class this release exists to eliminate. The shape
+that works is a `GenerateOptions.replicaIdentityFull: readonly string[]` passed by
+`@ultimat3/cli`'s `db-generate.ts` from the live-query set, and it lands with that caller or not at
+all.
+
 **A column the DATABASE computes is a different thing at every step, and `generated-column.ts` is
 all of them** — `As of 2026-08-24`. `ColumnDescriptionLike.generated` carries the
 `generated always as (<expr>) stored` body across the tier seam (this package cannot import

package/README.md

@@ -36,13 +36,17 @@ 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` |
+| `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 |
 | `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 |
@@ -181,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": "13.0.0",
+  "version": "15.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "13.0.0"
+    "@ultimat3/core": "15.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/check-ddl.ts

@@ -0,0 +1,224 @@
+// Single responsibility: every CHECK constraint a table declares — a COLUMN's own and an
+// INVARIANT's — and which of them a migration adds, rebuilds or drops. Split out of `generate.ts`
+// and `invariant-ddl.ts` because a column check was the one part of a column that reached
+// `create table` and nothing else: `columnClause` wrote `check (…)` inline and ANONYMOUS,
+// `snapshotOf` recorded nothing for it and `diffTable` had no arm for it, so the SECOND `x db gen`
+// turned `enumerated(POST_STATUSES)` into bare `text` accepting any string, and the value set the
+// entity still declares left the database with no statement anywhere saying so.
+//
+// One list, for the reason `declaredIndexes` is one list: `createTable`, `diffTable` and
+// `snapshotOf` must agree about what exists, and two producers of `add constraint` that never met
+// is `42710` on the very next generation — a migration nobody can apply.
+
+import { assert } from '@ultimat3/core';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
+import type { CheckDescription, TableDescription } from './introspect';
+import { invariantChecks, isIdentifier, MAX_IDENTIFIER_BYTES } from './invariant-ddl';
+import { constraintExpressionUnsafe, constraintNameUnsafe } from './invariant-errors';
+import { identifier } from './sql';
+import { statementsOf } from './statement-split';
+
+/**
+ * The convention alone, with nothing validated and nothing refused — one copy, so `columnCheckName`
+ * and `columnNamesConstraint` can never disagree about what a column's CHECK is called. The shape
+ * `spellConstraintName` already has in `invariant-ddl.ts`, and for the same reason.
+ *
+ * **Not a convention chosen here.** It is the name Postgres itself mints for an anonymous
+ * single-column CHECK — measured against a real server in `check-ddl.live.test.ts`, including for a
+ * multi-clause predicate like `scaleCheck`'s, which still names only one column. That is the whole
+ * reason this spelling and no other: every database generated before this landed is holding the old
+ * inline anonymous form under exactly this name, so a repair migration lands ON the constraint it
+ * means to correct instead of beside it under a second name.
+ */
+const spellColumnCheckName = (table: string, column: string): string => `${table}_${column}_check`;
+
+/**
+ * Whether a RECORDED constraint is one of THIS entity's columns' own CHECKs. Validates nothing and
+ * never throws, exactly as `namesConstraint` does not, because its caller is a REPORTER
+ * (`unrendered.ts`) reached by the `drift` gate step where a throw replaces a finding with a crash.
+ *
+ * It exists because the two conventions can land on one string: an entity whose `slug` column is
+ * checked and that also declares `invariant('slug', …)` as an ASSERT derives `posts_slug_check`
+ * twice, and `namesConstraint` matches on the name alone — which it must, since a hand-written
+ * migration names the constraint after the rule. Without this the assert reads as "this run drops
+ * the CHECK recorded for me" while the run declares and keeps it: a `-- UNRENDERED` block on a
+ * migration that lost nothing, which is a marker the next reviewer learns to ignore.
+ */
+export function columnNamesConstraint(entity: EntityDescriptionLike, recorded: string): boolean {
+  return entity.columns.some(
+    (column) =>
+      column.check !== null && recorded === spellColumnCheckName(entity.table, column.column),
+  );
+}
+
+/**
+ * What a column's own CHECK is called, with both operands validated — the reason `constraintNameFor`
+ * validates its own one file over: a physical column name arrives from a projection this package
+ * cannot typecheck, `add constraint` takes no parameters, and a name that closes its own quote
+ * produced a real `drop table` through `generateMigration` once already.
+ */
+export function columnCheckName(table: string, column: string): string {
+  if (!isIdentifier(table) || !isIdentifier(column)) throw constraintNameUnsafe(table, column);
+  const name = spellColumnCheckName(table, column);
+  // Bytes, never characters: 63 is what the server counts, and a truncation it performs silently
+  // makes two constraints one on the server while both names still differ in the snapshot.
+  const bytes = new TextEncoder().encode(name).length;
+  assert(
+    bytes <= MAX_IDENTIFIER_BYTES,
+    `constraint name "${name}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES} and says nothing`,
+    `.column('<shorter>')   # shorten the physical name of "${column}", then x db gen`,
+  );
+  return name;
+}
+
+/**
+ * The CHECK constraints an entity's COLUMNS declare, in column order — `enumerated()`'s closed value
+ * set, `tz()`'s IANA whitelist, `locale()`'s tag list, money's currency pattern and scale bound.
+ *
+ * Read off `ColumnDescriptionLike.check`, which is the one field `@ultimat3/entity` projects them
+ * through; a column carrying `null` declares none and contributes no row.
+ */
+export function columnChecks(entity: EntityDescriptionLike): readonly CheckDescription[] {
+  return entity.columns
+    .filter((column: ColumnDescriptionLike) => column.check !== null)
+    .map((column) => ({
+      name: columnCheckName(entity.table, column.column),
+      expression: column.check ?? '',
+    }));
+}
+
+/**
+ * Every CHECK this table declares. Columns first, then invariants — the order the old generator
+ * emitted them in, so a table declaring only invariants produces the statement it always produced.
+ *
+ * A duplicate name is REFUSED rather than deduped. Two `add constraint` statements under one name
+ * is `42710`, and the two sides mean different things: `invariant('status', …)` on a table whose
+ * `status` column is an `enumerated()` derives the same `posts_status_check` the column already
+ * owns, and silently keeping either one would enforce a rule the entity does not state. Same
+ * argument `declaredIndexes` makes for `42P07`, with the opposite remedy, because unlike two
+ * identical index definitions these two carry different predicates.
+ */
+export function declaredChecks(entity: EntityDescriptionLike): readonly CheckDescription[] {
+  const checks = [...columnChecks(entity), ...invariantChecks(entity)];
+  const seen = new Set<string>();
+  for (const check of checks) {
+    assert(
+      !seen.has(check.name),
+      `two declarations on "${entity.table}" name the constraint "${check.name}"`,
+      `invariant('${entity.table}_${check.name}', …)   # rename the invariant — a column's own CHECK already holds that name, then x db gen`,
+    );
+    seen.add(check.name);
+    // One command, over the merged list: `statementsOf` is this package's one lexer, so a `;`
+    // inside a string literal — `check (tag <> ';')`, and every `oneOf()` value list — is data and
+    // not a split. Applied here rather than per producer so a column's predicate, which arrives
+    // from an app's own `enumerated([...])` array, is guarded by the same rule an invariant's is.
+    const commands = statementsOf(check.expression).length;
+    if (commands > 1) throw constraintExpressionUnsafe(check.name, commands);
+  }
+  return checks;
+}
+
+/** `constraint "n" check (…)` — the clause form, for a table this migration creates. */
+export function checkClauses(entity: EntityDescriptionLike): readonly string[] {
+  return declaredChecks(entity).map(
+    (check) => `constraint ${identifier(check.name).text} check (${check.expression})`,
+  );
+}
+
+/** 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});`;
+
+export const dropCheck = (table: string, name: string): string =>
+  `alter table ${identifier(table).text} drop constraint ${identifier(name).text};`;
+
+/**
+ * The one statement that is correct on BOTH databases this generator cannot tell apart.
+ *
+ * A database generated before column checks were recorded is holding Postgres' own auto-named
+ * `<table>_<column>_check` from the old inline anonymous form; a database whose entity gained the
+ * check after the table was created is holding nothing, because the old `diffTable` emitted nothing.
+ * The snapshot reads identically in both — it records no check either way — so a bare
+ * `add constraint` is `42710` on the first, inside `ROLE=migrate`, with the server's words and none
+ * of the entity's. `drop constraint if exists` costs a notice on the second and repairs the first.
+ */
+const rebuildCheck = (table: string, check: CheckDescription): readonly string[] => [
+  `alter table ${identifier(table).text} drop constraint if exists ${identifier(check.name).text};`,
+  addCheck(table, check),
+];
+
+/**
+ * Which CHECK constraints an existing table gains, loses or has rebuilt. Postgres has no `alter
+ * constraint` for a predicate, so a moved expression is a drop and an add — the same shape
+ * `redefineIndex` uses, and `down` is pushed forwards and read backwards for the same reason.
+ *
+ * Both directions, the rule `foreignKeyPlan` states: a snapshot may not lie. A recorded constraint
+ * the entity no longer declares is DROPPED, and its `down` re-adds it from the expression the
+ * snapshot holds — so unlike a dropped column there is nothing to restore and nothing to refuse.
+ * `destructive.ts` deliberately excludes `drop constraint` for exactly this reason.
+ *
+ * `rebuilt` names the columns this migration dropped and re-added outright (`regenerate`'s
+ * 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));
+  // Checked columns only, in both sets — `columnCheckName` REFUSES a name it cannot spell, and a
+  // column declaring no check contributes no constraint for either set to be consulted about. Over
+  // every column this would refuse to generate a migration that touches none of them.
+  const checked = entity.columns.filter((column) => column.check !== null);
+  // Which names the OLD anonymous form could be holding: a column the recorded schema already had,
+  // whose check it did not record. A column this migration adds cannot have one, and a rebuilt one
+  // lost it with the column, so both take the bare add.
+  const exposed = new Set(
+    checked
+      .filter((column) => present.has(column.column) && !rebuilt.has(column.column))
+      .map((column) => columnCheckName(entity.table, column.column)),
+  );
+  const dropped = new Set(
+    checked
+      .filter((column) => rebuilt.has(column.column))
+      .map((column) => columnCheckName(entity.table, column.column)),
+  );
+  const wanted = declaredChecks(entity);
+  for (const check of wanted) {
+    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) && !predropped.has(check.name)
+          ? rebuildCheck(entity.table, check)
+          : [addCheck(entity.table, check)]),
+      );
+      plan.down.push(dropCheck(entity.table, check.name));
+      continue;
+    }
+    if (held.expression === check.expression) continue;
+    plan.up.push(dropCheck(entity.table, check.name), addCheck(entity.table, check));
+    plan.down.push(addCheck(entity.table, held), dropCheck(entity.table, check.name));
+  }
+  const declared = new Set(wanted.map((check) => check.name));
+  for (const check of live.checks ?? []) {
+    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));
+  }
+}

package/src/column-default.ts

@@ -0,0 +1,80 @@
+// Single responsibility: what a column's DEFAULT is, as SQL. Split out of `generate.ts` because
+// the question has two halves that must be answered together — what a declared default renders as,
+// and what it MEANS when a column claims one this generator cannot write down. That second half
+// had no answer at all until 2026-08-25: `hasDefault` reached the generator with no expression
+// beside it, so nine scalar defaults in the reference app's own schema were dropped in silence and
+// only `now()` and `gen_random_uuid()` survived, because those two are inferable from the kind.
+
+import { assert } from '@ultimat3/core';
+import { literal } from './sql';
+
+/**
+ * Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDefault`. Declared here
+ * rather than in `entity-shape.ts` so `defaultExpression` can name it without an import cycle,
+ * exactly as `IndexMethod` lives in `index-method.ts` and is read from the mirror.
+ *
+ * `uuid-v7` is what `entity()` stamps on a generated uuid key. It renders `gen_random_uuid()` —
+ * a v4 — because that is the only server-side generator Postgres 17 ships and it is what this
+ * generator has always emitted for such a key. The v7 is minted in JS on the write path; the
+ * column default is the fallback for a row nothing in this framework inserted.
+ */
+export type ColumnDefaultLike =
+  | { readonly kind: 'value'; readonly value: string | number | boolean | null }
+  | { readonly kind: 'generated'; readonly by: 'uuid-v7' | 'now' };
+
+/** The parts of a column description this file reads — nothing else. */
+interface DefaultedColumn {
+  readonly column: string;
+  readonly property: string;
+  readonly kind: string;
+  readonly primaryKey: boolean;
+  readonly hasDefault: boolean;
+  readonly default?: ColumnDefaultLike | undefined;
+}
+
+/**
+ * A literal reaches the statement TEXT — `create table` takes no parameters — so a string is
+ * quoted through the one escape this package has (`literal`), and a number this build cannot
+ * write down is refused rather than emitted as `NaN`, which is a syntax error whose first reader
+ * would be `ROLE=migrate`.
+ */
+function literalSql(column: DefaultedColumn, value: string | number | boolean | null): string {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return literal(value).text;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  assert(
+    Number.isFinite(value),
+    `column "${column.column}" declares a default of ${String(value)}, which is not a number Postgres can hold`,
+    `.default(0)   # give "${column.property}" a finite number, or drop the default`,
+  );
+  return String(value);
+}
+
+/**
+ * The `default …` a column clause carries, or `null` for a column that has none this generator can
+ * write. A DECLARED default wins over an inferred one; the two inferences below stay as the
+ * fallback for a description whose producer does not yet project the expression — see
+ * `unrenderedDefault`, which is what stops that fallback from being a silent loss.
+ */
+export function defaultExpression(column: DefaultedColumn): string | null {
+  if (!column.hasDefault) return null;
+  const declared = column.default;
+  if (declared !== undefined) {
+    return declared.kind === 'value'
+      ? literalSql(column, declared.value)
+      : declared.by === 'now'
+        ? 'now()'
+        : 'gen_random_uuid()';
+  }
+  if (column.kind === 'uuid' && column.primaryKey) return 'gen_random_uuid()';
+  if (column.kind === 'timestamptz') return 'now()';
+  return null;
+}
+
+/**
+ * Whether this column claims a default the generated SQL does not carry. Exactly the condition
+ * that lost nine columns' defaults in silence: `hasDefault: true` with nothing to render it from.
+ */
+export function hasUnrenderedDefault(column: DefaultedColumn): boolean {
+  return column.hasDefault && defaultExpression(column) === null;
+}

package/src/destructive.ts

@@ -5,6 +5,7 @@
 
 import { stripSqlNoise } from './sql-noise';
 import { noiseAt } from './sql-scan';
+import { statementExcerpt } from './statement-excerpt';
 import { statementsOf } from './statement-split';
 
 /** The line a migration carries to declare that applying it destroys data. */
@@ -90,20 +91,6 @@ const RULES: readonly (readonly [DestructiveKind, RegExp])[] = [
   ['retype-column', /\balter\s+column\b[\s\S]*?\btype\b/],
 ];
 
-/**
- * One capped line — an error prints this, not a whole script. Only the comments *preceding* the
- * statement come off, the ones `statementsOf` carries in from the file header; the SQL itself stays
- * verbatim, because `stripSqlNoise` blanks quoted identifiers and `drop table ""` names nothing an
- * author can act on. Blanking is for deciding, never for reporting.
- */
-function excerpt(statement: string): string {
-  const line = statement
-    .replace(/^(?:\s*(?:--[^\n]*|\/\*[\s\S]*?\*\/)\s*)+/, '')
-    .replace(/\s+/g, ' ')
-    .trim();
-  return line.length > 120 ? `${line.slice(0, 117)}...` : line;
-}
-
 /**
  * Every destructive statement in `up`, in apply order.
  *
@@ -117,7 +104,7 @@ export function destructiveStatements(up: string): readonly DestructiveStatement
   for (const statement of statementsOf(up)) {
     const bare = stripSqlNoise(statement).toLowerCase();
     const rule = RULES.find(([, pattern]) => pattern.test(bare));
-    if (rule !== undefined) found.push({ kind: rule[0], statement: excerpt(statement) });
+    if (rule !== undefined) found.push({ kind: rule[0], statement: statementExcerpt(statement) });
   }
   return found;
 }