@ultimat3/cli 1.2.0 → 3.0.0

package/README.md

@@ -11,17 +11,23 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
 | `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
 | `x build --target docker\|binary\|static` | one artifact | `ROLE` selects behaviour at start |
-| `x verify` | **the gate** | 16 named steps, each with pass/fail + duration |
+| `x verify` | **the gate** | 17 named steps, each with pass/fail + duration |
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
-| `x db gen\|migrate\|reset\|studio\|branch` | everything DB | `branch` = copy-on-write clone + preview URL |
+| `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
 | `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
 | `x doctor` | environment, ports, drift, PWA prerequisites | every finding carries a fix command |
 | `x deploy` | container deploy plan | compose or helm; zero platform primitives |
 | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
 | `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `describe <name>`, straight off the registries |
-| `x jobs ls\|show\|retry\|drain` | the queue | depth, dead letters, step traces, `retry --from-step`, `drain --to` |
+| `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` |
+| `x jobs ls\|show\|retry\|cancel\|drain` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`, `drain --to` |
 | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
-| `x errors explain <CODE>` | the error table, programmatically | refuses an unregistered code instead of inventing one |
+| `x env check\|example` | the typed environment `envSchema` declares | and the `.env.example` rendered from it |
+| `x secrets show\|init\|edit\|set\|rotate` | the committed encrypted secrets | decrypted into the `envSchema` variables of the same names |
+| `x policy list\|explain <subject>` | which clause decided a permission, and why | five packages print `x policy explain` as a denial's `fix:` |
+| `x i18n check\|add\|sync` | catalogs: gaps, a new locale, key sync | all three of i18n's own error fixes name it |
+| `x errors explain <CODE>` / `list` | the error table, programmatically | refuses an unregistered code instead of inventing one |
+| `x docs "<question>"` | the framework docs, offline | answered from the installed packages, never the network |
 | `x fix boundary <file>` | the minimal cut for a crossed surface boundary | prints the plan and the `git mv`; never rewrites a file |
 
 Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is also in the registry
@@ -41,28 +47,46 @@ X_DB_DRIFT: schema differs from migrations
 
 ```sh
 x verify --json
-# {"ok":false,"command":"verify","summary":"1 of 16 steps failed","steps":[...]}
+# {"ok":false,"command":"verify","summary":"1 of 17 steps failed","steps":[...]}
 ```
 
 ## `x verify` steps
 
 `typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
-contract-diff budgets manifest`
+contract-diff budgets manifest roadmap`
 
-One list, in cost order, defined once in `cmd-verify.ts` — the framework repo's own gate
-(`bun run verify`) runs exactly it. A step with nothing to check here reports as skipped, never as
+Seventeen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+count above is projected from that list, and the framework repo's own gate (`bun run verify`)
+runs exactly it. A step with nothing to check here reports as skipped, never as
 passed. Never bails early: an agent fixing three things needs all three findings from one run.
 There is no `--only` and no `--skip`; the exit code is non-zero if any step fails.
 
+A committed `x.verify.json` is the floor, `As of 2026-08`: it names the steps this repo has already
+proved it can run, and a step it names that reports nothing is `X_VERIFY_SUITE_VANISHED` rather
+than a skip.
+"Nothing" is both ways a suite disappears — no files at all, and every test in the files it found
+skipping itself, which is read back out of `bun test`'s own summary. `x new` writes one.
+
+An app extends the gate with its own conventions, never with its own step: a file in `guards/`
+exports a `guard` whose `check(root)` returns `Finding[]`, and the `boundaries` step runs every one
+of them. Nothing registers a guard — the directory is the registration — and what a guard returns
+is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUARD_FAILED`,
+`X_GUARD_FINDING_INVALID`). `x g guard <name>` scaffolds one with its test.
+
 ## Layout
 
 | File | Responsibility |
 |---|---|
 | `bin.ts` | argv, stdout, exit code — nothing else |
+| `write-line.ts` | the synchronous fd-1 write both published entry points use (`create-ultimate`'s too) |
 | `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 |
+| `guards.ts` | the app's own conventions: `guards/` discovered, run, and held to the error contract |
 | `cmd-*.ts` | one command group each |
 | `templates/` | scaffolding as typed string modules, not copied fixtures |
 | `app-load.ts` | import an app's modules so the framework registries hold it |
