@ultimat3/db 15.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
@@ -685,6 +688,36 @@ is the `add constraint` statement itself, not `x db migrate`: the migration decl
 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:
@@ -702,7 +735,7 @@ shape at a time on 18.4):
 | 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 |
+| 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.
@@ -729,25 +762,151 @@ pushes the restores forwards and is reversed as a whole, so it reads: drop the n
 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`
+**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
@@ -961,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/package.json

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

package/src/dependent-view.ts

@@ -0,0 +1,224 @@
+// Single responsibility: refuse a migration whose `alter column … type` a VIEW is compiled against,
+// before the statement is sent — and name the view, the column and the statement that recreates it.
+//
+// **This is the honest ceiling for views, and the reason it is not in the generator.** `x db gen`
+// runs with no database open; `SchemaDescription` has no field for a view; `introspect()` reads
+// none by construction (`app-relation.ts` excludes every non-table relation); and no `entity()` can
+// declare one. So nothing the generator reads knows a view exists, and a `GenerateOptions.views`
+// with no caller to fill it is the declared-and-never-wired defect this release exists to
+// eliminate. What DOES have a connection is `migrate()`, one statement before the abort — and the
+// catalog answers the question exactly, including for a view no migration in this repo wrote.
+//
+// Measured on 18.4: `alter table "dv_docs" alter column "rank" type text using "rank"::text` under
+// a view selecting that column answers `0A000 cannot alter type of a column used by a view or
+// rule`, with `rule _RETURN on view dv_docs_published depends on column "rank"` in a DETAIL field
+// nothing printed — surfaced as `X_DB_UNAVAILABLE: cannot reach the database`, whose registered
+// `fix:` says to set `DATABASE_URL`.
+//
+// It does not repair anything and does not claim to: the deploy still stops. What it replaces is
+// wrong advice about a healthy database with the two statements that unblock it.
+
+import type { DbClient } from './client';
+import { migrationViewDepends } from './migration-errors';
+import { identifier, join, sql } from './sql';
+import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+import { statementsOf } from './statement-split';
+
+/** One `alter table <table> alter column <column> type …`, as the catalog spells both names. */
+export interface RetypeTarget {
+  readonly table: string;
+  readonly column: string;
+}
+
+/**
+ * One name in a statement. Called a WORD and not the obvious lexer noun deliberately:
+ * `scripts/secret-compare.ts` reads a comparison whose operand is NAMED like a credential, and
+ * that noun is one of the names it reads — a `.text === spelling` under it is indistinguishable
+ * from an auth check to a static rule that has only the name to go on.
+ */
+interface SqlWord {
+  readonly text: string;
+  /** A quoted name is never a keyword — `"type"` is a column called type, not the clause. */
+  readonly quoted: boolean;
+}
+
+/**
+ * The names in one statement, in order, folded the way Postgres folds them: an unquoted identifier
+ * to lower case, a quoted one verbatim. Comments, string literals and dollar-quoted bodies
+ * contribute nothing, through this package's one lexer — `-- alter column` is prose and
+ * `'alter column'` is data.
+ */
+function wordsOf(statement: string): readonly SqlWord[] {
+  const words: SqlWord[] = [];
+  let at = 0;
+  while (at < statement.length) {
+    const noise = noiseAt(statement, at);
+    if (noise !== null) {
+      if (noise.kind === 'identifier') {
+        words.push({ text: statement.slice(at + 1, noise.end - 1), quoted: true });
+      }
+      at = noise.end;
+      continue;
+    }
+    if (!IDENTIFIER_PART.test(statement[at] ?? '')) {
+      at += 1;
+      continue;
+    }
+    let end = at;
+    while (end < statement.length && IDENTIFIER_PART.test(statement[end] ?? '')) end += 1;
+    words.push({ text: statement.slice(at, end).toLowerCase(), quoted: false });
+    at = end;
+  }
+  return words;
+}
+
+const keyword = (word: SqlWord | undefined, spelling: string): boolean =>
+  word !== undefined && !word.quoted && word.text === spelling;
+
+/**
+ * Every column this script retypes. Narrow ON PURPOSE — `alter table <t> … alter [column] <c> type`
+ * and nothing else — because a miss costs exactly what happens today (the server's own `0A000`,
+ * one statement later) while a false positive costs a catalog read and a refusal on a migration
+ * that would have applied. Every retype `generateMigration` emits is this shape; a hand-written
+ * `ALTER TABLE ONLY t …` is not, and is deliberately left to the server.
+ */
+export function retypeTargets(script: string): readonly RetypeTarget[] {
+  const targets: RetypeTarget[] = [];
+  for (const statement of statementsOf(script)) {
+    const words = wordsOf(statement);
+    const table = words[2];
+    if (!keyword(words[0], 'alter') || !keyword(words[1], 'table') || table === undefined) {
+      continue;
+    }
+    for (let index = 3; index < words.length; index += 1) {
+      if (!keyword(words[index], 'alter')) continue;
+      const at = keyword(words[index + 1], 'column') ? index + 2 : index + 1;
+      const column = words[at];
+      if (column === undefined || !keyword(words[at + 1], 'type')) continue;
+      targets.push({ table: table.text, column: column.text });
+    }
+  }
+  return targets;
+}
+
+interface ViewRow {
+  readonly view_name: string;
+  readonly table_name: string;
+  readonly column_name: string;
+  readonly definition: string;
+  /** `v` or `m`. A MATERIALISED view needs different DDL to drop and to recreate. */
+  readonly relkind: string;
+}
+
+/**
+ * `pg_depend` -> `pg_rewrite` is the only edge that records this: a view depends on a column
+ * through its `_RETURN` rule, never through a row in `pg_class` alone. Materialised views are
+ * included (`relkind = 'm'`) because they carry the same rule and fail the same way.
+ *
+ * One round trip for every target, `in` over both name lists, and the exact pairing filtered in
+ * the caller — a per-target query would be a loop of statements inside the migration's own
+ * transaction, and a cross-product read is cheap where a false pair is not.
+ */
+async function dependentViews(
+  client: DbClient,
+  targets: readonly RetypeTarget[],
+): Promise<readonly ViewRow[]> {
+  const tables = join(
+    [...new Set(targets.map((target) => target.table))].map((name) => sql`${name}`),
+  );
+  const columns = join(
+    [...new Set(targets.map((target) => target.column))].map((name) => sql`${name}`),
+  );
+  return client.query<ViewRow>(sql`
+    select distinct v.relname as view_name, c.relname as table_name, a.attname as column_name,
+           pg_get_viewdef(v.oid, true) as definition, v.relkind as relkind
+      from pg_depend d
+      join pg_rewrite r on r.oid = d.objid and d.classid = 'pg_rewrite'::regclass
+      join pg_class v on v.oid = r.ev_class
+      join pg_class c on c.oid = d.refobjid and d.refclassid = 'pg_class'::regclass
+      join pg_attribute a on a.attrelid = c.oid and a.attnum = d.refobjsubid
+     where v.relkind in ('v', 'm') and v.oid <> c.oid
+       and c.relname in (${tables}) and a.attname in (${columns})
+     order by v.relname
+  `);
+}
+
+/**
+ * One SQL statement as a single argv word for `psql -c`.
+ *
+ * SINGLE quotes, unlike `migrationConflict`'s `-c "…"`: `identifier()` writes the view's name in
+ * DOUBLE quotes, so a double-quoted shell word would end at the name. The definition is the
+ * server's own text and may hold a `'` of its own — `where status = 'published'` — so the one
+ * escape a POSIX shell has for it is spelled out here. This is not the SQL literal escape
+ * (`sql.ts`'s `literal()`, the tree's one copy of that); nothing below is sent to a server.
+ */
+const shellArg = (statement: string): string => `'${statement.replaceAll("'", `'\\''`)}'`;
+
+/** The invocation `migrationConflict` already writes, with the statement as its own argv word. */
+const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
+
+/**
+ * The two statements that unblock the deploy, as one line an operator pastes.
+ *
+ * It leads with the command to RUN and carries the follow-up in a `#` comment, the shape
+ * `migrateConcurrent` and `migrationSnapshotMissing` already write. It used to lead with bare DDL
+ * and a `#`: `#` is not a comment in Postgres, so psql read the whole line and failed on it, while
+ * a shell read `drop` as a program that does not exist. Neither reader could run it (axiom 4).
+ *
+ * `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. A refusal that raised `X_SQL_UNSAFE` in place of the finding would hand the
+ * operator an exception where a verdict was asked for, over a view name that is perfectly legal.
+ * The fallback still leads with a command that runs — a psql session — because quoting that name
+ * is the one step this package will not do twice: `identifier()` is its only identifier writer.
+ *
+ * The definition is collapsed to one line because `pg_get_viewdef(oid, true)` pretty-prints across
+ * several and a `fix:` is read as a command.
+ *
+ * `relkind` decides the DDL and is not cosmetic: `dependentViews` deliberately selects `'m'` as
+ * well as `'v'`, and Postgres refuses `drop view` on a materialised one — `WRONG_OBJECT_TYPE`,
+ * "use DROP MATERIALIZED VIEW". So the one case the query went out of its way to include was the
+ * one whose `fix:` could not run. `pg_get_viewdef` answers the SELECT for both kinds, so only the
+ * two keywords differ; a matview's indexes and its `WITH DATA` population are NOT carried, and
+ * the fix says so rather than implying the recreate is complete.
+ */
+function restoreView(view: string, definition: string, relkind: string): string {
+  const body = definition.replace(/\s+/g, ' ').replace(/;\s*$/, '').trim();
+  const materialised = relkind === 'm';
+  const kind = materialised ? 'materialized view' : 'view';
+  const note = materialised
+    ? '   # then re-create its indexes: a matview keeps none of them across a drop'
+    : '';
+  try {
+    const name = identifier(view).text;
+    return (
+      `${psql(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
+      `${psql(`create ${kind} ${name} as ${body}`)}${note}`
+    );
+  } catch {
+    return (
+      `psql "$DATABASE_URL"   # quote the ${kind} name ${JSON.stringify(view)} yourself, then: ` +
+      `drop ${kind} <name>; \\q; x db migrate; and create it again as: create ${kind} <name> as ${body}${note}`
+    );
+  }
+}
+
+/**
+ * Refuse before the ALTER, or return having sent nothing at all. A script that retypes no column
+ * costs one text scan and no round trip, which is every migration an app writes that is not a
+ * retype.
+ */
+export async function refuseDependentViews(client: DbClient, script: string): Promise<void> {
+  const targets = retypeTargets(script);
+  if (targets.length === 0) return;
+  const wanted = new Set(targets.map((target) => `${target.table}.${target.column}`));
+  for (const row of await dependentViews(client, targets)) {
+    if (!wanted.has(`${row.table_name}.${row.column_name}`)) continue;
+    throw migrationViewDepends(
+      row.view_name,
+      row.table_name,
+      row.column_name,
+      restoreView(row.view_name, row.definition, row.relkind),
+    );
+  }
+}

