@ultimat3/cli 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -7,12 +7,16 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
 | 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 |
 | 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 |
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
+| Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
+| App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
+| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 17 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
-| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
+| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error`. A class may sit beside its one thrower when `errors.ts` has no room under the 500-line ceiling — `db-seed.ts` and `metrics-endpoint.ts` do |
 | Subprocesses | only through `exec.ts`, so a test can inject a fake `Runner` |
 | Templates | `templates/*.ts` return strings; no fixture files on disk |
 | Strings | rendered output through `messages.ts`, missing key renders `⟦key⟧` — see below for what is *not* rendered output |
@@ -116,7 +120,9 @@ a shallow spread keeps one of them.
 
 | File | Job |
 |---|---|
-| `ts-scan.ts` | the strings a `fix:` can evaluate to, the `X_*` codes a file declares, and the ones it says it borrows |
+| `ts-scan.ts` | the masking every scan shares, the `X_*` codes a file declares, and the ones it says it borrows |
+| `fix-scan.ts` | the strings a `fix:` can evaluate to: under a key, at a factory's argument, at a class constructor's |
+| `fix-imports.ts` | which of those factories a file can call that it did not declare — one relative specifier, one file read |
 | `error-contract.ts` | the rules, the two checks that turn them into findings, and `collectDeclaredCodes` |
 | `fix-command.ts` | resolving an `x <command>` a `fix:` cites against the registry |
 | `source-files.ts` | which files are shipped source — shared with `filesize`, never a second list |
@@ -145,6 +151,8 @@ declared from the constant the command validates against), because `x jobs show
 working invocations. `positionalChoices` cannot express it: `fix-command.ts` reads that field only
 where a command declares no subcommands at all.
 
+**A command with no subcommands must still declare `positionalChoices`, or its second word is unjudged.** `x g migration` shipped in two `@ultimat3/admin` fix lines — a generator that has never existed, answered with `X_CLI_UNKNOWN_COMMAND` when run — because the `g` spec declared none and `fix-command.ts` returns `undefined` for an absent set. The third instance of this class (#131, then `x db branch <name>`). `cmd-generate.ts` now declares `positionalChoices: GENERATORS`, from the SAME constant `readKind` validates against, exactly as `cmd-test.ts` declares `TEST_TYPES` — `fix-command.test.ts` pins `x g migration` as a finding against the real catalog. A new command whose first positional is a closed set and does not declare it is a hole this rule cannot see.
+
 **And in that one slot, a `<placeholder>` is a finding too.** `x db branch <name>` is what two
 `@ultimat3/mcp` fix lines said; the citation reader does not read `<name>` as a word, so the slot
 was never examined and the line resolved clean while running it answers `X_CLI_UNKNOWN_COMMAND` —
@@ -176,7 +184,7 @@ and the step says so rather than guessing.
 helper, so the file held no `fix:` at all and `scanFixes` returned `[]` for all of it — the
 citation resolver was never given a string to judge, and two stale `x db branch <name>` lines
 shipped through the hole. `scanFixes` now also reads the argument in the `fix: string` position of
-a **local** helper, under four rules, each with its own case in `ts-scan.test.ts`: the helper must
+a **local** helper, under four rules, each with its own case in `fix-scan.test.ts`: the helper must
 BUILD an error (`code` key or `new …Error(` in its body), or `citedCommandProblem(fix, catalog)` —
 which takes a fix to *judge* it — would have its call sites read as declarations; the parameter
 list may hold no rest or destructured parameter, because neither has a reliable position; the call
@@ -185,12 +193,31 @@ because `prefix + 'x doctor'` reads as one literal there and publishing half a f
 publishing none. Measured over the whole tree: 16 files gained readable fixes, `readonly-sql.ts`
 went from 0 to 7, and **zero** new findings.
 
-What it still cannot see is **cross-file**: `dbNotImplemented` is exported from `@ultimat3/db` and
-called from `pglite-branch.ts`, and resolving that means an import graph and a per-symbol parameter
-table. Same for an error class with a positional `constructor(cause, fix)` — `@ultimat3/render`'s
-`errors.ts` has fourteen, and 15 of its codes have never had a fix line read. Measured: **zero**
-same-file call sites for that form, so a constructor rule would be dead code today. Named, not
-guessed at.
+**And a fix does not always arrive in the file that declares its builder**, which is where four
+bad `fix:` lines in `packages/ui/src/icons/build-icons.ts` shipped: `invalidIconDataError` is
+declared in `packages/ui/src/errors.ts`, and a per-package `errors.ts` full of factories is the
+house pattern, so the same-file rule left the most common shape of all unchecked. `fix-imports.ts`
+resolves it — the specifier is relative, the candidate paths are `<base>.ts{,x}` and
+`<base>/index.ts{,x}`, and the parameter position is the callee's. An alias is renamed to what the
+CALLER writes; a local declaration of the same name wins, because that is the function the call
+actually reaches. One module cache per run: `errors.ts` is imported by every file in its package.
+
+**An error CLASS is the same helper one keyword away**, and is now read too: the name is the
+class's, the parameter list its `constructor`'s, `new X(…)` is a call like any other. It was
+measured as dead code in the same-file rule — zero same-file call sites — and cross-file it is
+`@ultimat3/render`'s fourteen classes plus `@ultimat3/core`'s three image ones.
+
+Measured over the whole tree, `As of 2026-08`: **791 → 877** fix literals read, 37 files gained
+one, and **3 findings** the gate had never been able to see — `x verify --contract` and
+`x build --route` (two flags no command declares) and one `check …` line with no command token.
+
+What it still cannot see is a builder imported from another **package**: `candidatePaths` refuses a
+non-relative specifier, because resolving one means guessing which of 29 packages a bare name came
+from and a wrong guess reads an unrelated function's argument as a fix. Measured: 3 call sites in
+this repo, none of them a finding. It is **not** left silent — the step's `output` carries
+`checked {n} fix line(s), could not read {m}`, counted at `FixScan.unreadable`: an argument in a
+KNOWN fix position that is not one literal. Deliberately not "imports I could not open", which is
+1504 names here and 1310 of them are `join` and `UltimateError` — a number nobody can act on.
 
 `cli → admin` is a declared sideways edge (`scripts/lib/tiers.ts`): `x dev` **mounts** the
 dashboard, it never grows a second one. The CLI's only contribution is the facts no registry
@@ -285,6 +312,7 @@ regex and `+` is a quantifier — `n1` is what actually selects these tests.
 | `drift.ts` | `checkSourceDrift`: the `.hash` sidecar `x verify`'s `drift` step compares, no database needed |
 | `db-destructive.ts` | `checkDestructiveMigrations`: the same step's second half — every committed `up` that drops, truncates or retypes must carry `-- destructive: true` |
 | `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 |
 
 `jobs-driver.ts` is the ONE place a CLI command gets hold of the app's queue — `withJobDriver`,
 which `x jobs` and `x db backfill` both call. It reuses an ambient `jobDriver()` when a process
@@ -311,8 +339,12 @@ The typo is impossible rather than the keystroke tedious — and `@ultimat3/db`
 `x db branch drop <name>` as `X_BRANCH_EXISTS`'s `fix:` with no flag on it, so a flag here would
 break a shipped instruction.
 
-**The prefix half is not decoration: the marker records WHEN a clone was made and never what it was
-cloned FROM.** One Postgres server hosting two Ultimate apps answers `listBranches()` with both
+**The prefix half is not decoration, and it is no longer the only source guard.** The marker records
+the base `As of 2026-08-19` — `ultimate:branch:<base>:<iso>`, read back as `BranchInfo.base` — so
+`reapBranches` can skip another app's clones on its own. The prefix guard still stands and is what
+`ls`/`drop` read, because an **older** marker records no base at all: it is skipped by the reaper
+rather than dropped, which leaves `drop` needing an answer that does not depend on a field half the
+branches lack. One Postgres server hosting two Ultimate apps answers `listBranches()` with both
 apps' clones, and `branchNameOf` reduced `postly_branch_feat` and `analytics_branch_feat` to the
 same branch name — so `x db branch drop feat`, run against `postly`, was authorised by
 `analytics`'s row and then issued `drop database if exists "postly_branch_feat"` against a database
@@ -399,6 +431,29 @@ with nothing running, and against a database three migrations behind. An app who
 load generates **nothing**: a short registry is indistinguishable from deleted entities, and the
 diff would be a DROP nobody asked for.
 
+**An empty diff re-records the `.hash` sidecar, and that is what makes `X_DB_DRIFT` followable.**
+The hash `checkSourceDrift` compares covers every non-test file under `packages/db/src` — a seed, a
+helper, a decorator — not only the ones that imply DDL, and narrowing that glob would trade a loud
+error for a silent gap in the one check that catches "entities changed and no migration was
+generated". So detection stays broad and the REMEDY carries the weight: `x db gen "describe the
+change"` — the exact `fix:` the error hands out — records the current hash against the newest
+migration when the diff is empty, instead of writing nothing and leaving the gate red forever with
+hand-editing a generated file as the only way out. `GeneratedFiles.outcome` is the four things a run
+can be — `generated`, `hash-recorded`, `unchanged`, `blocked` — and `runGen` projects it onto
+`--json` on **every** branch: reporting `hash-recorded` as `generated` would name a migration nobody
+can apply, and reporting it as `unchanged` would hide a file this command wrote. That second one
+shipped: the no-migration branch hardcoded `data: { migration: null, files: [] }`, so the run that
+wrote the sidecar reported writing nothing to the machine reading the output.
+
+Nothing is masked, and the branch proves it rather than promising it: `loadApp` reported no findings
+(the registry is whole, never short), `declaredSchema` returned a real snapshot (`X_MIGRATION_SNAPSHOT_MISSING`
+otherwise), and the emptiness is `generateMigration`'s own verdict — the same call the written path
+takes. A migration with no migration id to record against writes nothing, which is the
+`x new --no-example` case: an entity against zero migrations is `create table` for all of it and
+never an empty diff. `reconcileSchemaHash` also declines to write when an OLDER migration already
+recorded the hash, because `checkSourceDrift` already answers clean there and restamping the newest
+sidecar would claim it produced a schema it did not — one predicate, `isRecorded`, read by both.
+
 One migration is one file, split by a lone `-- down` line. `<id>.down.sql` is a pre-1.2.0
 hand-written layout and `readMigrations` skips it — read as a migration it sorts next to its own
 `up` and drops every table the pair exists to reverse.
@@ -488,8 +543,10 @@ session-scoped and the grant dies when the connection returns to the pool, so ev
 itself as leader and a rolling update double-fires every task.
 
 The relay runs on `worker` and only `worker` — the role that exists wherever jobs run at all.
-Duplicating it is safe (publish-then-mark is at-least-once and the idempotency key collapses the
-repeat) but pointless.
+Duplicating it is safe — the claim is a **lease** taken in the statement that locks the row
+(`@ultimat3/jobs`' `outbox-pg.ts`, fenced on `claimed_by`), so two relays never hold one batch —
+but pointless. The idempotency key is not the reason and never was: its conflict target is a
+partial index over live states, so it collapses a repeat only while the first job is still live.
 
 `SQL_IDEMPOTENCY_TABLE` is applied beside `SQL_JOBS_TABLE`, and the store is installed by the boot
 rather than by the app, even though `@ultimat3/action` documents
@@ -581,6 +638,16 @@ route: a tenant-scoped key takes `AUTHORIZED_OBJECT_CACHE` (`private, max-age=0`
 `authorization`/`cookie`), and only a key no tenant owns keeps `immutable`. A genuinely public image
 belongs under `apps/web/site/`, which is a static asset and never touches that disk.
 
+**A variant is CACHED only at a width the framework can mint.** The cache key is built entirely
+from caller-supplied query values, so `?w=1`, `?w=2`, … each wrote a new object to the app's only
+disk, on a route every signed-in tenant may reach for their own keys. `@ultimat3/seo`'s
+`MAX_IMAGE_WIDTH` (8192) bounds that and does not close it. `isMintableWidth` is the bound:
+`DEFAULT_WIDTHS` **plus the source's own intrinsic width**, which is exactly the set `usableWidths`
+puts in a `srcset` — the constant alone would refuse the widest entry of any image whose intrinsic
+width is not one of the eight. Anything outside it is still served; only the `put` is refused, so
+no caller gains a new 4xx. `?q=` is deliberately still unbounded here — the closed set for quality
+is `@ultimat3/seo`'s to declare, not this file's.
+
 `ICON_SOURCE` lives here, not in `cmd-doctor.ts`, because this is the module that reads it: the
 diagnostic checks what `x dev` serves, so one constant cannot pass the check and serve nothing.
 It is a **PNG** — core decodes PNG and JPEG only, and the SVG this used to name could never
@@ -609,6 +676,35 @@ locked by a process that no longer exists.
 
 Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
 
+## A declared flag with no reader is a promise `x help` makes and nothing keeps
+
+`x deploy --critical` said *"security deploy: forces clients to reload"* and forced nothing: the
+value is written into the plan JSON (`cmd-deploy.ts`) and **no package reads that field**. The
+parser accepts every declared flag, so this is neither a parse error nor a type error — the flag
+worked perfectly and meant nothing, to the operator most likely to be shipping a security patch.
+
+`flag-reads.ts` is the rule that can see the class of defect: **every flag a command declares is
+read by something in the CLI's own source**, as `X_CLI_FLAG_UNREAD`. The four global flags are
+excluded — `--json`, `--help`, `--cwd` and `--verbose` are the parser's, read once for every
+command, and a per-command rule would report all thirty declarations of `--json`. The read test is
+deliberately generous: a bare `'name'` literal anywhere outside a `name:`/`short:` spec field
+counts, so a flag echoed only into `--json`, or read through a shared constant, is read. A gate
+that guessed at intent would report findings about working commands.
+
+It is enforced by `flag-reads.test.ts`, in the `unit` step — the same shape `cmd-planned.test.ts`
+and `error-catalog.test.ts` use for a rule about the CLI's own declarations, and the reason its
+`fix:` is a `bun test` line rather than an `x` command: the rule can only ever fire in this repo.
+Promoting it to `x verify`'s `boundaries` host check is one line in `scripts/verify.ts`.
+
+**It does not catch `--critical`, and that is the honest limit.** The flag IS read —
+`flagBool(ctx.args, 'critical')` — and what had no consumer was the plan FIELD, one level below any
+rule over names. Two stronger rules were measured and rejected: "the read must not be a property
+initializer" reports six flags, five of which work (`x db --allow-destructive`, `x jobs --queue`);
+"the summary must match the behaviour" is undecidable. So the flag's summary now says what it does,
+and forcing a reload stays what it always was — `@ultimat3/pwa`'s `updateSignal({ reason:
+'security' })`, which `As of 2026-08` has **no runtime caller anywhere**, in that package or
+outside it. Wiring the flag means giving that function a caller first.
+
 ## Planned commands are commands
 
 Every command in `wiki/CLI-Reference.md`'s planned table is in the registry, built from

package/README.md

@@ -82,6 +82,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `dispatch.ts` | parse → run → render → exit; the only I/O boundary |
 | `parse.ts` | flags, subcommands, `--json`, `--help`, suggestions |
 | `flag-number.ts` | the one integer-flag reader — `--port`, `--workers`, `--shard` |
+| `shell-quote.ts` | the one POSIX quoter for a value pasted into a `fix:` or a reproduce line |
 | `output.ts` | one data shape, two renderers, the 3-line error format |
 | `registry.ts` | the one command list |
 | `generate-kinds.ts` | which generators exist, and how a command line names one |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -35,28 +35,28 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/admin": "2.0.0",
-    "@ultimat3/ai": "2.0.0",
-    "@ultimat3/cache": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/entity": "2.0.0",
-    "@ultimat3/http": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/mail": "2.0.0",
-    "@ultimat3/manifest": "2.0.0",
-    "@ultimat3/mcp": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/pwa": "2.0.0",
-    "@ultimat3/query": "2.0.0",
-    "@ultimat3/realtime": "2.0.0",
-    "@ultimat3/render": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/seo": "2.0.0",
-    "@ultimat3/storage": "2.0.0",
-    "@ultimat3/testing": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/action": "4.0.0",
+    "@ultimat3/admin": "4.0.0",
+    "@ultimat3/ai": "4.0.0",
+    "@ultimat3/cache": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/entity": "4.0.0",
+    "@ultimat3/http": "4.0.0",
+    "@ultimat3/i18n": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/mail": "4.0.0",
+    "@ultimat3/manifest": "4.0.0",
+    "@ultimat3/mcp": "4.0.0",
+    "@ultimat3/policy": "4.0.0",
+    "@ultimat3/pwa": "4.0.0",
+    "@ultimat3/query": "4.0.0",
+    "@ultimat3/realtime": "4.0.0",
+    "@ultimat3/render": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/seo": "4.0.0",
+    "@ultimat3/storage": "4.0.0",
+    "@ultimat3/testing": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/budgets.ts

@@ -17,6 +17,14 @@ export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 export interface RouteStats {
   readonly path: string;
   readonly jsBytes: number;
+  /**
+   * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
+   * file and it emits static HTML — there is no browser in the build to observe a paint. So the
+   * comparison in `checkBudgets` below is reachable only for an app that writes its own stats, and
+   * `x new` no longer scaffolds an `lcp` budget for exactly that reason: a budget the build cannot
+   * weigh passes silently the moment a stats row exists, which is the false green this file's
+   * header is about. `RouteBudget.lcp` still accepts one — that key is `@ultimat3/render`'s.
+   */
   readonly lcpMs?: number;
   /** Import chain that pulled the heaviest module into this route. */
   readonly heaviestChain?: readonly string[];
