@ultimat3/cli 13.0.0 → 14.0.0

package/CLAUDE.md

@@ -293,6 +293,45 @@ is a **required** field, so shelling out to GitHub without stating a remedy is a
 than a review comment. A GraphQL response is untrusted input and is parsed against a schema, never
 cast: a `null` where an id was expected would otherwise become a mutation against `undefined`.
 
+## The browser-backed e2e driver lives here, because the adapter has nowhere else to be
+
+`@ultimat3/testing` declares `PageLike` and has never had a driver for it; `@ultimat3/scraping` owns
+the only real browser in the tree and speaks `ScrapePage`. Both are tier 5, so neither may import
+the other, and `testing -> scraping` would be a NEW sideways edge. This package already holds
+declared edges to **both** (`SIDEWAYS_ALLOW`, `scripts/lib/tiers.ts`) and is the one package allowed
+to know about everything — so the join is here, and it is the same rule
+`docs/architecture/01-package-map.md` states for wiring a route table into `pwa`.
+
+| File | Job |
+|---|---|
+| `e2e-driver.ts` | `installE2eDriver({ page, baseUrl })` — the ONE call an app's test preload makes. Registers `page` over its declaration and installs the `e2eTest` seam; returns the undo |
+| `e2e-page.ts` | `PageLike` over four members of `ScrapePage`, declared structurally so a test stands one up in six lines |
+| `e2e-locator.ts` | `LocatorLike` — a handle that resolves nothing until asked, one round trip per question |
+| `e2e-selection.ts` | what a locator SELECTS, as data, and the one in-page expression that resolves it |
+| `e2e-evaluate.ts` | the closure→string crossing, which is the only lossy edge in the adapter |
+| `e2e-errors.ts` | one constructor per refusal |
+| `e2e-dom-fixture.ts` | a document small enough to hold in a test and real enough to RUN the expressions above |
+
+**Absent by default, and that is a requirement rather than a state.** CI has no Chrome. Nothing here
+runs until `installE2eDriver` is called, so `hasE2eDriver()` still answers `false` and the gate's
+`e2e` step still refuses instead of passing over a browser it does not have.
+
+**`evaluate` is the edge that cannot be lossless.** `PageLike.evaluate` takes a closure and every
+browser port in this framework takes a string, so what crosses is `Function.prototype.toString()`
+and nothing else. A zero-parameter closure naming only page globals is supported; a native or bound
+function, a declared parameter and a method shorthand are refused STATICALLY, before a byte leaves;
+a binding the page does not have comes back named, from the page's own `ReferenceError`. Measured on
+Bun 1.4.0 and load-bearing: **Bun's transpiler folds `wanted === 3` to `!0` before `toString()` ever
+runs**, so a captured PRIMITIVE can vanish from the source and never fail at all, while a captured
+reference always survives as its name. No static rule in this process can see the difference — which
+is why the refusal is raised from the page's answer rather than from a scan of the source.
+
+**Three of `E2eFixtures`' four members refuse, deliberately.** `offline()` and `online()` need a CDP
+method for the browser's own network state and `CdpPageLike` declares none; `update()` needs a second
+build served under a new id, which is a fact about the server. A fixture that silently no-opped would
+make the assertion after it read as proof — `offline()` followed by "the fallback rendered" is the
+app's ONLINE page passing an offline test.
+
 ## The `errors` step enforces the error contract
 
 | File | Job |
@@ -534,8 +573,11 @@ regex and `+` is a quantifier — `n1` is what actually selects these tests.
 | `db-branch.ts` | what a branch IS: the closed verb set, the name it takes on disk and in `pg_database`, and list/create/drop per mode |
 | `cmd-db-branch.ts` | `x db branch`'s wiring alone — which verb, which refusal, and the one connection an external clone runs on |
 | `db-finding.ts` | one thrown value → one `Finding`, shared by `cmd-db.ts` and `cmd-db-branch.ts` |
