@ultimat3/cli 6.0.0 → 8.0.0

package/src/runtime-overrides.ts

@@ -8,7 +8,7 @@ import type { PurgeDriver } from '@ultimat3/cache';
 import type { Middleware, RateLimitStore } from '@ultimat3/http';
 import type { JobDriver } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
-import type { SyncAuthenticator, Transport } from '@ultimat3/realtime';
+import type { SyncAuthenticator, Transport } from '@ultimat3/realtime/server';
 import type { IsrStore } from '@ultimat3/render';
 import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
@@ -45,6 +45,11 @@ export interface RuntimeOverrides {
    * Where the HTTP rate limiter keeps its counters. It also DECIDES `rateLimit.scope`: a store
    * that says `'shared'` is a deployment declaring fleet-wide numbers, and `assertRateLimitScope`
    * holds the two halves together rather than a literal in the boot contradicting the store.
+   *
+   * Omitted, the boot installs `postgresRateLimitStore` over the pool it already opened
+   * (`startServices`) — so this replaces a SHARED default, not an absent one. A store whose scope
+   * is `'process'` is legal and warned about: it is every declared limit enforced once per
+   * replica, and `docker/helm/values.yaml` runs three.
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
@@ -59,8 +64,11 @@ export interface RuntimeOverrides {
   readonly images?: ImageTransformDriver;
   /**
    * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted
-   * — this field exists because that adapter can only ever answer `{ actor }`, and a real
-   * deployment's token has an `expiresAt` and a `refresh`, which is the whole of re-authorization.
+   * — and that adapter now carries `expiresAt` and `refresh` of its own (`SYNC_GRANT_TTL_MS`),
+   * re-asking the app's resolver with the upgrade's own `cookie`/`authorization`. So this field is
+   * no longer the only way to get re-authorization; it is how a deployment states a window the
+   * credential itself declares (a token's `exp`), or resolves identity from a header the adapter
+   * deliberately does not retain per socket.
    */
   readonly syncAuthenticate?: SyncAuthenticator;
 }

package/src/shot-settle.ts

@@ -0,0 +1,57 @@
+// When a shot may be TAKEN: the two rules that decide whether the page has finished hydrating,
+// separated from both the command that drives a browser and the verdict that judges what came
+// back. Plain values and an injected sleep, so the whole loop is proved with neither.
+
+import type { IslandCount } from './shot-verdict';
+
+/**
+ * When there is nothing left to wait for. `booted` counts the islands whose chunk the runtime
+ * ASKED for; `mounted` and `failed` are the two ways that request can end — so the outcome of
+ * every boot exists exactly when they add up to it. An island that never booted is not something
+ * to wait for (`visible` with nothing scrolled to it, `never` by declaration), and `null` is "the
+ * page answered no probe", which no amount of waiting turns into an answer.
+ */
+export const islandsSettled = (islands: IslandCount | null): boolean =>
+  islands === null || islands.mounted + islands.failed >= islands.booted;
+
+/**
+ * How often the island probe is re-read while the page settles. Short enough that a page whose
+ * mounts have already resolved pays one extra read and nothing else.
+ */
+export const SETTLE_POLL_MS = 100;
+
+export interface SettleOptions {
+  /** The extra budget a mount gets AFTER the boot deadline. Bounded: a picture is still owed. */
+  readonly windowMs: number;
+  readonly pollMs: number;
+  /** Injected by the test, so the poll is proved without spending its own window in real time. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+/**
+ * Read the probe until every booted island has settled, or the window runs out.
+ *
+ * `DEFAULT_SETTLE_MS` is the deadline at which the hydration runtime CALLS `import()` — `mounted`
+ * and `failed` land after it — so a single read at that instant reports `mounted: 0` for a page
+ * that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
+ * is the only shape that ends EARLY on a fast page and still bounds a slow one.
+ *
+ * A `null` answer never overwrites a real count: `null` means "not counted", and a probe that
+ * fails once would otherwise turn a page with islands into a page reported to have none.
+ */
+export async function settleIslands(
+  probe: () => Promise<IslandCount | null>,
+  options: SettleOptions,
+): Promise<IslandCount | null> {
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  let answer = await probe();
+  let waited = 0;
+  while (!islandsSettled(answer) && waited < options.windowMs) {
+    // At least 1ms, or a `pollMs` of zero is a loop with no exit while the window stands.
+    const step = Math.max(1, Math.min(options.pollMs, options.windowMs - waited));
+    await sleep(step);
+    waited += step;
+    answer = (await probe()) ?? answer;
+  }
+  return answer;
+}

package/src/shot-verdict.ts

@@ -0,0 +1,360 @@
+// What a shot CLAIMS, and what it refuses to claim: the verdict `x shot` writes beside the
+// picture, built from plain values so every rule here is testable with no browser, no dev server
+// and no `ParsedArgs` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
+
+import { probeImage } from '@ultimat3/core';
+import { ISLAND_FAILED_ATTRIBUTE, ISLAND_MOUNTED_ATTRIBUTE } from '@ultimat3/render';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { t, validate } from '@ultimat3/schema';
+import type { ConsoleLine, NetworkEntry, PageError } from '@ultimat3/scraping';
+import { msg } from './messages';
+import type { JsonValue } from './output';
+
+/**
+ * The one expression that counts islands, and it counts TWO different facts because they are two
+ * different facts. `data-x-island` is emitted by `emitIslandAttributes` for every island on the
+ * page including `hydrate: 'never'`, so its presence means "the server rendered an island here"
+ * and nothing about the client. `el.__x` is the boot promise `hydrateRuntime`'s prelude assigns
+ * (`el.__x=import(e).then(…)`), so it means "the runtime asked for this island's chunk" — still
+ * not "mount() resolved", which nothing in the DOM records today.
+ *
+ * An expression, never a closure: `CdpPageLike.evaluate` takes the string form only.
+ */
+/** Every key this command renders. `msg()` answers `⟦key⟧` for a miss, which no build can see. */
+export const SHOT_MESSAGE_KEYS = [
+  'cli.shot.ok',
+  'cli.shot.errors',
+  'cli.shot.redirected',
+  'cli.shot.picture',
+  'cli.shot.verdict',
+  'cli.shot.server.booted',
+  'cli.shot.server.reused',
+  'cli.shot.canvas',
+  'cli.shot.canvasUnreadable',
+  'cli.shot.islands',
+  'cli.shot.islandsUnknown',
+  'cli.shot.islandFailed',
+  'cli.shot.network',
+  'cli.shot.console',
+  'cli.shot.threw',
+  'cli.shot.pageError',
+  'cli.shot.blind.status',
+] as const;
+
+/**
+ * Four facts, not one, because they are genuinely different and conflating them is what makes a
+ * screenshot tool lie. `declared` is server-rendered and says nothing about the client.
+ * `booted` means the runtime CALLED `import()` — set before `mount()` settles, and legitimately
+ * absent for a `visible` or `interaction` island nothing has scrolled to or clicked. `mounted` and
+ * `failed` are the outcome, marked by the prelude itself when the mount promise settles.
+ *
+ * The attribute names are INTERPOLATED from `@ultimat3/render`'s own exports rather than typed
+ * here: this probe and the runtime that writes the markers have to agree, and a second spelling of
+ * `data-x-mounted` would read as "no island mounted" — a clean-looking answer that is wrong.
+ */
+export const ISLAND_PROBE =
+  '(function(){var els=document.querySelectorAll("[data-x-island]");var by={};var booted=0;' +
+  'var mounted=0;var failed=0;var failures=[];' +
+  'for(var i=0;i<els.length;i+=1){var el=els[i];' +
+  'var s=el.getAttribute("data-x-hydrate")||"unknown";by[s]=(by[s]||0)+1;' +
+  'if(el.__x!==undefined)booted+=1;' +
+  `if(el.hasAttribute("${ISLAND_MOUNTED_ATTRIBUTE}"))mounted+=1;` +
+  `if(el.hasAttribute("${ISLAND_FAILED_ATTRIBUTE}")){failed+=1;failures.push({` +
+  'island:el.getAttribute("data-x-island")||"",' +
+  `message:el.getAttribute("${ISLAND_FAILED_ATTRIBUTE}")||''});}}` +
+  'return{declared:els.length,booted:booted,mounted:mounted,failed:failed,' +
+  'byStrategy:by,failures:failures};})()';
+
+export interface IslandCount {
+  /** `[data-x-island]` in the served DOM — server-rendered, whatever the client then did. */
+  readonly declared: number;
+  /** Islands whose chunk the hydration runtime asked for. See `ISLAND_PROBE` for the distance. */
+  readonly booted: number;
+  /** Islands whose `mount()` RESOLVED. This is the one that answers "does the page work". */
+  readonly mounted: number;
+  /** Islands whose `mount()` REJECTED — the case a picture can never show. */
+  readonly failed: number;
+  /** `data-x-hydrate` value → count, so a `never` island is never read as a failure to boot. */
+  readonly byStrategy: Readonly<Record<string, number>>;
+  /** Which island threw, and what it said. Empty when `failed` is 0. */
+  readonly failures: readonly IslandFailure[];
+}
+
+export interface IslandFailure {
+  readonly island: string;
+  readonly message: string;
+}
+
+const islandProbeSchema: StandardSchemaV1<unknown, IslandCount> = t.object({
+  declared: t.number,
+  booted: t.number,
+  mounted: t.number,
+  failed: t.number,
+  byStrategy: t.record(t.number),
+  failures: t.array(t.object({ island: t.string, message: t.string })),
+}) as unknown as StandardSchemaV1<unknown, IslandCount>;
+
+/**
+ * `evaluate()` answers `unknown` on every driver — a page can return anything at all — so the
+ * probe's result is PARSED and never cast. `null` for anything that does not fit, because a
+ * malformed probe must not be able to take a capture down after the picture was already taken.
+ */
+export function parseIslandProbe(value: unknown): IslandCount | null {
+  const result = validate(islandProbeSchema, value);
+  return result.issues === undefined ? result.value : null;
+}
+
+export interface ShotCanvas {
+  readonly width: number;
+  readonly height: number;
+  readonly format: string;
+}
+
+/**
+ * The picture's own pixel size, read from the header bytes by `@ultimat3/core`'s one image probe —
+ * never a viewport number the tool asked for and cannot prove it got. `null` when the bytes are
+ * not a decodable image, which is a fact worth reporting rather than an exception worth throwing:
+ * the offline drivers answer a PNG signature with no IHDR behind it.
+ */
+export function canvasOf(bytes: Uint8Array): ShotCanvas | null {
+  try {
+    const info = probeImage(bytes);
+    return { width: info.width, height: info.height, format: info.format };
+  } catch {
+    return null;
+  }
+}
+
+export interface ShotInput {
+  readonly route: string;
+  readonly requestedUrl: string;
+  readonly finalUrl: string;
+  readonly server: 'booted' | 'reused';
+  readonly capturedAt: string;
+  /** The picture's filename, beside the verdict — a sibling, so the pair moves as one directory. */
+  readonly screenshot: string;
+  readonly bytes: Uint8Array;
+  readonly console: readonly ConsoleLine[];
+  /**
+   * Uncaught exceptions, which are NOT console lines: a throw calls no console method, so a page
+   * whose island exploded can have `console: []`. This is the field the whole command was for —
+   * "a picture cannot tell you the island threw".
+   */
+  readonly pageErrors: readonly PageError[];
+  /** Page errors the ring evicted, so `pageErrors.length` reads as a floor and not a total. */
+  readonly pageErrorsDropped: number;
+  readonly network: readonly NetworkEntry[];
+  readonly networkDropped: number;
+  /** `null` when the probe could not run or did not parse. Never a zero standing in for unknown. */
+  readonly islands: IslandCount | null;
+}
+
+export interface ShotVerdict extends ShotInput {
+  readonly ok: boolean;
+  /** The route asked for is not the document photographed. An `auth: 'required'` route's default. */
+  readonly redirected: boolean;
+  readonly errors: number;
+  readonly warnings: number;
+  readonly canvas: ShotCanvas | null;
+  readonly refused: number;
+  /** What this verdict cannot see, stated every time — a `0` whose blind spots are named. */
+  readonly blind: readonly string[];
+}
+
+/**
+ * What a shot is blind to, each naming the mechanism rather than apologising. Constant because
+ * these are properties of the browser port, not of a run — and in the artifact because `errors: 0`
+ * read without them is a claim the tool cannot support.
+ *
+ * It was three. `pageErrors` and `hydration` both left on 2026-08-21, when `@ultimat3/scraping`
+ * learned to capture `pageerror` and the hydration prelude learned to mark a mount's outcome. A
+ * blind spot is worth stating while it is true and worth DELETING the moment it is not: a stale
+ * one teaches an agent to distrust an answer the tool can now give.
+ */
+export const BLIND_SPOTS = ['cli.shot.blind.status'] as const;
+
+const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']): number =>
+  lines.filter((line) => line.level === level).length;
+
+/**
+ * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
+ * the route that was asked for.
+ *
+ * The throw is its own clause rather than folded into `errors` because an uncaught exception calls
+ * no console method — a page whose island died can log nothing at all, and `errors === 0` would
+ * then pass it. A rejected mount is a third silent one and was read by NOTHING until 2026-08-22:
+ * the prelude pays 129 B an island to write `data-x-failed`, the probe counted it into the
+ * artifact, and every island on a page could reject while the run reported "clean". `?? 0` keeps
+ * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
+ * A redirect is a failure of the CAPTURE rather than of the app: an agent that
+ * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
+ */
+export function buildVerdict(input: ShotInput): ShotVerdict {
+  const errors = levelCount(input.console, 'error');
+  return {
+    ...input,
+    ok:
+      errors === 0 &&
+      input.pageErrors.length === 0 &&
+      (input.islands?.failed ?? 0) === 0 &&
+      input.requestedUrl === input.finalUrl,
+    redirected: input.requestedUrl !== input.finalUrl,
+    errors,
+    warnings: levelCount(input.console, 'warn'),
+    canvas: canvasOf(input.bytes),
+    refused: input.network.filter((entry) => entry.refused !== undefined).length,
+    blind: BLIND_SPOTS.map((key) => msg(key)),
+  };
+}
+
+const consoleJson = (lines: readonly ConsoleLine[]): JsonValue =>
+  lines.map((line) => ({ level: line.level, text: line.text, at: line.at }));
+
+const islandJson = (islands: IslandCount | null): JsonValue =>
+  islands === null
+    ? null
+    : {
+        declared: islands.declared,
+        booted: islands.booted,
+        mounted: islands.mounted,
+        failed: islands.failed,
+        byStrategy: islands.byStrategy,
+        failures: islands.failures.map((failure) => ({
+          island: failure.island,
+          message: failure.message,
+        })),
+      };
+
+/** The artifact, and the same object `--json` carries under `data.verdict`. One shape, two files. */
+export function verdictJson(verdict: ShotVerdict): JsonValue {
+  return {
+    ok: verdict.ok,
+    route: verdict.route,
+    requestedUrl: verdict.requestedUrl,
+    finalUrl: verdict.finalUrl,
+    redirected: verdict.redirected,
+    server: verdict.server,
+    capturedAt: verdict.capturedAt,
+    screenshot: verdict.screenshot,
+    bytes: verdict.bytes.byteLength,
+    canvas:
+      verdict.canvas === null
+        ? null
+        : {
+            width: verdict.canvas.width,
+            height: verdict.canvas.height,
+            format: verdict.canvas.format,
+          },
+    console: {
+      total: verdict.console.length,
+      errors: verdict.errors,
+      warnings: verdict.warnings,
+      lines: consoleJson(verdict.console),
+    },
+    // Its own object, never merged into `console`: an uncaught exception calls no console method,
+    // and a reader who finds throws under `console` will look for them in the wrong stream.
+    pageErrors: {
+      total: verdict.pageErrors.length,
+      dropped: verdict.pageErrorsDropped,
+      thrown: verdict.pageErrors.map((error) => ({
+        message: error.message,
+        stack: error.stack ?? null,
+        at: error.at,
+      })),
+    },
+    islands: islandJson(verdict.islands),
+    network: {
+      requests: verdict.network.length,
+      refused: verdict.refused,
+      dropped: verdict.networkDropped,
+    },
+    blind: [...verdict.blind],
+  };
+}
+
+export interface ShotArtifacts {
+  readonly verdict: ShotVerdict;
+  /** Absolute path of the picture. */
+  readonly image: string;
+  /** Absolute path of this verdict on disk. */
+  readonly verdictFile: string;
+}
+
+const consoleLines = (verdict: ShotVerdict): readonly string[] =>
+  verdict.console
+    .filter((line) => line.level === 'error' || line.level === 'warn')
+    .map((line) => msg('cli.shot.console', { level: line.level, text: line.text.slice(0, 200) }));
+
+/** Human lines. Every fact here is a fact `--json` carries under `data.verdict`. */
+export function shotLines(artifacts: ShotArtifacts): readonly string[] {
+  const verdict = artifacts.verdict;
+  const islands = verdict.islands;
+  const canvas = verdict.canvas;
+  return [
+    msg(`cli.shot.server.${verdict.server}`, { url: verdict.finalUrl }),
+    canvas === null
+      ? msg('cli.shot.canvasUnreadable', { bytes: verdict.bytes.byteLength })
+      : msg('cli.shot.canvas', { width: canvas.width, height: canvas.height }),
+    islands === null
+      ? msg('cli.shot.islandsUnknown')
+      : msg('cli.shot.islands', {
+          booted: islands.mounted,
+          declared: islands.declared,
+          strategies: Object.entries(islands.byStrategy)
+            .map(([name, count]) => `${name}=${count}`)
+            .join(' '),
+        }),
+    msg('cli.shot.network', {
+      requests: verdict.network.length,
+      refused: verdict.refused,
+      dropped: verdict.networkDropped,
+    }),
+    ...verdict.pageErrors.map((error) =>
+      msg('cli.shot.pageError', {
+        message: error.message,
+        // The frame that names the island module and line. `message` alone says what went wrong
+        // and never where, which is the difference between a report and a lead.
+        at: error.stack?.split('\n')[1]?.trim() ?? '',
+      }),
+    ),
+    ...consoleLines(verdict),
+    msg('cli.shot.picture', { path: artifacts.image }),
+    msg('cli.shot.verdict', { path: artifacts.verdictFile }),
+  ];
+}
+
+/** The one line a reader sees first, and it names the gating fact rather than the file count. */
+export const shotSummary = (verdict: ShotVerdict): string => {
+  if (verdict.redirected) {
+    return msg('cli.shot.redirected', { route: verdict.route, url: verdict.finalUrl });
+  }
+  // Ahead of the console count, because a throw is the more severe fact AND the quieter one: an
+  // island that died can log nothing at all, so `errors` would report a clean page.
+  if (verdict.pageErrors.length > 0) {
+    return msg('cli.shot.threw', {
+      route: verdict.route,
+      thrown: verdict.pageErrors.length,
+      first: verdict.pageErrors[0]?.message ?? '',
+    });
+  }
+  // Ahead of the console count for the same reason, and it is the same silence: a rejected mount
+  // promise calls no console method either, so a page whose every island died can read `errors: 0`.
+  // The first failure is NAMED — "1 island failed" sends a reader back to the artifact for the one
+  // fact they need to start.
+  const failure = verdict.islands?.failures[0];
+  if (failure !== undefined) {
+    return msg('cli.shot.islandFailed', {
+      route: verdict.route,
+      failed: verdict.islands?.failed ?? 0,
+      island: failure.island,
+      message: failure.message,
+    });
+  }
+  if (verdict.errors > 0) {
+    return msg('cli.shot.errors', { route: verdict.route, errors: verdict.errors });
+  }
+  // `mounted`, not `booted`: "the runtime asked for the chunk" is not the claim worth making when
+  // the DOM can now say the mount RESOLVED.
+  return msg('cli.shot.ok', { route: verdict.route, islands: verdict.islands?.mounted ?? 0 });
+};

package/src/static-report.ts

@@ -0,0 +1,219 @@
+// The inventory of one `x build --target static`: which declared route reached the artifact, which
+// did not, and WHY for each. Written by the prerenderer, read back by `x build`, so both renderers
+// state the same thing. A skipped route with no reason is what turned "the island did not mount"
+// into a bug report about a page that had never been in `.x/static/` at all (#242).
+
+// `node:` twice, and only where Bun answers nothing: Bun ships no path API, and `rm(…, { force })`
+// deletes a report that may not be there without a branch. `existsSync` was a third and is gone —
+// `Bun.file(path).json()` already rejects on a missing file, into the catch that answers `undefined`.
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RenderMode } from '@ultimat3/core';
+import { RENDER_MODES } from '@ultimat3/core';
+import type { Surface } from '@ultimat3/render';
+import { SURFACE_SPECS, SURFACES, surfaceAllows } from '@ultimat3/render';
+import type { JsonValue } from './output';
+
+/** Beside `.x/build-stats.json`, and written by the same call — see `readStaticReport` below. */
+export const STATIC_REPORT_FILE = join('.x', 'static-report.json');
+
+export const SKIP_REASONS = [
+  'surface-forbids-static',
+  'mode-revalidates',
+  'mode-per-request',
+  'no-prerender-paths',
+] as const;
+
+export type SkipReason = (typeof SKIP_REASONS)[number];
+
+/**
+ * Type ALIASES, never interfaces — every shape below is JSON on both sides of a file, and only an
+ * alias carries the implicit index signature that makes it assignable to `JsonValue`. As
+ * interfaces, `data: { emitted, skipped }` in `cmd-build.ts` was TS2322 (`not assignable to type
+ * 'JsonValue'`) with nothing wrong in either file, and the obvious fixes — a cast, a widened
+ * annotation — are the two this repo refuses. Same rule `RouteContext` in `@ultimat3/render` is an
+ * alias for.
+ */
+
+/** The two declarations a skip decision reads. Narrower than `RouteEntry` so a test can state one. */
+export type RouteFacts = {
+  readonly surface: Surface;
+  readonly render: RenderMode;
+};
+
+export type SkippedRoute = RouteFacts & {
+  /** The DECLARED path, `/blog/:slug` — never a filled one, so the author can grep for it. */
+  readonly route: string;
+  readonly reason: SkipReason;
+  readonly why: string;
+};
+
+/** One HTML file in the artifact, and the declared route that produced it. */
+export type EmittedPage = {
+  readonly route: string;
+  readonly path: string;
+  /** Relative to the build output root, POSIX — the file a screenshot tool actually opens. */
+  readonly file: string;
+};
+
+export type StaticReport = {
+  readonly target: 'static';
+  readonly out: string;
+  readonly buildId: string;
+  readonly emitted: readonly EmittedPage[];
+  readonly skipped: readonly SkippedRoute[];
+};
+
+/**
+ * The ONE decision about what lands on a CDN — `isPrerenderable` is derived from it, so the answer
+ * and the reason can never disagree.
+ *
+ * Surface is asked FIRST, and that ordering is the whole finding. `app/` allows `stream | ssr` and
+ * nothing else, so no `render:` edit can put an app/ route into the artifact: the surface is the
+ * cause, and naming the mode would send an author to change the one thing that cannot help. On a
+ * surface that DOES allow `static`, the mode is the cause and the edit is real — which is why the
+ * two produce different sentences below rather than one flat "not prerendered".
+ */
+export function skipReasonFor(route: RouteFacts): SkipReason | null {
+  if (!surfaceAllows(route.surface, 'static')) return 'surface-forbids-static';
+  if (route.render === 'static') return null;
+  return route.render === 'isr' ? 'mode-revalidates' : 'mode-per-request';
+}
+
+/**
+ * `Object.freeze<Record<…>>`, never `const X: Readonly<Record<…>> = Object.freeze({…})`: the second
+ * form infers from the literal and accepts an EXTRA key in silence (`bun run frozen-records`).
+ *
+ * English rather than `t()`, for the reason every `cause:`/`fix:` in this repo is English: this is
+ * a diagnostic an agent pastes into a report, and `wiki/Error-Codes.md` is the same surface.
+ */
+const WHY = Object.freeze<Record<SkipReason, (route: RouteFacts) => string>>({
+  'surface-forbids-static': (route) =>
+    `${route.surface}/ surface — server-rendered, not prerendered; ` +
+    `${route.surface}/ allows ${SURFACE_SPECS[route.surface].allowedModes.join(' | ') || 'no render mode'}, ` +
+    'so no route on it can ever reach the artifact',
+  'mode-revalidates': (route) =>
+    `render: '${route.render}' regenerates on a tag or ttl and a published file cannot, ` +
+    "so it is served by the app — change it to render: 'static' to emit it",
+  'mode-per-request': (route) =>
+    `render: '${route.render}' is rendered per request, so it is served by the app — ` +
+    "change it to render: 'static' to emit it",
+  'no-prerender-paths': (route) =>
+    `render: '${route.render}' with dynamic params and no prerender() paths, so the build ` +
+    'enumerated nothing to write — add prerender() to the route',
+});
+
+/** The reason as a row: the code a machine keys off, and the sentence a human reads. */
+export function skippedRoute(
+  input: RouteFacts & { readonly route: string },
+  reason: SkipReason,
+): SkippedRoute {
+  return {
+    route: input.route,
+    surface: input.surface,
+    render: input.render,
+    reason,
+    why: WHY[reason](input),
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * A closed vocabulary, checked against the vocabulary itself. `typeof value === 'string'` is what
+ * `surface` and `render` were held to, and a string is not a `Surface`: the parse then handed back
+ * a `SkippedRoute` whose declared type says `'site' | 'app' | 'api' | 'shared'` while it holds
+ * whatever the file said, so `SURFACE_SPECS[route.surface]` on the read side is `undefined` at the
+ * first reader that indexes it. `SKIP_REASONS` was already checked this way; these two are the same
+ * kind of field and get the same rule.
+ */
+const inDomain = (domain: readonly string[], value: unknown): boolean =>
+  typeof value === 'string' && domain.includes(value);
+
+const isSkipped = (value: unknown): value is SkippedRoute =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  inDomain(SURFACES, value['surface']) &&
+  inDomain(RENDER_MODES, value['render']) &&
+  typeof value['why'] === 'string' &&
+  inDomain(SKIP_REASONS, value['reason']);
+
+const isEmitted = (value: unknown): value is EmittedPage =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  typeof value['path'] === 'string' &&
+  typeof value['file'] === 'string';
+
+/**
+ * Parsed, never cast. The file is this build's own output, but `x build` reads it back off disk
+ * after a subprocess — a truncated write or a hand-edit must read as "no report", which the caller
+ * already handles, rather than as a report with a `skipped` nobody can render.
+ */
+export function parseStaticReport(value: unknown): StaticReport | undefined {
+  if (!isRecord(value)) return undefined;
+  const { target, out, buildId, emitted, skipped } = value;
+  if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
+    return undefined;
+  }
+  if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
+  if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
+  return { target, out, buildId, emitted, skipped };
+}
+
+export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
+  const path = join(root, STATIC_REPORT_FILE);
+  await Bun.write(path, `${JSON.stringify(report, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * `undefined` means no report — an app whose `apps/web/prerender.ts` does not call `prerenderSite`.
+ * That app also writes no `.x/build-stats.json` (one call writes both), so `x verify`'s `budgets`
+ * step already reds it with `X_BUDGET_UNMEASURED`; this side stays quiet rather than adding a
+ * second code for one cause.
+ */
+export async function readStaticReport(root: string): Promise<StaticReport | undefined> {
+  try {
+    return parseStaticReport(await Bun.file(join(root, STATIC_REPORT_FILE)).json());
+  } catch {
+    return undefined;
+  }
+}
+
+/** Deleted before the builder is spawned, so a failed build can never report the last one's list. */
+export async function removeStaticReport(root: string): Promise<void> {
+  await rm(join(root, STATIC_REPORT_FILE), { force: true });
+}
+
+/**
+ * The `--json` half, beside `renderStaticReport`'s human one — and a `Record<string, JsonValue>`
+ * rather than a `JsonValue`, because `x build` SPREADS it into `data` beside `target` and
+ * `artifact`: a bare `JsonValue` admits a string, so the spread is TS2698 (`spread types may only
+ * be created from object types`) and no annotation at the call site can rescue it.
+ *
+ * A field the compiler cannot prove is JSON reds HERE, at the projection, rather than at whichever
+ * caller happens to hand the report to a renderer.
+ */
+export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
+  // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
+  // which the inventory is about — `data` already carries `artifact` and the build's own id.
+  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+}
+
+/**
+ * The human half. Fixed-width columns headed by the JSON's own field names, exactly as
+ * `renderRouteTable` is — the renderer invents no prose, so `--json` and the terminal cannot drift.
+ */
+export function renderStaticReport(report: StaticReport): readonly string[] {
+  const rows: readonly (readonly string[])[] = [
+    ...report.emitted.map((page) => ['emitted', page.route, page.file]),
+    ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+  ];
+  const widths = [0, 1].map((index) =>
+    Math.max(...rows.map((row) => (row[index] ?? '').length), 0),
+  );
+  return rows.map((row) =>
+    `  ${row.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join('  ')}`.trimEnd(),
+  );
+}