@ultimat3/cli 30.6.0 → 30.7.0

package/CLAUDE.md

@@ -87,6 +87,7 @@ Commands: `bun test packages/cli` (from the repo root: the preload),
 | `app-name.ts` | `x new`'s slug is asked of core's `defineConfig`, never a copied pattern; refused with a suggested name (`9lives` → `app-9lives`, `a` → `a-app`, cut at 64) |
 | `generate-grants.ts` | a written `policy.ts` or `entity.ts` declares and grants its permissions in `apps/web/shared/roles.ts`. Full rule: `docs/history/cli.md` |
 | `api-registration.ts` | a written job or task is listed in `apps/web/api/index.ts` |
+| `generate-exercise.ts` | a contract test's entry in `apps/web/exercise.ts` (`exercise-entry-edit.ts`) |
 | `handle-registration.ts` / `workspace-dep-edit.ts` / `templates/scaffold-db-client.ts` | a written entity joins `entities` in `packages/db/src/client.ts` (`X_DB_HANDLE_UNREGISTERED` carries the lines). Full rule: `docs/history/cli.md` |
 | `generated-imports.ts` | every sibling workspace a written file imports is declared in the manifest it landed under (`x g admin:page`'s `@<app>/i18n` in `apps/admin`) — `package-shape` would otherwise refuse the generator's own output (`X_WORKSPACE_DEP_UNDECLARED`) |
 | `admin-registration.ts` / `templates/admin-catalog.ts` / `source-edit.ts` | `--admin` wires the override it wrote into `admin.ts` (`X_ADMIN_RESOURCE_UNWIRED`) and the labels its screen reads. Full rule: `docs/history/cli.md` |
@@ -95,7 +96,7 @@ Commands: `bun test packages/cli` (from the repo root: the preload),
 | `generate-feature-required.ts` | `x g query`/`backfill` with no slice holding an `entity.ts` is `X_FEATURE_REQUIRED` |
 | `generate-sign-in*.ts` | `x g sign-in`: one flag, no name; OIDC swaps only `x new`'s bytes |
 | `generate-format-written.ts` | the app's Biome over the TypeScript a run created, best effort; `lint` judges |
-| `templates/scaffold-mcp-{json,endpoint,admin}.ts` | `.mcp.json` (`bunx @ultimat3/cli mcp serve`, never `bunx x`), the refusing `apps/web/mcp.ts` + `app/auth/agent-token.ts`, `apps/admin/mcp.ts`; `scaffold-agents-md.test.ts` resolves every command `AGENTS.md` names |
+| `templates/scaffold-mcp-{json,endpoint,admin}.ts` | `.mcp.json` (`bunx @ultimat3/cli mcp serve`, never `bunx x`) and the refusing MCP endpoints. Full rule: `docs/history/cli.md` |
 
 ### Boot (`x dev`, the container)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "30.6.0",
+  "version": "30.7.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "keywords": [
     "ultimate",
@@ -53,33 +53,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.7",
-    "@ultimat3/action": "30.6.0",
-    "@ultimat3/admin": "30.6.0",
-    "@ultimat3/ai": "30.6.0",
-    "@ultimat3/auth": "30.6.0",
-    "@ultimat3/cache": "30.6.0",
-    "@ultimat3/core": "30.6.0",
-    "@ultimat3/db": "30.6.0",
-    "@ultimat3/entity": "30.6.0",
-    "@ultimat3/flags": "30.6.0",
-    "@ultimat3/http": "30.6.0",
-    "@ultimat3/i18n": "30.6.0",
-    "@ultimat3/jobs": "30.6.0",
-    "@ultimat3/mail": "30.6.0",
-    "@ultimat3/manifest": "30.6.0",
-    "@ultimat3/mcp": "30.6.0",
-    "@ultimat3/money": "30.6.0",
-    "@ultimat3/notify": "30.6.0",
-    "@ultimat3/policy": "30.6.0",
-    "@ultimat3/pwa": "30.6.0",
-    "@ultimat3/query": "30.6.0",
-    "@ultimat3/realtime": "30.6.0",
-    "@ultimat3/render": "30.6.0",
-    "@ultimat3/schema": "30.6.0",
-    "@ultimat3/seo": "30.6.0",
-    "@ultimat3/storage": "30.6.0",
-    "@ultimat3/testing": "30.6.0",
-    "@ultimat3/time": "30.6.0",
+    "@ultimat3/action": "30.7.0",
+    "@ultimat3/admin": "30.7.0",
+    "@ultimat3/ai": "30.7.0",
+    "@ultimat3/auth": "30.7.0",
+    "@ultimat3/cache": "30.7.0",
+    "@ultimat3/core": "30.7.0",
+    "@ultimat3/db": "30.7.0",
+    "@ultimat3/entity": "30.7.0",
+    "@ultimat3/flags": "30.7.0",
+    "@ultimat3/http": "30.7.0",
+    "@ultimat3/i18n": "30.7.0",
+    "@ultimat3/jobs": "30.7.0",
+    "@ultimat3/mail": "30.7.0",
+    "@ultimat3/manifest": "30.7.0",
+    "@ultimat3/mcp": "30.7.0",
+    "@ultimat3/money": "30.7.0",
+    "@ultimat3/notify": "30.7.0",
+    "@ultimat3/policy": "30.7.0",
+    "@ultimat3/pwa": "30.7.0",
+    "@ultimat3/query": "30.7.0",
+    "@ultimat3/realtime": "30.7.0",
+    "@ultimat3/render": "30.7.0",
+    "@ultimat3/schema": "30.7.0",
+    "@ultimat3/seo": "30.7.0",
+    "@ultimat3/storage": "30.7.0",
+    "@ultimat3/testing": "30.7.0",
+    "@ultimat3/time": "30.7.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/cmd-exercise.ts

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { describeEntities, registeredEntities } from '@ultimat3/entity';
 import { registeredSubjects } from '@ultimat3/jobs';
 import type { NamedActor } from '@ultimat3/policy';
-import type { ExerciseRecord, SeedEntity } from '@ultimat3/testing';
+import type { ExercisePhaseMs, ExerciseRecord, SeedEntity } from '@ultimat3/testing';
 import {
   entitySeedWriter,
   planSweepLines,
@@ -26,8 +26,10 @@ import {
   crashFindingLines,
   EXERCISE_REPORT_FILE,
   exerciseFindings,
+  exercisePhaseLine,
   exerciseReport,
   renderExerciseTable,
+  slowestProofLines,
 } from './exercise-findings';
 import { readExerciseOverrides } from './exercise-overrides';
 import { entityTenantFindings } from './exercise-static';
@@ -79,6 +81,7 @@ async function exercise(
   const proved = registeredSubjects().filter(
     (subject) => only === undefined && !subjectStatic.some((f) => f.at === subject.entity),
   );
+  let pass: ExercisePhaseMs | undefined;
   const records: readonly ExerciseRecord[] = await withExerciseDatabase(root, ctx.env, (client) =>
     runExercisePass({
       entities,
@@ -87,8 +90,12 @@ async function exercise(
       ...(overrides === undefined ? {} : { overrides }),
       ...(only === undefined ? {} : { only }),
       roles: exerciseRoles,
+      onPhases: (ms) => {
+        pass = ms;
+      },
     }),
   );
+  const subjectStarted = performance.now();
   // The subject proof (`exercise-subject.ts`) on a scratch database of its own: the pass's rows
   // are committed, and a second seed graph beside them collides on every small unique domain.
   const subjectProofs =
@@ -97,7 +104,9 @@ async function exercise(
       : await withExerciseDatabase(root, ctx.env, (client) =>
           subjectProofFindings(proved, cores, client, overrides?.factories),
         );
-  const report = exerciseReport(records, seed);
+  const subject = Math.round(performance.now() - subjectStarted);
+  const phases = pass === undefined ? undefined : { ...pass, subject };
+  const report = exerciseReport(records, seed, phases);
   // The whole pass, not a one-primitive run's slice of it, is what the file is for — but a
   // one-primitive run is still a fact worth keeping, so it is written either way.
   await Bun.write(join(root, EXERCISE_REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
@@ -119,6 +128,8 @@ async function exercise(
         : msg('cli.exercise.summary', { ...report.counts, file: EXERCISE_REPORT_FILE }),
     lines: [
       ...renderExerciseTable(records),
+      ...(phases === undefined ? [] : [exercisePhaseLine(phases)]),
+      ...slowestProofLines(records),
       ...tenantFindingLines(records),
       ...crashFindingLines(records),
       ...planSweepLines(records),

package/src/cmd-generate.ts

@@ -14,6 +14,7 @@ import { invocationOf } from './command';
 import { localiseCatalogs, namedOrAppLocales } from './generate-catalog-locales';
 import { refuseChartAlertsFlags, runChartAlerts } from './generate-chart-alerts';
 import { appDisk, plannedDisk } from './generate-disk';
+import { writtenExercises } from './generate-exercise';
 import { assertFeatureExists } from './generate-feature';
 import { assertSliceToRead } from './generate-feature-required';
 import { generate, sliceDir } from './generate-files';
@@ -195,7 +196,13 @@ export const generateCommand: CliCommand = {
       const follow =
         refused.length > 0
           ? { edited: [], findings: [] }
-          : await followUpEdits(root, plan.written, dbModule, plannedDisk(root, planned));
+          : await followUpEdits(
+              root,
+              plan.written,
+              dbModule,
+              plannedDisk(root, planned),
+              writtenExercises(files, plan.written),
+            );
       const findings = [...refused, ...follow.findings];
       const touched = refused.length === 0 ? [...plan.written, ...follow.edited] : [];
       // Re-projected after a real write, from the loaded app: named, since their bytes are not
@@ -228,7 +235,13 @@ export const generateCommand: CliCommand = {
     // The edits a generated primitive needs outside its own slice, performed rather than left as
     // findings (`generate-follow-ups.ts`). Before the manifest load below, so the projection sees
     // them all — a repo reading a table the handle lacks would not load at all.
-    const follow = await followUpEdits(root, report.written, dbModule, appDisk(root));
+    const follow = await followUpEdits(
+      root,
+      report.written,
+      dbModule,
+      appDisk(root),
+      writtenExercises(files, report.written),
+    );
     const edited = follow.edited;
     // Before the manifest reads a byte of it. Only what this run created: an edited file is its
     // author's, and a run that reformatted one would hand them a diff they never asked for.

package/src/cmd-new.ts

@@ -12,6 +12,7 @@ import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
 import { AppNameEmptyError, AppNameIsPathError, MissingPositionalError } from './errors';
 import type { Runner } from './exec';
+import { withDeclaredExercises } from './generate-exercise';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import { type NewShape, readShape } from './new-shapes';
@@ -142,7 +143,7 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
     const overlay = SHAPE_OVERLAYS[options.shape];
     const base = planNewApp({ name: options.name, example: overlay.example });
     // Merge-aware, as below: a shape's catalog keys land in the one catalog the base wrote.
-    return dedupe(applyOverlay(base, overlay, names(options.name)));
+    return withDeclaredExercises(dedupe(applyOverlay(base, overlay, names(options.name))));
   }
   const app = names(options.name);
   const files: GeneratedFile[] = [
@@ -169,7 +170,8 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   // `repoFiles`' own catalog entry and the example resource's both target the same flat catalog
   // file, so this has to be the merge-aware dedupe — the one `cmd-generate.ts` uses for `x g` —
   // or the second contributor's keys would silently vanish instead of landing in the one file.
-  return dedupe(files);
+  // And each contract test's entry in `apps/web/exercise.ts`, the one file it reads it from.
+  return withDeclaredExercises(dedupe(files));
 }
 
 export interface WrittenApp {

package/src/error-codes.ts

@@ -250,6 +250,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_NEW_SHAPE_GENERATE_FAILED',
   'X_ISLAND_DISPOSER_MISSING',
   'X_SOCKET_HAND_ROLLED',
+  'X_EXERCISE_FILE_UNEDITABLE',
 ] as const;
 
 /**
@@ -470,6 +471,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliListedErrorCode, string>> = {
   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',
+  X_EXERCISE_FILE_UNEDITABLE: 'x g could not add an entry to apps/web/exercise.ts',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/exercise-entry-edit.ts

@@ -0,0 +1,169 @@
+// The one editor of an app's `apps/web/exercise.ts`: entries inserted into its single
+// `export const exercise = defineExercise({ … })`, read off the MASKED source (a call in a comment
+// or a string is prose), printed the way Biome leaves them, each import in Biome's order. A file
+// it cannot read that way is refused with the reason, never guessed at; a named entry is the app's.
+
+import { maskOf, readList, readProperties } from './source-list-edit';
+import { exerciseFiles } from './templates/scaffold-exercise';
+import { wrapImport } from './templates/wrap';
+
+/** One value an entry needs imported: `userActor` from `@ultimat3/core`. */
+export interface ExerciseImport {
+  readonly name: string;
+  readonly from: string;
+}
+
+/**
+ * One primitive's entry. `value` is its object literal printed at column 0 (`{\n  actor: …,\n}` or
+ * `{ off: '…' }`); the edit indents it to where the call's properties sit.
+ */
+export interface ExerciseEntry {
+  readonly name: string;
+  readonly value: string;
+  readonly imports?: readonly ExerciseImport[];
+}
+
+export type ExerciseEdit =
+  | { readonly kind: 'edited' | 'unchanged'; readonly source: string }
+  | { readonly kind: 'refused'; readonly reason: string };
+
+const CALL = /\bdefineExercise\s*\(\s*/g;
+const EXPORTED = /\bexport\s+const\s+exercise\s*=\s*defineExercise\s*\(/;
+/** An entry's key: `name:`, `'name':`, or a shorthand `name` — read off the entry's own text. */
+const KEY = /^(?:([A-Za-z_$][\w$]*)|'([^']*)'|"([^"]*)")\s*(?::|$)/;
+
+const refused = (reason: string): ExerciseEdit => ({ kind: 'refused', reason });
+
+/** `source` (or `x new`'s file when there is none) with every entry it does not name yet. */
+export function editExerciseFile(
+  source: string | undefined,
+  entries: readonly ExerciseEntry[],
+): ExerciseEdit {
+  const base = source ?? String(exerciseFiles()[0]?.contents ?? '');
+  const masked = maskOf(base);
+  const calls = [...masked.matchAll(CALL)];
+  const call = calls[0];
+  if (call === undefined) return refused('holds no defineExercise() call');
+  if (calls.length > 1) return refused(`holds ${calls.length} defineExercise() calls`);
+  const open = call.index + call[0].length;
+  if (masked[open] !== '{') {
+    return refused('hands defineExercise() something other than an object literal ({ … })');
+  }
+  if (!EXPORTED.test(masked)) {
+    return refused('does not declare it as export const exercise = defineExercise(…)');
+  }
+  const list = readList(base, masked, open);
+  if (list === undefined) return refused('has a defineExercise({ … }) that never closes');
+  const named = new Set(list.entries.map((entry) => keyOf(entry.text)));
+  const missing = unique(entries).filter((entry) => !named.has(entry.name));
+  if (missing.length === 0) return { kind: 'unchanged', source: base };
+
+  const inserted = insertRows(base, masked, list, missing);
+  const next = withImports(
+    inserted,
+    missing.flatMap((entry) => entry.imports ?? []),
+  );
+  return readsBack(next, missing)
+    ? { kind: 'edited', source: next }
+    : refused('reads back changed');
+}
+
+const keyOf = (text: string): string | undefined => {
+  const found = KEY.exec(text);
+  return found === null ? undefined : (found[1] ?? found[2] ?? found[3]);
+};
+
+const unique = (entries: readonly ExerciseEntry[]): readonly ExerciseEntry[] =>
+  entries.filter((entry, index) => entries.findIndex((e) => e.name === entry.name) === index);
+
+const lineIndent = (source: string, at: number): string => {
+  const start = source.lastIndexOf('\n', at - 1) + 1;
+  return /^[ \t]*/.exec(source.slice(start))?.[0] ?? '';
+};
+
+/** `  name: value,` with every line of the value under `indent`. */
+const row = (indent: string, entry: ExerciseEntry): string =>
+  `${indent}${entry.name}: ${entry.value.split('\n').join(`\n${indent}`)},`;
+
+function insertRows(
+  source: string,
+  masked: string,
+  list: NonNullable<ReturnType<typeof readList>>,
+  entries: readonly ExerciseEntry[],
+): string {
+  const outer = lineIndent(source, list.open);
+  const multiline = masked.slice(list.open, list.close).includes('\n');
+  const first = list.entries[0];
+  // A property's own indent where one starts its line; else one step in from the brace's line.
+  const startsLine =
+    first !== undefined &&
+    source.slice(source.lastIndexOf('\n', first.start - 1) + 1, first.start).trim() === '';
+  const indent =
+    multiline && startsLine && first !== undefined ? lineIndent(source, first.start) : `${outer}  `;
+  const rows = entries.map((entry) => row(indent, entry));
+  const closeLine = source.lastIndexOf('\n', list.close) + 1;
+  const last = list.entries.at(-1);
+  if (multiline && source.slice(closeLine, list.close).trim() === '') {
+    // Appended as the last rows, above the closing brace's own line; the comma the old last entry
+    // owes goes right after its code, before any comment beside it.
+    const before = source.slice(0, closeLine);
+    const head =
+      last === undefined || list.trailingComma
+        ? before
+        : `${before.slice(0, last.end)},${before.slice(last.end)}`;
+    return `${head}${rows.join('\n')}\n${source.slice(closeLine)}`;
+  }
+  // One line — `{}` or `{ keep: … }` — or a brace sharing its line with code: a row each, Biome's
+  // expanded shape, the old entries first.
+  const kept = list.entries.map((entry) => `${indent}${entry.text},`);
+  const head = source.slice(0, list.open + 1);
+  return `${head}\n${[...kept, ...rows].join('\n')}\n${outer}${source.slice(list.close)}`;
+}
+
+/** Every top-level `import … from '<x>';` of the source: where it spans and what it names. */
+const IMPORT = /^import\s+(type\s+)?\{([^}]*)\}\s*from\s*'([^']+)';[^\S\n]*$/gm;
+const ANY_IMPORT = /^import\s[^;]*?from\s*'([^']+)';/gm;
+
+/** Biome's groups, coarsely: builtins, then packages, then relative paths. */
+const rank = (from: string): number =>
+  /^(?:bun|node):/.test(from) ? 0 : from.startsWith('.') ? 2 : 1;
+
+const before = (left: string, right: string): boolean =>
+  rank(left) !== rank(right) ? rank(left) < rank(right) : left < right;
+
+function withImports(source: string, wanted: readonly ExerciseImport[]): string {
+  let next = source;
+  for (const want of wanted) {
+    const masked = maskOf(next);
+    const statements = [...next.matchAll(IMPORT)].filter((m) => masked[m.index] === 'i');
+    const named = statements.find((m) => m[1] === undefined && m[3] === want.from);
+    if (named !== undefined) {
+      const names = (named[2] ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+      if (names.includes(want.name)) continue;
+      const line = wrapImport([...names, want.name], want.from);
+      next = `${next.slice(0, named.index)}${line}${next.slice(named.index + named[0].length)}`;
+      continue;
+    }
+    const all = [...next.matchAll(ANY_IMPORT)].filter((m) => masked[m.index] === 'i');
+    const after = all.find((m) => before(want.from, m[1] ?? ''));
+    const last = all.at(-1);
+    const at = after?.index ?? (last === undefined ? 0 : last.index + last[0].length + 1);
+    next = `${next.slice(0, at)}${wrapImport([want.name], want.from)}\n${next.slice(at)}`;
+  }
+  return next;
+}
+
+/** One call still, and every inserted name a key of it now. */
+function readsBack(source: string, entries: readonly ExerciseEntry[]): boolean {
+  const masked = maskOf(source);
+  const calls = [...masked.matchAll(CALL)];
+  const call = calls[0];
+  if (calls.length !== 1 || call === undefined) return false;
+  const keys = new Set(
+    readProperties(source, masked, call.index + call[0].length).map((p) => p.key),
+  );
+  return entries.every((entry) => keys.has(entry.name));
+}

package/src/exercise-findings.ts

@@ -11,8 +11,9 @@ import {
   renderFixLiteral,
   renderFixShellArg,
 } from '@ultimat3/core';
-import type { ExerciseRecord } from '@ultimat3/testing';
+import type { ExercisePhaseMs, ExerciseRecord, ProofMs } from '@ultimat3/testing';
 import { crashEffectPlace, planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
+import { msg } from './messages';
 import type { Finding } from './output';
 import { renderTable } from './table';
 
@@ -73,7 +74,7 @@ const unreachedFinding = (record: ExerciseRecord): Finding => {
     cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}${defectOf(record)}`,
     fix:
       record.fix ??
-      `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
+      `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE} (an inline .contract({ exercise: {...} }) in a test is not read here: move it, then pass .contract({ exercise })), or { off: '<why>' }; then: x exercise ${name} --json`,
     docs: ERROR_DOCS_URL,
     at: EXERCISE_FILE,
   };
@@ -140,23 +141,89 @@ export const exerciseFindings = (records: readonly ExerciseRecord[]): readonly F
   ...planSweepFindings(records).map((one) => ({ ...one, docs: ERROR_DOCS_URL })),
 ];
 
+/** The pass's phases, and the subject proof the CLI runs after it on a database of its own. */
+export interface ExercisePhases extends ExercisePhaseMs {
+  readonly subject: number;
+}
+
 export interface ExerciseReport {
   readonly seed: number | null;
   readonly counts: ExerciseCounts;
+  /** Milliseconds per phase: absent only when the pass threw before it could say. */
+  readonly phases?: ExercisePhases;
   readonly records: readonly ExerciseRecord[];
 }
 
 export const exerciseReport = (
   records: readonly ExerciseRecord[],
   seed: number | undefined,
-): ExerciseReport => ({ seed: seed ?? null, counts: exerciseCounts(records), records });
+  phases?: ExercisePhases,
+): ExerciseReport => ({
+  seed: seed ?? null,
+  counts: exerciseCounts(records),
+  ...(phases === undefined ? {} : { phases }),
+  records,
+});
+
+const PHASE_ORDER = ['seed', 'primitives', 'scale', 'plans', 'subject'] as const;
+
+/** `took 10610 ms — seed 800 · primitives 9100 · … — slowest: primitives`. */
+export function exercisePhaseLine(phases: ExercisePhases): string {
+  const total = PHASE_ORDER.reduce((sum, key) => sum + phases[key], 0);
+  const slowest = PHASE_ORDER.reduce((top, key) => (phases[key] > phases[top] ? key : top));
+  return msg('cli.exercise.phases', {
+    total,
+    phases: PHASE_ORDER.map((key) => `${key} ${phases[key]}`).join(' · '),
+    slowest,
+  });
+}
+
+const PROOF_ORDER = ['tenant', 'crash', 'scale'] as const satisfies readonly (keyof ProofMs)[];
+
+/** How many records the slowest-proof lines name: the head of the list is where the time went. */
+export const SLOWEST_SHOWN = 5;
+
+/** The records whose one proof took longest, slowest first: `slowest: job x · crash 9000 ms`. */
+export function slowestProofLines(records: readonly ExerciseRecord[]): readonly string[] {
+  const proofs = records.flatMap((record) => {
+    const top = PROOF_ORDER.map((proof) => [proof, record.proofMs?.[proof] ?? 0] as const).reduce(
+      (best, one) => (one[1] > best[1] ? one : best),
+    );
+    return top[1] > 0 ? [{ record, proof: top[0], ms: top[1] }] : [];
+  });
+  return proofs
+    .toSorted((left, right) => right.ms - left.ms)
+    .slice(0, SLOWEST_SHOWN)
+    .map((one) =>
+      msg('cli.exercise.slowest', {
+        primitive: `${one.record.kind} ${one.record.name}`,
+        proof: one.proof,
+        ms: one.ms,
+      }),
+    );
+}
+
+const msOf = (value: number | undefined): string => (value === undefined ? '-' : String(value));
 
 /** 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'],
+    [
+      'primitive',
+      'kind',
+      'outcome',
+      'tenant',
+      'crash',
+      'code',
+      'statements',
+      'effects',
+      'ms',
+      'tenant ms',
+      'crash ms',
+      'scale ms',
+    ],
     records
       .toSorted(
         (left, right) =>
@@ -173,5 +240,8 @@ export const renderExerciseTable = (records: readonly ExerciseRecord[]): readonl
         String(one.statements),
         String(one.effects.length),
         String(one.ms),
+        msOf(one.proofMs?.tenant),
+        msOf(one.proofMs?.crash),
+        msOf(one.proofMs?.scale),
       ]),
   );

package/src/exercise-registration.ts

@@ -2,6 +2,7 @@
 // cannot run as generated, each turned off with its reason, so the app's next `x verify` is green.
 // An entry the app already declares is the app's and is never touched.
 
+import { editExerciseFile } from './exercise-entry-edit';
 import { exerciseFiles } from './templates/scaffold-exercise';
 
 export const EXERCISE_FILE = 'apps/web/exercise.ts';
@@ -30,27 +31,22 @@ export const signInExerciseEntries = (
     return entry === undefined ? [] : [entry];
   });
 
-const DEFINE = 'defineExercise({';
-
 /**
  * `source` with each entry not already named in it inserted at the top of `defineExercise({ … })`;
- * `undefined` when there is no file, which starts from `x new`'s. A file with no `defineExercise({`
- * is the app's own shape and is left as it is.
+ * `undefined` when there is no file, which starts from `x new`'s. A file the one editor
+ * (`exercise-entry-edit.ts`) cannot read is the app's own shape and is left as it is.
  */
 export function exerciseWithEntries(
   source: string | undefined,
   entries: readonly (readonly [string, string])[],
 ): string {
-  const base = source ?? String(exerciseFiles()[0]?.contents ?? '');
-  const at = base.indexOf(DEFINE);
-  if (at === -1) return base;
-  const missing = entries.filter(([name]) => !new RegExp(`\\b${name}\\s*:`).test(base));
-  if (missing.length === 0) return base;
-  const lines = missing.map(([name, why]) => `  ${name}: { off: ${singleQuoted(why)} },`);
-  const after = at + DEFINE.length;
-  // `defineExercise({})` — the scaffold's — opens onto its own close: the close gets its own line.
-  const rest = base.slice(after);
-  return `${base.slice(0, after)}\n${lines.join('\n')}${rest.startsWith('}') ? '\n' : ''}${rest}`;
+  const edit = editExerciseFile(
+    source,
+    entries.map(([name, why]) => ({ name, value: `{ off: ${singleQuoted(why)} }` })),
+  );
+  return edit.kind === 'refused'
+    ? (source ?? String(exerciseFiles()[0]?.contents ?? ''))
+    : edit.source;
 }
 
 /** A single-quoted TypeScript string literal, Biome's own quote style. */

package/src/generate-exercise.ts

@@ -0,0 +1,77 @@
+// `x g`'s half of the one exercise declaration: each written contract test's entry inserted into
+// `apps/web/exercise.ts` (created from `x new`'s shape when the app has none), since the test reads
+// it from there. A file the editor cannot read is `X_EXERCISE_FILE_UNEDITABLE`, the entry in its fix.
+
+import { UltimateError } from '@ultimat3/core';
+import type { ExerciseEntry } from './exercise-entry-edit';
+import { editExerciseFile } from './exercise-entry-edit';
+import { EXERCISE_FILE } from './exercise-registration';
+import type { GenerateDisk } from './generate-disk';
+import type { Finding } from './output';
+import type { GeneratedFile } from './templates';
+
+/** The entries the files this run WROTE carry — a skipped or conflicting file is owed none. */
+export const writtenExercises = (
+  files: readonly GeneratedFile[],
+  written: readonly string[],
+): readonly ExerciseEntry[] =>
+  files.flatMap((file) =>
+    'exercise' in file && file.exercise !== undefined && written.includes(file.path)
+      ? [file.exercise]
+      : [],
+  );
+
+/** One line of an entry: what the fix asks to paste, whitespace folded. */
+const oneLine = (entry: ExerciseEntry): string =>
+  `${entry.name}: ${entry.value.replace(/\s*\n\s*/g, ' ').replace(/, }/g, ' }')}`;
+
+/** Inserts `entries` into the app's exercise file; answers the path when it changed, or a refusal. */
+export async function declareGeneratedExercises(
+  entries: readonly ExerciseEntry[],
+  disk: GenerateDisk,
+): Promise<{ readonly edited: readonly string[]; readonly findings: readonly Finding[] }> {
+  if (entries.length === 0) return { edited: [], findings: [] };
+  const before = await disk.read(EXERCISE_FILE);
+  const edit = editExerciseFile(before, entries);
+  if (edit.kind === 'refused') {
+    return {
+      edited: [],
+      findings: [
+        {
+          code: 'X_EXERCISE_FILE_UNEDITABLE',
+          cause: `${EXERCISE_FILE} ${edit.reason}, so x g could not declare ${entries.map((e) => e.name).join(', ')} there and its contract test reads no entry`,
+          // The code to paste first: a fix is pasted from its first character.
+          fix: `${entries.map(oneLine).join(', ')},   # paste inside export const exercise = defineExercise({ … }) in ${EXERCISE_FILE}`,
+          at: EXERCISE_FILE,
+        },
+      ],
+    };
+  }
+  if (edit.kind === 'unchanged' && before !== undefined) return { edited: [], findings: [] };
+  await disk.write(EXERCISE_FILE, edit.source);
+  return { edited: [EXERCISE_FILE], findings: [] };
+}
+
+/**
+ * `x new`'s file set with every contract test's entry already in its `apps/web/exercise.ts` — the
+ * scaffold writes both at once, so there is no disk to edit. The file is the template's own, so a
+ * refusal is this package's defect and is thrown, never written.
+ */
+export function withDeclaredExercises(files: readonly GeneratedFile[]): readonly GeneratedFile[] {
+  const entries = writtenExercises(
+    files,
+    files.map((file) => file.path),
+  );
+  const at = files.findIndex((file) => file.path === EXERCISE_FILE);
+  const file = files[at];
+  if (entries.length === 0 || file === undefined || typeof file.contents !== 'string') return files;
+  const edit = editExerciseFile(file.contents, entries);
+  if (edit.kind === 'refused') {
+    throw new UltimateError({
+      code: 'X_EXERCISE_FILE_UNEDITABLE',
+      cause: `x new's own ${EXERCISE_FILE} ${edit.reason}, so its contract tests would read no entry`,
+      fix: 'bun test packages/cli/src/generate-exercise.test.ts   # the scaffold template and the editor disagree',
+    });
+  }
+  return files.map((one, index) => (index === at ? { ...one, contents: edit.source } : one));
+}