package/src/errors.ts

@@ -11,7 +11,6 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
 
 /**
@@ -31,6 +30,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_MIGRATION_IRREVERSIBLE',
   'X_MIGRATION_DESTRUCTIVE',
   'X_MIGRATION_SNAPSHOT_MISSING',
+  'X_MIGRATION_VIEW_DEPENDS',
   'X_MIGRATE_CONCURRENT',
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
@@ -72,6 +72,7 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_MIGRATION_IRREVERSIBLE: 'this migration cannot be reversed without data loss',
   X_MIGRATION_DESTRUCTIVE: 'this migration destroys data and does not say so',
   X_MIGRATION_SNAPSHOT_MISSING: 'the newest migration records no schema snapshot',
+  X_MIGRATION_VIEW_DEPENDS: 'a view is compiled against a column this migration retypes',
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
 };
@@ -284,26 +285,6 @@ export const serializationExhausted = (attempts: number, sourceError: unknown):
     sourceError,
   });
 
-/**
- * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
- * no timeout, so a migrator wedged on a partition — or OOM-killed with its backend still alive —
- * left `helm upgrade --wait` sitting inside one statement, printing nothing, with the job never
- * failing so `backoffLimit` never fired. A bounded `pg_try_advisory_lock` poll turns that into an
- * exit code.
- */
-export const migrateConcurrent = (lockKey: number, waitedMs: number): DbError =>
-  new DbError({
-    code: 'X_MIGRATE_CONCURRENT',
-    cause:
-      `another session still holds pg_advisory_lock(${lockKey}) after waiting ${waitedMs}ms, ` +
-      'so this migrator refused rather than block a deploy forever',
-    fix:
-      'psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity ' +
-      "join pg_locks using (pid) where locktype = 'advisory'\"" +
-      '   # pg_terminate_backend(pid) the wedged migrator, then: x db migrate',
-    meta: { lockKey, waitedMs },
-  });
-
 /** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
 export const dbDrift = (tableName: string, columnName: string): DbError =>
   new DbError({
@@ -313,85 +294,6 @@ export const dbDrift = (tableName: string, columnName: string): DbError =>
     meta: { table: tableName, column: columnName },
   });
 
-export const migrationConflict = (cause: string, fix: string): DbError =>
-  new DbError({ code: 'X_MIGRATION_CONFLICT', cause, fix });
-
-export const migrationIrreversible = (cause: string, fix: string): DbError =>
-  new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
-
-/**
- * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
- * negative count counts from the END: `steps: -1` selected every applied migration except the
- * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
- * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
- * as a different one is the failure a validated argument exists to prevent.
- */
-export const rollbackStepsInvalid = (received: number): DbError =>
-  new DbError({
-    code: 'X_INVARIANT',
-    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
-    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
-    meta: { steps: received },
-  });
-
-/**
- * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
- * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed
- * rather than rebuilt from a directory this package does not know: `db` is tier 1 and where an app
- * keeps its migrations is `@ultimat3/cli`'s answer, not this one's.
- */
-const snapshotSiblings = (file: string): string => file.replace(/\.snapshot\.json$/, '.*');
-
-/**
- * `20260817120000_add_posts` → `add_posts`, the argument `x db gen` takes. The name is free text
- * and only ever labels a *new* id, so an id carrying no stamp answers with itself rather than with
- * the empty string — a `fix:` ending in `x db gen ""` is a command that cannot be run.
- */
-const migrationNameOf = (id: string): string => id.replace(/^\d+_/, '') || id;
-
-/**
- * The sidecar every generated migration writes is what the *next* generation diffs against, so a
- * newest migration without one leaves nothing to diff. Refused rather than defaulted to the empty
- * schema, which would generate `create table` for every table the database already holds.
- */
-export const migrationSnapshotMissing = (id: string, file: string): DbError =>
-  new DbError({
-    code: 'X_MIGRATION_SNAPSHOT_MISSING',
-    cause: `migration "${id}" records no schema snapshot (${file}), so there is nothing to diff against`,
-    // Two remedies, both commands, in the order they are safe to try. "restore from version
-    // control" alone was neither: on a scaffolded app the sidecar was never written, so there is
-    // nothing to restore — and the drift this refusal answers named `x db gen` as *its* fix, so
-    // the two errors pointed at each other and an app's first migration had no way out.
-    // `x db gen` is named only *after* the files it would trip over are gone.
-    fix:
-      `git checkout -- ${file}   # or, if it was never written: ` +
-      `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`,
-    meta: { id, file },
-  });
-
-/**
- * One error per file, never one per statement: the marker declares the whole migration, so a
- * second finding would repeat an instruction the first already gave. `file` is app-relative and
- * arrives from the caller — `db` is tier 1 and does not know where an app keeps its migrations.
- *
- * Irreversible and destructive are two questions. `X_MIGRATION_IRREVERSIBLE` refuses to *generate*
- * a plan whose `down` cannot restore the rows; this one refuses to *ship* a plan whose `up`
- * destroys them without saying so — a retype is reversible in DDL and still rewrites every row.
- */
-export const migrationDestructive = (
-  file: string,
-  first: DestructiveStatement,
-  more = 0,
-): DbError =>
-  new DbError({
-    code: 'X_MIGRATION_DESTRUCTIVE',
-    cause:
-      `${file} ${DESTRUCTIVE_CAUSE[first.kind]} and does not declare it` +
-      `${more === 0 ? '' : ` (and ${more} more destructive)`}: ${first.statement}`,
-    fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
-    meta: { file, kind: first.kind, statements: more + 1 },
-  });
-
 export const sqlUnsafe = (received: string, position: number): DbError =>
   new DbError({
     code: 'X_SQL_UNSAFE',