@ultimat3/cli 22.6.2 → 22.7.0

package/src/verify-errors.ts

@@ -0,0 +1,49 @@
+// The gate's sizing and CI-split refusals: a bad budget env var, an unsplittable `--shard`, and a
+// `x verify merge` part that is not a verify document. Split from errors.ts at its size ceiling.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * `ULTIMATE_TEST_MEMORY_BUDGET` or `ULTIMATE_TEST_MAX_WORKERS` set to something that does not
+ * parse. Refused rather than ignored: a typo read as "the default" is a run sized for a machine
+ * the caller said this is not.
+ */
+export class TestBudgetInvalidError extends UltimateError {
+  constructor(name: string, value: string) {
+    super({
+      code: 'X_TEST_BUDGET_INVALID',
+      cause: `${name}=${JSON.stringify(value)} does not parse — ${
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'expected a positive integer'
+          : 'expected a size such as 3g, 512m or 4GiB'
+      }`,
+      fix:
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'ULTIMATE_TEST_MAX_WORKERS=4 x verify'
+          : 'ULTIMATE_TEST_MEMORY_BUDGET=3g x verify',
+    });
+  }
+}
+
+/** `x verify --shard` asked for a split the gate cannot make. */
+export class VerifyShardInvalidError extends UltimateError {
+  constructor(input: { reason: string; fix?: string }) {
+    super({
+      code: 'X_VERIFY_SHARD_INVALID',
+      cause: `x verify --shard: ${input.reason}`,
+      fix: input.fix ?? 'x verify --only unit --shard 1/4 --json',
+    });
+  }
+}
+
+/** A part handed to `x verify merge` that is not an `x verify --json` document. */
+export class VerifyMergeInputError extends UltimateError {
+  constructor(input: { file: string; reason: string; sourceError?: unknown }) {
+    super({
+      code: 'X_VERIFY_MERGE_INPUT',
+      cause: `x verify merge: ${input.file} ${input.reason}`,
+      fix: 'x verify --only <step> --json > part.json   # one document per part, the last line of stdout',
+      ...(input.sourceError === undefined ? {} : { sourceError: input.sourceError }),
+    });
+  }
+}

package/src/verify-floor.ts

