@ultimat3/cli 29.4.0 → 30.1.0

package/src/error-codes-shot.ts

@@ -0,0 +1,59 @@
+// The X_* codes of `x shot` and the dev MCP server's `ui.*` tools — the picture-taking surface —
+// split out of `error-codes.ts` at its 500-line ceiling. `error-codes.ts` folds these into the
+// CLI's one owned union and registers them in its one call; nothing else imports this file.
+
+/** Codes `x shot` and `ui.shot` / `ui.interact` / `ui.diff` declare and own. */
+export const CLI_SHOT_ERROR_CODES = [
+  'X_SHOT_BROWSER_MISSING',
+  // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
+  'X_UI_SHOT_ROUTE_UNKNOWN',
+  'X_UI_SHOT_ROUTE_UNBUDGETED',
+  // `ui.interact`: the four ways a step list is refused. All four REFUSE rather than trim or skip
+  // — a step dropped, a keystroke swallowed or a navigation followed changes what the picture is of.
+  'X_UI_INTERACT_STEPS_INVALID',
+  'X_UI_INTERACT_SECRET_FIELD',
+  'X_UI_INTERACT_LEFT_APP',
+  'X_UI_INTERACT_STEP_FAILED',
+  // `ui.diff`: the three ways two captures fail to become a comparison. The path gate is what
+  // lets a file-reading tool sit under `dev:read` — it reads `.x/shot/` and nothing else.
+  'X_UI_DIFF_PATH_OUTSIDE',
+  'X_UI_DIFF_FILE_MISSING',
+  'X_UI_DIFF_SIZE_MISMATCH',
+  // `x shot --island` — one code per way a component's named state fails to become a picture.
+  // The last of the four is the one that gates: it is checked against the expansion computed
+  // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
+  'X_SHOT_ISLAND_STATES_EMPTY',
+  'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
+  'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
+  'X_SHOT_ISLAND_MISSING',
+  // The raw-CDP shot page's own refusals (`cdp-shot-errors.ts` holds the classes): which host it
+  // may open, which element it was pointed at, and which key it was asked to press.
+  'X_SHOT_HOST_REFUSED',
+  'X_SHOT_ELEMENT_MISSING',
+  'X_SHOT_ELEMENT_UNREADY',
+  'X_SHOT_KEY_INVALID',
+] as const;
+
+export type CliShotErrorCode = (typeof CLI_SHOT_ERROR_CODES)[number];
+
+/** Their titles, typed over the list above so a code without one is a build error. */
+export const CLI_SHOT_ERROR_TITLES: Readonly<Record<CliShotErrorCode, string>> = {
+  X_SHOT_BROWSER_MISSING: '`x shot` has no browser to launch',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
+  X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
+  X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
+  X_UI_INTERACT_SECRET_FIELD: 'ui.interact refused to type into a password field',
+  X_UI_INTERACT_LEFT_APP: 'a ui.interact step navigated off the dev server origin',
+  X_UI_INTERACT_STEP_FAILED: 'a ui.interact step raised a scraping error',
+  X_UI_DIFF_PATH_OUTSIDE: 'ui.diff was handed a path that does not resolve inside .x/shot/',
+  X_UI_DIFF_FILE_MISSING: 'ui.diff was handed a capture that is not on disk',
+  X_UI_DIFF_SIZE_MISMATCH: 'ui.diff was handed two captures of different sizes',
+  X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
+  X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
+  X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
+  X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
+  X_SHOT_HOST_REFUSED: "x shot was asked to open a host outside the run's allow list",
+  X_SHOT_ELEMENT_MISSING: 'no element matched the selector before the deadline',
+  X_SHOT_ELEMENT_UNREADY: 'the element matched and never became ready to act on',
+  X_SHOT_KEY_INVALID: 'a key chord the browser cannot press',
+};

package/src/error-codes-tooling.ts