@@ -70,7 +94,13 @@ There is no `--only` and no `--skip`; the exit code is non-zero if any step fail
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
 | `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
+| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it |
+| `prerender.ts` | `x build --target static`: which `site/` routes qualify, and where the bytes land |
+| `metrics-endpoint.ts` | the `METRICS_PATH` scrape listener every role opens, on `METRICS_PORT` |
+| `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `dev-*.ts` | what `x dev` boots: services, runtime, routes, hooks, roles, the `/_x` mount |
+| `island-bundle.ts` | every `*.island.tsx` built as its own entry point, content-hashed |
+| `island-routes.ts` | the one route those chunks are served from, in dev and in the container |
 | `mcp-host.ts` | the shell-side half of `@ultimat3/mcp`'s dev server — db, tests, logs, verify |
 | `verify-step.ts` | the step shape, the step names, the host-check hook |
 | `verify-tests.ts` | one `bun test` invocation per test type |
@@ -90,6 +120,9 @@ no second OpenAPI builder and no second surface-boundary walk anywhere in this p
 apps/web/app/<feature>/{entity,repo,service,policy,errors,ui}.ts
 apps/web/app/<feature>/{actions,queries,live,jobs,tasks}/<name>.ts
 apps/web/{site,app}/<path>/page.tsx
