@ultimat3/db 13.0.0 → 14.0.0

package/CLAUDE.md

@@ -653,6 +653,113 @@ 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.
 
+**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

@@ -43,6 +43,10 @@ await withTransaction(async (tx) => {
 | `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 |
+| `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "13.0.0",
+  "version": "14.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": "14.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/check-ddl.ts

@@ -0,0 +1,212 @@
+// 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})`,
+  );
+}
+
+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 =>
+  `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.
+ */
+export function checkPlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: { up: string[]; down: string[] },
+  rebuilt: 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 held = dropped.has(check.name) ? undefined : recorded.get(check.name);
+    if (held === undefined) {
+      plan.up.push(
+        ...(exposed.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)) 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;
 }

package/src/drift.ts

@@ -5,7 +5,7 @@
 
 import { baseClient, type DbClient } from './client';
 import { DbError } from './errors';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { foreignKeyTarget, onDeleteRule, rebuildForeignKey } from './foreign-key';
 import { indexMethodOf } from './index-method';
 import {
   type ForeignKeyDescription,
@@ -192,9 +192,7 @@ function changedForeignKey(
       `"${declared.referencedTable}" ` +
       `${rule === null ? 'declares no on delete rule' : `is on delete ${rule}`}, not what ` +
       'migrations declare',
-    fix:
-      `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}` +
-      '   # in a new migration',
+    fix: `${rebuildForeignKey(table, declared, held)}   # in a new migration`,
   };
 }
 

package/src/entity-shape.ts

@@ -2,6 +2,7 @@
 // tier 1 and may never import `entity` (tier 2), so a snapshot arrives as a parameter and every
 // part of it — a column's `on delete` rule included — crosses the seam by shape or not at all.
 
+import type { ColumnDefaultLike } from './column-default';
 import type { IndexMethod } from './index-method';
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
@@ -32,6 +33,45 @@ export interface ColumnDescriptionLike {
    * was a `23502`, because nothing computed it.
    */
   readonly generated?: string | undefined;
+  /**
+   * What the column defaults to, when the declaration carries the value and not only the flag.
+   * Optional for the reason `onDelete` and `generated` are: this package cannot import
+   * `@ultimat3/entity`, so a field that is not on the projection reaches no DDL at all.
+   *
+   * `hasDefault` beside it is NOT redundant and is not being replaced. It is the older, narrower
+   * fact — "this column defaults to something" — and it is what `generatedClause` reads to refuse
+   * a column that is both generated and defaulted. Where `hasDefault` is true and this is absent,
+   * `defaultExpression` falls back to the two defaults inferable from the kind and everything else
+   * is REPORTED as unrendered rather than dropped (`unrendered.ts`).
+   */
+  readonly default?: ColumnDefaultLike | undefined;
+}
+
+/**
+ * Structurally assignment-compatible with `@ultimat3/entity`'s `InvariantDescription`.
+ *
+ * An invariant is written once and enforced twice — in the app on every write, and in Postgres as
+ * a CHECK or a unique index. The second half reached no SQL at all until 2026-08-25, because this
+ * mirror had no `invariants` field: a regenerated migration silently held none of them, including
+ * the composite UNIQUE that `upsertAll`'s `on conflict` is inferred against, so a replay-safe
+ * write became a duplicate row on a database the framework itself generated.
+ */
+export interface InvariantDescriptionLike {
+  /** The rule's own name. `<table>_<name>_check` / `_key` is the constraint it becomes. */
+  readonly name: string;
+  /** `assert` is a rule only the app can run — no SQL, and nothing for a migration to emit. */
+  readonly kind: 'check' | 'unique' | 'assert';
+  readonly message: string;
+  /** The predicate for a `check`, the column list for a `unique`, `null` for an `assert`. */
+  readonly sql: string | null;
+  /** Partial-constraint predicate, e.g. `deleted_at is null`. `null` covers every row. */
+  readonly where: string | null;
+  /**
+   * The physical columns a `unique` names, when the declaration carries them. Optional, and
+   * `uniqueColumns()` falls back to splitting `sql` when it is absent — see the argument in
+   * `invariant-ddl.ts` for why that fallback is a validated re-read and not a name parsed back.
+   */
+  readonly columns?: readonly string[] | undefined;
 }
 
 /**
@@ -66,4 +106,10 @@ export interface EntityDescriptionLike {
   readonly primaryKey: readonly string[];
   readonly columns: readonly ColumnDescriptionLike[];
   readonly indexes: readonly IndexDescriptionLike[];
+  /**
+   * The domain rules the database must hold too. Optional so no existing description changes
+   * shape, exactly as `onDelete`, `generated` and `using` are — and absent reads as "declares
+   * none", which is what every hand-built description in this package's own tests is.
+   */
+  readonly invariants?: readonly InvariantDescriptionLike[] | undefined;
 }

package/src/foreign-key-plan.ts

@@ -5,6 +5,7 @@
 import type { EntityDescriptionLike } from './entity-shape';
 import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
+import { identifier } from './sql';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -137,10 +138,17 @@ export interface ConstraintPlans {
   readonly doomed: ReadonlySet<string>;
 }
 
-/** A key whose target is being dropped: gone on the way up, a note on the way back. */
+/**
+ * A key whose target is being dropped: gone on the way up, a note on the way back.
+ *
+ * The note goes through `identifier` too. A `--` comment ends at the first newline, so a name
+ * holding one is a second command on the line after it — the same escape `columnClause` closed,
+ * one quoting rule short of the statement above it.
+ */
 function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
   preDrops.up.push(dropForeignKey(table, constraint));
   preDrops.down.push(
-    `-- constraint "${constraint}" on "${table}" cannot be restored; "${target}" is gone`,
+    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
+      `cannot be restored; ${identifier(target).text} is gone`,
   );
 }