-| `drift.ts` | `checkSourceDrift`: the `.hash` sidecar `x verify`'s `drift` step compares, no database needed |
+| `drift.ts` | `checkSourceDrift`: the `.hash` sidecar the `drift` step compares, no database needed |
+| `schema-diff.ts` | what two GENERATED snapshots disagree about, as data — the pure half |
+| `schema-drift.ts` | `checkMigrationDrift`: entity declarations against the newest `.snapshot.json`, and the composition the `drift` step and `x doctor` both read |
 | `db-destructive.ts` | `checkDestructiveMigrations`: the same step's second half — every committed `up` that drops, truncates or retypes must carry `-- destructive: true` |
+| `db-ungeneratable.ts` | `checkUngeneratableMigrations`: the same step's fourth rail — every committed `up` holding SQL `x db gen` could not have written must say how many, as `-- ungeneratable: <n>` |
 | `db-backfill.ts` | `x db backfill --list`: the flag parsing, the ledger read and the table |
 | `db-seed.ts` | `x db seed`, everything except the argv: `SEED_GLOBS` (where a seed is declared), `discoverSeeds`, `parseSeedTierFlag`, `selectSeeds` (which seeds this invocation runs, and its two refusals — `X_DECLARATION_UNKNOWN` and `X_SEED_ENVIRONMENT`), `runSeeds` (one transaction **per seed**, never one around the run) and the two renderers. The `db-backfill.ts` split repeated: a driver plus plain strings in, plain rows out, so every rule is testable with no `ParsedArgs` and no boot. Which tiers an environment takes is `@ultimat3/entity`'s `seedTiersFor` — two copies of "may this seed run" would be two answers |
 
@@ -643,6 +685,84 @@ file, never one per statement — the marker declares the whole migration. It ri
 than becoming an eighteenth step because it is this step's own question over this step's own files;
 a new step is for a genuinely new question.
 