@@ -0,0 +1,29 @@
+// The X_* codes of the app tooling commands — `x client`, `x graph` / `x impact` and `x repro` —
+// split out of `error-codes.ts` at its 500-line ceiling, as `error-codes-shot.ts` was. That file
+// folds these into the CLI's one owned union and registers them in its one call.
+
+/** Codes `x client`, `x graph`, `x impact` and `x repro` declare and own. */
+export const CLI_TOOLING_ERROR_CODES = [
+  'X_CLIENT_SPEC_UNSUPPORTED',
+  'X_CLIENT_STALE',
+  'X_CLIENT_EDITED',
+  'X_GRAPH_NODE_UNKNOWN',
+  'X_CLIENT_SPEC_INVALID',
+  'X_REPRO_UNKNOWN',
+  'X_REPRO_NOT_REPRODUCED',
+  'X_REPRO_CAPTURE_OFF',
+] as const;
+
+export type CliToolingErrorCode = (typeof CLI_TOOLING_ERROR_CODES)[number];
+
+/** Their titles, typed over the list above so a code without one is a build error. */
+export const CLI_TOOLING_ERROR_TITLES: Readonly<Record<CliToolingErrorCode, string>> = {
+  X_CLIENT_SPEC_UNSUPPORTED: 'x client met an OpenAPI construct its compiler refuses',
+  X_CLIENT_STALE: 'a generated client is older than the document it was compiled from',
+  X_CLIENT_EDITED: 'a generated client file was changed by hand',
+  X_GRAPH_NODE_UNKNOWN: 'x graph or x impact was asked about a node the app graph does not hold',
+  X_CLIENT_SPEC_INVALID: 'x client was handed a document that is not OpenAPI 3.0 or 3.1',
+  X_REPRO_UNKNOWN: 'x repro was given an id nothing holds',
+  X_REPRO_NOT_REPRODUCED: 'a written repro test did not fail the way the original did',
+  X_REPRO_CAPTURE_OFF: 'x repro was given a request id while failure capture is off',
+};

package/src/error-codes.ts

@@ -3,6 +3,10 @@
 // the CLI is the surface an agent reads first — a failure here has to be actionable without a doc
 // lookup or a second round-trip. The classes that throw these codes live in `./errors`.
 import { registerErrorCodes } from '@ultimat3/core';
