@ultimat3/cli 19.1.3 → 19.3.1

package/CLAUDE.md

@@ -8,12 +8,13 @@ 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 |
+| Test execution | `test-shards.ts`'s `testArgs` — ONE `bun test --parallel=N` per PASS (`test-passes.ts`; a selection mixing `live`/`e2e` files with the rest is two passes, the serial one at `--parallel=1`), 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 |
 | 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>`. Both forms answer now: `--help` is read off the flag loop and `readSubcommand` is SKIPPED when it is set, so `x db --help`, `x mcp --help` and `x pr --help` print usage instead of exiting 1 with this same refusal — which is what they did on every command taking a subcommand until 2026-08 (`parse.test.ts` pins it across the shipped registry) |
 | 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 |
+| Passthrough | `CommandSpec.passthrough`, **declared**. `ParsedArgs.passthrough` says "handed to the underlying tool verbatim" and had no reader anywhere, so `x test unit -- --coverage --bail` parsed both flags and dropped both — a run that measured nothing reporting what a coverage run reports. `x test` forwards them to `bun test` (before the file list) and prints them back in its reproduce line; every other command refuses a non-empty `--` tail with `X_CLI_BAD_FLAG` rather than dropping it. `help`/`version` short-circuit ahead of the command and are exempt |
 | 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 20 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` |
@@ -81,7 +82,7 @@ source only: a test file's import is not judged, because `packages/*` here decla
 read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
 very edge the rule is looking for.
 
-`app-permissions.ts` is the `policy` step, and it is the twentieth. Two references in the whole
+`app-permissions.ts` is the `policy` step. Two references in the whole
 framework are bare strings nothing checks — `RoleDef.grants` and `RouteGuard.permission` — while
 `can()` calls `assertPermission` and throws `X_PERMISSION_UNKNOWN` on the first request that
 reaches the route. So `x new` shipped an app that granted `dashboard:read`, required it on
@@ -108,9 +109,19 @@ halves are `undefined`/empty with no replica configured, and an EMBEDDED binding
 PGlite has no standby. Not `@ultimat3/http`'s pipeline, which would make the HTTP tier know what a
 database is; the boot is the only tier that may know about a request and a pool.
 
+`flag-number.ts`'s `portPairAfter` is the one suggestion for a caller that binds a PAIR, and
+`neighbouringPort` is for a caller that binds one port. `x dev` takes `PORT` **and** `PORT + 1`, so
+the neighbour of a taken web port is the sync port — both `x doctor`'s `X_PORT_IN_USE` and
+`dev-sync.ts`'s handed back the port the finding had just named as taken, each under a test that
+said it ended the failure. It answers downward at the top of the range for the reason
+`neighbouringPort` does, and one further: the suggestion's own neighbour has to exist, or
+`syncPortFor` refuses it with `X_PORT_INVALID`.
+
 `port-probe.ts` is the one `portFree`, because two commands ask it and must not disagree:
-`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the `PORT + 1`
-sync port, each labelled with the role that wants it — and `startSync` asks it after a failed
+`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the sync port,
+which it derives with `syncPortFor` (the boot's own rule: a `--port` at the top of the range has no
+sync port at all, so the probe reports `X_PORT_INVALID` instead of probing the port BELOW it, which
+is what `neighbouringPort` answered there) — each labelled with the role that wants it — and `startSync` asks it after a failed
 `listenSyncNode` so a taken neighbour is `X_PORT_IN_USE` rather than `X_CLI_UNEXPECTED` over
 `Bun.serve`'s own English rendered into a `cause:`. It is ASKED, never read off the caught value,
 which is what `scripts/catch-render.ts` refuses; anything else the listener failed on is re-thrown
@@ -119,6 +130,36 @@ untouched. `x doctor` also probes `DATABASE_URL` with a real `select 1` through
 credentials, which is the case an operator most needs told about — and reports `X_DB_UNAVAILABLE`
 with that package's own two-branch fix. An EMBEDDED binding is not probed: that lock is `x dev`'s.
 