+**The `drift` step reads the SNAPSHOT, not only the hash, `As of 2026-08-25`.** `checkSourceDrift`
+compares a schema-source hash to a `.hash` sidecar and never reads what the migration RECORDED, so
+`dummy/social-media-clone` sat green while **nine declared CHECK constraints had never reached any
+database** — a comment body could be whitespace, a like count could go negative, an email needed no
+`@` — and a squash that dropped ten invariants and nine defaults would have been green too. The
+source had not moved, so nothing that hashes source could see it. `checkSnapshotDrift`
+(`schema-drift.ts`) diffs `snapshotOf(describeEntities())` against `declaredSchema(readMigrations())`
+— both sides are `snapshotOf`'s own spelling, which is what makes a check, a default and a column
+type comparable at all. Measured against that app rolled back to the state its gate was green in:
+**20 findings**, 9 checks and 11 defaults.
+
+**Two directions, two codes, because they are two repairs.** `X_DB_SCHEMA_UNMIGRATED` is a
+declaration the migrations do not carry — the database will never get it. `X_DB_SCHEMA_UNDECLARED`
+is a migration carrying what nothing declares any more, whose fix names BOTH branches, because the
+declaration may have been lost rather than removed and `x db gen` would emit the DROP. One "drift"
+verdict over both teaches a reader neither.
+
+**Absent is not empty, and reading it as "recorded none" would fail every existing app on its first
+run.** `TableDescription.checks` is absent — never `[]` — on a table declaring none, exactly like
+`IndexDescription.using` and `ColumnDescription.generated`. Both sides normalise to empty
+(`schema-diff.ts`), `using` reads through `indexMethodOf` and `order` through `?? 'asc'`, or an app
+whose sidecar predates any of the three reports a difference on every index it has.
+
+**The hash half stays, and runs second.** It catches what the snapshot comparison cannot see at all
+— a seed, a helper or a TS-only invariant moving under `packages/db/src` with no statement behind
+it, which is what `reconcileSchemaHash` exists to re-record. It is SUPPRESSED when the snapshot half
+found something: both then answer one condition and only one of them is an instruction, since
+`schema hashes to 3f2a, newest migration recorded 91bc` names no constraint, no column and no table.
+
+**An app whose modules will not import is not judged here.** `appEntities` answers `undefined`
+rather than a short registry, which would read as "every table was dropped" and hand out a DROP per
+table for one file's syntax error — the same stance `generateAppMigration` takes with its `blocked`
+outcome. The cost is that a schema check can be silently skipped under an already-red gate; the
+alternative is a false red whose fix destroys data.
+
+**The FOURTH thing the `drift` step asks is what neither hash nor snapshot can see: SQL no
+declaration carries at all.** `ALTER TABLE posts REPLICA IDENTITY FULL;` sits in
+`examples/dummy/packages/db/migrations/0001_init.sql`, no generator emits it, no snapshot records
+it, and a squash drops it in silence — and no declaration-based check can ever see it, because a
+regenerated sidecar equals the declaration by construction. `db-ungeneratable.ts` reports it,
+`As of 2026-08-25`. It classifies nothing itself: `@ultimat3/db`'s `ungeneratableStatements`
+matches each statement's leading verb phrase against `GENERATABLE_FORMS` — everything
+`generateMigration` emits, held honest in both directions by that package's own test — because
+every SQL classifier in the tree is db's (`sql-scan.ts`, `statement-split.ts`, `sql-noise.ts`,
+`destructive.ts`) and a second one here is the reimplementation this file's own rule forbids.
+Measured: **7 statements in `examples/dummy`** (five `CREATE TYPE … AS ENUM`, two
+`REPLICA IDENTITY FULL`), **0 in all four `dummy/social-media-clone` migrations** and 0 in
+`examples/dummy`'s own generated `0002_money_scale.sql` — real generator output reports nothing,
+which is the half a rail like this lives or dies on.
+
+**The declaration is a header line, and it carries a COUNT: `-- ungeneratable: 7`.** Not
+`@ultimat3/db`'s code but this package's (`X_MIGRATION_UNGENERATABLE`), because the only remedy
+available for every statement it reports is a line in the migration file, and where an app keeps
+its migrations is this package's fact — db classifies and deliberately declares no code. Three
+decisions behind that shape:
+
+| Decision | Why |
+|---|---|
+| in the migration file, not a pin table here | the gate runs in every generated app, and a table in `packages/cli/src` can hold no row for an app it has never seen. `-- destructive: true` in the same directory, read by the same reader, is the precedent |
+| a count, not a boolean | the first hand-written statement would otherwise buy the file an unlimited allowance, and statements a reader never sees again are this rail's whole subject. A ratchet in the `README_FENCE_BACKLOG` sense: `found > declared` reports, a declared count that is too high is a pin nobody lowered |
+| the **header** — before the first statement | `hasDestructiveMarker` had to become a lexical scan because a regex over the raw file matched its marker inside a block comment and inside a dollar-quoted body, and `noiseAt` is db's and unexported. A run anchored at index 0 needs no scanner to be exact: before the first statement there is no string, no quoted identifier and no dollar body for a marker to hide in |
+
+**The `fix:` names the marker first and `x db gen` second, and that order is the point.**
+Regenerating is exactly what *discards* these statements, so the command every other db code
+answers with is the one this one must not lead with — `X_MIGRATION_UNGENERATABLE`'s `CLI_FIXES` row
+is `x verify --only drift`, and the re-declare branch (an enum is a text column plus a check
+invariant) rides behind an em-dash because it is available for some of the statements and never
+for `REPLICA IDENTITY FULL`, which nothing in the framework emits.
+
+**`x db gen` reports what it could not write, and exits 0.** `GeneratedMigration.unrendered` reached
+the committed `.sql` as a `-- UNRENDERED` comment and nothing else read it; `db-generate.ts` now
+carries it on every branch (a REQUIRED field, so forgetting to project it is a type error) and
+`cmd-db.ts` prints the count plus each entry's own remedy and carries the list under
+`data.unrendered`. Not a non-zero exit: `x db gen` is the `fix:` on `X_DB_DRIFT` and four other
+shipped errors, and a fix that always exits 1 is not an instruction — the `x i18n add fr` failure,
+repeated. The red belongs at the gate, and the `drift` step reads the SAME list to decide that
+`x db gen` is not the fix it should be handing out.
+
 The *source* half is a different question with a different answer: `checkSourceDrift` hashes the
 entity source against what `x db gen` recorded, answers the same before and after a migration, and
 opens nothing — which is what lets the gate run it in a CI with no database. It stays on `x verify`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "13.0.0",