@@ -123,6 +131,23 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
 
 const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
 const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
+const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
+
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
+ * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
+ * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
+ * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
+ * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
+ */
+const carriesJson = (attrs: string): boolean => {
+  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
+  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
+  // test alone charged an SEO structured-data block as executable JavaScript all over again.
+  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
+  return type.trim().toLowerCase().endsWith('json');
+};
+
 /**
  * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
  * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
@@ -144,8 +169,9 @@ export interface MeasuredJs {
 }
 
 /**
- * What a rendered document actually makes the browser execute: the bytes of every inline script,
- * the size of every file a `src` points at, and the size of every island chunk it boots. Measured
+ * What a rendered document actually makes the browser execute: the bytes of every inline script
+ * the parser will run, the size of every file a `src` points at, and the size of every island
+ * chunk it boots. A JSON-typed script is skipped — it is data the parser never runs. Measured
  * from the emitted HTML rather than from the declared graph, because the graph is what a route
  * *says* it ships and this gate exists to catch the case where those two disagree.
  */
@@ -162,7 +188,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   };
 
   for (const match of html.matchAll(SCRIPT_TAG)) {
-    const src = SRC_ATTR.exec(match.groups?.['attrs'] ?? '')?.groups?.['src'];
+    const attrs = match.groups?.['attrs'] ?? '';
+    if (carriesJson(attrs)) continue;
+    const src = SRC_ATTR.exec(attrs)?.groups?.['src'];
     if (src === undefined) {
       jsBytes += Buffer.byteLength(match.groups?.['body'] ?? '', 'utf8');
       continue;
@@ -181,11 +209,6 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   return { jsBytes, entries };
 }
 
-/** The total alone, for a caller with nothing to say about which module was the heavy one. */
-export async function measureJsBytes(html: string, out: string): Promise<number> {
-  return (await measureDocumentJs(html, out)).jsBytes;
-}
-
 /**
  * The file `checkBudgets` reads. Written by the build and by nothing else — a stats file produced
  * anywhere but from real output is the false green this gate exists to prevent.

package/src/cmd-db-branch.ts

@@ -11,6 +11,7 @@ import {
   branchDatabaseName,
   createExternalBranch,
   createPgliteBranch,
+  databaseNameOf,
   dropExternalBranch,
   dropPgliteBranch,
   isBranchName,
@@ -27,6 +28,7 @@ import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagString, nearest } from './parse';
+import { portFromEnv } from './serve';
 import { renderTable } from './table';
 
 /**
@@ -145,7 +147,9 @@ async function runCreate(
   services: DevServices,
   name: string,
 ): Promise<CommandResult> {
-  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
+  // `portFromEnv`, never a bare `Number.parseInt`: the latter reads `PORT=abc` as `NaN` and put
+  // `http://feat.localhost:NaN` in `data.preview` — a machine-readable field naming no port.
+  const port = portFromEnv(ctx.env);
   let branch: BranchRow;
   try {
     branch =
@@ -205,7 +209,7 @@ function notABranch(services: DevServices, name: string): CommandResult {
   const target =
     services.db.mode === 'embedded'
       ? pgliteBranchLocation(services.db.url, name)
-      : branchDatabaseName(services.db.url.split('/').at(-1) ?? 'postgres', name);
+      : branchDatabaseName(databaseNameOf(services.db.url), name);
   return failure(msg('cli.db.branch.failed'), {
     code: 'X_DB_BRANCH_FAILED',
     cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,

package/src/cmd-db.ts

@@ -1,4 +1,4 @@
-// `x db gen|migrate|reset|studio|branch|backfill` — everything that touches the database. One
+// `x db gen|migrate|reset|seed|studio|branch|backfill` — everything that touches the database. One
 // subcommand per line and no fall-through: a word this file does not know is refused, never
 // re-read as an argument to the last branch. `branch` itself is `cmd-db-branch.ts`.
 //
@@ -12,7 +12,8 @@
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveEnvironment } from '@ultimat3/core';
-import { type DriftReport, driftError } from '@ultimat3/db';
+import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
+import { postgresDriver } from '@ultimat3/entity';
 import { BackfillPendingError } from '@ultimat3/jobs';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
@@ -34,6 +35,16 @@ import {
 import { BRANCH_SUBCOMMANDS } from './db-branch';
 import { stepFinding } from './db-finding';
 import { generateAppMigration } from './db-generate';
+import type { SeedPassRow } from './db-seed';
+import {
+  discoverSeeds,
+  parseSeedTierFlag,
+  renderSeedTable,
+  runSeeds,
+  seedPassToJson,
+  seedTotals,
+  selectSeeds,
+} from './db-seed';
 import { resolveServices } from './dev-services';
 import {
   BadFlagError,
@@ -49,14 +60,22 @@ import { findingFrom } from './output';
 import { flagBool, flagString } from './parse';
 import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch', 'backfill'] as const;
+export const DB_SUBCOMMANDS = [
+  'gen',
+  'migrate',
+  'reset',
+  'seed',
+  'studio',
+  'branch',
+  'backfill',
+] as const;
 
 export const dbCommand: CliCommand = {
   spec: {
     name: 'db',
-    summary: 'gen, migrate, reset, studio, branch, backfill',
+    summary: 'gen, migrate, reset, seed, studio, branch, backfill',
     usage:
-      'x db gen "add publish_at" | migrate | reset | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+      'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
     requiresApp: true,
     subcommands: DB_SUBCOMMANDS,
     // Declared from the constant `runBranchCommand` validates against, never a second literal: it
@@ -64,7 +83,21 @@ export const dbCommand: CliCommand = {
     // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
     subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
     flags: [
-      { name: 'name', type: 'string', summary: 'migration or branch name, or backfill to filter' },
+      {
+        name: 'name',
+        type: 'string',
+        summary: 'migration, branch or seed name, or backfill to filter',
+      },
+      {
+        name: 'tier',
+        type: 'string',
+        summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
+      },
+      {
+        name: 'dry-run',
+        type: 'boolean',
+        summary: 'seed: report what each seed would write, and write nothing',
+      },
       { name: 'list', type: 'boolean', summary: 'backfill: print the x_backfills ledger' },
       {
         name: 'pending',
@@ -106,6 +139,7 @@ export const dbCommand: CliCommand = {
     if (sub === 'gen') return runGen(ctx, root, argument ?? 'change');
     if (sub === 'migrate') return runMigrate(ctx, root, msg('cli.db.migrate.applied'));
     if (sub === 'reset') return runReset(ctx, root);
+    if (sub === 'seed') return runSeed(ctx, root);
     if (sub === 'studio') throw plannedSubcommand('db', 'studio');
     if (sub === 'backfill') return runBackfill(ctx, root);
     if (sub === 'branch') return runBranchCommand(ctx, root);
@@ -125,8 +159,14 @@ export const dbCommand: CliCommand = {
 
 /**
  * Source in, files out — no database is opened, so this answers the same in CI and on a laptop
- * with nothing running. A diff that finds nothing writes nothing and still exits 0: "no change" is
- * an answer, and an empty migration would take a ledger row and a checksum forever.
+ * with nothing running. A diff that finds nothing writes no MIGRATION and still exits 0: "no
+ * change" is an answer, and an empty migration would take a ledger row and a checksum forever. It
+ * may still write the `.hash` sidecar `x verify`'s `drift` step reads, which is what makes
+ * `X_DB_DRIFT`'s `fix:` — this command — a real instruction rather than a no-op.
+ *
+ * So there are THREE answers, not two, and `--json` carries `outcome` on every one: collapsing
+ * `hash-recorded` into either neighbour tells the machine reading this output that a migration
+ * exists when none does, or that nothing was written when the sidecar was.
  */
 async function runGen(ctx: CommandContext, root: string, name: string): Promise<CommandResult> {
   let generated: Awaited<ReturnType<typeof generateAppMigration>>;
@@ -148,9 +188,21 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
     return {
       ok: generated.findings.length === 0,
       command: 'db',
-      summary: msg('cli.db.gen.unchanged'),
+      // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
+      // the `drift` step reads back.
+      summary:
+        generated.outcome === 'hash-recorded'
+          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+          : msg('cli.db.gen.unchanged'),
       findings: generated.findings,
-      data: { migration: null, files: [] },
+      // `files` is what this command WROTE, so the empty array here was a false claim.
+      lines: generated.files.map((file) => `  ${file}`),
+      data: {
+        outcome: generated.outcome,
+        migration: null,
+        files: [...generated.files],
+        schemaHash: generated.schemaHash ?? null,
+      },
     };
   }
   return {
@@ -159,6 +211,7 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
     summary: msg('cli.db.gen.written', { id: migration.id }),
     lines: generated.files.map((file) => `  ${file}`),
     data: {
+      outcome: generated.outcome,
       migration: migration.id,
       name: migration.name,
       files: [...generated.files],
@@ -233,6 +286,81 @@ async function runReset(ctx: CommandContext, root: string): Promise<CommandResul
   return runMigrate(ctx, root, msg('cli.db.reset.done'));
 }
 
+/**
+ * `x db seed [<name>]` — the fixture graph, applied and replayable.
+ *
+ * The environment is resolved BEFORE anything is imported or connected: a run this environment does
+ * not take must refuse without having opened a connection to the database it was refusing to write
+ * to. `selectSeeds` asks the same question a second time, on the seeds themselves, because seeding
+ * is the one irreversible thing this command does (`db-seed.ts`).
+ *
+ * `withJobDriver` is the boot, though nothing here claims a job: it is the CLI's one answer to
+ * "which database is this command talking to", and it also puts a real queue behind any
+ * `handle.enqueue()` a seeded write triggers. A second boot path would be a second answer.
+ */
+async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const environment = resolveEnvironment({ env: ctx.env });
+  const requested = parseSeedTierFlag(
+    flagString(ctx.args, 'tier') ?? ctx.env['ULTIMATE_SEED_TIER'],
+  );
+  const name = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const discovery = await discoverSeeds(root);
+  const chosen = selectSeeds({
+    discovered: discovery.seeds,
+    ...(name === undefined ? {} : { name }),
+    environment,
+    requested,
+  });
+  if (chosen.length === 0) {
+    return {
+      ok: true,
+      command: 'db',
+      summary: msg('cli.db.seed.none'),
+      findings: discovery.findings,
+      data: seedPassToJson([]),
+    };
+  }
+  return withJobDriver(root, ctx, async () => {
+    const rows = await runSeeds({
+      seeds: chosen,
+      driver: postgresDriver(),
+      dryRun,
+      env: ctx.env,
+      // One transaction per seed, so a seed that throws takes only its own rows with it.
+      transaction: (work) => withTransaction(() => work()),
+    });
+    return seedPassResult(rows, dryRun, discovery.findings);
+  });
+}
+
+function seedPassResult(
+  rows: readonly SeedPassRow[],
+  dryRun: boolean,
+  findings: readonly Finding[],
+): CommandResult {
+  const totals = seedTotals(rows);
+  const failures = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+  return {
+    ok: failures.length === 0 && findings.length === 0,
+    command: 'db',
+    summary:
+      totals.failed > 0
+        ? msg('cli.db.seed.failed', { failed: totals.failed, count: rows.length })
+        : dryRun
+          ? msg('cli.db.seed.dryRun', { count: rows.length })
+          : msg('cli.db.seed.done', {
+              count: rows.length,
+              inserted: totals.inserted,
+              updated: totals.updated,
+              skipped: totals.skipped,
+            }),
+    findings: [...failures, ...findings],
+    lines: renderSeedTable(rows).map((line) => `  ${line}`),
+    data: seedPassToJson(rows),
+  };
+}
+
 /**
  * Four shapes, one subcommand: `--list` reads the `x_backfills` ledger, `--pending` diffs it
  * against what the app DECLARED, and `<name>` / `--all` gate a pass and put it on the queue. A