+`doctor-offline.ts` is `x doctor`'s offline-fallback check, and it is the shape of a diagnostic
+that could not be closed. The probe was the literal `apps/web/app/offline.tsx` — a filename
+`assertRouteFilename` REFUSES (`X_ROUTE_FILE_INVALID`: the directory is the URL, so a page is
+`page.tsx`) — while `x new` scaffolds `apps/web/site/offline/page.tsx` and the finding's own `fix:`
+writes `apps/web/app/offline/page.tsx`. Three different paths, so every app the framework has ever
+produced reported `X_PWA_NO_OFFLINE_FALLBACK` from its first `x doctor`, running the fix changed
+nothing, and the app that HAD the route was told it did not. It now reads the DECLARED
+`pwa.offline.fallback` through `loadPwaArtifacts` and matches it against `describeRoutes()` —
+**`site/` only**, `As of 2026-09`. It accepted `app/` too, on the argument that both surfaces answer
+the same URL; true, and not the question. `SURFACE_SPECS` allows `app/` exactly `stream | ssr`, only
+a `static` route is prerendered, and `serviceWorkerArtifacts` precaches a rendered DOCUMENT
+(`documents.get(fallback)`) — so an `app/` fallback has nothing to precache and the offline
+navigation reaches the network it exists to survive without. The check and its own `fix:` disagreed
+about one code. Not closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
+either, and `NavigableRoute` carries no render mode. An app whose modules will not import is not
+judged at all, which is
+`appEntities`' rule (`schema-drift.ts`) one registry over. The fix is `x g route <name>
+--surface site` only where the fallback is one path segment the generator can really produce: a
+nested path slugifies to a DIFFERENT url, so there it is the config edit instead — a `fix:` that
+runs and leaves the finding where it was is the defect this file exists to end. **`site`, not
+`app`**: the document that answers a lost network has to render with no network, no session and no
+database, which `app/` (`ssr | stream`) cannot promise, and it is the line `@ultimat3/pwa`'s own
+`X_PWA_NO_OFFLINE_FALLBACK` hands out for the same code — two fixes for one code are two answers.
+
+`X_ENV_MISSING`'s fix is the file write, for the same reason. It was `x new --force`, which cannot
+run where the reader is standing: `x new` takes a `<name>` positional (`X_CLI_BAD_FLAG` without
+one) and with one it scaffolds a SECOND app beside the broken one. `cp .env.example
+.env.development` — the committed projection of `envSchema`, which is what `x env example` writes
+and `X_ENV_EXAMPLE_DRIFT` keeps honest.
+
 `i18n-index.ts` is the one writer of an app's `packages/i18n/src/index.ts`, shared by `x g` and
 `x i18n add|sync`. A catalog on disk and a SELECTABLE locale were two different sets: `x i18n add
 fr` wrote the file, exited 0, and left `x verify --only i18n` red with `X_CATALOG_UNREGISTERED`
@@ -156,6 +197,7 @@ them is answered by this table rather than by a second convention:
 | `x tasks` | `cmd-tasks.ts`, `tasks-facts.ts` | `registeredTasks()` + `@ultimat3/time`'s cron resolution |
 | `x policy` | `cmd-policy.ts`, `policy-facts.ts` | `@ultimat3/policy`'s `policyMatrix()` over the app's own `Policy` objects |
 | `x i18n` | `cmd-i18n.ts`, `i18n-audit.ts`, `i18n-registration.ts` | `@ultimat3/i18n`'s `extractFromFiles` + `auditCatalogs`, then the live catalog registry |
+| `x i18n check` and the `policy` step, before either registry | `duplicate-packages.ts` | `Bun.resolveSync` of `@ultimat3/i18n` / `@ultimat3/policy` / `@ultimat3/entity` from the app root, every workspace and the CLI's own directory, keyed by REALPATH. Two real directories is `X_PACKAGE_DUPLICATED`: a registry is per module instance, so the app registers into one copy and the CLI reads the other — `x i18n check` said "move `defineCatalogs()`" about a call that was already where it belongs (ai-maxxing, 2026-09-05), and the policy step was green over an undeclared grant. A workspace symlink to one checkout is one copy; two store entries at ONE version are two |
 
 Each pairs a `cmd-*.ts` of CLI wiring with a facts module that takes plain inputs and returns plain
 data, so the projection is testable without a `ParsedArgs` — the `cmd-jobs.ts` / `jobs-report.ts`
@@ -405,7 +447,26 @@ cannot be missing from the precache manifest.
 |---|---|
 | `cmd-dev.ts` | mounts `/sw.js` and `/x-sw-register.js`; built ONCE at boot and deliberately not rebuilt on the watcher tick — a worker that changes under a page it already controls is the update path, and re-emitting one per keystroke exercises it on every save |
 | `serve.ts` | the same two routes in the container, from the same call |
-| `prerender.ts` | writes both as FILES into the export — a static host runs no route table, so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the artifact |
+| `prerender.ts` | writes both as FILES into the export — a static host runs no route table, so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the artifact. In TWO halves, `As of 2026-09-06`: `serviceWorkerHead(pwa)` before the render loop, because every document has to name the script, and `serviceWorkerArtifacts` AFTER it, because a precache revision is the content hash of a document that does not exist yet |
+
+**A precache revision is the DOCUMENT's content hash, and until 2026-09-06 it was the build id.**
+`pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+`{"url":"/","revision":"<buildId>","bytes":0}`: two deploys of a byte-identical site re-fetched
+every precached page, which is the one thing `packages/pwa/src/precache.ts`' own header says must
+never happen, and `DEFAULT_PRECACHE_WARN_BYTES` was a 5 MB budget over a total that could not count
+one byte of HTML. The cause was ORDER — `prerender.ts` emitted the worker before the render loop —
+so the emission moved after it and `ServiceWorkerInput.documents` carries `renderStatic`'s own
+`hash` and byte count per rendered path. `x dev` and `serve.ts` pass none and keep the build id:
+neither has rendered a page at boot, and inventing a hash for bytes that do not exist is a revision
+that never changes when the page does. **The offline document is fed through its own pair**, because
+`buildPrecacheManifest` adds it ITSELF as `reason: 'fallback'` ahead of every route and `add()`
+keeps the first entry per url — so the route entry of the same url is shadowed and only
+`offlineFallbackRevision` / `offlineFallbackBytes` (`ServiceWorkerConfig`, `@ultimat3/pwa`) can
+decide it. That pair was declared and fed by nobody for one commit; `serviceWorkerArtifacts` reads
+the fallback path out of the same `documents` map, so the one page an offline navigation depends on
+is content-addressed like every other. A fallback this pass did not render — no route serves it,
+which `x doctor` reports as `X_PWA_NO_OFFLINE_FALLBACK` — is absent from the map and keeps the
+build id.
 
 **Registration is an EXTERNAL script, never inline**, and that is a CSP fact rather than a
 preference: `startWeb` computes a `script-src` sha256 per inline script, so an unhashed one is