-    "@ultimat3/admin": "13.0.0",
-    "@ultimat3/ai": "13.0.0",
-    "@ultimat3/auth": "13.0.0",
-    "@ultimat3/cache": "13.0.0",
-    "@ultimat3/core": "13.0.0",
-    "@ultimat3/db": "13.0.0",
-    "@ultimat3/entity": "13.0.0",
-    "@ultimat3/flags": "13.0.0",
-    "@ultimat3/http": "13.0.0",
-    "@ultimat3/i18n": "13.0.0",
-    "@ultimat3/jobs": "13.0.0",
-    "@ultimat3/mail": "13.0.0",
-    "@ultimat3/manifest": "13.0.0",
-    "@ultimat3/mcp": "13.0.0",
-    "@ultimat3/money": "13.0.0",
-    "@ultimat3/notify": "13.0.0",
-    "@ultimat3/policy": "13.0.0",
-    "@ultimat3/pwa": "13.0.0",
-    "@ultimat3/query": "13.0.0",
-    "@ultimat3/realtime": "13.0.0",
-    "@ultimat3/render": "13.0.0",
-    "@ultimat3/schema": "13.0.0",
-    "@ultimat3/scraping": "13.0.0",
-    "@ultimat3/seo": "13.0.0",
-    "@ultimat3/storage": "13.0.0",
-    "@ultimat3/testing": "13.0.0",
-    "@ultimat3/time": "13.0.0",
+    "@ultimat3/action": "14.0.0",
+    "@ultimat3/admin": "14.0.0",
+    "@ultimat3/ai": "14.0.0",
+    "@ultimat3/auth": "14.0.0",
+    "@ultimat3/cache": "14.0.0",
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/db": "14.0.0",
+    "@ultimat3/entity": "14.0.0",
+    "@ultimat3/flags": "14.0.0",
+    "@ultimat3/http": "14.0.0",
+    "@ultimat3/i18n": "14.0.0",
+    "@ultimat3/jobs": "14.0.0",
+    "@ultimat3/mail": "14.0.0",
+    "@ultimat3/manifest": "14.0.0",
+    "@ultimat3/mcp": "14.0.0",
+    "@ultimat3/money": "14.0.0",
+    "@ultimat3/notify": "14.0.0",
+    "@ultimat3/policy": "14.0.0",
+    "@ultimat3/pwa": "14.0.0",
+    "@ultimat3/query": "14.0.0",
+    "@ultimat3/realtime": "14.0.0",
+    "@ultimat3/render": "14.0.0",
+    "@ultimat3/schema": "14.0.0",
+    "@ultimat3/scraping": "14.0.0",
+    "@ultimat3/seo": "14.0.0",
+    "@ultimat3/storage": "14.0.0",
+    "@ultimat3/testing": "14.0.0",
+    "@ultimat3/time": "14.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-db.ts

@@ -21,7 +21,7 @@ import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { BRANCH_SUBCOMMANDS } from './db-branch';
 import { stepFinding } from './db-finding';
-import { generateAppMigration } from './db-generate';
+import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
 import type { SeedPassRow } from './db-seed';
 import {
   discoverSeeds,
@@ -192,6 +192,12 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
       findings: [stepFinding(error, 'X_DB_GEN_FAILED')],
     };
   }
+  // Loud on BOTH branches, and never an exit code. `x db gen` is the `fix:` on `X_DB_DRIFT` and on
+  // four other shipped errors, so a run that exits 1 whenever the description carries a default
+  // this build cannot project would make every one of those instructions unfollowable — the
+  // `x i18n add fr` failure, repeated. The count is the verdict; the gate's own `drift` step is
+  // where a red belongs, and it reads the same list to decide that `x db gen` is not the fix.
+  const lost = unrenderedLines(generated.unrendered);
   const migration = generated.migration;
   if (migration === undefined) {
     return {
@@ -205,12 +211,13 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
           : msg('cli.db.gen.unchanged'),
       findings: generated.findings,
       // `files` is what this command WROTE, so the empty array here was a false claim.
-      lines: generated.files.map((file) => `  ${file}`),
+      lines: [...generated.files.map((file) => `  ${file}`), ...lost],
       data: {
         outcome: generated.outcome,
         migration: null,
         files: [...generated.files],
         schemaHash: generated.schemaHash ?? null,
+        unrendered: unrenderedJson(generated.unrendered),
       },
     };
   }