+apps/web/{site,app}/<path>/<name>.island.tsx     # x g island <name> --at <dir>
+apps/admin/src/pages/<name>.tsx                  # x g admin:page <name> --permission p
+guards/<name>.ts                                 # x g guard <name>
 ```
 
 Every emitted source has a `<file>.test.ts` beside it that passes on the first run.
@@ -97,4 +130,4 @@ Every emitted source has a `<file>.test.ts` beside it that passes on the first r
 ## Errors
 
 `X_CLI_UNKNOWN_COMMAND` `X_CLI_BAD_FLAG` `X_VERIFY_FAILED` `X_NOT_IN_APP` `X_BUN_VERSION`
-`X_NOT_IMPLEMENTED`
+`X_NOT_IMPLEMENTED` `X_GUARD_INVALID` `X_GUARD_FAILED` `X_GUARD_FINDING_INVALID`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -34,27 +35,28 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "1.2.0",
-    "@ultimat3/admin": "1.2.0",
-    "@ultimat3/ai": "1.2.0",
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/db": "1.2.0",
-    "@ultimat3/entity": "1.2.0",
-    "@ultimat3/http": "1.2.0",
-    "@ultimat3/i18n": "1.2.0",
-    "@ultimat3/jobs": "1.2.0",
-    "@ultimat3/mail": "1.2.0",
-    "@ultimat3/manifest": "1.2.0",
-    "@ultimat3/mcp": "1.2.0",
-    "@ultimat3/policy": "1.2.0",
-    "@ultimat3/pwa": "1.2.0",
-    "@ultimat3/query": "1.2.0",
-    "@ultimat3/realtime": "1.2.0",
-    "@ultimat3/render": "1.2.0",
-    "@ultimat3/seo": "1.2.0",
-    "@ultimat3/storage": "1.2.0",
-    "@ultimat3/testing": "1.2.0",
-    "@ultimat3/time": "1.2.0"
+    "@ultimat3/action": "3.0.0",
+    "@ultimat3/admin": "3.0.0",
+    "@ultimat3/ai": "3.0.0",
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/entity": "3.0.0",
+    "@ultimat3/http": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/mail": "3.0.0",
+    "@ultimat3/manifest": "3.0.0",
+    "@ultimat3/mcp": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/pwa": "3.0.0",
+    "@ultimat3/query": "3.0.0",
+    "@ultimat3/realtime": "3.0.0",
+    "@ultimat3/render": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/seo": "3.0.0",
+    "@ultimat3/storage": "3.0.0",
+    "@ultimat3/testing": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/api-routes.ts

@@ -0,0 +1,16 @@
+// The app's API over HTTP, composed once: the write half `@ultimat3/action` projects and the read
+// half `@ultimat3/query` projects. `x dev` and `serve.ts` both mount THIS rather than each listing
+// the registries themselves — two lists is how `query.client()` shipped deriving `/_x/query/<kebab>`
+// against a route neither file mounted, compiling everywhere and 404ing everywhere.
+
+import { listActions, toRoute } from '@ultimat3/action';
+import type { Route } from '@ultimat3/http';
+import { listQueries, toQueryRoute } from '@ultimat3/query';
+
+/**
+ * Whatever loading the app's modules put in the two registries, as routes. Read at call time,
+ * never at import: importing the app IS the registration, and it happens after this module loads.
+ */
+export function apiRoutes(): readonly Route[] {
+  return [...listActions().map(toRoute), ...listQueries().map(toQueryRoute)];
+}

package/src/app-auth.ts

@@ -0,0 +1,32 @@
+// The one fact `x dev` and `serve.ts` need out of `app.config.ts` before a listener binds: where
+// this app's sign-in page is. Sibling of `app-env.ts`'s `loadEnvSchema`, and imports the config
+// for the same reason — a regex over the app's source is the pattern `app-load.ts` refuses.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
+export const APP_CONFIG_EXPORT = 'config';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * `auth.signInPath`, or `null` when the app declares none.
+ *
+ * Structural, not `instanceof`: `defineConfig` returns a plain object, and a config that resolved
+ * through an older version of core simply has no `auth` section. `null` is the safe answer either
+ * way — it is what turns the browser redirect off and leaves the problem document in place.
+ */
+export async function loadSignInPath(root: string): Promise<string | null> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!existsSync(configPath)) return null;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return null;
+  const auth = config['auth'];
+  if (!isRecord(auth)) return null;
+  const path = auth['signInPath'];
+  return typeof path === 'string' && path.startsWith('/') ? path : null;
+}

package/src/app-entities.ts

@@ -0,0 +1,18 @@
+// How many entities an app declares, answered the way this package answers every question about a
+// primitive: load the app, then project the registry — never a scan of the source. An entity may be
+// declared anywhere `loadApp` reaches, so a text rule over `packages/db/src` would miss the ones
+// that are not there and mistake a type-only import for a declaration.
+
+import { describeEntities } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+
+/**
+ * A module that will not import registers nothing, so a broken app answers with a SHORT count and
+ * never a throw — `loadApp` collects import failures as findings rather than raising them. Callers
+ * must therefore read a zero as "nothing is declared *that this process could load*", which is why
+ * the one caller uses it to go quiet rather than to accuse.
+ */
+export async function countDeclaredEntities(root: string): Promise<number> {
+  await loadApp(root);
+  return describeEntities().length;
+}

package/src/app-env.ts

@@ -0,0 +1,103 @@
+// The app's typed environment as the CLI sees it: the `defineEnv` declaration read back out of
+// `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
+// declaration, both files (axiom 2) — nothing here holds a second list of variable names.
+
+// Bun ships no equivalent: `existsSync` answers whether this root is an app, `join` builds the
+// host-separator path to the two files this module reads.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
+import { checkEnvExample, ENV_EXAMPLE_PATH, renderEnvExample } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/**
+ * The one export name the CLI looks for. `defineEnv()` returns the resolved VALUES, so the
+ * declaration it validated is unreachable from its result — an app that wants `.env.example`,
+ * `x env check` and the drift gate names the record it passed in:
+ *
+ * ```ts
+ * export const envSchema = { DATABASE_URL: { type: 'url', … } } satisfies EnvSchema;
+ * export const env = defineEnv(envSchema);
+ * ```
+ *
+ * An app that exports no `envSchema` declares no environment, so there is nothing to project and
+ * nothing to drift — every check here reports nothing rather than inventing a requirement.
+ */
+export const ENV_SCHEMA_EXPORT = 'envSchema';
+
+const ENV_TYPES = new Set(['string', 'url', 'number', 'integer', 'port', 'boolean', 'enum']);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isDecl = (value: unknown): value is EnvVarDecl =>
+  isRecord(value) && typeof value['type'] === 'string' && ENV_TYPES.has(value['type']);
+
+/** Structural, not `instanceof`: the schema is a plain record the app authored, never a class. */
+export const isEnvSchema = (value: unknown): value is EnvSchema =>
+  isRecord(value) && Object.values(value).every(isDecl);
+
+/**
+ * Import `app.config.ts` and hand back the declaration it exports. Importing is the only honest
+ * way to read it — the alternative is a regex over the app's source, which is the pattern
+ * `app-load.ts` exists to refuse. `undefined` means "this root declares no environment"; a config
+ * that will not import throws, and the caller turns that into the finding.
+ */
+export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!existsSync(configPath)) return undefined;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const declared = module[ENV_SCHEMA_EXPORT];
+  if (declared === undefined) return undefined;
+  return isEnvSchema(declared) ? declared : undefined;
+}
+
+/** The bytes `.env.example` must hold. Deterministic, so a rewrite that changes nothing diffs to nothing. */
+export const envExampleFor = (schema: EnvSchema): string => renderEnvExample(schema);
+
+const driftFinding = (cause: string): Finding => ({
+  code: 'X_ENV_EXAMPLE_DRIFT',
+  cause,
+  // The generator, not the assertion: `assertEnvExample`'s own fix is a `Bun.write(…)` call for
+  // an app that has a schema object in scope, and a gate reader has a shell.
+  fix: 'x env example',
+  docs: 'https://ultimate.dev/errors/X_ENV_EXAMPLE_DRIFT',
+  at: ENV_EXAMPLE_PATH,
+});
+
+/**
+ * The gate half. Byte-exact against the projection, not just "every key is present somewhere":
+ * the example carries each variable's description, whether it is required and its default, and a
+ * key-only rule would let all three rot while the file still passed. Missing keys are still called
+ * out by name first, because that is the failure a reader can act on without diffing.
+ */
+export async function envExampleFindings(root: string): Promise<readonly Finding[]> {
+  let schema: EnvSchema | undefined;
+  try {
+    schema = await loadEnvSchema(root);
+  } catch (error) {
+    return [{ ...findingFrom(error), at: APP_CONFIG_FILE }];
+  }
+  if (schema === undefined) return [];
+  const expected = envExampleFor(schema);
+  const file = Bun.file(join(root, ENV_EXAMPLE_PATH));
+  if (!(await file.exists())) {
+    return [
+      driftFinding(
+        `${ENV_EXAMPLE_PATH} does not exist and ${ENV_SCHEMA_EXPORT} declares ${Object.keys(schema).length} variable(s)`,
+      ),
+    ];
+  }
+  const text = await file.text();
+  if (text === expected) return [];
+  const report = checkEnvExample(schema, text);
+  return [
+    driftFinding(
+      report.missing.length > 0
+        ? `${ENV_EXAMPLE_PATH} does not declare ${report.missing.join(', ')}, declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`
+        : `${ENV_EXAMPLE_PATH} is no longer the projection of ${ENV_SCHEMA_EXPORT} — a description, a default or the required flag has moved`,
+    ),
+  ];
+}