@@ -981,7 +1042,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `dev-render.ts` | one HTTP route per registered `route`, through render's own mode function |
-| `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role serves |
+| `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role **still** serves — the app's own surface CSS is a file under `/styles/` (`style-bundle.ts`) admitted by `'self'`, so a production boot extends the directive with nothing |
 | `script-csp.ts` | the `script-src` sha256 of every inline `<script>` it serves — the hydration runtime, from `@ultimat3/render`'s own `HYDRATE_RUNTIME_BODIES` |
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
@@ -995,6 +1056,12 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `statement-loop.ts` | one verdict → the finding, the panel fact, the overlay notice and the log line |
 | `dev-policy.ts` | which actors to ask about, and which capability each policy gates |
 | `cmd-dev.ts` | boot order, mounting `/_x`, installing the span exporter, the file watcher |
+| `dev-watch.ts` | which paths under the app root `x dev` may not watch: the app's own `.gitignore` (`gitignore.ts`) plus a floor of five directory names an ignore file cannot be relied on to carry — `.git`, `.x`, `node_modules`, `.personal`, `.claude` — every one of them dotted or an install, matched as a path SEGMENT at any depth |
+| `dev-watch-tree.ts` | the watch SET: one `watch(dir, { recursive: false })` per ADMITTED directory, a new directory picked up on `rename`, a removed one giving its descriptor back, and the 30ms trailing debounce |
+| `dev-reload.ts` | one rebuild at a time — a tick arriving mid-build coalesces into ONE trailing rebuild, for the newest file |
+| `gitignore.ts` | what git ignores, as data: parse, the ancestor chain up to the repository, and last-match-wins |
+| `path-segments.ts` | `hasPathSegment` — a directory of that exact name, never a substring of one |
+| `style-bundle.ts` / `style-routes.ts` | a surface's CSS as one content-hashed file under `/styles/`, served `immutable` — `island-bundle.ts` / `island-routes.ts`' shape one asset over. It was an inline `<style>` until 2026-09-06: 156,738 bytes, identical on every page, inside a `private, no-store` document. The URL is the hash alone, no surface in the name: a surface is not a property of the bytes, and an app whose only CSS is its global layer would otherwise write three identical files into its static export and three entries into a precache manifest that has a budget |
 | `mcp-host.ts` | the `DevCapabilities` half of `@ultimat3/mcp`'s `DevHost` — db, tests, logs, verify |
 | `mcp-db-target.ts` | which database the host is pointed at: whether it is a branch, and whether it is production |
 | `mcp-errors.ts` | `errors.explain`: one runnable command per code, typed over `CliErrorCode` |
