@ultimat3/testing 30.6.0 → 30.7.0

package/CLAUDE.md

@@ -45,19 +45,19 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | `LOG_LEVEL` above `info` filters the TERMINAL | `quiet-logs.ts` pins the logger at `info` while core loads, so a collecting `setLogSink` still sees `warn` under `LOG_LEVEL=error`. It stays the preload's FIRST import |
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
 | Fixtures | the preload registers the framework bag — an app registers only what it alone knows (`seed`, `actorFor`) |
-| Every `e2eTest` is audited | `e2e-a11y.ts` (rules), `e2e-a11y-run.ts` (per-test run, `allow`, dedupe), `ax-node.ts` (the one AX reader); the full tree is read only in `cdp-e2e-page.ts` (`FULL_AX_TREE`, a convention). No switch; `allow` needs a non-blank `because`. And every raw tab: `e2e-a11y-tabs.ts`, checked after each `goto`/`reload` and at the test's end from the preload's `afterEach`; exceptions are `allowA11y([{ role, selector, because }])` |
+| Every `e2eTest` is audited | `e2e-a11y.ts` (rules), `e2e-a11y-run.ts` (per-test run, `allow`, dedupe), `ax-node.ts` (the one AX reader); full tree only in `cdp-e2e-page.ts`. No switch; `allow` needs a `because`. Raw tabs: `e2e-a11y-tabs.ts` ([history](../../docs/history/testing.md#a11y-on-raw-tabs)) |
 | The exercise pass runs what is registered | `exercise.ts` (`runExercisePass`): every action, query and job once, its own tenant pair off one `seedGraph`, an actor `exercise-actor.ts` picks, 39's `runExercise` as the verdict. Rows COMMITTED. Overrides only via `defineExercise` (blank `off` refused). A job runs ALONE (`exercise-job-run.ts`): a fresh queue, one `tick()`, what it queued left on the caller's queue unrun — never a `drain()` |
 | An override `input` is awaited, as the call's actor | `exercise-override-input.ts`: run inside the call's own request, so `useContext().actor` is the seated actor; the one way to a signed input. `async` ones are left out of `x drill`'s load |
 | A passkey test signs for real | `softAuthenticator` is `@ultimat3/auth/soft-authenticator`'s, never re-exported here (one value, one path: `flight-copies`) and never a second one (auth's own suites need it, and auth cannot import testing) |
 | A reached job is crash-proven | `exercise-crash.ts`: `crashProof` with the control's input and actor, after the tenant proof; only `diverged` is red (`X_JOB_CRASH_DIVERGED`), its place `crashEffectPlace` (`inside` a step via jobs' `currentStep()`, or `after` one). Its world is `alone`: only the job's own row is claimed, a child is an `enqueue:` effect, never run. Committed: job bodies escape transactions |
 | The tenant proof is taint only | `tenant-proof.ts`: B, A, B; B is A's role minus `tenancy:cross`. Leak = seeded canary or unhanded id (`tenant-canary.ts`); write = moved digest. Only `crossed` is red |
-| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts`; red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; credited: a partial unique whose predicate the statement states (one row), a declared equality-then-range index under a limit; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
+| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts` (keys: `plan-sort-key.ts`, conditions: `plan-conditions.ts`); red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; credited: a partial unique whose predicate the statement states (one row), a declared equality-then-range index under a limit, every `or` arm a declared index leads; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
 | A shape that grows with the rows is red | `scale-sweep-run.ts`: two more tenants at `SCALE_SIZES` (2, 8 rows a table), every reached primitive once in each; `judgeScale` (pure) reds `X_QUERY_SCALES_WITH_ROWS`. Under `expectedQueryLoop` it is listed with its reason |
 | An erase is PROVED, not asserted | `subject-proof.ts` (`subjectProof`, run by cli's `exercise-subject.ts`): canaries in every table, one person erased, every stored row searched; a survivor outside `retain` is `X_SUBJECT_ERASE_INCOMPLETE`, naming table and column, never the value |
 | A captured failure replays as a test | `repro.ts`: `reproduce(bundle, { driver })` seeds the rows it read, freezes the clock at its instant, invokes as its actor; masked fields are stood in (`repro-stand-in.ts`). An unregistered name ANSWERS as the failure. `reproJob(runJobs, failure)` for a dead job. What `x repro --write` emits |
 | A vendor's answers are a cassette | `cassette.ts`: replay = one `mockFetch` route per recorded URL, seal kept (`X_CASSETTE_MISSING`, `X_CASSETTE_UNUSED`). Record = `ULTIMATE_CASSETTE=record` + `record.hosts`, refused under `CI` (`X_CASSETTE_RECORD_REFUSED`), headers allow-listed, credential keys masked, bytes scanned before disk (`X_CASSETTE_SECRET`). The request side is never written |
 | One seed writer | `entitySeedWriter({ entities, client \| driver })` (`seed-writer.ts`) writes through each entity's own repository; `snapshot` is required; `entity` loads on the first write, so the barrel stays entity-free |
-| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, a `matches()` pattern (`seed-pattern-sample.ts`, read off the CHECK by `seed-graph-patterns.ts`), `$meta.schema` (sampler `require`d on first use), through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
+| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, a `matches()` pattern (schema's `patternSamples`; CHECK read by `seed-graph-patterns.ts`), `$meta.schema` (sampler `require`d on first use), through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
 | e2e without a driver | `e2eTest` becomes `test.skip`; the gate reports the step SKIPPED (or `X_VERIFY_SUITE_VANISHED` when `x.verify.json` requires it), never passed |
 | The seam has an inverse | `resetE2eDriver()`: `useE2eDriver` writes MODULE scope, so a file that installs a browser undoes it |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "30.6.0",
+  "version": "30.7.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "keywords": [
     "ultimate",
@@ -46,21 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.6.0",
-    "@ultimat3/cache": "30.6.0",
-    "@ultimat3/core": "30.6.0",
-    "@ultimat3/db": "30.6.0",
-    "@ultimat3/entity": "30.6.0",
-    "@ultimat3/http": "30.6.0",
-    "@ultimat3/i18n": "30.6.0",
-    "@ultimat3/jobs": "30.6.0",
-    "@ultimat3/mail": "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/time": "30.6.0"
+    "@ultimat3/action": "30.7.0",
+    "@ultimat3/cache": "30.7.0",
+    "@ultimat3/core": "30.7.0",
+    "@ultimat3/db": "30.7.0",
+    "@ultimat3/entity": "30.7.0",
+    "@ultimat3/http": "30.7.0",
+    "@ultimat3/i18n": "30.7.0",
+    "@ultimat3/jobs": "30.7.0",
+    "@ultimat3/mail": "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/time": "30.7.0"
   }
 }

package/src/define-exercise.ts

@@ -1,6 +1,6 @@
-// `defineExercise({ publishPost: { input, actor }, sendInvoice: { off: 'why' } })`: an app's
-// overrides for the exercise pass, one entry per primitive. Each value IS 39's `.contract({
-// exercise })` option, re-exported rather than restated, so one shape answers both questions.
+// `defineExercise({ publishPost: { input, actor }, sendInvoice: { off: 'why' } })`: an app's ONE
+// declaration of each primitive's exercise. `x exercise` reads it, and so does every contract
+// test — the whole value handed to `.contract({ exercise })` (action's `ExerciseDeclarations`).
 // A blank `off` is refused here, at declaration; an unknown name when the pass runs.
 
 import type { ExerciseOptions } from '@ultimat3/action';