package/src/app-load.ts

@@ -10,7 +10,7 @@ import { registerActions } from '@ultimat3/action';
 import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
-import { isRouteConfig, registerRoute } from '@ultimat3/render';
+import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -31,6 +31,14 @@ const APP_GLOBS = [
  */
 const ENTRY_POINT = /^apps\/[^/]+\/(?:server|prerender)\.tsx?$/;
 
+/**
+ * A `*.island.tsx` is a CLIENT entry point and is deliberately not imported here. It registers no
+ * primitive — a page names it by specifier, never by import — and importing it would put the one
+ * module the framework guarantees is outside the server's graph inside this process's, where a
+ * top-level `document` reference takes the whole scan down (axiom 6).
+ */
+const CLIENT_ENTRY_POINT = /\.island\.tsx$/;
+
 export interface LoadedApp {
   readonly root: string;
   /** App-root-relative POSIX paths of every module that imported, sorted. */
@@ -73,7 +81,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
       if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
-      if (ENTRY_POINT.test(file)) continue;
+      if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file)) continue;
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;
@@ -114,7 +122,16 @@ async function register(
       // The build counts boundaries from the compiled JSX; before a build there is only the
       // source, and `render: 'stream'` is rejected without one — so count them in the text.
       const source = await Bun.file(absolute).text();
-      registerRoute({ file, config, suspenseBoundaries: countSuspense(source) });
+      // The page component comes from the same module as its config, resolved by render's own
+      // rule — the CLI does not decide which export is a page any more than it decides what a
+      // route is. A module with no component registers without one, and renders a bare shell.
+      const component = pageComponentOf(module);
+      registerRoute({
+        file,
+        config,
+        suspenseBoundaries: countSuspense(source),
+        ...(component === undefined ? {} : { component }),
+      });
     }
     registerActions(module);
     registerQueries(module);

package/src/bin.ts

@@ -3,15 +3,16 @@
 // dispatch.ts, so the whole CLI is testable without spawning a process.
 
 import { dispatch } from './dispatch';
+// The write itself is `write-line.ts`: `create-ultimate`'s entry point needs the identical one,
+// and a second copy of a note about pipe truncation is a second copy that drifts.
+import { writeLine } from './write-line';
 
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),
   env: Bun.env,
   bunVersion: Bun.version,