@@ -1002,6 +1069,44 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `mcp-test-output.ts` | reading `bun test`'s own summary back into a `TestRun` |
 | `cmd-mcp.ts` | `x mcp serve`: the two transports, and the local developer's caller |
 
+**The watch set is a REGISTRATION decision, not a filter, `As of 2026-09-06`.** `watch(root, {
+recursive: true })` takes one inotify descriptor per directory in the tree — measured on `x dev`
+against `examples/dummy`: **110 descriptors, 39 of them (35%) under `.x/` and `node_modules/`**, and
+on a monorepo root **1901, of which 1490 (78%) were `.git/` and `node_modules/`**, where one
+`git status` delivered 5 `.git/index` events into the JS callback. `isIgnoredPath` answered
+correctly every time and answered too late: the kernel queue entry, the callback and the slot out of
+`max_user_watches` (8192 on many distributions) were already spent. Bun 1.4.0's `fs.watch` has no
+ignore option, so `dev-watch-tree.ts` walks the root itself and registers one non-recursive watcher
+per admitted directory, pruning at descent.
+
+**And the ignore set is the app's own `.gitignore`.** Seven hand-listed directory names were wrong
+in both directions. Nothing read the ignore file, so `touch tsconfig.tsbuildinfo` — the file every
+`bun run typecheck` rewrites, named by `x new`'s own scaffolded `.gitignore` — logged
+`reloaded tsconfig.tsbuildinfo in 113ms`, a full `appManifest()` plus `buildIslands()`; on the
+framework root 54 git-ignored directories were unfiltered. And `dist` and `coverage` were matched at
+ANY depth, so an app's own `/dist` or `/coverage` ROUTE never reloaded — silently, which the file's
+own header calls worse than a spurious rebuild. `gitignore.ts` reads it with git's own anchoring
+(unanchored at any depth, a leading `/` or an inner slash where it is written, `!` re-including,
+a trailing `/` directory-only) and walks ANCESTOR ignore files up to the directory holding `.git` —
+`examples/dummy` carries none of its own and every rule about it lives in the repository root's. The
+file is re-read, and the whole watch set re-walked, on any write naming `.gitignore`; nothing ever
+spawns `git check-ignore`. `x new`'s scaffold writes `/dist/` and `/coverage/` **root-anchored** for
+this reason, plus `packages/*/dist/`. It is `fix-path.ts`'s parser, lifted: two readers of one file
+are two answers to what an app committed.
+
+**A watcher event carries no filename when the WATCHED directory itself moves.** Bun's recursive
+watcher delivers `undefined` — not `null` — on `mv myapp myapp2`, a re-clone or a volume remount,
+and `isIgnoredPath(undefined)` threw a `TypeError` inside an fs callback, outside any `try`, with no
+`uncaughtException` handler: `x dev` died with a stack trace. The listener is total over
+`string | Buffer | null | undefined` and logs `dev.watch.unnamed_event` once.
+
+**The reload has an in-flight guard, and it is the state that needed it.** A 45ms drip — a slow
+`git checkout`, a formatter walking files, `x db gen` — measured **40 reloads for 40 files**, each
+launching `Promise.all([appManifest, buildIslands])` while the previous still ran and assigning
+`state.manifest` / `state.islands` in COMPLETION order, so a slower earlier tick could land on top
+of a newer one. `coalesceReloads` (`dev-reload.ts`) keeps the LAST tick that arrived during a
+rebuild and starts exactly one more.
+
 `api-routes.ts` is the app's own API surface, composed **once** and mounted by both `cmd-dev.ts`
 and `serve.ts`: `listActions().map(toRoute)` from `@ultimat3/action` plus
 `listQueries().map(toQueryRoute)` from `@ultimat3/query`. Two lists is how `query.client()`
@@ -1134,8 +1239,20 @@ island's `src` is a string, so no import edge reaches it and the page's graph st
 against bytes. Two islands that both import the same helper each carry a copy; that is the honest
 number for what booting either one costs.
 