@@ -41,6 +41,13 @@ export interface VerifyFloor {
    * found` from its own shell, not a framework opinion about which compiler is correct.
    */
   readonly typecheckBin?: string;
+  /**
+   * Run every parallel test file in a fresh global (`bun test --isolate`). Absent or `false` is
+   * the default since 22.7: one global per worker process, reused across the files it runs — 2-5x
+   * faster, measured (`test-workers.ts`). A repository whose tests lean on per-file module state
+   * says `true` here once, in the file that configures the gate, and `x test`/`x verify` honour it.
+   */
+  readonly isolate?: boolean;
   /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
   readonly problems: readonly string[];
 }
@@ -51,6 +58,22 @@ export const BUDGET_FIELD = 'agentsMdMaxBytes';
 /** The floor's typecheck-binary key. Named once: the problem quotes it and the fix repairs it. */
 export const TYPECHECK_BIN_FIELD = 'typecheckBin';
 
+/** The floor's isolation key. */
+export const ISOLATE_FIELD = 'isolate';
+
+function readIsolate(payload: Record<string, unknown> | undefined): {
+  isolate?: boolean;
+  problems: readonly string[];
+} {
+  const raw = payload?.[ISOLATE_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'boolean')
+    return {
+      problems: [`"${ISOLATE_FIELD}" is ${JSON.stringify(raw)}, which is not true or false`],
+    };
+  return { isolate: raw, problems: [] };
+}
+
 /**
  * `agentsMdMaxBytes`, or a reason it is not one. A budget that is not a positive whole number is
  * the caller's bug and must not silently fall back to the default: a floor file that says
@@ -123,16 +146,19 @@ export function parseVerifyFloor(
   const record = asRecord(payload);
   const budget = readBudget(record);
   const typecheckBin = readTypecheckBin(record);
+  const isolate = readIsolate(record);
   const steps = record?.['steps'];
   if (!Array.isArray(steps)) {
     return {
       steps: [],
       ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
       ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+      ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
       problems: [
         'it has no "steps" array of step names',
         ...budget.problems,
         ...typecheckBin.problems,
+        ...isolate.problems,
       ],
     };
   }
@@ -142,7 +168,9 @@ export function parseVerifyFloor(
     steps: named.filter((step) => declared.includes(step)),
     ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
     ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+    ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
     problems: [
+      ...isolate.problems,
       ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
       ...typecheckBin.problems,
       ...(unknown.length === 0

package/src/verify-merge.ts

@@ -0,0 +1,235 @@
+// `x verify merge <part.json…>`: n CI jobs' `x verify --only … [--shard i/n] --json` documents
+// back into ONE gate verdict. Green only when the parts are provably the whole gate:
+//
+// - every step of `VERIFY_STEP_NAMES` reported by exactly one part — or, for a sharded step, by
+//   shards 1..n exactly once each, all counting the same corpus (`corpusHash`);
+// - the zero-tests floor applied to the SUMMED counts of a sharded step, which each shard deferred;
+// - any gap is a named `X_VERIFY_MERGE_INCOMPLETE` finding, never a silent pass.
+//
+// The merged document is a gate run (no `notAGateRun`), because the question it answers — did
+// every step run, over the whole tree, and pass — is the gate's question.
+
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { msg } from './messages';
+import type { CommandResult, Finding, StepResult } from './output';
+import type { TestCounts } from './test-counts';
+import { VerifyMergeInputError } from './verify-errors';
+import type { VerifyFloor } from './verify-floor';
+import { floorRequires, skippedSuiteFinding } from './verify-floor';
+import { verifySummary } from './verify-run';
+import { VERIFY_STEP_NAMES } from './verify-step';
+
+interface PartStep {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly durationMs: number;
+  readonly skipped: boolean;
+  readonly findings: readonly Finding[];
+  readonly workers?: number;
+  readonly tests?: TestCounts;
+  readonly output?: string;
+  readonly shard?: {
+    readonly index: number;
+    readonly total: number;
+    readonly corpusHash: string;
+    readonly files: readonly string[];
+  };
+}
+
+export interface VerifyPart {
+  readonly file: string;
+  readonly durationMs: number;
+  readonly steps: readonly PartStep[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * The LAST non-empty line that parses: `bin/check --json` prints the build's document and then
+ * the gate's, and a reader takes the last one.
+ */
+export function parsePart(file: string, text: string): VerifyPart {
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  if (lines.length === 0) throw new VerifyMergeInputError({ file, reason: 'is empty' });
+  let doc: unknown;
+  try {
+    doc = JSON.parse(lines[lines.length - 1] as string);
+  } catch (error) {
+    throw new VerifyMergeInputError({
+      file,
+      reason: `does not end in a JSON document (${renderThrowable(error)})`,
+      sourceError: error,
+    });
+  }
+  if (!isRecord(doc) || doc['command'] !== 'verify' || !Array.isArray(doc['steps'])) {
+    throw new VerifyMergeInputError({
+      file,
+      reason: 'is not an x verify --json document (no "command": "verify" with "steps")',
+    });
+  }
+  const data = isRecord(doc['data']) ? doc['data'] : {};
+  const steps: PartStep[] = [];
+  for (const raw of doc['steps'] as unknown[]) {
+    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
+      throw new VerifyMergeInputError({ file, reason: 'holds a step without a name and ok' });
+    }
+    steps.push(raw as unknown as PartStep);
+  }
+  return {
+    file,
+    durationMs: typeof data['durationMs'] === 'number' ? data['durationMs'] : 0,
+    steps,
+  };
+}
+
+const gap = (cause: string, at?: string): Finding => ({
+  code: 'X_VERIFY_MERGE_INCOMPLETE',
+  cause,
+  fix: 'x verify merge parts/*.json --json   # after every CI job uploaded its part',
+  docs: ERROR_DOCS_URL,
+  ...(at === undefined ? {} : { at }),
+});
+
+const sumCounts = (steps: readonly PartStep[]): TestCounts | undefined => {
+  const counted = steps.filter((step) => step.tests !== undefined);
+  if (counted.length === 0) return undefined;
+  return counted.reduce<TestCounts>(
+    (sum, step) => ({
+      ran: sum.ran + (step.tests?.ran ?? 0),
+      skipped: sum.skipped + (step.tests?.skipped ?? 0),
+    }),
+    { ran: 0, skipped: 0 },
+  );
+};
+
+/** One step's entries from every part, folded into one step result and its gaps. */
+function mergeStep(
+  name: string,
+  entries: readonly { readonly part: string; readonly step: PartStep }[],
+  floor: VerifyFloor | undefined,
+): StepResult {
+  if (entries.length === 0) {
+    return {
+      name,
+      ok: false,
+      durationMs: 0,
+      findings: [gap(`step "${name}" is in no part — no CI job ran it`, name)],
+    };
+  }
+  const sharded = entries.filter((entry) => entry.step.shard !== undefined);
+  const whole = entries.filter((entry) => entry.step.shard === undefined);
+  const gaps: Finding[] = [];
+  if (whole.length > 1 || (whole.length > 0 && sharded.length > 0)) {
+    gaps.push(
+      gap(
+        `step "${name}" is reported by ${String(entries.length)} parts (${entries
+          .map((entry) => entry.part)
+          .join(', ')}) — each step belongs to one job, or to one full set of shards`,
+        name,
+      ),
+    );
+  }
+  if (sharded.length > 0) {
+    const totals = new Set(sharded.map((entry) => entry.step.shard?.total));
+    const hashes = new Set(sharded.map((entry) => entry.step.shard?.corpusHash));
+    if (totals.size > 1) {
+      gaps.push(gap(`step "${name}" mixes splits of ${[...totals].join(' and ')} shards`, name));
+    }
+    if (hashes.size > 1) {
+      gaps.push(
+        gap(
+          `step "${name}"'s shards counted ${String(hashes.size)} different corpora — every job must check out the same commit`,
+          name,
+        ),
+      );
+    }
+    const total = Math.max(...sharded.map((entry) => entry.step.shard?.total ?? 0));
+    const seen = new Map<number, number>();
+    for (const entry of sharded) {
+      const index = entry.step.shard?.index ?? 0;
+      seen.set(index, (seen.get(index) ?? 0) + 1);
+    }
+    const missing = Array.from({ length: total }, (_, i) => i + 1).filter((i) => !seen.has(i));
+    const doubled = [...seen].filter(([, count]) => count > 1).map(([index]) => index);
+    if (missing.length > 0) {
+      gaps.push(
+        gap(
+          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}`,
+          name,
+        ),
+      );
+    }
+    if (doubled.length > 0) {
+      gaps.push(gap(`step "${name}" has shard(s) ${doubled.join(', ')} more than once`, name));
+    }
+  }
+  const steps = entries.map((entry) => entry.step);
+  const tests = sumCounts(steps);
+  // The floor each shard deferred, on the summed counts: a split step whose shards together ran
+  // nothing is the same vanished suite a whole run that ran nothing is.
+  const nothingRan = sharded.length > 0 && tests !== undefined && tests.ran === 0;
+  const required = floorRequires(floor, name);
+  const floorGap = nothingRan && required ? [skippedSuiteFinding(name, tests.skipped)] : [];
+  const findings = [...steps.flatMap((step) => step.findings), ...gaps, ...floorGap];
+  const output = steps
+    .filter((step) => !step.ok && step.output !== undefined && step.output.length > 0)
+    .map((step) => step.output as string)
+    .join('\n');
+  const skipped =
+    sharded.length > 0 ? nothingRan && !required : steps.every((step) => step.skipped);
+  return {
+    name,
+    ok: steps.every((step) => step.ok) && gaps.length === 0 && floorGap.length === 0,
+    // The slowest job: the parts ran side by side, and wall time is what a CI run waits on.
+    durationMs: Math.max(...steps.map((step) => step.durationMs)),
+    ...(skipped ? { skipped: true } : {}),
+    findings,
+    ...(output.length === 0 ? {} : { output }),
+    ...(tests === undefined ? {} : { tests }),
+  };
+}
+
+/** The gate verdict n parts add up to. */
+export function mergeParts(
+  parts: readonly VerifyPart[],
+  floor: VerifyFloor | undefined,
+  declared: readonly string[] = VERIFY_STEP_NAMES,
+): CommandResult {
+  const unknown = parts.flatMap((part) =>
+    part.steps
+      .filter((step) => !declared.includes(step.name))
+      .map((step) => gap(`${part.file} reports "${step.name}", which x verify does not run`)),
+  );
+  const steps = declared.map((name) =>
+    mergeStep(
+      name,
+      parts.flatMap((part) =>
+        part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
+      ),
+      floor,
+    ),
+  );
+  const failed = steps.filter((step) => !step.ok).map((step) => step.name);
+  const skipped = steps.filter((step) => step.skipped === true).map((step) => step.name);
+  const durationMs = Math.max(0, ...parts.map((part) => part.durationMs));
+  const ok = failed.length === 0 && unknown.length === 0;
+  const summary = verifySummary({ results: steps, failed, skipped, totalMs: durationMs });
+  return {
+    ok,
+    command: 'verify',
+    summary: msg('cli.verify.merged', { parts: parts.length, summary }),
+    steps,
+    ...(unknown.length === 0 ? {} : { findings: unknown }),
+    data: {
+      failed,
+      skipped,
+      durationMs,
+      merged: { parts: parts.map((part) => part.file) },
+    },
+    exitCode: ok ? 0 : 1,
+  };
+}

package/src/verify-run.ts

@@ -5,7 +5,6 @@
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
-import { sharedWorkers } from './test-workers';
 import {
   floorRequires,
   readVerifyFloor,
@@ -41,23 +40,27 @@ export async function runVerify(
     await pending;
     pending = undefined;
   };
-  // A parallel suite inside that window shares the cores with the static group, so its DEFAULT
-  // width is one per core (`sharedWorkers`); an explicit `--workers` is the caller's and stands.
-  const shared: VerifyContext =
-    ctx.workers === undefined && beside.length > 0 ? { ...ctx, workers: sharedWorkers() } : ctx;
+  // Isolation is the floor file's unless the caller said: absent in both is off (22.7).
+  const base: VerifyContext =
+    ctx.isolate === undefined && floor?.isolate !== undefined
+      ? { ...ctx, isolate: floor.isolate }
+      : ctx;
+  // A parallel suite inside the overlap window used to be narrowed to one worker per core; the
+  // default is at most that already (`test-workers.ts`), so the window runs the same plan.
+  const shared: VerifyContext = base;
   for (const step of selected) {
     if (beside.includes(step)) continue;
     if (step.name === SERIAL_SUITES[0]) {
       pending = Promise.all(
         beside.map(async (other) => {
-          byName.set(other.name, await runStep(other, ctx, floor));
+          byName.set(other.name, await runStep(other, base, floor));
         }),
       ).then(() => undefined);
     } else if (!SERIAL_SUITES.includes(step.name)) {
       await join();
     }
     const inWindow = pending !== undefined && SERIAL_SUITES.includes(step.name);
-    byName.set(step.name, await runStep(step, inWindow ? shared : ctx, floor));
+    byName.set(step.name, await runStep(step, inWindow ? shared : base, floor));
   }
   await join();
   // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
@@ -113,7 +116,7 @@ const onlyList = (only: VerifyContext['only']): readonly string[] | undefined =>
  * vacuous gate stayed invisible. It names the skipped steps, not just how many: "17/17" is worth
  * something only when the gap is visible in the same glance.
  */
-function verifySummary(input: {
+export function verifySummary(input: {
   readonly results: readonly StepResult[];
   readonly failed: readonly string[];
   readonly skipped: readonly string[];
@@ -196,7 +199,9 @@ async function runStep(
   // ONE definition of "nothing ran", read twice, because the floor decides which of the two
   // things it means — exactly as it already does for a step whose `applies` said no.
   const tests = outcome.tests;
-  const nothingRan = tests !== undefined && tests.ran === 0;
+  // A shard's slice may hold nothing, or only skipped tests, and still be a correct slice: the
+  // "did the suite run at all" question is asked by `x verify merge`, on the summed counts.
+  const nothingRan = tests !== undefined && tests.ran === 0 && outcome.shard === undefined;
   const required = floorRequires(floor, step.name);
   // A step the floor requires whose suite executed nothing is the same vanished suite as a step
   // with no files at all — the run just had to finish before it could be seen. Appended to the
@@ -213,6 +218,8 @@ async function runStep(
     findings: [...outcome.findings, ...vanished],
     ...(outcome.output === undefined ? {} : { output: outcome.output }),
     ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+    ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
+    ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
     ...(tests === undefined ? {} : { tests }),
   };
 }

package/src/verify-shard.ts

@@ -0,0 +1,145 @@
+// `x verify --only <step> --shard i/n`: one CI job's slice of a parallel test step, and the facts
+// `x verify merge` needs to prove that n jobs' slices were the whole corpus exactly once.
+//
+// The split is a PURE function of the sorted file list, n and (optionally) a timings file — never
+// of the machine, the clock or the order a glob yielded — so job 3 of 8 is the same files on every
+// runner, and a failing shard reproduces locally with the same flags.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { CryptoHasher } from 'bun';
+import type { ShardFacts } from './output';
+import { VerifyShardInvalidError } from './verify-errors';
+import type { VerifyStepName } from './verify-step';
+
+/** The steps a shard may split: the parallel suites. `live` and `e2e` are serial by design. */
+export const SHARDABLE_STEPS: readonly VerifyStepName[] = ['unit', 'contract', 'job'];
+
+export interface ShardSpec {
+  /** 1-based, as a CI matrix counts. */
+  readonly index: number;
+  readonly total: number;
+}
+
+/** `3/8` → `{ index: 3, total: 8 }`, refused unless `1 <= i <= n`. */
+export function parseShard(raw: string): ShardSpec {
+  const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(raw);
+  const index = match === null ? Number.NaN : Number(match[1]);
+  const total = match === null ? Number.NaN : Number(match[2]);
+  if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || total < 1 || index < 1) {
+    throw new VerifyShardInvalidError({ reason: `"${raw}" is not i/n (e.g. 2/4)` });
+  }
+  if (index > total) {
+    throw new VerifyShardInvalidError({
+      reason: `shard ${String(index)} does not exist in a ${String(total)}-way split (1..${String(total)})`,
+      fix: `x verify --only unit --shard ${renderFixShellArg(`${String(total)}/${String(total)}`, '<i/n>')} --json`,
+    });
+  }
+  return { index, total };
+}
+
+/**
+ * The steps a shard run may name: every one must be shardable. Refused with the step named, and a
+ * fix that keeps the shardable ones — `live`/`e2e` belong in a job of their own.
+ */
+export function assertShardable(only: readonly VerifyStepName[] | undefined): void {
+  if (only === undefined || only.length === 0) {
+    throw new VerifyShardInvalidError({
+      reason: 'a shard is one slice of ONE parallel step and needs --only to name it',
+      fix: 'x verify --only unit --shard 1/4 --json',
+    });
+  }
+  const refused = only.filter((step) => !SHARDABLE_STEPS.includes(step));
+  if (refused.length > 0) {
+    const kept = only.filter((step) => SHARDABLE_STEPS.includes(step));
+    throw new VerifyShardInvalidError({
+      reason: `${refused.join(', ')} cannot be split (only ${SHARDABLE_STEPS.join(', ')}); run ${
+        refused.length === 1 ? 'it' : 'them'
+      } in a job of its own without --shard`,
+      fix:
+        kept.length === 0
+          ? `x verify --only ${renderFixShellArg(refused.join(','), '<step,step>')} --json`
+          : `x verify --only ${renderFixShellArg(kept.join(','), '<step,step>')} --shard 1/4 --json`,
+    });
+  }
+}
+
+/** sha256 of the sorted list, one path a line: equal across shards iff they split one corpus. */
+export const corpusHash = (files: readonly string[]): string => {
+  const hasher = new CryptoHasher('sha256');
+  hasher.update([...files].sort().join('\n'));
+  return hasher.digest('hex');
+};
+
+/** Per-file durations in ms — `{ "path": ms }`, as in Bun's `--timings` file's `files`. */
+export type Timings = Readonly<Record<string, number>>;
+
+/**
+ * Which files shard `index` of `total` runs. Round-robin over the sorted list by default — every
+ * shard gets a slice of every directory. With `timings`, greedy longest-first: each file, slowest
+ * first (ties by path), goes to the shard with the least total so far (ties to the lowest index);
+ * a file the timings do not know is costed at their median, so a new file cannot pile onto one job.
+ */
+export function shardFiles(
+  files: readonly string[],
+  spec: ShardSpec,
+  timings?: Timings,
+): ShardFacts {
+  const sorted = [...new Set(files)].sort();
+  const hash = corpusHash(sorted);
+  let picked: string[];
+  if (timings === undefined) {
+    picked = sorted.filter((_, position) => position % spec.total === spec.index - 1);
+  } else {
+    const known = sorted
+      .map((file) => timings[file])
+      .filter((ms): ms is number => typeof ms === 'number' && Number.isFinite(ms) && ms >= 0)
+      .sort((a, b) => a - b);
+    const median = known.length === 0 ? 1 : (known[Math.floor(known.length / 2)] as number);
+    const cost = (file: string): number => {
+      const ms = Object.hasOwn(timings, file) ? timings[file] : undefined;
+      return typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 ? ms : median;
+    };
+    const order = [...sorted].sort((a, b) => cost(b) - cost(a) || (a < b ? -1 : a > b ? 1 : 0));
+    const loads = Array.from({ length: spec.total }, () => 0);
+    const owner = new Map<string, number>();
+    for (const file of order) {
+      let best = 0;
+      for (let shard = 1; shard < spec.total; shard += 1) {
+        if ((loads[shard] as number) < (loads[best] as number)) best = shard;
+      }
+      loads[best] = (loads[best] as number) + cost(file);
+      owner.set(file, best);
+    }
+    picked = sorted.filter((file) => owner.get(file) === spec.index - 1);
+  }
+  return { index: spec.index, total: spec.total, corpusHash: hash, files: picked };
+}
+
+/** A timings file, or a refusal naming it — a CI job must not silently fall back to round-robin. */
+export async function readTimings(path: string): Promise<Timings> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new VerifyShardInvalidError({
+      reason: `--timings ${path} does not exist`,
+      fix: 'bun test --timings=timings.json --update-timings   # writes it, then commit or cache it',
+    });
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await file.text());
+  } catch {
+    parsed = undefined;
+  }
+  // Bun's own `--update-timings` writes `{ "version": 1, "files": { "path": ms } }`; a bare map
+  // is accepted too.
+  if (typeof parsed === 'object' && parsed !== null && 'files' in parsed) {
+    parsed = (parsed as { files: unknown }).files;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new VerifyShardInvalidError({
+      reason: `--timings ${path} is not a JSON object of { "path": ms }`,
+      fix: 'bun test --timings=timings.json --update-timings',
+    });
+  }
+  return parsed as Timings;
+}

package/src/verify-step.ts

@@ -5,7 +5,7 @@
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
-import type { Finding } from './output';
+import type { Finding, ShardFacts } from './output';
 import type { TestCounts } from './test-counts';
 
 /**
@@ -78,6 +78,21 @@ export interface VerifyContext {
    * narrowing: no value of it changes which steps run or what "green" means.
    */
   readonly workers?: number;
+  /**
+   * A fresh global per test file (`bun test --isolate`). Absent means `x.verify.json`'s
+   * `"isolate"`, and absent there means off — the default since 22.7.
+   */
+  readonly isolate?: boolean;
+  /**
+   * One slice of an n-way CI split of each selected parallel step's file list (`--shard i/n`,
+   * 1-based `index`). Only with `only`; `x verify merge` reassembles the verdict.
+   */
+  readonly shard?: {
+    readonly index: number;
+    readonly total: number;
+    /** Bun `--timings` durations: greedy longest-first instead of round-robin. */
+    readonly timings?: Readonly<Record<string, number>>;
+  };
   /**
    * Some steps, by name — an iteration loop, and the one thing here that IS a narrowing. The
    * whole gate costs minutes (3m19s at the framework root on 12 cores, `As of 2026-09-23`), which
@@ -103,6 +118,10 @@ export interface StepOutcome {
    * reading the step list's source.
    */
   readonly workers?: number;
+  /** Why `workers` is what it is — `4 workers (budget 4.0 GB)`. Printed on the step line. */
+  readonly widthReason?: string;
+  /** The CI slice this step ran, under `--shard`: which files, and a hash of the whole list. */
+  readonly shard?: ShardFacts;
   /**
    * What the suite executed, for the steps that run one. Absent means this step spawned no test
    * process at all — a check step, or the `eval` step answering with declarations alone — and is