-  write: (line) => {
-    process.stdout.write(`${line}\n`);
-  },
+  write: writeLine,
 });
 
 process.exit(code);

package/src/budgets.ts

@@ -44,8 +44,44 @@ function declaredBudgets(js: number | null, lcp: number | undefined): string {
  * finding, never a pass: a route that clears the gate without ever being weighed is exactly the
  * false green axiom 5 exists to prevent. Only a route that declares nothing is skipped.
  */
-export function checkBudgets(manifest: Manifest, stats: BuildStats): readonly Finding[] {
-  const byPath = new Map(stats.routes.map((route) => [route.path, route]));
+/**
+ * Two ways a budget goes unweighed, and they are not one instruction.
+ *
+ * `undefined` stats is "no build has ever run in this repo" — one command closes every route at
+ * once, and `.x/` is gitignored, so this is the state a fresh clone and a fresh scaffold are in.
+ * A stats file that exists and has no row for this route is the other thing entirely: a build DID
+ * run and could not weigh this one, which is `PrerenderReport.unmeasured`'s question and not a
+ * second build's. Reporting the first as the second is what sends a reader to re-run a build that
+ * already did everything it was going to do.
+ */
+function unmeasuredFinding(url: string, declared: string, built: boolean): Finding {
+  return {
+    code: 'X_BUDGET_UNMEASURED',
+    cause: built
+      ? `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} has no row for it, so the build ran and could not weigh it`
+      : `${url} declares a ${declared} budget and no build has written ${BUILD_STATS_FILE} in this repo`,
+    // `--target static` is load-bearing and `x build` alone was a fix that changes nothing: the
+    // flag defaults to `docker`, and only the static target runs `apps/web/prerender.ts`, which is
+    // the one caller of `writeBuildStats`. When a build already ran, the second half is where the
+    // answer is — the report names every route it could not weigh, and why.
+    fix: built
+      ? `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`
+      : 'x build --target static --json && x verify --json',
+    docs: 'https://ultimate.dev/errors/X_BUDGET_UNMEASURED',
+    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.
+ */
+export function checkBudgets(
+  manifest: Manifest,
+  stats: BuildStats | undefined,
+): readonly Finding[] {
+  const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
   const findings: Finding[] = [];
   for (const route of manifest.routes) {
     const measured = byPath.get(route.url);
@@ -53,13 +89,7 @@ export function checkBudgets(manifest: Manifest, stats: BuildStats): readonly Fi
     const lcp = route.budget?.lcp;
     if (measured === undefined) {
       if (js !== null || lcp !== undefined) {
-        findings.push({
-          code: 'X_BUDGET_UNMEASURED',
-          cause: `${route.url} declares a ${declaredBudgets(js, lcp)} budget but ${BUILD_STATS_FILE} has no entry for it`,
-          fix: 'x build && x verify',
-          docs: 'https://ultimate.dev/errors/X_BUDGET_UNMEASURED',
-          at: route.url,
-        });
+        findings.push(unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined));
       }
       continue;
     }
@@ -90,3 +120,98 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
   if (!existsSync(path)) return undefined;
   return (await Bun.file(path).json()) as BuildStats;
 }
+
+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
+ * never for the code that runtime boots. The entry attribute is that module URL, so it is read as
+ * exactly what it is: a file the browser will execute.
+ */
+const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
+
+/** One executable module the document names, and what it weighs on disk. */
+export interface MeasuredEntry {
+  readonly url: string;
+  readonly bytes: number;
+}
+
+export interface MeasuredJs {
+  readonly jsBytes: number;
+  /** Every `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
+  readonly entries: readonly MeasuredEntry[];
+}
+
+/**
+ * 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.
+ */
+export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
+  let jsBytes = 0;
+  const entries: MeasuredEntry[] = [];
+  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;
+    const file = Bun.file(join(out, url.slice(1)));
+    const bytes = (await file.exists()) ? file.size : 0;
+    entries.push({ url, bytes });
+    jsBytes += bytes;
+  };
+
+  for (const match of html.matchAll(SCRIPT_TAG)) {
+    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;
+    }
+    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);
+    await weigh(url);
+  }
+  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.
+ */
+export async function writeBuildStats(root: string, stats: BuildStats): Promise<string> {
+  const path = join(root, BUILD_STATS_FILE);
+  await Bun.write(path, `${JSON.stringify(stats, null, 2)}\n`);
+  return path;
+}