-**The chunk URL is content-addressed with render's own `contentHash`** — the function that already
-stamps an ETag and a precache revision. One identity for a byte string, not a third.
+**The chunk URL is SOURCE-addressed, not byte-addressed, `As of 2026-09-06`.** `graphHash` hashes
+the build's inputs — the source map's `sourcesContent`, sorted, plus the entry's app-relative path,
+the framework version and `Bun.version` — with render's own `contentHash`, the function that already
+stamps an ETag and a precache revision. Hashing the OUTPUT is what it did, and `Bun.build` is not
+byte-deterministic under `minify`: measured on 1.4.0, one entry point, no source file touched, a
+131,589-byte island alternated between two outputs of identical length differing only in minified
+identifier names, roughly one build in ten. The URL then flapped — ten names in ten minutes in
+ai-maxxing — so the service worker precached a chunk that 404ed and the `immutable` cache never hit.
+The cost of the alternative was measured and refused: `minify: { identifiers: false }` IS
+deterministic and is +47% raw, +20% gzipped, on every island of every app. `sourcemap: 'external'`
+pays for the input list (277ms against 276ms) and its `//# debugId=` line is stripped, so the
+shipped bytes are unchanged. Two processes can therefore serve two byte strings at one URL — the
+same program under different local names — and a per-file cache keeps ONE process serving one.
+Delete `graphHash` the day `Bun.build` is deterministic.
 
 **`x dev`, the container and the static export all mount the same table.** `serve.ts` builds the
 islands at boot for the same reason it mounts `apiRoutes()`: a seam that works in dev and not in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.1.3",
+  "version": "19.3.1",
   "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": "19.1.3",
-    "@ultimat3/admin": "19.1.3",
-    "@ultimat3/ai": "19.1.3",
-    "@ultimat3/auth": "19.1.3",
-    "@ultimat3/cache": "19.1.3",
-    "@ultimat3/core": "19.1.3",
-    "@ultimat3/db": "19.1.3",
-    "@ultimat3/entity": "19.1.3",
-    "@ultimat3/flags": "19.1.3",
-    "@ultimat3/http": "19.1.3",
-    "@ultimat3/i18n": "19.1.3",
-    "@ultimat3/jobs": "19.1.3",
-    "@ultimat3/mail": "19.1.3",
-    "@ultimat3/manifest": "19.1.3",
-    "@ultimat3/mcp": "19.1.3",
-    "@ultimat3/money": "19.1.3",
-    "@ultimat3/notify": "19.1.3",
-    "@ultimat3/policy": "19.1.3",
-    "@ultimat3/pwa": "19.1.3",
-    "@ultimat3/query": "19.1.3",
-    "@ultimat3/realtime": "19.1.3",
-    "@ultimat3/render": "19.1.3",
-    "@ultimat3/schema": "19.1.3",
-    "@ultimat3/scraping": "19.1.3",
-    "@ultimat3/seo": "19.1.3",
-    "@ultimat3/storage": "19.1.3",
-    "@ultimat3/testing": "19.1.3",
-    "@ultimat3/time": "19.1.3",
+    "@ultimat3/action": "19.3.1",
+    "@ultimat3/admin": "19.3.1",
+    "@ultimat3/ai": "19.3.1",
+    "@ultimat3/auth": "19.3.1",
+    "@ultimat3/cache": "19.3.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/db": "19.3.1",
+    "@ultimat3/entity": "19.3.1",
+    "@ultimat3/flags": "19.3.1",
+    "@ultimat3/http": "19.3.1",
+    "@ultimat3/i18n": "19.3.1",
+    "@ultimat3/jobs": "19.3.1",
+    "@ultimat3/mail": "19.3.1",
+    "@ultimat3/manifest": "19.3.1",
+    "@ultimat3/mcp": "19.3.1",
+    "@ultimat3/money": "19.3.1",
+    "@ultimat3/notify": "19.3.1",
+    "@ultimat3/policy": "19.3.1",
+    "@ultimat3/pwa": "19.3.1",
+    "@ultimat3/query": "19.3.1",
+    "@ultimat3/realtime": "19.3.1",
+    "@ultimat3/render": "19.3.1",
+    "@ultimat3/schema": "19.3.1",
+    "@ultimat3/scraping": "19.3.1",
+    "@ultimat3/seo": "19.3.1",
+    "@ultimat3/storage": "19.3.1",
+    "@ultimat3/testing": "19.3.1",
+    "@ultimat3/time": "19.3.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-boundaries.ts

