@ultimat3/cli 29.3.2 → 30.0.0

package/src/prerender.ts

@@ -16,29 +16,37 @@ import {
 import type { RouteEntry } from '@ultimat3/render';
 import { describePages, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
+import { loadAppConfig } from './app-config-load';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, routeStatsRow, writeBuildStats } from './budgets';
+import { clientErrorsStaticWarning } from './client-errors-routes';
 import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
 import { PrerenderLoadFailedError } from './errors';
 import { FAVICON_PATH, faviconBytes } from './favicon';
-import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
 import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
-import { measurementActorLabel, measureScope, withAppUrl } from './measure-scope';
+import { measurementActorLabel, measureScope, publicScope, withAppUrl } from './measure-scope';
 import { loadNavigation, pageNavigation } from './page-navigation';
 import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
+import { asksPrerender, enumerateOnce, type RouteEntries } from './prerender-entries';
+import { heaviestSource } from './prerender-heaviest';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
 import type { PrerenderedPage, PrerenderReport } from './prerender-report';
+import { collectSeoReads } from './prerender-seo-reads';
 import type { ServedMeasure } from './prerender-served';
 import { servedMeasure } from './prerender-served';
+import { clientVitalsStaticWarning, vitalsBuild } from './prerender-vitals';
 import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
 import { routeDocument, servedDocument } from './runtime-render';
 import { writeSiteAssets } from './site-assets';
 import { loadSiteSettings, originWarning, publicOrigin } from './site-config';
+import type { LlmsPages } from './site-llms-pages';
+import { newestSourceMtime } from './source-mtime';
+import { staticCapture } from './static-capture';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 import { styleBundle, writeStyles } from './style-bundle';
@@ -80,29 +88,8 @@ export interface PrerenderOptions {
    * on a production build, because a placeholder canonical is one a search engine indexes.
    */
   readonly origin?: string;
-}
-
-/**
- * The heaviest thing the document actually boots, named by the source file an author can open.
- * An island chunk is content-addressed, so its URL says nothing on its own — mapping it back
- * through the bundle is what turns `X_BUDGET_EXCEEDED` from a number into an instruction.
- */
-function heaviestSource(
-  bundle: IslandBundle,
-  entries: readonly { readonly url: string; readonly bytes: number }[],
-): readonly string[] | undefined {
-  const heaviest = entries.reduce<{ url: string; bytes: number } | undefined>(
-    (max, entry) => (max === undefined || entry.bytes > max.bytes ? entry : max),
-    undefined,
-  );
-  if (heaviest === undefined) return undefined;
-  const chunk = bundle.chunkAt(heaviest.url);
-  if (chunk !== undefined) return [chunk.file];
-  // A shared chunk has no file of its own: the chain is an island on THIS page that imports it.
-  const importer = bundle.chunks.find(
-    (one) => one.imports.includes(heaviest.url) && entries.some((entry) => entry.url === one.url),
-  );
-  return importer === undefined ? [heaviest.url] : [importer.file, heaviest.url];
+  /** Photograph declared social cards. Absent: on unless `ULTIMATE_BUILD_CAPTURE=off` (`--no-capture`). */
+  readonly capture?: boolean;
 }
 
 export const DEFAULT_ORIGIN = 'https://localhost';
@@ -130,6 +117,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // The load `x dev` and `x manifest` perform: importing the app's modules fills the route registry.
   // A module that would not import registered nothing, so its page would vanish from the export
   // under a green build — refused BEFORE the export is emptied, so the last good artifact survives.
+  // Read BEFORE the app loads: a source saved while this build runs is newer than this, so the
+  // gate's `budgets` step rebuilds rather than weighing bytes that predate the save.
+  const sourcesAt = await newestSourceMtime(options.root);
   const loaded = await loadApp(options.root);
   if (loaded.findings.length > 0) throw new PrerenderLoadFailedError(loaded.findings);
   // Emptied before anything is written: a deleted route's HTML kept shipping when it only grew.
@@ -140,7 +130,14 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const origin = declaredOrigin ?? DEFAULT_ORIGIN;
   // Written to stderr as well as returned: an app's `prerender.ts` prints its report as ONE JSON
   // line on stdout, and a build that parses it must not meet a warning inside it.
-  const warnings = originWarning(tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT, declaredOrigin);
+  const clientErrors = (await loadAppConfig(options.root))?.clientErrors;
+  // Real-user timings as served: a site/ page that lists them is exported carrying the script.
+  const vitals = vitalsBuild(clientErrors?.vitals);
+  const warnings = [
+    ...originWarning(tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT, declaredOrigin),
+    ...clientErrorsStaticWarning(clientErrors),
+    ...clientVitalsStaticWarning(vitals),
+  ];
   for (const warning of warnings) writeErrorLine(`warning: ${warning}`);
   // The app's locales as `loadApp` read them, ONCE, off `@ultimat3/i18n`'s one reader — the same
   // answer the PWA manifest and the service worker below are built from. The default first, so
@@ -211,6 +208,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   if (navigation.script !== undefined) {
     await Bun.write(join(options.out, navigation.script.url.slice(1)), navigation.script.code);
   }
+  // Before any site/ document names it, for the router's reason: weighed off disk, and charged.
+  if (vitals.siteHead !== undefined && vitals.script !== undefined) {
+    await Bun.write(join(options.out, vitals.script.url.slice(1)), vitals.script.code);
+  }
   // The registration TAG now, the worker itself after the render loop — the two halves are wanted
   // at different moments and used to be taken at the same one. Every document below has to name
   // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
@@ -263,8 +264,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // process, because an `app/` page's `load` calls policy-guarded queries over its typed client
   // and no server is listening during a build. `renderStatic` keeps `ctx`: its output is a
   // published file, and a `site/` load a policy refuses must fail the build, never render another
-  // actor's rows into it.
+  // actor's rows into it. `published` authenticates nobody: sitemap and llms.txt reads run in it.
   const measure = await measureScope({ origin, buildId });
+  const published = publicScope({ origin, buildId });
   // Started on the first route that needs weighing, and released however the loop ends.
   const database = measureDatabase(options.root);
   const documentOptions = {
@@ -281,6 +283,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     ...(pwa === undefined
       ? {}
       : { pwaHead: (locale: string) => pwa.headFor(locale) + (swHead ?? '') }),
+    ...(vitals.siteHead === undefined ? {} : { siteHead: vitals.siteHead }),
   };
   const render = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
     routeDocument(entry, data, documentOptions);
@@ -288,7 +291,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // composed on the first route that needs it, so a build weighing none builds no page boot.
   let weighing: Promise<ServedMeasure> | undefined;
   const served = (): Promise<ServedMeasure> => {
-    weighing ??= servedMeasure(options.root, buildId, islands);
+    weighing ??= servedMeasure(options.root, buildId, islands, vitals);
     return weighing;
   };
   const document = (
@@ -300,6 +303,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       render(entry, data),
     );
 
+  // The seo seam is installed for the loop and only the loop (`static-capture.ts`).
+  const capture = await staticCapture(options.out, options.capture);
+  let entries: RouteEntries = new Map();
+  const enumerate = enumerateOnce();
+  let llmsPages: LlmsPages = new Map();
   try {
     for (const entry of routeEntries()) {
       const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
@@ -314,10 +322,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         try {
           // A dynamic route is rendered at the paths its own `prerender()` lists, and the row holds
           // the heaviest — a static route's rule. One that lists none is its own finding.
-          // Inside the measuring scope: a route's `prerender()` lists its paths by reading the app's
-          // own data, the same way its `load` does.
+          // `prerender()` reads the app's own data as its `load` does — as nobody for a route the
+          // sitemap asks, because the one memo hands this answer to `collectSeoReads`.
           await database.ready();
-          const plan = await withAppUrl(origin, () => measure.run(() => measurePaths(entry)));
+          const enumerateIn = asksPrerender(entry) ? published : measure.run;
+          const plan = await withAppUrl(origin, () =>
+            enumerateIn(() => measurePaths(entry, enumerate)),
+          );
           if ('unmeasured' in plan) {
             unmeasured.push(plan.unmeasured);
             continue;
@@ -413,9 +424,22 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       }
       if (heaviest !== undefined) routes.push(heaviest);
     }
+    // Before the scope and the database are released: `siteSeo` reads these instead of asking
+    // `prerender()` or a page's `load` again, when nothing answers the app's own query any more.
+    ({ entries, llmsPages } = await collectSeoReads({
+      root: options.root,
+      origin,
+      defaultLocale,
+      scope: (fn) => withAppUrl(origin, () => published(fn)),
+      before: () => database.ready(),
+      enumerate,
+    }));
   } finally {
+    capture.close();
     await database.close();
   }
+  // The variants and cards the exported documents name, before the worker precaches them.
+  await capture.write(pages);
   // The worker, LAST: every document it precaches has now been rendered, hashed and weighed. A
   // static host runs no route table, so both files go into the artifact — a
   // `<script src="/x-sw-register.js">` in every document is a 404 otherwise, which is the same
@@ -437,7 +461,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   if (serviceWorker !== undefined) {
     await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
   }
-  const stats = await writeBuildStats(options.root, { routes });
+  const stats = await writeBuildStats(options.root, {
+    routes,
+    ...(sourcesAt === undefined ? {} : { sourcesAt }),
+  });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
   // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that
   // app with `X_BUDGET_UNMEASURED`, which is why this side needs no second code of its own.
@@ -467,5 +494,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     serviceWorkerWarnings: serviceWorker?.warnings ?? [],
     warnings,
     origin,
+    entries,
+    llmsPages,
   };
 }

