@ultimat3/cli 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -8,6 +8,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
 | Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |
+| Test execution | `test-shards.ts`'s `testArgs` — ONE `bun test --parallel=N`, never N processes this repo packs itself. It did pack them, largest-first greedy over file SIZE, and the packer was deleted for buying **nothing**: four interleaved runs each on the 1296-file unit corpus gave 58.2/60.0/65.0/66.5s hand-packed against 54.5/57.8/61.7/64.5s under `--parallel=8`, within noise, because both are work-bound — 436.7s of file time is a 54.6s floor on 8 workers and the slowest single file is 20.5s. A greedy pack of 1296 small items lands near-optimal by accident. `--timings` is refused on the same evidence (#342). `--parallel` implies `--isolate`, so the per-file module registry is unchanged, and the per-worker database is too: `@ultimat3/testing`'s `workerId` already read `BUN_TEST_WORKER_ID`, which Bun sets 1..N. `ULTIMATE_TEST_WORKER` is set only for a single-shard `x test --worker I` rerun, which is one process |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
@@ -273,11 +274,28 @@ image of the wrong thing.
 `page.pageErrors()` are bounded rings over the whole SESSION, so a shared one files state A's
 console errors under state B — and per-state attribution is the half of the artifact that gates.
 
-**The picture is the VIEWPORT, not a crop.** `@ultimat3/scraping`'s `CaptureRequest` is `fullPage`
-alone, so there is no clip rectangle to ask for; the framing knob is the state's own `viewport`,
-passed to `launch()` as `defaultViewport` through `LocalBrowserOptions.options`. That is why there
-is one browser per declared viewport, memoised. The verdict names it as a blind spot rather than
-implying a crop it did not perform.
+**The picture is the CROP TARGET, `As of 2026-08-26`** — the readiness probe's own box, which is
+the selector the manifest declared or the island's host element. Measured on `examples/dummy`
+before it: 720x560 for a component whose box the verdict reported, in the same run, as 688x104.
+`CaptureClip` had been on the port since #336 and `island-shot.ts` passed none, and this paragraph
+said the port "takes no clip rectangle" — so did the verdict's own `blind` list, which is a blind
+spot naming a capability the tool has, the same lie as one hiding a gap. The state's `viewport` is
+still what the page is LAID OUT in, so there is still one browser per declared viewport, memoised;
+it is no longer what the picture is.
+
+**The clip is translated, not copied.** `getBoundingClientRect()` answers VIEWPORT coordinates and
+a capture clip is in PAGE coordinates; they agree only at the origin, which is the one case a
+harness happens to be in and is a rule nothing enforces. So the probe returns `scroll` beside `box`
+and `clipFor` adds them — a component below the fold would otherwise crop a band it is not in, with
+a picture that looks like a picture and nothing anywhere to report it. `box` keeps meaning the DOM's
+own answer, because that is what the verdict publishes.
+
+**Both themes are photographed by emulating the PREFERENCE.** `page.colorScheme(target.theme)`
+before the navigation, so the first paint already has it. The harness's `data-theme` attribute stays
+— it is right for a component that READS a theme it does not own — but it is the OUTCOME of a theme
+decision, and a component that resolves `'system'` itself deletes it on mount: `x shot --island`
+reported four pictures and wrote two, byte-identical, same md5 (#338). Re-setting the attribute
+after readiness is not the repair; it photographs a state the component would never reach.
 
 **`loadApp` does not import a states file**, for the reason it does not import an island: it
 registers no primitive, and importing it would put `@ultimat3/testing` in the server module graph of
@@ -573,6 +591,8 @@ 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` |
+| `db-accept-created.ts` | `acceptCreatedTables`: the post-migrate report minus the tables the applied migrations' own SQL creates — the half `@ultimat3/db`'s `unexpectedTable` names |
+| `db-subscribes.ts` | `replicaIdentityTables`: the tables `x db gen` grants `REPLICA IDENTITY FULL`, read off each live query's declared `subscribes:` — and `X_QUERY_SUBSCRIBES_UNKNOWN` for a name no entity's table matches |
 | `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 |
@@ -674,6 +694,47 @@ is only the channel each has. `ROLE=migrate` logged and exited 0 until it did no
 whose only signal is the exit code reported success over a schema nobody can reconstruct, which is
 the failure the post-migrate check exists to catch.
 
+**`x db gen` emits `REPLICA IDENTITY FULL`, and the set is DECLARED rather than derived**,
+`As of 2026-08-26` (#357). `@ultimat3/realtime` refuses a live subscription to a table without it —
+logical replication carries no old row on an UPDATE, so no patch can be computed — and for two
+years nothing in the framework emitted one. It could not be derived, and that is the load-bearing
+fact: the relation name lives inside the query's `sql:` callback, which no generator can invoke
+without valid input (`describeSql` says so itself — "`null` when no sample input was supplied").
+So a live query DECLARES it (`subscribes:`, `@ultimat3/query`), the declaration is machine-checked
+against the resolved `shape.entity` on the first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`), and
+`db-subscribes.ts` reads it off `describeQueries()` — the same source `frameworkSources` copies onto
+`QueryFact.subscribes`, one hop earlier, because building the manifest here would re-load the app
+and demand a `package.json` that `x db gen` has never needed.
+
+**The third `subscribes:` refusal is this package's, because no other tier can ask it.**
+`@ultimat3/db` keeps only the declared names an entity's table matches and DROPS the rest — it has
+no way to tell a typo from a table another migration owns — and `@ultimat3/query` holds no table
+catalog at all. So `subscribes: ['posts', 'user']` granted the identity to `posts`, dropped `user`
+in silence, and read as granted. `X_QUERY_SUBSCRIBES_UNKNOWN` refuses it BEFORE anything is
+written, naming the query and offering the tables the app does declare. It is checked after
+`loadApp`'s findings, never before: a module that would not import leaves the registry short, and
+every name whose entity lives in it would then look like a typo.
+
+**And it accepts a table the migrations it just applied demonstrably created**, `As of 2026-08-26`
+(issue #345). A snapshot records only what ENTITIES declare, so a table created by a HAND-WRITTEN
+migration reached no sidecar and was `unexpected-table` on every deploy forever — with a `fix:`
+that generated an empty migration, because `x db gen` diffs the entity registry against the newest
+snapshot and the table is on neither side. `@ultimat3/db` fixed the wording; `acceptCreatedTables`
+(`db-accept-created.ts`) is the half that file's `unexpectedTable` names, and it is composed around
+`checkDrift` inside `runMigrations`, so `x db migrate` and `ROLE=migrate` accept the same set.
+**Only `unexpected-table`, and only for a name a migration's SQL creates** — which is what keeps it
+an acceptance rather than the check switched off: a table absent from the snapshot produces exactly
+one difference (`diffSchema` reports it and never compares its columns), and a table nobody
+declared and no migration created is still reported, cause and `fix:` intact. The evidence is the
+applied list itself: `migrate()` runs first, so every file on disk has been applied by the time the
+question is asked. The verb phrase is read ANCHORED off the raw statement, which is the whole
+protection — a `create table` can only be at position 0 by being one, so `values ('create table
+ghost')` opens with `insert` and a comment-only chunk is not a statement at all. A `stripSqlNoise`
+pass was written first and deleted: it could not change one answer, and a defence that cannot fail
+is one nobody can test. Everything the anchor admits and the name grammar does not — a comment
+between the keywords, a `temp` table, a qualifier naming a schema `checkDrift` never introspected —
+contributes nothing, which reports drift that could have been accepted and never the reverse.
+
 **The `drift` step asks a third thing, off the same directory and with no database either: is every
 destructive statement declared?** `db-destructive.ts` reads each committed migration through
 `migrations.ts` — the reader `x db migrate` applies from, because a rail checking a list the
@@ -751,8 +812,15 @@ decisions behind that shape:
 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.
+invariant) rides behind an em-dash because it is available for some of the statements and not all.
+**`REPLICA IDENTITY FULL` was the statement with no second branch, and stopped being one on
+2026-08-26** (#357): a live query declares the relations it is patched from (`subscribes:`),
+`db-subscribes.ts` reads them off the same registry the manifest is projected from, `x db gen`
+emits the ALTER and `@ultimat3/db` records it on the snapshot so it is emitted once. The re-declare
+branch covers it now: declare `subscribes:` and regenerate. A statement already committed is a
+different question and still counts — `GENERATABLE_FORMS` (`@ultimat3/db`) matches a leading verb
+phrase and does not carry this one, measured at 7 found / 7 declared on `examples/dummy`'s
+`0001_init.sql`, `As of 2026-08-26` — so the marker branch remains the only remedy for SQL on disk.
 
 **`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
@@ -813,6 +881,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-runtime.ts` | start the rest on top of it and install the remaining accessors (storage, mail, transport) |
 | `dev-cache.ts` | which cache tiers this process reads through, and the cross-instance invalidation hop |
 | `dev-purge.ts` | the hourly retention sweep: which framework tables this boot owns, the `purge()` job over them and the `task` that fires it |
+| `dev-notify-retention.ts` | `notify.inboxReadRetentionMs` / `inboxUnreadRetentionMs` off the app's own `app.config.ts` — the sibling of `loadSignInPath` and `loadCacheTiers`, because `startServices` holds no `AppConfig` |
 | `dev-sync.ts` | the `sync` role: its live-query registry, who is dialling it, and the socket it owns |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through |
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
@@ -824,6 +893,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
 | `dev-hooks.ts` | the pipeline's `authorize` seam, decided from the app's own `Policy` objects |
 | `dev-replica.ts` | which boot gets a standby, and the one middleware frame that opens the read scope |
+| `dev-replicator.ts` | the `replicator` role: the feed selected, locked and pumped — and `replicatedRelations()`, the entity TABLES it filters on |
 | `dev-roles.ts` | `--role` selection plus start/stop for `web`, `sync`, `worker`, `scheduler` |
 | `dev-dashboard.ts` | the `DevSources` hooks only this process can answer, and the two CLI panels |
 | `dev-traces.ts` | core's spans → the `/_x` timeline's request traces |
@@ -912,6 +982,19 @@ The per-TENANT subscription cap is deliberately unset, and **both halves of it a
 nothing — and no default is defensible when one tenant is a person and the next is five thousand
 seats. The per-socket 128 stands because a socket is one browser tab.
 
+**The change feed is filtered by TABLE, never by entity name**, `As of 2026-08-26`.
+`replicatedRelations()` (`dev-replicator.ts`) is the one projection, and both of its readers are
+catalog readers: `PgReplicationStream` keeps a change only when `#entities.has(relation.name)` and a
+pgoutput Relation message names the table, while `warnPartialIdentity` matches the same list against
+`pg_class.relname`. An entity NAME is the framework's own registry key — a cache tag, a policy and
+`x entities describe` are all keyed by it — and `entity('user', { table: 'users' })` makes the two
+different strings. It passed `.name`, so a renamed table matched on neither side: **every change
+skipped** and a replica-identity warning that could never fire, with no error anywhere. Invisible to
+every fixture in the tree, because `table` defaults to the name verbatim and all six entities in
+`examples/dummy` have `name === table` — `dev-replicator.test.ts` uses `billingAccount` on
+`billing_accounts` for exactly that reason, and proves the value through the real call chain:
+`assertIdentifier` refuses `billingAccount` before any connection and accepts `billing_accounts`.
+
 `trustProxy` is read from `TRUSTED_PROXY_HOPS` in `startWeb`, the way `PORT` and `ROLE` are read: it
 is a fact about the deployment, not an app config choice, and one image runs behind an ingress in
 one cluster and behind nothing on a laptop. Without it `ctx.ip` is the ingress's socket address on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "16.0.0",
+  "version": "18.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "16.0.0",
-    "@ultimat3/admin": "16.0.0",
-    "@ultimat3/ai": "16.0.0",
-    "@ultimat3/auth": "16.0.0",
-    "@ultimat3/cache": "16.0.0",
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/db": "16.0.0",
-    "@ultimat3/entity": "16.0.0",
-    "@ultimat3/flags": "16.0.0",
-    "@ultimat3/http": "16.0.0",
-    "@ultimat3/i18n": "16.0.0",
-    "@ultimat3/jobs": "16.0.0",
-    "@ultimat3/mail": "16.0.0",
-    "@ultimat3/manifest": "16.0.0",
-    "@ultimat3/mcp": "16.0.0",
-    "@ultimat3/money": "16.0.0",
-    "@ultimat3/notify": "16.0.0",
-    "@ultimat3/policy": "16.0.0",
-    "@ultimat3/pwa": "16.0.0",
-    "@ultimat3/query": "16.0.0",
-    "@ultimat3/realtime": "16.0.0",
-    "@ultimat3/render": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/scraping": "16.0.0",
-    "@ultimat3/seo": "16.0.0",
-    "@ultimat3/storage": "16.0.0",
-    "@ultimat3/testing": "16.0.0",
-    "@ultimat3/time": "16.0.0",
+    "@ultimat3/action": "18.0.0",
+    "@ultimat3/admin": "18.0.0",
+    "@ultimat3/ai": "18.0.0",
+    "@ultimat3/auth": "18.0.0",
+    "@ultimat3/cache": "18.0.0",
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/db": "18.0.0",
+    "@ultimat3/entity": "18.0.0",
+    "@ultimat3/flags": "18.0.0",
+    "@ultimat3/http": "18.0.0",
+    "@ultimat3/i18n": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/mail": "18.0.0",
+    "@ultimat3/manifest": "18.0.0",
+    "@ultimat3/mcp": "18.0.0",
+    "@ultimat3/money": "18.0.0",
+    "@ultimat3/notify": "18.0.0",
+    "@ultimat3/policy": "18.0.0",
+    "@ultimat3/pwa": "18.0.0",
+    "@ultimat3/query": "18.0.0",
+    "@ultimat3/realtime": "18.0.0",
+    "@ultimat3/render": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/scraping": "18.0.0",
+    "@ultimat3/seo": "18.0.0",
+    "@ultimat3/storage": "18.0.0",
+    "@ultimat3/testing": "18.0.0",
+    "@ultimat3/time": "18.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-root.ts

@@ -7,7 +7,19 @@ import { BunVersionError, NotInAppError } from './errors';
 
 export const APP_CONFIG_FILE = 'app.config.ts';
 export const MANIFEST_FILE = 'x.manifest.json';
-export const REQUIRED_BUN = '1.3.0';
+/**
+ * The floor the shipped `x` enforces, and it must not sit below what `x` EMITS. It said `1.3.0`
+ * through 2026-08-27 while `x test` spent `bun test --isolate` — a flag Bun introduced in
+ * **1.3.13** — so a user on a Bun this file declared supported got an unknown-flag failure out of
+ * the gate's dominant step, with `x doctor` reporting the runtime as fine. `--parallel` arrived in
+ * the same release and is emitted now.
+ *
+ * `1.4.0` rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI pins
+ * `1.4.x`, both images build on `oven/bun:1.4-*`, and the per-worker database rests on
+ * `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4.0 and on nothing older. `scripts/bun-pin.test.ts`
+ * holds this to the same series as every other pin.
+ */
+export const REQUIRED_BUN = '1.4.0';
 
 export interface AppRoot {
   readonly dir: string;

package/src/cmd-dev.ts

@@ -46,6 +46,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
+import { loadPwaArtifacts } from './pwa-artifacts';
 import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
@@ -171,6 +172,11 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
+  // Resolved once, before the first route: the manifest's bytes and the three head elements that
+  // name it. `undefined` for an app that is not installable, and then nothing is mounted and no
+  // document changes — the 0kb baseline is not spent on a `<link>` to a file that does not exist.
+  const pwa = await loadPwaArtifacts(options.root);
+
   const routes: readonly Route[] = [
     ...devDashboardRoutes(dashboard),
     // The same API table the container serves: a read that answers here and 404s in production
@@ -179,7 +185,11 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
     // variants every `srcset` promises. Mounted before the app's own routes so a page route can
     // never shadow `/icons` or `/media`.
-    ...assetRoutes({ root: options.root, storage: runtime.storage }),
+    ...assetRoutes({
+      root: options.root,
+      storage: runtime.storage,
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
     ...storageRoutes({ storage: runtime.storage }),
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
@@ -193,7 +203,11 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
       islands: () => state.islands,
       states: () => loadIslandStates(options.root),
     }),
-    ...appRoutes({ buildId, resolveIsland: (file) => state.islands.resolverFor(file) }),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => state.islands.resolverFor(file),
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+    }),
   ];
 
   const replicaOverride = replicaOverrides(undefined, services.db, options.env);

package/src/cmd-doctor.ts

@@ -10,8 +10,8 @@ import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/stor
 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 { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
+import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';

package/src/cmd-test.ts

@@ -20,7 +20,7 @@ import { discoverTests, missingSelection, readSample, readType, sampleFiles } fr
 import { runShards } from './test-shards';
 import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
-import { TEST_TYPES } from './verify-tests';
+import { SERIAL_TYPES, TEST_TYPES } from './verify-tests';
 
 /**
  * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
@@ -33,10 +33,10 @@ const readIndex = (args: ParsedArgs, name: string, min: number): number | undefi
     command: 'test',
     min,
     // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
-    // accepted, `planShards` clamps only to the file count, and `runParallel` `Promise.all`s them —
-    // one Bun process per test FILE, each with the framework module graph and a cloned database.
-    // `--worker` is an index into that split, so the same bound holds it (the exact upper index is
-    // `workers - 1`, refused a line below by the check that knows the real width).
+    // accepted and the run clamps only to the file count, which is one Bun worker per test FILE,
+    // each with the framework module graph and a cloned database. `--worker` is an index into an
+    // N-way split, so the same bound holds it (the exact upper index is `workers - 1`, refused a
+    // line below by the check that knows the real width).
     max: WORKER_CEILING,
     example: `x test --${name} ${Math.max(min, 1)}`,
   });
@@ -103,19 +103,20 @@ export const testCommand: CliCommand = {
   spec: {
     name: 'test',
     summary:
-      'run one test type — or the whole suite — across N processes, one isolated database per worker',
+      'run one test type — or the whole suite — across N workers, one isolated database per worker',
     usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
       {
         name: 'workers',
         type: 'string',
-        summary: `process count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+        summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
       },
       {
         name: 'worker',
         type: 'string',
-        summary: 'rerun only shard I of the same split — reproduces a CI worker failure locally',
+        summary:
+          'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
       },
       { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
       {
@@ -172,7 +173,17 @@ export const testCommand: CliCommand = {
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
     const requested = readIndex(ctx.args, 'workers', 1) ?? defaultWorkers();
-    const workers = Math.max(1, Math.min(requested, files.length));
+    // A serial type is serial HERE TOO, `As of 2026-08-27`. `verify-tests.ts` routes `live` and
+    // `e2e` through `runSerial` and this command never read the same list, so `x verify` ran one
+    // process over the very files `x test live --workers 8` ran eight over — two answers to one
+    // question, which is axiom 1, and the dangerous one is the command a human types while
+    // debugging. What makes them serial is not a preference: a logical replication slot is named
+    // at the Postgres CLUSTER level, so a per-worker database does not isolate it and two workers
+    // race `pg_create_logical_replication_slot`; `e2e` shares one built `dist/` and one browser
+    // profile. Neither is visible without a real `TEST_DATABASE_URL`, which is why the split
+    // measured green for as long as it did.
+    const ceiling = type !== undefined && SERIAL_TYPES.includes(type) ? 1 : files.length;
+    const workers = Math.max(1, Math.min(requested, ceiling));
     const only = readIndex(ctx.args, 'worker', 0);
     if (only !== undefined && only >= workers) {
       throw new BadFlagError({

package/src/db-accept-created.ts

@@ -0,0 +1,207 @@
+// Single responsibility: accept a table an applied migration's own SQL created. A snapshot records
+// only what ENTITIES declare, so a hand-written `create table` is `unexpected-table` on every
+// deploy forever (issue #345) — and the migration list `x db migrate` has just applied is the one
+// piece of evidence that the app owns the relation. Named in `@ultimat3/db`'s `unexpectedTable`.
+
+import type { DriftReport, Migration } from '@ultimat3/db';
+import { statementsOf } from '@ultimat3/db';
+
+/**
+ * `create table`, `create unlogged table`, either with `if not exists`. Anchored, so only the verb
+ * phrase a statement OPENS with counts.
+ *
+ * `temp`/`temporary` is deliberately absent: a temporary table lives in `pg_temp` and can never be
+ * the relation `checkDrift` introspected, so reading one as evidence would accept a `drafts`
+ * somebody created by hand on the strength of SQL that never touched it.
+ */
+const CREATE_TABLE = /^create\s+(?:unlogged\s+)?table\s+(?:if\s+not\s+exists\s+)?/i;
+
+/**
+ * `drop table`, with `if exists`. A migration that creates a relation and later drops it OWNS
+ * neither: re-creating `legacy_audit` by hand afterwards is drift, and a set that only ever grew
+ * accepted it forever. `cascade`/`restrict` and a comma list are handled by the caller.
+ */
+const DROP_TABLE = /^drop\s+table\s+(?:if\s+exists\s+)?/i;
+
+/** `alter table … rename to …` — the old name stops existing and the new one starts. */
+const ALTER_TABLE = /^alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?/i;
+const RENAME_TO = /^\s*rename\s+to\s+/i;
+
+/**
+ * One identifier: quoted (with `""` for a literal quote) or bare. The bare form is Postgres' own
+ * charset — a letter or `_` to open, then letters, digits, `_` and `$` — with everything above
+ * ASCII admitted, since the server accepts any multibyte letter and a name it accepts must be
+ * readable here or the relation behind it is drift nobody can clear.
+ */
+const NAME = /^(?:("(?:[^"]|"")+")|([A-Za-z_\u0080-\uFFFF][A-Za-z0-9_$\u0080-\uFFFF]*))/;
+
+/** A qualifier's dot, with the whitespace Postgres allows on either side of it. */
+const DOT = /^\s*\.\s*/;
+
+/** The schema `checkDrift` compares — `introspect()`'s default, and what `runMigrations` asks for. */
+const COMPARED_SCHEMA = 'public';
+
+/**
+ * Postgres folds an unquoted identifier to lower case and stores a quoted one verbatim, so
+ * `CREATE TABLE LegacyAudit` and `create table legacyaudit` are the same relation and
+ * `"LegacyAudit"` is a different one. The catalog name is what a drift difference carries, so the
+ * fold has to happen here or the comparison misses on every unquoted name that was not typed flat.
+ */
+function unquote(match: RegExpExecArray): string {
+  const quoted = match[1];
+  if (quoted === undefined) return (match[2] ?? '').toLowerCase();
+  return quoted.slice(1, -1).replaceAll('""', '"');
+}
+
+/**
+ * The relation one statement creates, or `null`.
+ *
+ * **The anchor is the whole protection**, and it is read off the raw text. A statement can only
+ * open with `create table` by BEING one: `values ('create table ghost')` opens with `insert`, and
+ * a chunk that is nothing but a comment is not a statement at all (`statementsOf` drops it). A
+ * `stripSqlNoise` pass was written here first and then deleted — it could not change one answer,
+ * because position 0 is the one position no literal, comment or dollar body can cover, and a
+ * defence that cannot fail is a defence nobody can test.
+ *
+ * Anything the anchor admits but the name grammar does not — a comment between the keywords,
+ * `create table (` — contributes nothing. Fail-closed: drift that could have been accepted is
+ * reported, never the reverse.
+ */
+function createdBy(statement: string): string | null {
+  const text = statement.trimStart();
+  const head = CREATE_TABLE.exec(text);
+  if (head === null) return null;
+  const rest = text.slice(head[0].length);
+  const first = NAME.exec(rest);
+  if (first === null) return null;
+
+  const tail = rest.slice(first[0].length);
+  const dot = DOT.exec(tail);
+  if (dot === null) return unquote(first);
+  const second = NAME.exec(tail.slice(dot[0].length));
+  if (second === null) return null;
+  // A qualifier naming another schema is evidence about a relation this report never mentions:
+  // `checkDrift` introspects one schema, and `audit.drafts` is not the `drafts` it compared.
+  return unquote(first) === COMPARED_SCHEMA ? unquote(second) : null;
+}
+
+/**
+ * Every relation a migration script creates, in statement order.
+ *
+ * `statementsOf` is `@ultimat3/db`'s own splitter — the one `x db migrate` sends by — so a `;`
+ * inside a literal, an identifier or a dollar-quoted body is not a statement boundary here either.
+ */
+export function createdTables(up: string): readonly string[] {
+  const owned = new Set<string>();
+  applyOwnership(up, owned);
+  return [...owned];
+}
+
+/**
+ * Fold one migration's statements over the owned set, IN ORDER.
+ *
+ * A set that only ever grew was the defect: `create table legacy_audit` followed by
+ * `drop table legacy_audit` left the name accepted, so a `legacy_audit` somebody re-created by
+ * hand afterwards lost its `unexpected-table` finding — real drift, silenced, which is the one
+ * thing this module may not do.
+ *
+ * Fail-closed on anything the grammar cannot read: a `drop`/`rename` this cannot parse REMOVES
+ * nothing it is unsure about only when it could not name a relation at all; when it can name one,
+ * dropping it from the set is always the safe direction, because the cost of being wrong is a
+ * difference reported that could have been accepted.
+ */
+function applyOwnership(up: string, owned: Set<string>): void {
+  for (const statement of statementsOf(up)) {
+    const created = createdBy(statement);
+    if (created !== null) {
+      owned.add(created);
+      continue;
+    }
+    for (const dropped of droppedBy(statement)) owned.delete(dropped);
+    const renamed = renamedBy(statement);
+    if (renamed === null) continue;
+    // Only inherit ownership when the OLD name was owned: renaming a hand-made table into a name
+    // a migration once created must not launder it into an accepted one.
+    owned.delete(renamed.from);
+    if (renamed.owned) owned.add(renamed.to);
+  }
+}
+
+/** Every relation one `drop table` names — the form takes a comma list. */
+function droppedBy(statement: string): readonly string[] {
+  const text = statement.trimStart();
+  const head = DROP_TABLE.exec(text);
+  if (head === null) return [];
+  const dropped: string[] = [];
+  let rest = text.slice(head[0].length);
+  for (;;) {
+    const name = qualifiedName(rest);
+    if (name === null) break;
+    if (name.table !== null) dropped.push(name.table);
+    if (!/^\s*,/.test(name.rest)) break;
+    rest = name.rest.replace(/^\s*,\s*/, '');
+  }
+  return dropped;
+}
+
+/** `alter table <old> rename to <new>`, or `null`. `owned` is filled in by the caller's set. */
+function renamedBy(statement: string): { from: string; to: string; owned: boolean } | null {
+  const text = statement.trimStart();
+  const head = ALTER_TABLE.exec(text);
+  if (head === null) return null;
+  const source = qualifiedName(text.slice(head[0].length));
+  if (source === null || source.table === null) return null;
+  const verb = RENAME_TO.exec(source.rest);
+  if (verb === null) return null;
+  const target = qualifiedName(source.rest.slice(verb[0].length));
+  if (target === null || target.table === null) return null;
+  return { from: source.table, to: target.table, owned: true };
+}
+
+/**
+ * One optionally schema-qualified relation name and what follows it. `table` is `null` when the
+ * qualifier names a schema `checkDrift` never introspected — the same rule `createdBy` applies.
+ */
+function qualifiedName(input: string): { table: string | null; rest: string } | null {
+  const first = NAME.exec(input);
+  if (first === null) return null;
+  const tail = input.slice(first[0].length);
+  const dot = DOT.exec(tail);
+  if (dot === null) return { table: unquote(first), rest: tail };
+  const second = NAME.exec(tail.slice(dot[0].length));
+  if (second === null) return null;
+  const rest = tail.slice(dot[0].length + second[0].length);
+  return { table: unquote(first) === COMPARED_SCHEMA ? unquote(second) : null, rest };
+}
+
+/**
+ * The drift report minus the tables these migrations demonstrably create.
+ *
+ * **Only `unexpected-table`, and only for a name a migration's SQL creates.** That is what makes
+ * this an acceptance and not the check switched off: a table absent from the snapshot produces
+ * exactly ONE difference (`diffSchema` reports it and never compares its columns), so nothing else
+ * about the relation was being said, and every difference about a table that IS declared — a
+ * missing column, a changed index, a dropped constraint — passes through untouched.
+ *
+ * The migrations are the list `x db migrate` applied immediately before the check, which is why
+ * "created" is provable rather than assumed: `runMigrations` applies every pending file and then
+ * asks, so a `create table` still on disk and unapplied is not one this path can be handed.
+ *
+ * Identity in, identity out when nothing matched — a report this has nothing to say about is not
+ * its to rebuild.
+ */
+export function acceptCreatedTables(
+  report: DriftReport,
+  migrations: readonly Migration[],
+): DriftReport {
+  // In migration ORDER, across the whole list: ownership is a running state, not a union. A
+  // relation created by 0003 and dropped by 0007 is owned by neither.
+  const created = new Set<string>();
+  for (const migration of migrations) applyOwnership(migration.up, created);
+  if (created.size === 0) return report;
+  const differences = report.differences.filter(
+    (difference) => !(difference.kind === 'unexpected-table' && created.has(difference.table)),
+  );
+  if (differences.length === report.differences.length) return report;
+  return { ok: differences.length === 0, differences };
+}

package/src/db-generate.ts

@@ -13,7 +13,9 @@ import {
   snapshotJson,
 } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
+import { describeQueries } from '@ultimat3/query';
 import { loadApp } from './app-load';
+import { replicaIdentityTables } from './db-subscribes';
 import { reconcileSchemaHash, writeSchemaHash } from './drift';
 import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
 import type { Finding } from './output';
@@ -103,10 +105,25 @@ export async function generateAppMigration(
     throw migrationSnapshotMissing(id, join(MIGRATIONS_DIR, snapshotFileName(id)));
   }
 
+  const entities = describeEntities();
+  // Read AFTER the findings check above, never before: a module that would not import leaves the
+  // registry short, and every `subscribes:` name whose entity lives in that module would then look
+  // like a typo. The refusal below is only sound over a whole registry.
+  //
+  // `describeQueries()` is the manifest's own source — `frameworkSources` copies this exact field
+  // onto `QueryFact.subscribes` and changes nothing — so this is the manifest fact one hop earlier.
+  // Building the manifest here would re-load the app and demand a `package.json`, which `x db gen`
+  // has never needed: generation reads declarations and writes files.
+  const replicaIdentityFull = replicaIdentityTables(
+    describeQueries(),
+    new Set(entities.map((entity) => entity.table)),
+  );
+
   const migration = generateMigration({
-    entities: describeEntities(),
+    entities,
     current,
     name: options.name,
+    replicaIdentityFull,
     ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
   });
   // An empty diff writes no MIGRATION — one with no statement still takes a ledger row, a checksum