@@ -18,6 +18,7 @@ import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
 import { quoteArg } from './shell-quote';
 
 export const BOUNDARY_CODES = [
@@ -56,8 +57,16 @@ const isDbSpecifier = (specifier: string): boolean =>
   specifier.endsWith('/db') ||
   /^@[^/]+\/db$/.test(specifier) ||
   specifier === 'drizzle-orm';
+/**
+ * `node:http` and `node:https` are HTTP too, and the anchor could not reach them: `http` had to
+ * follow a `/` or start the string, and a `node:` specifier has a colon there. So the one spelling
+ * that needs no dependency at all — a service reaching straight for the runtime's own client — was
+ * the one spelling this rule could not see. Matched on the boundary character rather than by
+ * listing every prefix, and still anchored at both ends: `node:http2-fake` and
+ * `@ultimat3/https-client` are names, not HTTP.
+ */
 const isHttpSpecifier = (specifier: string): boolean =>
-  specifier === '@ultimat3/http' || /(^|\/)http($|\/)/.test(specifier);
+  specifier === '@ultimat3/http' || /(^|[/:])https?($|\/)/.test(specifier);
 
 /** The transpiler rejects a shebang, and an app's `bin/` entry points legitimately have one. */
 export const stripShebang = (source: string): string =>
@@ -236,7 +245,7 @@ export async function readAppSources(root: string): Promise<readonly SourceFile[
   for (const pattern of APP_GLOBS) {
     const glob = new Bun.Glob(pattern);
     for await (const path of glob.scan({ cwd: root, absolute: false })) {
-      if (path.includes('node_modules') || path.includes('.test.')) continue;
+      if (hasPathSegment(path, 'node_modules') || path.includes('.test.')) continue;
       const posix = path.split('\\').join('/');
       files.push({ path: posix, source: await Bun.file(joinPath(root, posix)).text() });
     }

package/src/app-load.ts

@@ -21,6 +21,7 @@ import '@ultimat3/render/server';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
+import { hasPathSegment } from './path-segments';
 
 /** Every place an app keeps code the framework has to see. */
 const APP_GLOBS = [
@@ -95,7 +96,10 @@ export async function loadApp(root: string): Promise<LoadedApp> {
 
   for (const pattern of APP_GLOBS) {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      // A SEGMENT, never a substring: an app checked out under
+      // `~/dev/node_modules-experiments/myapp` answered `includes('node_modules')` for every
+      // file it holds, so this loop imported none of them and the app registered nothing.
+      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
       if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
         continue;

package/src/app-openapi.ts

@@ -1,12 +1,20 @@
-// `openapi.json`, projected from the action registry by `@ultimat3/action`. The CLI writes the
-// file and compares the bytes; it does not know how an operation is shaped, which is why there
-// is no second OpenAPI builder to drift from the one the server serves.
+// `openapi.json`, projected from the two registries: the actions by `@ultimat3/action`'s
+// `buildOpenApi`, the queries by `@ultimat3/query`'s `queryOpenApiPaths`. The CLI merges the two
+// `paths` maps — those packages are one tier and cannot compose each other — writes the file and
+// compares the bytes; it does not know how an operation is shaped, which is why there is no third
+// OpenAPI builder to drift from the ones the packages serve. Until 2026-09 only the actions were
+// here, and every `GET /_x/query/<name>` the server mounted was a route the spec had never heard of.
 
 import { buildOpenApi, serializeOpenApi } from '@ultimat3/action';
 import type { Manifest } from '@ultimat3/manifest';
+import { queryOpenApiPaths } from '@ultimat3/query';
 
 export const OPENAPI_FILE = 'openapi.json';
 
 /** The exact bytes on disk — deterministic, so `x verify` can compare them literally. */
-export const openApiJson = (manifest: Manifest): string =>
-  serializeOpenApi(buildOpenApi({ title: manifest.app.name, version: manifest.app.version }));
+export const openApiJson = (manifest: Manifest): string => {
+  const document = buildOpenApi({ title: manifest.app.name, version: manifest.app.version });
+  // Action paths are `/api/...`, query paths `/_x/query/...`: disjoint by prefix, so the spread
+  // can never shadow one with the other. `serializeOpenApi` sorts the merged keys.
+  return serializeOpenApi({ ...document, paths: { ...document.paths, ...queryOpenApiPaths() } });
+};

package/src/browser-launcher.ts

@@ -13,6 +13,7 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
+import { CHROME_CANDIDATES } from './cdp-launch';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -56,6 +57,33 @@ export class ShotBrowserMissingError extends UltimateError {
   }
 }
 
+/**
+ * The OTHER half of "no browser": the library is installed and there is no Chrome for it to start.
+ *
+ * The same code as the class above because it is the same question to a reader — `x shot` has no
+ * browser — and a code is a stable public name, not a taxonomy. The cause and the fix are what
+ * differ, and they are the half that is acted on: `bun add -d puppeteer-core` cannot install
+ * Chrome, and `export CHROME_PATH=…` cannot install a client that speaks CDP.
+ *
+ * Raised BEFORE the dev server, which is the whole point of it: the launch that used to report this
+ * happens inside `driver.open()`, one embedded Postgres past the point where the answer was already
+ * decidable from the environment and the filesystem.
+ */
+export class ShotChromeMissingError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_SHOT_BROWSER_MISSING',
+      cause: `x shot launches a browser here and none was named or found — no ${BROWSER_PATH_VARS.join(' or ')} is set, and none of ${CHROME_CANDIDATES.join(', ')} is on disk`,
+      // One literal, for `fix-scan.ts`'s reason — the same rule the class above states. It names an
+      // export rather than an install because a path is the one repair that works whatever the
+      // browser is and wherever the distribution put it; `--cdp-url` is the answer for a box that
+      // will never have one, and it is a flag `x shot` already ships.
+      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome or Chromium binary; a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
+      meta: { tried: [...CHROME_CANDIDATES], vars: [...BROWSER_PATH_VARS] },
+    });
+  }
+}
+
 /**
  * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
  * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
@@ -99,22 +127,43 @@ export interface AppBrowserOptions {
   readonly load?: (path: string) => Promise<unknown>;
 }
 
-/** The path a run will launch, or `undefined` for "let the library find its own". */
+/** True when a named executable is really there — a bad `--browser` is refused before a boot. */
+export const browserBinaryExists = (path: string): boolean => existsSync(path);
+
+/**
+ * The path a run will launch, or `undefined` when this machine has no browser to launch.
+ *
+ * NOT "let the library find its own": `puppeteer-core` ships no browser and has no default, so a
+ * launch with no `executablePath` throws ``An `executablePath` or `channel` must be specified``
+ * from inside somebody else's library, one dev-server boot after the point where the answer was
+ * knowable. So the last step is a PROBE — the same four paths `cdp-launch.ts` already tries for the
+ * e2e driver, imported rather than restated, because two lists of Chrome locations that must agree
+ * is the drift axiom 2 refuses.
+ *
+ * A value NAMED in the flag or the environment is answered without touching the filesystem, even
+ * when nothing is there: an operator who typed a path has a belief about which binary runs, and
+ * silently substituting a probed one would photograph a page in a browser they did not choose.
+ * `shotBrowserChoice` reports that path as absent instead.
+ *
+ * `exists` is the injectable seam, so the probe is asserted the same way on a machine with Chrome
+ * and on one without.
+ */
 export const executablePathFrom = (
   flag: string | undefined,
   env: Readonly<Record<string, string | undefined>>,
+  exists: (path: string) => boolean = browserBinaryExists,
 ): string | undefined => {
   if (flag !== undefined && flag.length > 0) return flag;
   for (const name of BROWSER_PATH_VARS) {
     const value = env[name];
     if (value !== undefined && value.length > 0) return value;
   }
+  for (const candidate of CHROME_CANDIDATES) {
+    if (exists(candidate)) return candidate;
+  }
   return undefined;
 };
 
-/** True when a named executable is really there — a bad `--browser` is refused before a boot. */
-export const browserBinaryExists = (path: string): boolean => existsSync(path);
-
 /** The endpoint a run will attach to, or `undefined` for "launch one here". */
 export const cdpUrlFrom = (
   flag: string | undefined,

package/src/budgets.ts

@@ -12,6 +12,7 @@ import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
+import type { UnmeasuredRoute } from './static-report';
 
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
@@ -87,14 +88,52 @@ function unmeasuredFinding(url: string, declared: string, built: boolean): Findi
   };
 }
 