package/src/pwa-artifacts.ts

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
 import { escapeHtml, localeSegment, pushWired } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import { applyCacheHeaders, textResponse } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import {
   appleTouchLinks,
@@ -180,7 +180,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
  * `/assets/pwa/wide.png` — answers the content-hashed URL the site actually serves, exactly as
  * `asset()` does in a page. The site serves an asset ONLY at its hashed URL, and the manifest took
  * `src` verbatim, so an app had to hash its own screenshots to avoid shipping a 404 in the install
- * sheet (notificado.co's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
+ * sheet (one adopter's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
  * broken image in an install prompt; any other `src` passes untouched — an absolute path outside
  * `/assets/`, an already hashed one, or a shortcut icon's off-site URL (core screens screenshots and
  * shortcut urls to absolute paths, not icon sources).
@@ -262,7 +262,8 @@ export const pwaManifestRoute = (artifacts: PwaArtifacts): Route => ({
   },
   handler: async (_request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
     applyCacheHeaders(
-      new Response(manifestIn(artifacts.manifests, ctx.locale)?.body ?? artifacts.body, {
+      // `textResponse` for the length it declares: `compress` reads nothing undeclared.
+      textResponse(manifestIn(artifacts.manifests, ctx.locale)?.body ?? artifacts.body, {
         headers: { 'content-type': 'application/manifest+json; charset=utf-8' },
       }),
       MANIFEST_CACHE,

package/src/pwa-manifest-locales.ts

@@ -26,7 +26,7 @@ const strings = (value: unknown): readonly string[] =>
 /**
  * The manifests' locales, off `appLocaleSet`'s answer (`@ultimat3/i18n/app-catalogs`) — an app
  * with no catalogs is `UNDECLARED_LOCALES`, the framework default alone. The manifest's `lang` was
- * the generator's hardcoded `'en'` for an `es-co` app (notificado.co, 22.3.2). Deduplicated by URL
+ * the generator's hardcoded `'en'` for an `es-co` app (one adopter, 22.3.2). Deduplicated by URL
  * segment, the unit a locale prefix is spelled in.
  */
 export function appLocales(set: AppLocaleSet): AppLocales {

package/src/registry.ts

@@ -11,21 +11,27 @@ import { authSpec } from './cmd-auth-spec';
 import { buildSpec } from './cmd-build-spec';
 import { ciSpec } from './cmd-ci-spec';
 import { cleanSpec } from './cmd-clean-spec';
+import { clientSpec } from './cmd-client-spec';
 import { dbSpec } from './cmd-db-spec';
 import { deploySpec } from './cmd-deploy-spec';
 import { devSpec } from './cmd-dev-spec';
 import { docsSpec } from './cmd-docs-spec';
 import { doctorSpec } from './cmd-doctor-spec';
+import { drillSpec } from './cmd-drill-spec';
 import { envSpec } from './cmd-env-spec';
 import { errorsSpec } from './cmd-errors-spec';
+import { exerciseSpec } from './cmd-exercise-spec';
 import { fixSpec } from './cmd-fix-spec';
 import { generateSpec } from './cmd-generate-spec';
+import { graphSpec } from './cmd-graph-spec';
 // Registered here, not by whichever command body happens to load: `dispatch` renders a CLI code's
 // title for a refusal raised before any body is imported.
 import './error-codes';
 import { createHelpCommand, createVersionCommand } from './cmd-help';
 import { i18nSpec } from './cmd-i18n-spec';
+import { impactSpec } from './cmd-impact-spec';
 import { jobsSpec } from './cmd-jobs-spec';
+import { mailSpec } from './cmd-mail-spec';
 import { manifestSpec } from './cmd-manifest-spec';
 import { mcpSpec } from './cmd-mcp-spec';
 import { newSpec } from './cmd-new-spec';
@@ -33,11 +39,14 @@ import { plannedCommands } from './cmd-planned';
 import { policySpec } from './cmd-policy-spec';
 import { prSpec } from './cmd-pr-spec';
 import { actionsSpec, entitiesSpec, queriesSpec } from './cmd-registries-spec';
+import { reproSpec } from './cmd-repro-spec';
 import { routesSpec } from './cmd-routes-spec';
 import { secretsSpec } from './cmd-secrets-spec';
 import { shotSpec } from './cmd-shot-spec';
+import { stopSpec } from './cmd-stop-spec';
 import { tasksSpec } from './cmd-tasks-spec';
 import { testSpec } from './cmd-test-spec';
+import { upgradeSpec } from './cmd-upgrade-spec';
 import { vapidSpec } from './cmd-vapid-spec';
 import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand } from './command';
@@ -78,6 +87,7 @@ const lazy = (spec: CommandSpec, load: () => Promise<CliCommand>): LazyCommand =
 export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(newSpec, async () => (await import('./cmd-new')).newCommand),
   lazy(devSpec, async () => (await import('./cmd-dev')).devCommand),
+  lazy(stopSpec, async () => (await import('./cmd-stop')).stopCommand),
   lazy(buildSpec, async () => (await import('./cmd-build')).buildCommand),
   lazy(testSpec, async () => (await import('./cmd-test')).testCommand),
   lazy(verifySpec, async () => (await import('./cmd-verify')).verifyCommand),
@@ -99,14 +109,22 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(jobsSpec, async () => (await import('./cmd-jobs')).jobsCommand),
   lazy(tasksSpec, async () => (await import('./cmd-tasks')).tasksCommand),
   lazy(policySpec, async () => (await import('./cmd-policy')).policyCommand),
+  lazy(exerciseSpec, async () => (await import('./cmd-exercise')).exerciseCommand),
+  lazy(drillSpec, async () => (await import('./cmd-drill')).drillCommand),
   lazy(i18nSpec, async () => (await import('./cmd-i18n')).i18nCommand),
+  lazy(mailSpec, async () => (await import('./cmd-mail')).mailCommand),
   lazy(errorsSpec, async () => (await import('./cmd-errors')).errorsCommand),
+  lazy(reproSpec, async () => (await import('./cmd-repro')).reproCommand),
   lazy(docsSpec, async () => (await import('./cmd-docs')).docsCommand),
   lazy(fixSpec, async () => (await import('./cmd-fix')).fixCommand),
   lazy(affectedSpec, async () => (await import('./cmd-affected')).affectedCommand),
   lazy(shotSpec, async () => (await import('./cmd-shot')).shotCommand),
   lazy(prSpec, async () => (await import('./cmd-pr')).prCommand),
   lazy(ciSpec, async () => (await import('./cmd-ci')).ciCommand),
+  lazy(upgradeSpec, async () => (await import('./cmd-upgrade')).upgradeCommand),
+  lazy(clientSpec, async () => (await import('./cmd-client')).clientCommand),
+  lazy(graphSpec, async () => (await import('./cmd-graph')).graphCommand),
+  lazy(impactSpec, async () => (await import('./cmd-impact')).impactCommand),
 ];
 
 /**

package/src/repro-bundle.ts

@@ -0,0 +1,65 @@
+// Single responsibility: what `x repro <id>` is about — a dead job (`x_jobs` and its steps, with or
+// without capture), a captured request (`x_failures` by bundle, request or trace id, else the newest
+// bundle of a fingerprint), or a bundle file (`--from`). Reads only; refuses with `X_REPRO_*`.
+
+import type { FailureBundle } from '@ultimat3/core';
+import { isJsonObject } from '@ultimat3/core';
+import { postgresFailureStore } from '@ultimat3/db';
+import type { JobDriver } from '@ultimat3/jobs';
+import { inspectJob } from '@ultimat3/jobs';
+import type { JobFailure } from '@ultimat3/testing';
+import { ReproCaptureOffError, ReproUnknownError } from './repro-errors';
+import { jobFailureOf } from './repro-job';
+
+export type ReproSubject =
+  | { readonly kind: 'job'; readonly failure: JobFailure }
+  | { readonly kind: 'request'; readonly bundle: FailureBundle };
+
+/** A uuid in any spelling `x_jobs.id` accepts — `cmd-jobs.ts`' rule, so no statement is wasted. */
+const JOB_ID = /^\{?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\}?$/i;
+
+const isBundle = (value: unknown): value is FailureBundle =>
+  isJsonObject(value) &&
+  typeof value['name'] === 'string' &&
+  (value['primitive'] === 'action' || value['primitive'] === 'query') &&
+  Array.isArray(value['reads']);
+
+const isJobFailure = (value: unknown): value is JobFailure =>
+  isJsonObject(value) &&
+  typeof value['jobId'] === 'string' &&
+  typeof value['name'] === 'string' &&
+  Array.isArray(value['steps']);
+
+/** `--from <file>`: a bundle `x repro <id> --json` printed (`data.bundle` or `data.failure`), or one bare. */
+export async function subjectFromFile(path: string): Promise<ReproSubject> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) throw new ReproUnknownError({ id: path });
+  const parsed: unknown = await file.json();
+  const data = isJsonObject(parsed) && isJsonObject(parsed['data']) ? parsed['data'] : parsed;
+  const inner = isJsonObject(data) ? (data['bundle'] ?? data['failure'] ?? data) : data;
+  if (isBundle(inner)) return { kind: 'request', bundle: inner };
+  if (isJobFailure(inner)) return { kind: 'job', failure: inner };
+  throw new ReproUnknownError({ id: path });
+}
+
+/**
+ * A job first — its row exists whether or not capture is on — then the captured bundles. Not found
+ * anywhere: `X_REPRO_CAPTURE_OFF` when the app never stored bundles, `X_REPRO_UNKNOWN` otherwise.
+ */
+export async function resolveSubject(
+  driver: JobDriver,
+  id: string,
+  captureOn: boolean,
+): Promise<ReproSubject> {
+  if (JOB_ID.test(id)) {
+    const trace = await inspectJob(driver, id);
+    if (trace !== undefined) {
+      return { kind: 'job', failure: jobFailureOf(trace, await driver.steps.list(trace.runId)) };
+    }
+  }
+  const store = postgresFailureStore();
+  const bundle = (await store.find(id)) ?? (await store.latest(id));
+  if (bundle !== undefined) return { kind: 'request', bundle };
+  if (!captureOn) throw new ReproCaptureOffError({ id });
+  throw new ReproUnknownError({ id });
+}

package/src/repro-errors.ts

@@ -0,0 +1,47 @@
+// The three ways `x repro` refuses: an id nothing holds, a capture that was never on, and a written
+// test that ran and did not fail the way the original did. Registered in `error-codes.ts`.
+
+import { renderFixShellArg, UltimateError } from '@ultimat3/core';
+
+export class ReproUnknownError extends UltimateError {
+  constructor(input: { readonly id: string }) {
+    super({
+      code: 'X_REPRO_UNKNOWN',
+      cause: `no dead job, captured request, trace or fingerprint matches "${input.id}"`,
+      fix: 'x repro --list --json',
+      meta: { id: input.id },
+    });
+  }
+}
+
+export class ReproCaptureOffError extends UltimateError {
+  constructor(input: { readonly id: string }) {
+    super({
+      code: 'X_REPRO_CAPTURE_OFF',
+      cause: `"${input.id}" is no job, and failureCapture is disabled in app.config.ts, so no request bundle was ever stored`,
+      fix: 'x jobs list --json   # a job id replays with capture off; for requests set failureCapture: { enabled: true } in app.config.ts',
+      meta: { id: input.id },
+    });
+  }
+}
+
+export interface NotReproducedInput {
+  readonly id: string;
+  readonly expected: string;
+  readonly got: string | null;
+  readonly masked: readonly string[];
+  readonly file: string;
+  readonly build: string | null;
+}
+
+export class ReproNotReproducedError extends UltimateError {
+  constructor(input: NotReproducedInput) {
+    const masked = input.masked.length === 0 ? 'none' : input.masked.join(', ');
+    super({
+      code: 'X_REPRO_NOT_REPRODUCED',
+      cause: `${input.file} ended in ${input.got ?? 'a pass'}, not ${input.expected}; masked fields: ${masked}; captured on build ${input.build ?? 'unknown'}`,
+      fix: `x repro ${renderFixShellArg(input.id, '<id>')} --json, then set the listed masked fields and unread rows by hand in ${renderFixShellArg(input.file, '<the written test>')}`,
+      meta: { ...input },
+    });
+  }
+}

package/src/repro-job.ts

@@ -0,0 +1,72 @@
+// Single responsibility: a dead job as a replay — what `inspectJob` and the run's step records say,
+// folded into the `JobFailure` `reproJob` takes, and the `.job.test.ts` that replays it. Pure: the
+// reads are `repro-bundle.ts`', the write is `repro-write.ts`'.
+
+import type { ErrorReport } from '@ultimat3/core';
+import { captureValue, errorFingerprint, singleLine } from '@ultimat3/core';
+import type { JobTrace, StepRecord } from '@ultimat3/jobs';
+import type { JobFailure } from '@ultimat3/testing';
+import { tsLiteral } from './repro-literal';
+
+const CODE = /X_[A-Z0-9_]+/;
+
+/** `inspectJob`'s trace (input already masked as `x jobs show` masks it) plus the run's steps. */
+export function jobFailureOf(trace: JobTrace, records: readonly StepRecord[]): JobFailure {
+  const { value, masked } = captureValue(trace.input);
+  return {
+    jobId: trace.id,
+    name: trace.name,
+    input: value,
+    masked,
+    // Completed steps only, in the order the run took them: each one replays from its output.
+    steps: records
+      .filter((record) => record.status === 'completed')
+      .map((record) => ({ name: record.name, output: record.output ?? null })),
+    code: CODE.exec(trace.lastError ?? '')?.[0] ?? null,
+    step: records.find((record) => record.status === 'failed')?.name ?? null,
+  };
+}
+
+/** The group a job failure reports under — `source: 'job'`, the job's name as the operation. */
+export function jobFingerprint(failure: JobFailure): string | null {
+  if (failure.code === null) return null;
+  const report: Pick<ErrorReport, 'code' | 'source' | 'scope'> = {
+    code: failure.code,
+    source: 'job',
+    scope: { operation: failure.name },
+  };
+  // `errorFingerprint` reads three fields through total accessors; the rest of a report is not read.
+  return errorFingerprint(report as ErrorReport);
+}
+
+export interface ReproSourceMeta {
+  /** Bare id, as the user typed it — the comment says how the file came to be. */
+  readonly id: string;
+  /** Module specifiers imported for their registrations (the app's API index), relative. */
+  readonly imports: readonly string[];
+}
+
+export const header = (lines: readonly string[]): string =>
+  lines.map((line) => `// ${singleLine(line)}`).join('\n');
+
+/** A `.job.test.ts` that is RED until the fault is fixed: the run must settle with no error. */
+export function jobTestSource(failure: JobFailure, meta: ReproSourceMeta): string {
+  const masked = failure.masked.length === 0 ? 'none' : failure.masked.join(', ');
+  return `${header([
+    `x repro ${meta.id}: job "${failure.name}" died with ${failure.code ?? 'an uncoded failure'} at step "${failure.step ?? '(the body)'}".`,
+    'Written by `x repro --write`. Red until the fault is fixed: the completed steps replay from',
+    `their stored output, then the job runs once more. Masked input fields (${masked}) are stood in`,
+    'for from the schema — set them here when the failure needs their real shape.',
+  ])}
+
+import { expect, type JobFailure, jobTest, reproJob } from '@ultimat3/testing';
+${meta.imports.map((specifier) => `import '${specifier}';`).join('\n')}
+
+const FAILURE: JobFailure = ${tsLiteral(failure)};
+
+jobTest(${tsLiteral(`repro ${meta.id.slice(0, 8)}: ${failure.name} settles`)}, async ({ runJobs }) => {
+  const outcome = await reproJob(runJobs, FAILURE);
+  expect(outcome.failure).toBeNull();
+});
+`;
+}

package/src/repro-literal.ts

@@ -0,0 +1,41 @@
+// Single responsibility: a JSON value as a TypeScript literal in the repo's own style — single
+// quotes, two spaces, trailing commas, keys bare where they can be — so a test `x repro --write`
+// emits passes `lint` without a formatter and reads like a test someone wrote.
+
+const BARE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+const quoted = (text: string): string =>
+  `'${text
+    .replaceAll('\\', '\\\\')
+    .replaceAll("'", "\\'")
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')
+    .replaceAll('
', '\\u2028')
+    .replaceAll('
', '\\u2029')}'`;
+
+/** `__proto__` written bare or quoted SETS the prototype; only a computed key stays a key. */
+const keyOf = (key: string): string =>
+  key === '__proto__' ? `[${quoted(key)}]` : BARE_KEY.test(key) ? key : quoted(key);
+
+/** `value` rendered at `depth` (its first line is not indented; nested lines are). */
+export function tsLiteral(value: unknown, depth = 0): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'string') return quoted(value);
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null';
+  if (typeof value === 'boolean') return String(value);
+  const pad = '  '.repeat(depth + 1);
+  const close = '  '.repeat(depth);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    return `[\n${value.map((entry) => `${pad}${tsLiteral(entry, depth + 1)},`).join('\n')}\n${close}]`;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const lines = entries.map(
+      ([key, entry]) => `${pad}${keyOf(key)}: ${tsLiteral(entry, depth + 1)},`,
+    );
+    return `{\n${lines.join('\n')}\n${close}}`;
+  }
+  return 'null';
+}

package/src/repro-request.ts

@@ -0,0 +1,48 @@
+// Single responsibility: a captured request bundle as the `.contract.test.ts` that replays it —
+// rows seeded through the app's own driver, the clock frozen at the failure, the actor and input
+// as captured. Pure: the read is `repro-bundle.ts`', the write `repro-write.ts`'.
+
+import type { FailureBundle } from '@ultimat3/core';
+import type { ReproSourceMeta } from './repro-job';
+import { header } from './repro-job';
+import { tsLiteral } from './repro-literal';
+
+export interface RequestSourceMeta extends ReproSourceMeta {
+  /** `@<app>/db` — the package exporting `driver`; `null` when the app has none (no rows seeded). */
+  readonly dbPackage: string | null;
+  /** The build that is about to run the test, to say so when it is not the captured one. */
+  readonly build: string | null;
+}
+
+export function requestTestSource(bundle: FailureBundle, meta: RequestSourceMeta): string {
+  const masked = bundle.masked.length === 0 ? 'none' : bundle.masked.join(', ');
+  const drift =
+    bundle.build !== null && meta.build !== null && bundle.build !== meta.build
+      ? `Captured on build ${bundle.build}, replayed on ${meta.build}: a different outcome may be the fix already shipped.`
+      : `Captured on build ${bundle.build ?? 'unknown'}.`;
+  const lines = [
+    `x repro ${meta.id}: ${bundle.primitive} "${bundle.name}" answered ${bundle.code} (fingerprint ${bundle.fingerprint}).`,
+    'Written by `x repro --write`. Red until the fault is fixed: the rows it read are seeded, the',
+    'clock is frozen at the failure, and it runs again as the same actor with the same input.',
+    `Masked input fields (${masked}) are stood in for from the schema. ${drift}`,
+    ...(bundle.truncated
+      ? ['The bundle was truncated at capture: some rows it read are not here.']
+      : []),
+  ];
+  const driverImport =
+    meta.dbPackage === null ? '' : `import { driver } from '${meta.dbPackage}';\n`;
+  const options = meta.dbPackage === null ? '' : ', { driver }';
+  return `${header(lines)}
+
+import type { FailureBundle } from '@ultimat3/core';
+import { expect, reproduce, test } from '@ultimat3/testing';
+${driverImport}${meta.imports.map((specifier) => `import '${specifier}';`).join('\n')}
+
+const BUNDLE: FailureBundle = ${tsLiteral(bundle)};
+
+test(${tsLiteral(`repro ${meta.id.slice(0, 8)}: ${bundle.name} answers without ${bundle.code}`)}, async () => {
+  const outcome = await reproduce(BUNDLE${options});
+  expect(outcome.failure).toBeNull();
+});
+`;
+}