+import type { CliShotErrorCode } from './error-codes-shot';
+import { CLI_SHOT_ERROR_CODES, CLI_SHOT_ERROR_TITLES } from './error-codes-shot';
+import type { CliToolingErrorCode } from './error-codes-tooling';
+import { CLI_TOOLING_ERROR_CODES, CLI_TOOLING_ERROR_TITLES } from './error-codes-tooling';
 
 /** Codes this package declares and owns. */
 export const CLI_OWNED_ERROR_CODES = [
@@ -161,34 +165,6 @@ export const CLI_OWNED_ERROR_CODES = [
   // source-level fix, and an agent following it here edits a file that is already right — the
   // repair is an install, and only `duplicate-packages.ts` can see that.
   'X_PACKAGE_DUPLICATED',
-  'X_SHOT_BROWSER_MISSING',
-  // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
-  'X_UI_SHOT_ROUTE_UNKNOWN',
-  'X_UI_SHOT_ROUTE_UNBUDGETED',
-  // `ui.interact`: the four ways a step list is refused. All four REFUSE rather than trim or skip
-  // — a step dropped, a keystroke swallowed or a navigation followed changes what the picture is of.
-  'X_UI_INTERACT_STEPS_INVALID',
-  'X_UI_INTERACT_SECRET_FIELD',
-  'X_UI_INTERACT_LEFT_APP',
-  'X_UI_INTERACT_STEP_FAILED',
-  // `ui.diff`: the three ways two captures fail to become a comparison. The path gate is what
-  // lets a file-reading tool sit under `dev:read` — it reads `.x/shot/` and nothing else.
-  'X_UI_DIFF_PATH_OUTSIDE',
-  'X_UI_DIFF_FILE_MISSING',
-  'X_UI_DIFF_SIZE_MISMATCH',
-  // `x shot --island` — one code per way a component's named state fails to become a picture.
-  // The last of the four is the one that gates: it is checked against the expansion computed
-  // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
-  'X_SHOT_ISLAND_STATES_EMPTY',
-  'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
-  'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
-  'X_SHOT_ISLAND_MISSING',
-  // The raw-CDP shot page's own refusals (`cdp-shot-errors.ts` holds the classes): which host it
-  // may open, which element it was pointed at, and which key it was asked to press.
-  'X_SHOT_HOST_REFUSED',
-  'X_SHOT_ELEMENT_MISSING',
-  'X_SHOT_ELEMENT_UNREADY',
-  'X_SHOT_KEY_INVALID',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -237,6 +213,43 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_CATALOG_SLOT_MISMATCH',
   'X_CATALOG_UNTRANSLATED',
   'X_WORKER_QUEUE_UNKNOWN',
+  'X_UPGRADE_DIRTY_TREE',
+  'X_UPGRADE_MIXED_PINS',
+  'X_UPGRADE_HOP_TOO_WIDE',
+  'X_UPGRADE_REGISTRY_UNREACHABLE',
+  'X_UPGRADE_PIN_UNREADABLE',
+  'X_UPGRADE_VERSION_UNPUBLISHED',
+  'X_UPGRADE_INSTALL_FAILED',
+  'X_UPGRADE_GATE_UNREADABLE',
+  'X_DEPLOY_BUILD_UNSTAMPED',
+  'X_DEPLOY_UNSTABLE',
+  'X_DEPLOY_QUEUE_UNSERVED',
+  'X_DEPLOY_BUILD_MISMATCH',
+  'X_JOB_OUTLASTS_DRAIN',
+  'X_FEATURE_REQUIRED',
+  'X_BOUNDARY_PACKAGE_TO_APP',
+  'X_APP_IMPORT_UNRESOLVED',
+  'X_STREAM_ALREADY_FLUSHED',
+  'X_QUERY_SLICE_ENTITY',
+  'X_DEPLOY_ENV_MISSING',
+  'X_ENV_FILE_EXISTS',
+  'X_DEV_STOP_TIMEOUT',
+  'X_DEV_STOP_DENIED',
+  'X_ASSET_RETAIN_FAILED',
+  'X_APP_MODULE_LOAD_FAILED',
+  'X_CHART_MISSING',
+  'X_ENTITY_VIEW_DRIFT',
+  'X_ENTITY_RETAIN_UNSWEPT',
+  'X_NEW_SHAPE_UNKNOWN',
+  'X_NEW_SHAPE_CONFLICT',
+  'X_SEO_CARD_ROUTE_UNKNOWN',
+  'X_SEO_CARD_BROWSER_MISSING',
+  'X_IMAGE_SOURCE_UNREADABLE',
+  'X_VERIFY_SKIPS_OVER_CEILING',
+  'X_ASSET_VARIANT_UNDECLARED',
+  'X_NEW_SHAPE_GENERATE_FAILED',
+  'X_ISLAND_DISPOSER_MISSING',
+  'X_SOCKET_HAND_ROLLED',
 ] as const;
 
 /**
@@ -260,9 +273,8 @@ export const CLI_BORROWED_ERROR_CODES = [
   // nearest declared name all come from `permissionUnknown`. A CLI-owned twin would be a second
   // wording for the condition `can()` already refuses at run time, and the two would drift.
   'X_PERMISSION_UNKNOWN',
-  // `@ultimat3/db`'s, reported by `x doctor`'s database probe with that package's own two-branch
-  // fix. The CLI is the half that asks BEFORE a pool is opened; the condition and the remedy are
-  // both db's, and a CLI twin would be one unreachable database with two names.
+  // `@ultimat3/db`'s, reported by `x doctor`'s database probe with db's own fix: the CLI only asks
+  // before a pool opens, and a CLI twin would be one unreachable database with two names.
   'X_DB_UNAVAILABLE',
   'X_CONFIG_INVALID',
   'X_ENV_MISSING',
@@ -271,17 +283,24 @@ export const CLI_BORROWED_ERROR_CODES = [
 ] as const;
 
 /** Every code the CLI can throw: the ones it owns plus the one it borrows. */
-export const CLI_ERROR_CODES = [...CLI_OWNED_ERROR_CODES, ...CLI_BORROWED_ERROR_CODES] as const;
+export const CLI_ERROR_CODES = [
+  ...CLI_OWNED_ERROR_CODES,
+  ...CLI_SHOT_ERROR_CODES,
+  ...CLI_TOOLING_ERROR_CODES,
+  ...CLI_BORROWED_ERROR_CODES,
+] as const;
 
-export type CliOwnedErrorCode = (typeof CLI_OWNED_ERROR_CODES)[number];
+/** The codes listed in THIS file — the ones `CLI_ERROR_TITLES` below must title. */
+type CliListedErrorCode = (typeof CLI_OWNED_ERROR_CODES)[number];
+export type CliOwnedErrorCode = CliListedErrorCode | CliShotErrorCode | CliToolingErrorCode;
 export type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
 
 /**
  * Registered titles, so `x errors list` enumerates the CLI's codes alongside every other
  * package's instead of leaving a hole an agent has to read source to fill. Typed over
- * `CliOwnedErrorCode`, so adding a code without a title is a build error.
+ * `CliListedErrorCode`, so adding a code without a title is a build error.
  */
-export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
+export const CLI_ERROR_TITLES: Readonly<Record<CliListedErrorCode, string>> = {
   X_CLI_UNKNOWN_COMMAND: 'not a command in the registry',
   X_CLI_BAD_FLAG: 'unknown flag, missing value, or a value the command refuses',
   X_VERIFY_FAILED: 'at least one x verify step failed',
@@ -355,24 +374,6 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
-  X_SHOT_BROWSER_MISSING: '`x shot` has no browser to launch',
-  X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
-  X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
-  X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
-  X_UI_INTERACT_SECRET_FIELD: 'ui.interact refused to type into a password field',
-  X_UI_INTERACT_LEFT_APP: 'a ui.interact step navigated off the dev server origin',
-  X_UI_INTERACT_STEP_FAILED: 'a ui.interact step raised a scraping error',
-  X_UI_DIFF_PATH_OUTSIDE: 'ui.diff was handed a path that does not resolve inside .x/shot/',
-  X_UI_DIFF_FILE_MISSING: 'ui.diff was handed a capture that is not on disk',
-  X_UI_DIFF_SIZE_MISMATCH: 'ui.diff was handed two captures of different sizes',
-  X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
-  X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
-  X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
-  X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
-  X_SHOT_HOST_REFUSED: "x shot was asked to open a host outside the run's allow list",
-  X_SHOT_ELEMENT_MISSING: 'no element matched the selector before the deadline',
-  X_SHOT_ELEMENT_UNREADY: 'the element matched and never became ready to act on',
-  X_SHOT_KEY_INVALID: 'a key chord the browser cannot press',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',
@@ -430,12 +431,57 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_CATALOG_SLOT_MISMATCH: 'two locales define one key with different interpolation slots',
   X_CATALOG_UNTRANSLATED: "a locale still carries the reference locale's value",
   X_WORKER_QUEUE_UNKNOWN: 'WORKER_QUEUES names a queue no job and no jobs.queues entry declares',
+  X_UPGRADE_DIRTY_TREE: 'x upgrade refused a tree with uncommitted changes',
+  X_UPGRADE_MIXED_PINS: 'x upgrade found two @ultimat3/* versions across the workspaces',
+  X_UPGRADE_HOP_TOO_WIDE: 'x upgrade --to is outside the one hop a run may make',
+  X_UPGRADE_REGISTRY_UNREACHABLE: 'x upgrade could not read the published versions from npm',
+  X_UPGRADE_PIN_UNREADABLE: 'x upgrade found an @ultimat3/* dependency that names no version',
+  X_UPGRADE_VERSION_UNPUBLISHED: 'x upgrade --to names a version npm does not have',
+  X_UPGRADE_INSTALL_FAILED: 'bun install failed after x upgrade wrote the pins',
+  X_UPGRADE_GATE_UNREADABLE: 'the installed x verify answered with no JSON report',
+  X_DEPLOY_BUILD_UNSTAMPED: 'the deployment answers with no build header',
+  X_DEPLOY_UNSTABLE: 'the build answered but did not hold',
+  X_DEPLOY_QUEUE_UNSERVED: 'a registered queue has no serving worker of this build',
+  X_DEPLOY_BUILD_MISMATCH: 'production never served this build',
+  X_JOB_OUTLASTS_DRAIN: "a job's declared timeout outlasts the worker's budget",
+  X_FEATURE_REQUIRED: 'x g query or x g backfill named no slice to read',
+  X_BOUNDARY_PACKAGE_TO_APP: 'packages/ imported apps/ at runtime',
+  X_APP_IMPORT_UNRESOLVED: 'an app module imports what does not resolve',
+  X_STREAM_ALREADY_FLUSHED: 'a response header was written after the stream flushed',
+  X_QUERY_SLICE_ENTITY: 'x g query into a slice whose entity is not the one it scaffolds',
+  X_DEPLOY_ENV_MISSING: 'x deploy --method compose found no complete .env.production',
+  X_ENV_FILE_EXISTS: 'x env init --production found .env.production already written',
+  X_DEV_STOP_TIMEOUT: 'x stop sent SIGTERM and x dev did not exit in time',
+  X_DEV_STOP_DENIED: 'x stop may not signal the x dev the lock names',
+  X_ASSET_RETAIN_FAILED: 'Build assets were not retained',
+  X_APP_MODULE_LOAD_FAILED:
+    'an app module failed to load, so the role refused to serve a partial app',
+  X_CHART_MISSING: 'x g chart-alerts found no Helm chart to write into',
+  X_ENTITY_VIEW_DRIFT: "a view entity's columns disagree with the view its migration created",
+  X_ENTITY_RETAIN_UNSWEPT: 'an entity declares retain and no purge() sweeps it',
+  X_NEW_SHAPE_UNKNOWN: 'x new --shape names no registered shape',
+  X_NEW_SHAPE_CONFLICT: 'x new --shape with --no-example',
+  X_SEO_CARD_ROUTE_UNKNOWN: 'og.capture names a path no site/ route answers',
+  X_SEO_CARD_BROWSER_MISSING:
+    'a static build with social cards found no browser to photograph them',
+  X_IMAGE_SOURCE_UNREADABLE: 'a responsiveImage src is not a file the static export holds',
+  X_VERIFY_SKIPS_OVER_CEILING: 'a step skipped more tests than its skipCeiling allows',
+  X_ASSET_VARIANT_UNDECLARED: 'an /assets image variant responsiveImage() never mints',
+  X_NEW_SHAPE_GENERATE_FAILED: 'a shape generator failed in the new app',
+  X_ISLAND_DISPOSER_MISSING: "an island's mount returns no disposer",
+  X_SOCKET_HAND_ROLLED: 'an app upgrades a websocket itself',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws
 // X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
 registerErrorCodes(
-  Object.fromEntries(Object.entries(CLI_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+  Object.fromEntries(
+    Object.entries({
+      ...CLI_ERROR_TITLES,
+      ...CLI_SHOT_ERROR_TITLES,
+      ...CLI_TOOLING_ERROR_TITLES,
+    }).map(([code, title]) => [code, { title }]),
+  ),
 );
 
 // This file exports NO `docsFor(code)`, and adding one back is the defect. A CLI error passes no

package/src/error-contract.ts

@@ -42,8 +42,8 @@ export const COMMAND_TOKENS: readonly RegExp[] = [
   // Built from `fix-path.ts`'s extension list, because the token that makes a fix count as an
   // instruction is exactly the token `citedPathProblem` then has to resolve.
   new RegExp(FILE_TOKEN_PATTERN),
-  // A repo script, run as written: `bin/check --full`, `./bin/probe`. An app's gate is `bin/check`,
-  // so without this the one command its fixes most often name read as the banned word "check".
+  // A repo script, run as written: `bin/check --full`, `./bin/probe`. An app's own wrapper is often
+  // `bin/check` (an older scaffold's gate), so without this its fixes read as the banned word "check".
   // Anchored like `x` above — `/usr/bin/env` and `robin/check` are not the repo's scripts.
   // (`scripts/<name>.ts` is already a file token.)
   /(?:^|[\s;|&("'`])(?:\.\/)?bin\/[\w.-]+/,

package/src/errors.ts

@@ -123,11 +123,30 @@ export class VerifyFailedError extends UltimateError {
 
 /** The command needs an app root (a directory containing `app.config.ts`) and found none. */
 export class NotInAppError extends UltimateError {
-  constructor(input: { command: string; from: string }) {
+  constructor(input: {
+    command: string;
+    from: string;
+    /** `app.config.ts` directories under `from`: an app below the cwd is one `cd` away. */
+    below?: readonly string[];
+    /** `from` already depends on the framework, so `x new` would be a second project, not a fix. */
+    adopter?: boolean;
+  }) {
+    const [first] = input.below ?? [];
+    const found = (input.below ?? []).join(', ');
     super({
       code: 'X_NOT_IN_APP',
-      cause: `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
-      fix: 'x new myapp && cd myapp',
+      cause:
+        first !== undefined
+          ? `"x ${input.command}" runs from the directory holding app.config.ts, and that is below ${input.from}: ${found}`
+          : input.adopter === true
+            ? `"x ${input.command}" must run inside an Ultimate app; ${input.from} depends on @ultimat3/* but no app.config.ts exists at or above it, or within three directories below`
+            : `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
+      fix:
+        first !== undefined
+          ? `cd ${quoteArg(first)} && x ${quoteArg(input.command)} --json`
+          : input.adopter === true
+            ? `x new scratch-app --dry-run --json   # its file list carries app.config.ts; write one at the app root, then re-run: x ${quoteArg(input.command)} --json`
+            : 'bunx create-ultimate myapp && cd myapp',
     });
   }
 }

package/src/exercise-database.ts

@@ -0,0 +1,99 @@
+// Where `x exercise` runs: a test process, pinned before the app loads, on a scratch migrated
+// database installed as the ambient `db()` and thrown away after — never the developer's own (the
+// pass COMMITS its rows), on the engine the schema dump replays on (`db-replay-engine.ts`), so the
+// gate needs nothing listening, exactly as the `drift` step does not.
+
+import type { Environment } from '@ultimat3/core';
+import { ENVIRONMENT_KEY, resolveEnvironment, UltimateError } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { migrate, raw, setDbClient } from '@ultimat3/db';
+import { testSealKeyEnv } from '@ultimat3/testing';
+import { chooseReplayEngine, withScratchDatabase } from './db-replay-engine';
+import { applyFrameworkSchema } from './framework-schema';
+import { readMigrations } from './migrations';
+import { resolveServices } from './runtime-bindings';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * A deployed environment asked for the pass. `X_CONTRACT_EXERCISE_ENVIRONMENT`, core's code for
+ * the same refusal one level down — with this command's fix, never `bun test`'s.
+ */
+export class ExerciseDeployRefusedError extends UltimateError {
+  constructor(environment: Environment) {
+    super({
+      code: 'X_CONTRACT_EXERCISE_ENVIRONMENT',
+      cause: `x exercise runs every handler on generated input, and ${ENVIRONMENT_KEY} resolved ${environment}: the pass runs in development or test only`,
+      fix: `${ENVIRONMENT_KEY}=development x exercise --json   # from a checkout, never against a deploy`,
+      meta: { environment },
+    });
+  }
+}
+
+/**
+ * The environment the pass runs as: always `test`, once a deploy is refused. The pass is a test run
+ * on a scratch database thrown away after it, and an app picks its store from this answer at module
+ * load: a `development` app on its embedded memory store would read none of the rows seeded here.
+ */
+export function exerciseEnvironment(env: Env): Environment {
+  const environment = resolveEnvironment({ env });
+  if (environment !== 'development' && environment !== 'test') {
+    throw new ExerciseDeployRefusedError(environment);
+  }
+  return 'test';
+}
+
+const PINNED = [ENVIRONMENT_KEY, 'NODE_ENV'] as const;
+
+/**
+ * `work` — the app's load and the pass — in a test process: the environment pinned BEFORE any app
+ * module reads it, and the throwaway seal key `bun test` gets when the app supplied none (CI names
+ * no `ULTIMATE_SECRETS_KEY`, and every row sealed here dies with the scratch database). Every
+ * variable is put back as found: a command that exits must not leave the next one a test process.
+ */
+export async function withExerciseProcess<T>(
+  root: string,
+  env: Env,
+  work: () => Promise<T>,
+): Promise<T> {
+  const environment = exerciseEnvironment(env);
+  const pinned: Record<string, string> = Object.fromEntries(
+    PINNED.map((key) => [key, environment]),
+  );
+  const added = { ...pinned, ...testSealKeyEnv({ root, env: { ...env, ...pinned } }) };
+  const previous = Object.keys(added).map((key) => [key, process.env[key]] as const);
+  Object.assign(process.env, added);
+  try {
+    return await work();
+  } finally {
+    for (const [key, value] of previous) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  }
+}
+
+/**
+ * Framework tables, then every migration — the order every real boot runs them in — then `work`
+ * with the client installed. Released either way: a command that exits holding an installed
+ * client would hand the next caller in this process a closed pool.
+ */
+export async function withExerciseDatabase<T>(
+  root: string,
+  env: Env,
+  work: (client: DbClient) => Promise<T>,
+): Promise<T> {
+  const migrations = await readMigrations(root);
+  const engine = await chooseReplayEngine(migrations, env);
+  const { stateDir } = resolveServices(root, env);
+  return withScratchDatabase(engine, stateDir, async (client) => {
+    await applyFrameworkSchema((statement) => client.execute(raw(statement)));
+    await migrate({ migrations, client });
+    setDbClient(client);
+    try {
+      return await work(client);
+    } finally {
+      setDbClient(undefined);
+    }
+  });
+}

package/src/exercise-findings.ts

@@ -0,0 +1,159 @@
+// What `x exercise` makes of a pass's records: one finding per `unreached` primitive, carrying the
+// override to paste as its fix, and per crossed tenant and diverged crash proof; the counts; the
+// table; and the one report document both `--json` and `.x/exercise.json` hold. Pure — records in, plain values out — so the gate step and the
+// command cannot disagree about what is red.
+
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import {
+  ERROR_DOCS_URL,
+  renderCauseValue,
+  renderFixLiteral,
+  renderFixShellArg,
+} from '@ultimat3/core';
+import type { ExerciseRecord } from '@ultimat3/testing';
+import { planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
+import type { Finding } from './output';
+import { renderTable } from './table';
+
+/** Where the pass's report is written, app-root-relative: state, gitignored with the rest of `.x/`. */
+export const EXERCISE_REPORT_FILE = join('.x', 'exercise.json');
+
+/** The file an override is pasted into — `defineExercise()`'s one home. */
+export const EXERCISE_FILE = 'apps/web/exercise.ts';
+
+type Outcome = ExerciseRecord['outcome'];
+
+export interface ExerciseCounts {
+  readonly total: number;
+  readonly reached: number;
+  readonly refused: number;
+  readonly unreached: number;
+  readonly off: number;
+}
+
+export const exerciseCounts = (records: readonly ExerciseRecord[]): ExerciseCounts => {
+  const count = (outcome: Outcome): number =>
+    records.filter((one) => one.outcome === outcome).length;
+  return {
+    total: records.length,
+    reached: count('reached'),
+    refused: count('refused'),
+    unreached: count('unreached'),
+    off: count('off'),
+  };
+};
+
+/**
+ * `X_CONTRACT_EXERCISE_UNREACHED`, `@ultimat3/action`'s code for the same silence one level up: a
+ * primitive no run got to as an allowed actor. The fix is the override the pass printed, or the
+ * input shape to fill when it printed none — then the one-primitive rerun that proves it.
+ */
+const unreachedFinding = (record: ExerciseRecord): Finding => {
+  const name = renderFixShellArg(record.name, '<name>');
+  const override = record.override ?? `${record.name}: { input: { /* a value it accepts */ } }`;
+  const stopped = record.code === undefined ? '' : ` — stopped on ${record.code}`;
+  const why = record.reason === undefined ? '' : ` (${renderCauseValue(record.reason)})`;
+  return {
+    code: 'X_CONTRACT_EXERCISE_UNREACHED',
+    cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}`,
+    fix: `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
+    docs: ERROR_DOCS_URL,
+    at: EXERCISE_FILE,
+  };
+};
+
+type CrashFinding = Extract<
+  NonNullable<ExerciseRecord['crash']>,
+  { readonly verdict: 'diverged' }
+>['findings'][number];
+
+const crashFindingsOf = (record: ExerciseRecord): readonly CrashFinding[] =>
+  record.crash?.verdict === 'diverged' ? record.crash.findings : [];
+
+/**
+ * `X_JOB_CRASH_DIVERGED`, testing's code: a reached job, killed at a step boundary, made an effect
+ * more often than a clean run — it sits outside every `step.run`, so a retry makes it again. One
+ * finding per effect and the step it follows, every boundary that showed it named in the cause.
+ */
+const crashFindings = (record: ExerciseRecord): readonly Finding[] => {
+  const groups = new Map<string, CrashFinding[]>();
+  for (const one of crashFindingsOf(record)) {
+    const key = `${one.effect}\u0000${one.after ?? ''}`;
+    groups.set(key, [...(groups.get(key) ?? []), one]);
+  }
+  const job = renderFixShellArg(record.name, '<job>');
+  return [...groups.values()].map((group): Finding => {
+    const [first] = group as [CrashFinding, ...CrashFinding[]];
+    const where =
+      first.after === undefined
+        ? 'before the first step'
+        : `after step ${JSON.stringify(first.after)}`;
+    const at = group.map((one) => JSON.stringify(one.boundary)).join(', ');
+    return {
+      code: 'X_JOB_CRASH_DIVERGED',
+      cause: `job ${renderCauseValue(record.name)} killed at ${at} made ${renderCauseValue(first.effect)} ${first.killed}× against ${first.clean}× in a clean run: it runs outside every step, ${where}, so the retry after a crash makes it again`,
+      fix: `x exercise ${job} --json   # in job(${renderFixLiteral(record.name, '<job>')}): wrap the ${renderFixLiteral(first.effect, '<effect>')} made ${where} in step.run('<name>', async () => …)`,
+      docs: ERROR_DOCS_URL,
+      at: `${record.kind} ${record.name}`,
+    };
+  });
+};
+
+/** One line per killed boundary that diverged: `job chargeOrder · killed at mail · X_… effect 2×`. */
+export const crashFindingLines = (records: readonly ExerciseRecord[]): readonly string[] =>
+  records.flatMap((record) =>
+    crashFindingsOf(record).map(
+      (one) =>
+        `${record.kind} ${record.name} · killed at ${one.boundary} · X_JOB_CRASH_DIVERGED ${one.effect} ${one.killed}× (clean ${one.clean}×)`,
+    ),
+  );
+
+/**
+ * Unreached primitives, then the tenant proof's crossed ones: tenant B handed A's data or changed
+ * A's row; then the crash proof's diverged jobs. `unproven`, either proof's, is reported on the
+ * record and never red — the pass could not ask, which is not an answer.
+ */
+export const exerciseFindings = (records: readonly ExerciseRecord[]): readonly Finding[] => [
+  ...records.filter((one) => one.outcome === 'unreached').map(unreachedFinding),
+  ...tenantProofFindings(records).map((one) => ({ ...one, docs: ERROR_DOCS_URL })),
+  ...records.flatMap(crashFindings),
+  // The plan and scale sweeps: a statement no index serves, a shape that grows with the rows.
+  ...planSweepFindings(records).map((one) => ({ ...one, docs: ERROR_DOCS_URL })),
+];
+
+export interface ExerciseReport {
+  readonly seed: number | null;
+  readonly counts: ExerciseCounts;
+  readonly records: readonly ExerciseRecord[];
+}
+
+export const exerciseReport = (
+  records: readonly ExerciseRecord[],
+  seed: number | undefined,
+): ExerciseReport => ({ seed: seed ?? null, counts: exerciseCounts(records), records });
+
+/** Unreached first — the rows that need a hand — then refused, off, reached; by name within. */
+const RANK: readonly Outcome[] = ['unreached', 'refused', 'off', 'reached'];
+
+export const renderExerciseTable = (records: readonly ExerciseRecord[]): readonly string[] =>
+  renderTable(
+    ['primitive', 'kind', 'outcome', 'tenant', 'crash', 'code', 'statements', 'effects', 'ms'],
+    records
+      .toSorted(
+        (left, right) =>
+          RANK.indexOf(left.outcome) - RANK.indexOf(right.outcome) ||
+          left.name.localeCompare(right.name),
+      )
+      .map((one) => [
+        one.name,
+        one.kind,
+        one.outcome,
+        one.tenant?.verdict ?? '-',
+        one.crash?.verdict ?? '-',
+        one.code ?? '-',
+        String(one.statements),
+        String(one.effects.length),
+        String(one.ms),
+      ]),
+  );

package/src/exercise-overrides.ts

@@ -0,0 +1,42 @@
+// `apps/web/exercise.ts`, read: the one `defineExercise()` export an app may declare, or none. A
+// file with no such export, or with two, is refused — an override nobody reads is a silent skip,
+// and two are two answers to one question.
+
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import type { ExerciseOverrides } from '@ultimat3/testing';
+import { EXERCISE_FILE } from './exercise-findings';
+
+const isOverrides = (value: unknown): value is ExerciseOverrides =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { readonly kind?: unknown }).kind === 'exercise-overrides';
+
+/**
+ * The file exists and declares no single `defineExercise()` export. `X_CONTRACT_EXERCISE_UNDECLARED`
+ * — `@ultimat3/action`'s code for an exercise option that says nothing — because that is what a
+ * file of overrides the pass cannot find is.
+ */
+export class ExerciseOverridesUnreadableError extends UltimateError {
+  constructor(found: number) {
+    super({
+      code: 'X_CONTRACT_EXERCISE_UNDECLARED',
+      cause: `${EXERCISE_FILE} exports ${found === 0 ? 'no' : String(found)} defineExercise() value${found === 1 ? '' : 's'}, so x exercise cannot tell which overrides to apply`,
+      fix: `export const exercise = defineExercise({});   # one export in ${EXERCISE_FILE}, imported from @ultimat3/testing`,
+    });
+  }
+}
+
+/** The overrides, or `undefined` when the app has no `apps/web/exercise.ts`. */
+export async function readExerciseOverrides(root: string): Promise<ExerciseOverrides | undefined> {
+  const path = join(root, EXERCISE_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  const found = Object.values(module).filter(isOverrides);
+  const [only] = found;
+  if (found.length !== 1 || only === undefined) {
+    throw new ExerciseOverridesUnreadableError(found.length);
+  }
+  return only;
+}