+/**
+ * The ONE code a failed measurement is reported under by its own name rather than as
+ * `X_BUDGET_UNMEASURED`. Its cause is complete — the island, the prop, its bytes, the cap — and
+ * its fix is an edit to the page, so the step's own "run x build and read the list" would put a
+ * second command between the author and a sentence the build had already composed. Every other
+ * render failure keeps the generic finding: a `TypeError` from a `load` that wanted a request is
+ * a reason to read the report, not an instruction.
+ *
+ * ONE code and not "any coded error", deliberately. `X_NO_CONTEXT`, `X_UNAUTHENTICATED` and
+ * `X_DB_UNAVAILABLE` from a measurement render are facts about the BUILD's environment, and
+ * reporting them under their own codes would tell the author to fix a database the gate never
+ * had. The list grows by a decision, per code, here.
+ */
+const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set(['X_ISLAND_PROPS_INVALID']);
+
+/**
+ * The build's own finding for a route it could not weigh, when that failure is an instruction.
+ * Read off the static report's `unmeasured` list — the same list `X_BUDGET_UNMEASURED`'s `fix:`
+ * sends its reader to, now read by the step itself for the one code it can act on.
+ */
+function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Finding | undefined {
+  const entry = unmeasured.find((one) => one.path === url);
+  if (entry?.code === undefined || !REPORTED_BY_OWN_CODE.has(entry.code)) return undefined;
+  return {
+    code: entry.code,
+    cause: entry.cause ?? entry.reason,
+    fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}
+
 /**
  * `undefined` stats means no build has run; `{ routes: [] }` means one ran and emitted nothing.
  * The parameter is widened rather than defaulted, because collapsing the two here is exactly the
  * distinction the finding above exists to make.
+ *
+ * `unmeasured` is the static report's list of routes the build rendered and could not weigh, with
+ * each failure's code when it had one. Optional because the report is written beside the stats
+ * and can be absent for the same reason; with it, a route whose measurement failed on a code in
+ * `REPORTED_BY_OWN_CODE` is reported under that code, with the build's own cause and fix.
  */
 export function checkBudgets(
   manifest: Manifest,
   stats: BuildStats | undefined,
+  unmeasured: readonly UnmeasuredRoute[] = [],
 ): readonly Finding[] {
   const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
   const findings: Finding[] = [];
@@ -104,7 +143,10 @@ export function checkBudgets(
     const lcp = route.budget?.lcp;
     if (measured === undefined) {
       if (js !== null || lcp !== undefined) {
-        findings.push(unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined));
+        findings.push(
+          ownCodeFinding(route.url, unmeasured) ??
+            unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined),
+        );
       }
       continue;
     }
@@ -185,9 +227,24 @@ export interface MeasuredJs {
 export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
   let jsBytes = 0;
   const entries: MeasuredEntry[] = [];
+  // Deduped ONCE, across both readers below, and the unit is the FETCH: a browser downloads a URL
+  // once however many times the document names it, so `budget.js` — a byte budget — counts it
+  // once. Two instances of one island are two wrappers and one chunk; so are a `<script src>`
+  // repeated by a page and its layout, and a src that is also an island entry. Only the island
+  // half was deduped, so a document naming one script twice was charged twice and could fail a
+  // budget it clears.
+  //
+  // EXECUTION is a different count and this is deliberately not it. A repeated classic
+  // `<script src>` runs once per element (a module runs once per document, off the module map), so
+  // the layout-plus-page case above really does execute twice — for zero extra bytes. That is a
+  // CPU cost, and this gate is a bound on what the browser downloads and parses. An INLINE script
+  // is not in this set for the same reason: two identical inline bodies are two copies of the
+  // bytes in the document, so both are charged.
+  const fetched = new Set<string>();
   const weigh = async (url: string): Promise<void> => {
     // Only a path inside the artifact can be weighed; a cross-origin script is not this build's.
-    if (!url.startsWith('/')) return;
+    if (!url.startsWith('/') || fetched.has(url)) return;
+    fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
     const bytes = (await file.exists()) ? file.size : 0;
     entries.push({ url, bytes });
@@ -204,13 +261,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     }
     await weigh(src);
   }
-  // Deduped: two instances of one island are two wrappers and one chunk, and a browser that
-  // imports the same module twice fetches and executes it once.
-  const booted = new Set<string>();
   for (const match of html.matchAll(ENTRY_ATTR)) {
     const url = match.groups?.['url'];
-    if (url === undefined || booted.has(url)) continue;
-    booted.add(url);
+    if (url === undefined) continue;
     await weigh(url);
   }
   return { jsBytes, entries };