@@ -11,12 +11,17 @@ import type { SeedFactory } from './seed-graph-plan';
 /** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
 export type ExerciseOverride = ExerciseOptions;
 
-/** What `defineExercise` returns: the overrides, by primitive name. Read by `runExercisePass`. */
+/**
+ * What `defineExercise` returns: the overrides, by primitive name. Read by `runExercisePass` and,
+ * structurally, by `.contract({ exercise })` (`define-exercise.test.ts` pins the assignability).
+ */
 export interface ExerciseOverrides {
   readonly kind: 'exercise-overrides';
   readonly entries: ReadonlyMap<string, ExerciseOverride>;
   /** The entity an actor is a row of, by name: its id is bound to a seeded row. */
   readonly actorEntity?: string;
+  /** The column of that entity whose value IS the actor's id (`memberships.userId`); else its key. */
+  readonly actorColumn?: string;
   /** By entity name: the pass's graph builds those rows with them (`seedGraph`'s `factories`). */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
   /** The app's hook, run once inside the pass's sealed room (`exercise-setup.ts`). */
@@ -28,9 +33,12 @@ export interface ExerciseAppOptions {
   /**
    * The entity whose rows ARE the app's actors (`members`, `users`): each actor's id becomes a
    * seeded row's key in its own tenant, so a handler writing `ctx.actor.id` into a foreign key
-   * writes a row that exists. Omitted, an actor's id is its role's name.
+   * writes a row that exists. `{ entity, column }` names the column that holds the user instead
+   * (`{ entity: membership, column: 'userId' }`). Omitted, a deterministic uuid per role and tenant.
    */
-  readonly actor?: { readonly $name: string };
+  readonly actor?:
+    | { readonly $name: string }
+    | { readonly entity: { readonly $name: string }; readonly column: string };
   /**
    * By entity name, `seedGraph`'s own option: a table whose rows a generated value cannot satisfy
    * (an `invariant` across columns) is built by the app's `defineFactory`. An unknown name is
@@ -67,7 +75,11 @@ export function defineExercise(
   return Object.freeze({
     kind: 'exercise-overrides',
     entries,
-    ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
+    ...(app.actor === undefined
+      ? {}
+      : 'entity' in app.actor
+        ? { actorEntity: app.actor.entity.$name, actorColumn: app.actor.column }
+        : { actorEntity: app.actor.$name }),
     ...(app.factories === undefined ? {} : { factories: app.factories }),
     ...(app.setup === undefined ? {} : { setup: app.setup }),
   });

package/src/errors.ts

@@ -70,6 +70,8 @@ export const TESTING_ERROR_CODES = [
   'X_CASSETTE_RECORD_REFUSED',
   'X_TEST_MODULE_MOCK_UNRESTORABLE',
   'X_EXERCISE_SETUP_UNSEALED',
+  'X_JOB_CRASH_UNBOUNDED',
+  'X_EXERCISE_ACTOR_USER_UNSEATED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -135,6 +137,8 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_CASSETTE_RECORD_REFUSED: 'a cassette recording was refused',
   X_TEST_MODULE_MOCK_UNRESTORABLE: 'a mocked module could not be put back at the file boundary',
   X_EXERCISE_SETUP_UNSEALED: 'an exercise setup let a host through the seal',
+  X_JOB_CRASH_UNBOUNDED: 'a crash proof needs more kill points than its bound',
+  X_EXERCISE_ACTOR_USER_UNSEATED: "the exercise pass could not seat its actor's x_users row",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -146,12 +150,8 @@ registerErrorCodes(
   ),
 );
 
-// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
-// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
-// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
-// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
-// answered 404, host included, on every error it has ever thrown; restating the replacement here
-// would be the same constant in eight places waiting to drift again.
+// No `docs:` below: `UltimateError` fills core's `ERROR_DOCS_URL`, one page per code set (a wiki
+// TABLE ROW has no anchor; per-code links answered 404 until 9.x). Restating it here would drift.
 
 /**
  * A test reached the network without a mock or an allowlist entry. Always a bug, never a flake.

package/src/exercise-actor-user.ts

@@ -0,0 +1,63 @@
+// The user an exercise actor IS: one `x_users` row per actor the pass acts as, written before the
+// call, so a handler reading its caller through `@ultimat3/auth` (`findUserById(ctx.actor.id)`)
+// finds the row production always has. Only where the table exists — the framework schema every
+// `x exercise` database is built with — and only for an actor whose id has a user's shape.
+
+import type { Actor } from '@ultimat3/core';
+import { isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Whether `x_users` exists on this client, asked once per client: the schema does not move. */
+const hasUsers = new WeakMap<DbClient, Promise<boolean>>();
+
+/** The insert was refused: the pass cannot act as a user it could not create. */
+export class ExerciseActorUserUnseatedError extends UltimateError {
+  constructor(error: unknown) {
+    super({
+      code: 'X_EXERCISE_ACTOR_USER_UNSEATED',
+      cause: `x exercise writes one x_users row per actor it acts as, and the insert was refused: ${isUltimateError(error) ? error.cause : renderThrowable(error)}`,
+      fix: 'x exercise --json   # after a migration under packages/db/migrations/ gives the column the app added to x_users a default, or makes it nullable',
+      sourceError: error,
+    });
+  }
+}
+
+/**
+ * Seat every actor in `actors` as an `x_users` row: id, a reserved `.invalid` address unique per
+ * id, its tenant, roles, permissions and scopes. Idempotent (`on conflict (id) do nothing`), so
+ * the same role in the same tenant — one id, `exerciseActorId` — is written once however often the
+ * pass acts as it. No installed client, no table, no uuid: nothing to seat, nothing written.
+ */
+export async function seatActorUsers(actors: readonly (Actor | null)[]): Promise<void> {
+  const users = [
+    ...new Map(
+      actors.filter((a): a is Actor => a !== null && UUID.test(a.id)).map((a) => [a.id, a]),
+    ).values(),
+  ];
+  if (users.length === 0) return;
+  const { db, dbClientInstalled, sql } = await import('@ultimat3/db');
+  if (!dbClientInstalled()) return;
+  const client = db();
+  let known = hasUsers.get(client);
+  if (known === undefined) {
+    known = client
+      .one<{ found: boolean }>(sql`select to_regclass('x_users') is not null as found`)
+      .then((row) => row?.found === true);
+    hasUsers.set(client, known);
+  }
+  if (!(await known)) return;
+  for (const user of users) {
+    const org = typeof user.orgId === 'string' && UUID.test(user.orgId) ? user.orgId : null;
+    try {
+      await client.execute(sql`
+        insert into x_users (id, email, org_id, roles, permissions, scopes)
+        values (${user.id}, ${`${user.id}@exercise.invalid`}, ${org}, ${[...(user.roles ?? [])]},
+                ${[...(user.permissions ?? [])]}, ${[...(user.scopes ?? [])]})
+        on conflict (id) do nothing`);
+    } catch (error) {
+      throw new ExerciseActorUserUnseatedError(error);
+    }
+  }
+}

package/src/exercise-actor.ts

@@ -26,6 +26,21 @@ export type ActorChoice =
 export const inTenant = (actor: Actor | null, tenant: string): Actor | null =>
   actor === null ? null : Object.freeze({ ...actor, orgId: tenant });
 
+/**
+ * A role's actor id in one tenant: a uuid, as `ctx.actor.id` always is in production (an
+ * `x_users` key), and the same one every time for that role in that tenant — so a rerun on a seed
+ * replays byte for byte, and A's actor is never B's. Name-based (SHA-1, version 5 bits), never
+ * random: nothing about it may depend on the order the pass asks.
+ */
+export function exerciseActorId(role: string, tenant: string): string {
+  const digest = new Bun.CryptoHasher('sha1').update(`x-exercise-actor\0${role}\0${tenant}`);
+  const bytes = digest.digest().subarray(0, 16);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = bytes.toHex();
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
 type Verdict = 'allowed' | 'denied' | 'undecidable';
 
 /**
@@ -64,7 +79,8 @@ export function chooseActor(
   tenant: string,
   override: ExerciseOverride | undefined,
 ): ActorChoice {
-  if (override !== undefined && 'actor' in override) {
+  // An input-only entry (`{ input }`, no `actor`) keeps the pick below: only a DECLARED actor wins.
+  if (override !== undefined && !('off' in override) && override.actor !== undefined) {
     return { kind: 'actor', actor: inTenant(override.actor, tenant), name: 'override' };
   }
   const candidates = grants(tenant);
@@ -92,12 +108,23 @@ export function chooseActor(
           : `none of ${ordered.map((c) => c.name).join(', ')} is allowed by ${policy.label} or holds ${permissions.join(', ') || 'its grant'}`,
     };
   }
-  return { kind: 'actor', actor: pick[0].actor, name: pick[0].name };
+  const [{ actor, name }] = pick;
+  return { kind: 'actor', actor: asRoleUser(actor, name, tenant), name };
 }
 
+/** A role's actor with the id a production actor has: `exerciseActorId(role, tenant)`. */
+const asRoleUser = (actor: Actor | null, name: string, tenant: string): Actor | null =>
+  actor === null ? null : Object.freeze({ ...actor, id: exerciseActorId(name, tenant) });
+
 /** The seeded rows an actor can be one of: the pass's graph, read for one entity. */
 export interface ActorRows {
   readonly entity: { readonly $name: string; readonly $primaryKey: readonly string[] };
+  /**
+   * The column whose value IS the user (`memberships.userId`); omitted, the row's own key. A
+   * membership's id is not a user's id, and a handler that reads `ctx.actor.id` as `x_users`'s
+   * must find the membership by the column that holds it.
+   */
+  readonly column?: string;
   readonly rows: readonly {
     readonly tenant: string | null;
     readonly row: Readonly<Record<string, unknown>>;
@@ -106,13 +133,15 @@ export interface ActorRows {
 
 /**
  * The actor as a ROW of the entity the app named (`defineExercise(…, { actor: members })`): its
- * id becomes the key of a seeded row in its tenant, the one carrying one of its roles when any
- * does. Without it an actor's id is a role name, and every handler that writes `ctx.actor.id`
- * into a foreign key — `authorId` — is refused by the database.
+ * id becomes the key — or the named `column` — of a seeded row in its tenant, the one carrying
+ * one of its roles when any does. Without it an actor's id is `exerciseActorId(role, tenant)`, a
+ * user no table of the app's holds, so a handler writing `ctx.actor.id` into a foreign key —
+ * `authorId` — is refused by the database.
  */
 export function asSeededRow(actor: Actor | null, tenant: string, rows: ActorRows): Actor | null {
-  const key = rows.entity.$primaryKey[0];
-  if (actor === null || key === undefined || rows.entity.$primaryKey.length !== 1) return actor;
+  const key =
+    rows.column ?? (rows.entity.$primaryKey.length === 1 ? rows.entity.$primaryKey[0] : undefined);
+  if (actor === null || key === undefined) return actor;
   const own = rows.rows.filter((row) => row.tenant === tenant || row.tenant === null);
   const roles = actor.roles ?? [];
   const row =

package/src/exercise-crash.ts

@@ -1,5 +1,5 @@
-// The crash proof, as the exercise pass runs it: a job its control reached is killed at every step
-// boundary with the control's own input and actor (`crashProof`), and the answer is a plain record
+// The crash proof, as the exercise pass runs it: a job its control reached is killed at every
+// distinct step boundary with the control's own input and actor (`crashProof`), and the answer is a plain record
 // `.x/exercise.json` can hold. Run after the control, so its runs meet the rows the control left.
 
 import type { Actor } from '@ultimat3/core';
@@ -34,7 +34,11 @@ export async function proveCrash(
   const worker = ctxOf(actor === null ? { role: 'worker' } : { role: 'worker', actor });
   try {
     const report = await crashProof(handle, input, { context: () => worker });
-    const counted = { boundaries: report.boundaries.length, reruns: report.reruns.length };
+    const counted = {
+      boundaries: report.boundaries.length,
+      crossed: report.crossed,
+      reruns: report.reruns.length,
+    };
     return report.divergences.length === 0
       ? { verdict: 'held', ...counted }
       : { verdict: 'diverged', ...counted, findings: report.divergences.map(findingOf) };

package/src/exercise-drift-hint.ts

@@ -0,0 +1,28 @@
+// The override line a drifted primitive's record carries: `name: { input: (drawn) => ({ ...drawn,
+// digest: "<must match ^[0-9a-f]{64}$>" }) },` — the field no draw can fill, named and bound,
+// rendered by core's one `renderDrawnInput`. No `actor:`: the pass picks one when the entry has none.
+
+import { renderDrawnInput, renderExerciseKey, sampleGapBinding } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Sampler } from './exercise-input';
+
+/** `idFields` are the input's id-shaped keys: each wants a real row's id, as the other hints say. */
+export function driftOverrideLine(
+  name: string,
+  schema: StandardSchemaV1,
+  sampler: Sampler,
+  idFields: readonly string[],
+): string {
+  const gaps = sampler.sampleGaps(schema);
+  const bindings = [
+    ...gaps.map((path) => sampleGapBinding(path, sampler.describeSampleGap(schema, path))),
+    ...idFields
+      .filter((field) => !gaps.includes(field))
+      .map((field) => ({ path: field, placeholder: '<a real id>' })),
+  ];
+  const input =
+    bindings.length === 0
+      ? "(drawn) => ({ ...drawn, field: '<a value the refinement accepts>' })"
+      : renderDrawnInput(bindings);
+  return `${renderExerciseKey(name)}: { input: ${input} },`;
+}

package/src/exercise-input.ts

@@ -10,6 +10,9 @@ import type { SeedEntity } from './seed-graph-shape';
 export interface Sampler {
   sampleInput(schema: StandardSchemaV1): unknown;
   arbitrary(schema: StandardSchemaV1, options: { seed: number; run: number }): unknown;
+  /** The fields the minimal draw cannot fill, and what each needs: a drift's hint names them. */
+  sampleGaps(schema: StandardSchemaV1): readonly string[];
+  describeSampleGap(schema: StandardSchemaV1, path: string): string;
 }
 
 /** On demand: a `packages/core` test that never exercises anything must not load the walker. */

package/src/exercise-job-tenant.ts

@@ -9,9 +9,13 @@ export interface TenantOf {
   tenantFor(input: unknown): string | undefined;
 }
 
-/** `seated`: the input names the tenant. `fixed`: no field it reads moves the org it answers. */
+/**
+ * `seated`: the input names the tenant. `fixed`: no field it reads moves the org it answers.
+ * `none`: `tenant: 'none'` — no org reaches the run, so whoever enqueues it the run is the same.
+ */
 export type JobTenantBinding =
   | { readonly kind: 'seated'; readonly input: unknown }
+  | { readonly kind: 'none'; readonly input: unknown }
   | { readonly kind: 'fixed'; readonly declared: string | undefined };
 
 type Path = readonly string[];
@@ -85,16 +89,17 @@ function setAt(input: unknown, path: Path, value: unknown): unknown {
 }
 
 /**
- * `input` naming `tenant` wherever `handle.tenantFor` reads it. A `'none'` job, or one already
- * naming it, comes back as given. A read path is kept only if setting it moves the answer to
- * `tenant` — a field read and then ignored is left as drawn.
+ * `input` naming `tenant` wherever `handle.tenantFor` reads it. One already naming it comes back as
+ * given; a `'none'` job comes back as given, as `none` — the tenant proof's write half reads it
+ * (`tenant-proof.ts`, `TenantAttack.tenantless`). A read path is kept only if setting it moves the
+ * answer to `tenant` — a field read and then ignored is left as drawn.
  */
 export function bindJobTenant(handle: TenantOf, input: unknown, tenant: string): JobTenantBinding {
   const declared = answer(handle, input);
   if (declared === tenant) return { kind: 'seated', input };
   const reads = pathsRead(handle, input);
   // `tenant: 'none'` is never called: no org named, none read, so none to disagree with.
-  if (declared === undefined && reads.length === 0) return { kind: 'seated', input };
+  if (declared === undefined && reads.length === 0) return { kind: 'none', input };
   const moving = reads.filter((path) => answer(handle, setAt(input, path, tenant)) === tenant);
   const bound = moving.reduce<unknown>((value, path) => setAt(value, path, tenant), input);
   return moving.length > 0 && answer(handle, bound) === tenant

package/src/exercise-override-input.ts

@@ -15,13 +15,34 @@ export function overrideInput(
   name: string,
   override: ExerciseOverride | undefined,
 ): OverrideInput | undefined {
-  const bind = bindDrawn(
-    override !== undefined && 'actor' in override ? override.input : undefined,
-  );
+  // Any entry but `off` may bind: `{ input }` alone keeps the pass's own actor and still binds.
+  const bind = bindDrawn(override === undefined || 'off' in override ? undefined : override.input);
   if (bind === undefined) return undefined;
-  return (drawn, actor) => withExerciseRequest(name, actor, async () => bind(drawn));
+  const declared = override === undefined || 'off' in override ? undefined : override.actor;
+  return async (drawn, actor) =>
+    rehomed(
+      await withExerciseRequest(name, actor, async () => bind(drawn)),
+      declared?.orgId,
+      actor?.orgId,
+    );
 }
 
+/**
+ * The bound input, re-homed with its actor: the pass seats a declared actor in each tenant it
+ * seeds, so a top-level value equal to the org the entry DECLARED (`orgId: '<org>'`, the same
+ * literal the contract test runs with) is that tenant's. Without it A's own call names an org its
+ * actor is not in, and a policy comparing the two denies every run.
+ */
+function rehomed(input: unknown, from: string | undefined, to: string | undefined): unknown {
+  if (from === undefined || to === undefined || from === to || !isPlainObject(input)) return input;
+  return Object.fromEntries(
+    Object.entries(input).map(([key, value]) => [key, value === from ? to : value]),
+  );
+}
+
+const isPlainObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
 /**
  * Whether an override's input is declared `async` — state the pass computes, which a load that
  * draws with no pass behind it (`x drill`) cannot reproduce. The function's own tag, never a call:
@@ -29,6 +50,6 @@ export function overrideInput(
  */
 export const isAsyncInput = (override: ExerciseOverride | undefined): boolean =>
   override !== undefined &&
-  'actor' in override &&
+  !('off' in override) &&
   override.input !== undefined &&
   Object.prototype.toString.call(override.input) === '[object AsyncFunction]';

package/src/exercise-report.ts

@@ -79,12 +79,21 @@ export interface CrashFinding {
   readonly inside?: string;
 }
 
-/** The crash proof's verdict on a reached job: killed at every step boundary (`crashProof`). */
+/**
+ * The crash proof's verdict on a reached job: killed at every distinct step boundary, a loop's rows
+ * as one (`crashProof`). `boundaries` is the kills, `crossed` the boundaries they stand for.
+ */
 export type CrashProof =
-  | { readonly verdict: 'held'; readonly boundaries: number; readonly reruns: number }
+  | {
+      readonly verdict: 'held';
+      readonly boundaries: number;
+      readonly crossed?: number;
+      readonly reruns: number;
+    }
   | {
       readonly verdict: 'diverged';
       readonly boundaries: number;
+      readonly crossed?: number;
       /** Lost answers that reran a step: at-least-once, counted, never red. */
       readonly reruns: number;
       readonly findings: readonly CrashFinding[];
@@ -118,6 +127,33 @@ export interface ExerciseRecord {
   readonly plans?: PlanProof;
   /** On a reached primitive: its statement shapes at 2 and at 8 rows a table (`scale-sweep.ts`). */
   readonly scale?: ScaleProof;
+  /** Wall time of each proof that ran on it; `ms` above is the control's own call. */
+  readonly proofMs?: ProofMs;
+}
+
+/**
+ * Milliseconds per proof of one record. No `plans`: one statement is planned once for every
+ * primitive that sent it, so its time is the pass's (`ExercisePhaseMs.plans`), never one record's.
+ */
+export interface ProofMs {
+  /** B's two legs and the snapshots around them, the control's own call excepted. */
+  readonly tenant?: number;
+  /** Every run the crash proof made. */
+  readonly crash?: number;
+  /** Its calls at both sizes; seeding the sized graphs is the pass's (`ExercisePhaseMs.scale`). */
+  readonly scale?: number;
+}
+
+/** Milliseconds per phase of one pass, so a slow pass names its slow part. */
+export interface ExercisePhaseMs {
+  /** The pass's one seed graph, written. */
+  readonly seed: number;
+  /** Every primitive's control and its tenant and crash proofs. */
+  readonly primitives: number;
+  /** The scale sweep: its two sized graphs written, every reached primitive called in each. */
+  readonly scale: number;
+  /** The plan sweep: every distinct statement the pass sent, planned. */
+  readonly plans: number;
 }
 
 /** What an effect carried, for the tenant proof's read half: searched, never reported as is. */

package/src/exercise-sweeps.ts

@@ -1,6 +1,7 @@
 // What runs after every primitive's own call: the scale sweep (each reached one again, at 2 and at 8
 // rows a table) and the plan sweep (every statement the pass sent, planned on the migrated
-// database). Both verdicts land on the record of the primitive that sent the statements.
+// database). Both verdicts land on the record of the primitive that sent the statements, and each
+// sweep's time on the pass.
 
 import type { Actor } from '@ultimat3/core';
 import type { ExerciseOverrides } from './define-exercise';
@@ -9,11 +10,11 @@ import { asSeededRow, chooseActor } from './exercise-actor';
 import type { Sampler } from './exercise-input';
 import { bindIds, drawInput, seededIds } from './exercise-input';
 import { overrideInput } from './exercise-override-input';
-import type { ExerciseRecord } from './exercise-report';
+import type { ExercisePhaseMs, ExerciseRecord } from './exercise-report';
 import type { Subject } from './exercise-subjects';
 import { seatIn } from './exercise-subjects';
 import { sweepPlans } from './plan-sweep';
-import type { ScaleSweepOptions } from './scale-sweep-run';
+import type { ScaleSubject, ScaleSweepOptions } from './scale-sweep-run';
 import { scaleSweep } from './scale-sweep-run';
 import type { SeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
@@ -30,7 +31,12 @@ export const actorRowsOf = (options: CallOptions, graph: SeedGraph): ActorRows |
   const name = options.overrides?.actorEntity;
   const entity = options.entities.find((one) => one.$name === name);
   if (entity === undefined) return undefined;
-  return { entity, rows: graph.inserts.filter((row) => row.entity === entity.$name) };
+  const column = options.overrides?.actorColumn;
+  return {
+    entity,
+    rows: graph.inserts.filter((row) => row.entity === entity.$name),
+    ...(column === undefined ? {} : { column }),
+  };
 };
 
 /** The actor of `chosen`, seated as a row of the app's actor entity in `tenant` when it names one. */
@@ -66,6 +72,25 @@ export async function sizedCall(
   return { actor, input: seatIn(subject, given, tenant) };
 }
 
+/** The records with both sweeps' verdicts and scale time on them, and each sweep's whole time. */
+export interface Swept {
+  readonly records: readonly ExerciseRecord[];
+  readonly ms: Pick<ExercisePhaseMs, 'scale' | 'plans'>;
+}
+
+/** `subject`'s calls, each timed into `spent` under its name: the sweep calls it once per size. */
+const timed = (subject: ScaleSubject, spent: Map<string, number>): ScaleSubject => ({
+  ...subject,
+  call: async (...args) => {
+    const started = performance.now();
+    try {
+      return await subject.call(...args);
+    } finally {
+      spent.set(subject.name, (spent.get(subject.name) ?? 0) + performance.now() - started);
+    }
+  },
+});
+
 /**
  * The scale sweep inside the room, the room closed, then the plan sweep — on the installed client
  * only: with none, the pass ran on a driver that sends no SQL and there is no plan to read.
@@ -73,24 +98,41 @@ export async function sizedCall(
 export async function attachSweeps(
   records: readonly ExerciseRecord[],
   options: ScaleSweepOptions,
-): Promise<readonly ExerciseRecord[]> {
+): Promise<Swept> {
+  const spent = new Map<string, number>();
   let scale: Awaited<ReturnType<typeof scaleSweep>>;
+  const scaleStarted = performance.now();
   try {
-    scale = await scaleSweep(options);
+    scale = await scaleSweep({
+      ...options,
+      subjects: options.subjects.map((subject) => timed(subject, spent)),
+    });
   } finally {
     await options.room[Symbol.asyncDispose]();
   }
+  const plansStarted = performance.now();
   const db = await import('@ultimat3/db');
   const plans = db.dbClientInstalled()
     ? await sweepPlans(db.db(), options.room.sent(), options.entities)
     : new Map();
-  return records.map((record) => {
+  const ms = {
+    scale: Math.round(plansStarted - scaleStarted),
+    plans: Math.round(performance.now() - plansStarted),
+  };
+  const swept = records.map((record) => {
     const proof = plans.get(record.name);
     const sized = scale.get(record.name);
+    const scaleMs = spent.get(record.name);
+    const proofMs = {
+      ...record.proofMs,
+      ...(scaleMs === undefined ? {} : { scale: Math.round(scaleMs) }),
+    };
     return {
       ...record,
       ...(proof === undefined ? {} : { plans: proof }),
       ...(sized === undefined ? {} : { scale: sized }),
+      ...(Object.keys(proofMs).length === 0 ? {} : { proofMs }),
     };
   });
+  return { records: swept, ms };
 }