@@ -218,13 +225,14 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
     ok: true,
     command: 'db',
     summary: msg('cli.db.gen.written', { id: migration.id }),
-    lines: generated.files.map((file) => `  ${file}`),
+    lines: [...generated.files.map((file) => `  ${file}`), ...lost],
     data: {
       outcome: generated.outcome,
       migration: migration.id,
       name: migration.name,
       files: [...generated.files],
       schemaHash: generated.schemaHash ?? null,
+      unrendered: unrenderedJson(generated.unrendered),
     },
   };
 }

package/src/cmd-doctor.ts

@@ -11,12 +11,12 @@ import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
 import { ICON_SOURCE } from './dev-assets';
-import { checkSourceDrift } from './drift';
 import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
+import { checkMigrationDrift } from './schema-drift';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -262,7 +262,7 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
     database: () => probeDatabase(process.env['DATABASE_URL']),
-    drift: async () => (root === undefined ? [] : checkSourceDrift(root)),
+    drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
   };
 }

package/src/db-generate.ts

@@ -4,7 +4,7 @@
 
 // `node:path` — Bun ships no path joiner of its own, and these paths are built, not opened.
 import { join } from 'node:path';
-import type { GeneratedMigration } from '@ultimat3/db';
+import type { GeneratedMigration, UnrenderedDeclaration } from '@ultimat3/db';
 import {
   DESTRUCTIVE_MARKER,
   declaredSchema,
@@ -39,6 +39,14 @@ export interface GeneratedFiles {
   readonly files: readonly string[];
   /** What the source hashes to, whenever this run was in a position to record it. */
   readonly schemaHash?: string | undefined;
+  /**
+   * Every declaration the generator could not write down, on EVERY branch that got as far as
+   * running it — a `.default('draft')` the description carries no expression for is unrendered
+   * whether or not this run had a diff to write. Required, not optional: a caller that forgets to
+   * project it is a type error, which is the only reason the field was silent for as long as it
+   * was.
+   */
+  readonly unrendered: readonly UnrenderedDeclaration[];
   /** Modules that would not load. Non-empty means nothing was generated. */
   readonly findings: readonly Finding[];
 }
@@ -81,7 +89,9 @@ export async function generateAppMigration(
   options: GenerateMigrationOptions,
 ): Promise<GeneratedFiles> {
   const app = await loadApp(root);
-  if (app.findings.length > 0) return { outcome: 'blocked', files: [], findings: app.findings };
+  if (app.findings.length > 0) {
+    return { outcome: 'blocked', files: [], findings: app.findings, unrendered: [] };
+  }
 
   const migrations = await readMigrations(root);
   const current = declaredSchema(migrations);
@@ -115,13 +125,16 @@ export async function generateAppMigration(
     const newest = migrations[migrations.length - 1];
     // No migration to record against, which in this branch means no entity is declared either —
     // a registry against zero migrations is `create table` for all of it, never an empty diff.
-    if (newest === undefined) return { outcome: 'unchanged', files: [], findings: [] };
+    if (newest === undefined) {
+      return { outcome: 'unchanged', files: [], findings: [], unrendered: migration.unrendered };
+    }
     const reconciled = await reconcileSchemaHash(root, newest.id);
     return {
       outcome: reconciled.written ? 'hash-recorded' : 'unchanged',
       schemaHash: reconciled.hash,
       files: reconciled.written ? [`${MIGRATIONS_DIR}/${hashFileName(newest.id)}`] : [],
       findings: [],
+      unrendered: migration.unrendered,
     };
   }
 
@@ -140,5 +153,42 @@ export async function generateAppMigration(
     schemaHash,
     files: [sql, snapshot, hashFileName(migration.id)].map((file) => `${MIGRATIONS_DIR}/${file}`),
     findings: [],
+    unrendered: migration.unrendered,
   };
 }
+
+/**
+ * The loss, on the human path. `-- UNRENDERED` in the emitted SQL is a comment, and a comment in a
+ * file nobody opens is not a verdict — this is what `x db gen` PRINTS, so the count is read the
+ * moment the migration is written rather than at the review that may not happen.
+ *
+ * Empty in, empty out: a header on every run marks none of them, the rule `unrenderedComment` and
+ * `destructive.ts` both already state for their own markers.
+ */
+export function unrenderedLines(entries: readonly UnrenderedDeclaration[]): readonly string[] {
+  if (entries.length === 0) return [];
+  return [
+    `  ${entries.length} declaration${entries.length === 1 ? '' : 's'} reached no SQL — this migration is smaller than the entities declare`,
+    ...entries.flatMap((entry) => [
+      `    ${entry.kind} on "${entry.table}"."${entry.name}": ${entry.cause}`,
+      `      fix: ${entry.fix}`,
+    ]),
+  ];
+}
+
+/**
+ * The same list under `--json`, field for field. Spread into plain objects because `data` is a
+ * `JsonValue` and the payload has to carry the same facts the human lines do — a `--json` reader
+ * that had to parse a rendered sentence back is the drift `renderHuman` exists to prevent.
+ */
+export function unrenderedJson(
+  entries: readonly UnrenderedDeclaration[],
+): readonly Record<string, string>[] {
+  return entries.map((entry) => ({
+    kind: entry.kind,
+    table: entry.table,
+    name: entry.name,
+    cause: entry.cause,
+    fix: entry.fix,
+  }));
+}

package/src/db-ungeneratable.ts

@@ -0,0 +1,108 @@
+// The hand-written-SQL rail at the gate: a committed `up` holding statements `x db gen` could
+// never have written must say how many, or a squash discards them in silence. Files, not the
+// database, so the rail fires in CI. `@ultimat3/db` owns the classifier (`GENERATABLE_FORMS`);
+// this file owns the declaration an app makes about its own migration, and the code for it.
+
+import { UltimateError } from '@ultimat3/core';
+import { ungeneratableStatements } from '@ultimat3/db';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
+import { type Finding, findingFrom } from './output';
+
+/** The header line a migration carries to declare how many hand-written statements it holds. */
+export const ungeneratableMarker = (count: number): string => `-- ungeneratable: ${count}`;
+
+/**
+ * Everything before the first statement: whitespace and comments, and nothing else can be there.
+ *
+ * That restriction is the whole reason the marker is a HEADER line rather than any top-level
+ * comment. `hasDestructiveMarker` had to be rewritten as a lexical scan because a regex over the
+ * raw file matched its marker inside a block comment and inside a dollar-quoted body, where it
+ * declares nothing — and `noiseAt`, the scanner that answers that, is `@ultimat3/db`'s and is not
+ * exported. A run anchored at index 0 needs no scanner to be exact: before the first statement
+ * there is no string, no quoted identifier and no dollar body for a marker to hide in.
+ *
+ * A nested block comment (`/* /* *\/ *\/`, which Postgres allows) ends the run early, so a marker
+ * below one is not seen and the migration reports. Fail-closed, which is the safe direction: the
+ * repair is moving the line up, never a finding nobody can see.
+ */
+const HEADER = /^(?:\s*(?:--[^\n]*|\/\*[\s\S]*?\*\/))*/;
+
+/** Anchored to the whole line, so `-- ungeneratable: 2 was wrong` declares nothing. */
+const MARKER_LINE = /^[ \t]*--[ \t]*ungeneratable:[ \t]*(\d+)[ \t]*\r?$/im;
+
+/**
+ * How many hand-written statements this `up` admits to. Absent is `0` — a migration that says
+ * nothing has declared nothing, which is what makes the rule apply to every app that never heard
+ * of it.
+ *
+ * The FIRST marker wins where a file carries two. Taking the largest would let a stale line raise
+ * the allowance of the file it sits in, and the direction that fires is `found > declared`.
+ */
+export function declaredUngeneratable(up: string): number {
+  const header = HEADER.exec(up)?.[0] ?? '';
+  // Block comments come out first: everything left in the run is then whitespace or a line
+  // comment, and a marker inside `/* … */` is prose about a marker rather than one.
+  const lines = header.replace(/\/\*[\s\S]*?\*\//g, ' ');
+  const declared = MARKER_LINE.exec(lines)?.[1];
+  return declared === undefined ? 0 : Number.parseInt(declared, 10);
+}
+
+/**
+ * A migration holding SQL no declaration carries and no snapshot records.
+ *
+ * One error per file, never one per statement: the header line declares the whole migration, so a
+ * second finding would repeat the instruction the first already gave — `migrationDestructive`'s
+ * rule, for the same reason.
+ *
+ * Two remedies, and the order is deliberate. The marker is always available and always correct:
+ * the statement stays, and the next author to squash these migrations is told by the file itself
+ * that regenerating it loses something. Re-declaring is available only for the statements an
+ * entity can express — an enum is a text column plus a check invariant, which `x db gen` writes —
+ * and never for `REPLICA IDENTITY FULL`, which nothing in the framework emits, so a `fix:` naming
+ * only the second branch would be an instruction half its readers cannot carry out.
+ */
+export class MigrationUngeneratableError extends UltimateError {
+  constructor(input: { file: string; declared: number; statements: readonly string[] }) {
+    const found = input.statements.length;
+    // The count is stated once. `migrationDestructive` says "(and 3 more)" because its subject is
+    // one statement plus an unstated remainder; here the number IS the declaration being asked for,
+    // so repeating it as a remainder would print the same fact twice in one line.
+    const first = `${found === 1 ? '' : `, the first of ${found}`}: ${input.statements[0] ?? ''}`;
+    super({
+      code: 'X_MIGRATION_UNGENERATABLE',
+      cause:
+        `${input.file} holds ${found} statement${found === 1 ? '' : 's'} x db gen could not have ` +
+        `written and declares ${input.declared}${first}`,
+      fix:
+        `add the header line "${ungeneratableMarker(found)}" to ${input.file}, so a squash carries ` +
+        'these statements by hand — or re-declare what an entity can express (an enum is a text ' +
+        'column plus a check invariant) and regenerate: x db gen "<name>"',
+    });
+  }
+}
+
+/**
+ * Every committed migration whose `up` holds more hand-written statements than its header admits.
+ *
+ * `readMigrations` is the reader `x db migrate` applies from, and only its `up` half is judged —
+ * a rail checking a list the migrator does not run, or SQL the migrator never sends, enforces
+ * nothing. An app with no migrations directory has nothing to declare and reports nothing.
+ *
+ * A declared count HIGHER than what is there is not a finding: the ratchet only refuses a rise,
+ * exactly as `README_FENCE_BACKLOG` and `TEST_TYPECHECK_PINS` do, and a count that fell is a pin
+ * nobody lowered rather than SQL nobody can see.
+ */
+export async function checkUngeneratableMigrations(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for (const migration of await readMigrations(root)) {
+    const statements = ungeneratableStatements(migration.up);
+    const declared = declaredUngeneratable(migration.up);
+    if (statements.length <= declared) continue;
+    const file = `${MIGRATIONS_DIR}/${migration.id}.sql`;
+    findings.push({
+      ...findingFrom(new MigrationUngeneratableError({ file, declared, statements })),
+      at: file,
+    });
+  }
+  return findings;
+}

package/src/e2e-dom-fixture.ts

@@ -0,0 +1,117 @@
+// A document small enough to hold in a test and real enough to RUN the driver's own in-page
+// expressions. Without it every claim about `getByRole` and `getByText` would be an assertion
+// about a string, and a string that never executes cannot be wrong about a page.
+//
+// Its own file, the pattern `dev-roles-fixture.ts` and `policy-fixture.ts` already set here.
+
+/** One element. `attrs` is data, so every read of it goes through `Object.hasOwn` below. */
+export interface FakeE2eElement {
+  readonly tag: string;
+  readonly attrs: Readonly<Record<string, string>>;
+  readonly text?: string;
+  readonly children?: readonly FakeE2eElement[];
+  /** What `getComputedStyle` answers. Absent is the browser's own default — visible. */
+  readonly style?: { display?: string; visibility?: string; opacity?: string };
+}
+
+interface Node {
+  tagName: string;
+  textContent: string;
+  readonly attributes: Record<string, string>;
+  readonly descendants: Node[];
+  readonly style: { display: string; visibility: string; opacity: string };
+  getAttribute(name: string): string | null;
+  setAttribute(name: string, value: string): void;
+  removeAttribute(name: string): void;
+  contains(other: Node): boolean;
+}
+
+const textOf = (element: FakeE2eElement): string =>
+  [element.text ?? '', ...(element.children ?? []).map(textOf)]
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+function build(element: FakeE2eElement): Node {
+  const attributes: Record<string, string> = { ...element.attrs };
+  const children = (element.children ?? []).map(build);
+  const descendants = children.flatMap((child) => [child, ...child.descendants]);
+  const node: Node = {
+    tagName: element.tag.toUpperCase(),
+    textContent: textOf(element),
+    attributes,
+    descendants,
+    style: {
+      display: element.style?.display ?? 'block',
+      visibility: element.style?.visibility ?? 'visible',
+      opacity: element.style?.opacity ?? '1',
+    },
+    getAttribute: (name) => (Object.hasOwn(attributes, name) ? (attributes[name] as string) : null),
+    setAttribute: (name, value) => {
+      attributes[name] = value;
+    },
+    removeAttribute: (name) => {
+      delete attributes[name];
+    },
+    contains: (other) => descendants.includes(other),
+  };
+  return node;
+}
+
+/** `tag`, `*`, `[attr]`, `[attr="value"]` and any combination — every shape this driver emits. */
+const SIMPLE = /^([a-zA-Z0-9*]*)((?:\[[^\]]*\])*)$/;
+
+function matchesSimple(node: Node, selector: string): boolean {
+  const parsed = SIMPLE.exec(selector.trim());
+  if (parsed === null) return false;
+  const tag = parsed[1] ?? '';
+  if (tag !== '' && tag !== '*' && tag.toUpperCase() !== node.tagName) return false;
+  for (const clause of (parsed[2] ?? '').matchAll(/\[([^\]=]+)(?:=("[^"]*"|[^\]]*))?\]/g)) {
+    const name = (clause[1] ?? '').trim();
+    const held = node.getAttribute(name);
+    if (held === null) return false;
+    const raw = clause[2];
+    if (raw !== undefined && held !== raw.replace(/^"|"$/g, '')) return false;
+  }
+  return true;
+}
+
+const matches = (node: Node, selector: string): boolean =>
+  selector.split(',').some((part) => part.trim() !== '' && matchesSimple(node, part));
+
+/**
+ * The globals a driver expression names, bound to one tree. `getComputedStyle` and `document` are
+ * handed in as arguments rather than assigned to `globalThis`: a test that installed a fake
+ * `document` on the process would leak it into every later file in the run.
+ */
+export function fakeE2eDocument(root: FakeE2eElement): Readonly<Record<string, unknown>> {
+  const rootNode = build(root);
+  const all = [rootNode, ...rootNode.descendants];
+  return {
+    document: {
+      querySelectorAll: (selector: string): Node[] => all.filter((node) => matches(node, selector)),
+      querySelector: (selector: string): Node | null =>
+        all.find((node) => matches(node, selector)) ?? null,
+      getElementById: (id: string): Node | null =>
+        all.find((node) => node.getAttribute('id') === id) ?? null,
+    },
+    getComputedStyle: (node: Node) => node.style,
+  };
+}
+
+/**
+ * Run an expression the driver built, in THIS process, against a stubbed global scope.
+ *
+ * `new Function` and not `eval`: the body evaluates with no access to this module's scope, so a
+ * name the expression does not receive as a parameter is genuinely free — which is exactly the
+ * `ReferenceError` a captured closure produces in a real browser, and the thing the evaluate
+ * wrapper has to be proved against.
+ */
+export async function runInFakePage(
+  expression: string,
+  globals: Readonly<Record<string, unknown>> = {},
+): Promise<unknown> {
+  const names = Object.keys(globals);
+  const body = new Function(...names, `return (${expression});`) as (...args: unknown[]) => unknown;
+  return await body(...names.map((name) => globals[name]));
+}