@ultimat3/testing 30.2.0 → 30.4.0

package/CLAUDE.md

@@ -51,13 +51,13 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | 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`). 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; 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`; 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 |
 | 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, 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 (`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 |
 | 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/README.md

@@ -34,7 +34,8 @@ unitTest('the clock moves only when the test moves it', ({ clock }) => {
 | `seed-graph-error.ts` | `X_SEED_GRAPH_UNSATISFIED`, its fix naming the `defineFactory` to write; `X_SEED_GRAPH_ENTITY_UNKNOWN`, a plan and a writer built from two entity sets |
 | `seed-writer.ts` | `entitySeedWriter({ entities, client })` or `({ entities, driver? })` — the `SeedWriter` that writes a graph through each entity's own repository: Postgres or PGlite through a client, or a driver. `@ultimat3/entity` loads on the first write. `snapshot(rows)`, required on every `SeedWriter`, reads rows back as one digest each (`md5(t::text)` over a client), `null` for a row gone |
 | `exercise.ts` | `runExercisePass({ entities, writer, roles, seed?, overrides?, only? })` — every registered action, query and job once, each on its own committed tenant pair, one `ExerciseRecord` per primitive, the tenant proof's verdict on its `tenant`. What `x exercise` runs |
-| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) } })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) }, setup?: () => mockFetch(…) \| cassette(…) })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `exercise-setup.ts` | `withExerciseSetup(room, setup)`: the app's `setup` run inside the sealed room before the first row, its handle disposed before the room restores the network; an `allowHost` in it is `X_EXERCISE_SETUP_UNSEALED`. Types `ExerciseSetup`, `ExerciseSetupHandle` |
 | `exercise-actor.ts` · `exercise-input.ts` · `exercise-report.ts` | the first `x policy explain` actor the policy allows, minted in the primitive's tenant · the input: override, then a seeded id by field stem, then the minimal draw (`@ultimat3/schema/sample`, loaded dynamically) · the room one run executes in (network sealed, mail captured, clock frozen) and its record, `overrideLine` the entry to paste |
 | `tenant-proof.ts` | internal (`CROSS_TENANT_SCOPE` is `@ultimat3/entity`'s): `proveTenant` — B with A's ids, A's own call, B again; each B leg between two snapshots of A's rows. `withoutCrossTenant` strips `tenancy:cross` (`CROSS_TENANT_SCOPE`) from B; `publicReason` decides `public` |
 | `tenant-canary.ts` | internal: `tenantTaint` — one tenant's rows, ids and marks (row canaries, key parts of `MIN_TAINT_ID_LENGTH` 8 or more no other tenant shares); `findTaint` — every path holding one |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "30.2.0",
+  "version": "30.4.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.2.0",
-    "@ultimat3/cache": "30.2.0",
-    "@ultimat3/core": "30.2.0",
-    "@ultimat3/db": "30.2.0",
-    "@ultimat3/entity": "30.2.0",
-    "@ultimat3/http": "30.2.0",
-    "@ultimat3/i18n": "30.2.0",
-    "@ultimat3/jobs": "30.2.0",
-    "@ultimat3/mail": "30.2.0",
-    "@ultimat3/policy": "30.2.0",
-    "@ultimat3/pwa": "30.2.0",
-    "@ultimat3/query": "30.2.0",
-    "@ultimat3/realtime": "30.2.0",
-    "@ultimat3/render": "30.2.0",
-    "@ultimat3/schema": "30.2.0",
-    "@ultimat3/time": "30.2.0"
+    "@ultimat3/action": "30.4.0",
+    "@ultimat3/cache": "30.4.0",
+    "@ultimat3/core": "30.4.0",
+    "@ultimat3/db": "30.4.0",
+    "@ultimat3/entity": "30.4.0",
+    "@ultimat3/http": "30.4.0",
+    "@ultimat3/i18n": "30.4.0",
+    "@ultimat3/jobs": "30.4.0",
+    "@ultimat3/mail": "30.4.0",
+    "@ultimat3/policy": "30.4.0",
+    "@ultimat3/pwa": "30.4.0",
+    "@ultimat3/query": "30.4.0",
+    "@ultimat3/realtime": "30.4.0",
+    "@ultimat3/render": "30.4.0",
+    "@ultimat3/schema": "30.4.0",
+    "@ultimat3/time": "30.4.0"
   }
 }

package/src/define-exercise.ts

@@ -5,6 +5,7 @@
 
 import type { ExerciseOptions } from '@ultimat3/action';
 import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import type { ExerciseSetup } from './exercise-setup';
 import type { SeedFactory } from './seed-graph-plan';
 
 /** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
@@ -18,6 +19,8 @@ export interface ExerciseOverrides {
   readonly actorEntity?: 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`). */
+  readonly setup?: ExerciseSetup;
 }
 
 /** What the whole pass needs to know of the app, beside the per-primitive entries. */
@@ -34,6 +37,13 @@ export interface ExerciseAppOptions {
    * refused when the pass runs.
    */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
+  /**
+   * Run in the exercise process once the network is sealed, before the first row: install the
+   * `mockFetch` routes or `cassette()` your vendor-calling handlers need, so they run for real.
+   * What it returns (a cassette, any `Disposable`) is disposed after the pass. `allowHost` here is
+   * `X_EXERCISE_SETUP_UNSEALED` — the pass never sends a call out.
+   */
+  readonly setup?: ExerciseSetup;
 }
 
 /** `X_CONTRACT_EXERCISE_UNDECLARED`, 39's code for the same silence: an `off` with no reason. */
@@ -59,6 +69,7 @@ export function defineExercise(
     entries,
     ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
     ...(app.factories === undefined ? {} : { factories: app.factories }),
+    ...(app.setup === undefined ? {} : { setup: app.setup }),
   });
 }
 

package/src/errors.ts

@@ -69,6 +69,7 @@ export const TESTING_ERROR_CODES = [
   'X_CASSETTE_SECRET',
   'X_CASSETTE_RECORD_REFUSED',
   'X_TEST_MODULE_MOCK_UNRESTORABLE',
+  'X_EXERCISE_SETUP_UNSEALED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -133,6 +134,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_CASSETTE_SECRET: 'a cassette about to be written holds a secret value',
   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',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/exercise-job-tenant.ts

@@ -0,0 +1,103 @@
+// A job's input, seated in the tenant the pass enqueues it under. A job DECLARES its org as a
+// function of its input (`tenant: (input) => input.orgId`), so a drawn input names a random org and
+// the enqueue refuses it (`X_JOB_TENANT_MISMATCH`). The fields that function reads are found by
+// reading them — a recording proxy, no field-name guess — and each is set to the seated tenant.
+
+/** The handle's half the binder needs: `AnyJobHandle.tenantFor`, structurally. */
+export interface TenantOf {
+  readonly name: string;
+  tenantFor(input: unknown): string | undefined;
+}
+
+/** `seated`: the input names the tenant. `fixed`: no field it reads moves the org it answers. */
+export type JobTenantBinding =
+  | { readonly kind: 'seated'; readonly input: unknown }
+  | { readonly kind: 'fixed'; readonly declared: string | undefined };
+
+type Path = readonly string[];
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
+};
+
+/** What `tenantFor` answered, or `undefined` for a throw: an unreadable input names no org. */
+const answer = (handle: TenantOf, input: unknown): string | undefined => {
+  try {
+    return handle.tenantFor(input);
+  } catch {
+    return undefined;
+  }
+};
+
+/** How deep an absent parent is filled in to read past it: `payload.input.orgId` is two. */
+const ABSENT_DEPTH = 4;
+
+/** The value at `path`, `undefined` when any step of it is absent. */
+const getAt = (input: unknown, path: Path): unknown =>
+  path.reduce<unknown>((value, key) => (isPlainObject(value) ? value[key] : undefined), input);
+
+/** Every property path `tenantFor` read, at any depth of plain objects — a missing one included. */
+function readOnce(handle: TenantOf, input: unknown): readonly Path[] {
+  const read: Path[] = [];
+  const watch = (value: unknown, at: Path): unknown =>
+    !isPlainObject(value)
+      ? value
+      : new Proxy(value, {
+          get(target, key, receiver) {
+            if (typeof key !== 'string') return Reflect.get(target, key, receiver);
+            const path = [...at, key];
+            read.push(path);
+            return watch(Reflect.get(target, key, receiver), path);
+          },
+        });
+  answer(handle, watch(input, []));
+  return read;
+}
+
+/**
+ * Every path read, past absent parents too: a read that found nothing is filled with `{}` and read
+ * again, so `payload.input.orgId` — a scoped backfill's tenant, its `input` left out of the
+ * minimal draw — is found, not lost to the throw reading `orgId` of `undefined`.
+ */
+function pathsRead(handle: TenantOf, input: unknown, depth = 0): readonly Path[] {
+  const reads = readOnce(handle, input);
+  if (depth >= ABSENT_DEPTH) return reads;
+  const deeper = reads
+    .filter((path) => getAt(input, path) === undefined)
+    .flatMap((path) => pathsRead(handle, setAt(input, path, {}), depth + 1));
+  const seen = new Set<string>();
+  return [...reads, ...deeper].filter((path) => {
+    const key = JSON.stringify(path);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** `input` with `path` set to `value`, copied along the path only. */
+function setAt(input: unknown, path: Path, value: unknown): unknown {
+  const [head, ...rest] = path;
+  if (head === undefined) return value;
+  const base = isPlainObject(input) ? input : {};
+  return { ...base, [head]: setAt(base[head], rest, value) };
+}
+
+/**
+ * `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.
+ */
+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 };
+  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
+    ? { kind: 'seated', input: bound }
+    : { kind: 'fixed', declared };
+}

package/src/exercise-report.ts

@@ -13,6 +13,7 @@ import {
 import type { RowObserver } from '@ultimat3/entity';
 import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
 import { testMail } from './fixture-mail';
+import { routeMatches } from './mock-route';
 import type { PlanProof, SentStatement } from './plan-sweep';
 import type { ScaleProof, StatementTally } from './scale-sweep';
 import {
@@ -99,6 +100,11 @@ export interface ExerciseRecord {
   readonly ms: number;
   /** For an `unreached` one: the line to paste into `defineExercise({ … })`. */
   readonly override?: string;
+  /**
+   * For an `unreached` one no override reaches: the edit that does, in place of the paste — a job
+   * whose `tenant(input)` names one fixed org (`exercise-subjects.ts`'s `fixedTenant`).
+   */
+  readonly fix?: string;
   /** On every record that ran — absent only on `off` and `refused`. The fields above are A's. */
   readonly tenant?: TenantProof;
   /** On a reached job only: its control's input, killed at every step boundary. */
@@ -223,6 +229,10 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
     },
     end: (): Observed => {
       const calls = requestLog().slice(logFrom);
+      // A call a route answered never left the process: the app's `setup` installed it.
+      const { mocks } = captureNetwork();
+      const refused = (call: (typeof calls)[number]): boolean =>
+        !local(call.url) && !mocks.some((route) => routeMatches(route, call));
       const effects: ExerciseEffect[] = [
         ...[...tally(rows)].map(([key, count]): ExerciseEffect => {
           const [entity = '', op = ''] = key.split('\u0000');
@@ -236,11 +246,11 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
             kind: 'network',
             method: call.method,
             host: hostOf(call.url),
-            refused: !local(call.url),
+            refused: refused(call),
           }),
         ),
       ];
-      const refusedHosts = calls.filter((call) => !local(call.url)).map((c) => hostOf(c.url));
+      const refusedHosts = calls.filter(refused).map((c) => hostOf(c.url));
       const payloads: EffectPayload[] = [
         ...mail.outbox().map(({ message }, i) => ({
           path: `effect.mail[${i}]`,

package/src/exercise-setup.ts

@@ -0,0 +1,68 @@
+// `defineExercise(…, { setup })`, run: the app's hook inside the pass's sealed room, before the
+// first row is seeded, disposed before the room restores the network. What it installs — a
+// `mockFetch` route, a `cassette()` — answers a vendor call; `allowHost` would send one for real.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import type { ExerciseRoom } from './exercise-report';
+import { captureNetwork } from './sealed-network';
+
+/** What a setup may hand back to be undone after the pass: a `cassette()`, a `using` resource. */
+export type ExerciseSetupHandle = Disposable | AsyncDisposable;
+
+/**
+ * Runs once per pass, in the exercise process, after the seal and before any primitive. Returns
+ * nothing when there is nothing to undo — a `mockFetch` route goes with the room.
+ */
+export type ExerciseSetup = () =>
+  | void
+  | ExerciseSetupHandle
+  | Promise<void>
+  | Promise<ExerciseSetupHandle>
+  | Promise<ExerciseSetupHandle | undefined>;
+
+const setupUnsealed = (hosts: readonly string[]): UltimateError =>
+  new UltimateError({
+    code: 'X_EXERCISE_SETUP_UNSEALED',
+    cause: `defineExercise(…, { setup }) called allowHost(${hosts.map((host) => renderCauseValue(host)).join(', ')}): the pass would send a primitive's call out for real, where every vendor is answered by mockFetch or cassette()`,
+    fix: "mockFetch('https://<host>/*', handler)   # or cassette(import.meta.dir, '<name>') — in apps/web/exercise.ts's setup, in place of allowHost('<host>')",
+    meta: { hosts },
+  });
+
+async function release(handle: unknown): Promise<void> {
+  if (typeof handle !== 'object' || handle === null) return;
+  if (Symbol.asyncDispose in handle) await (handle as AsyncDisposable)[Symbol.asyncDispose]();
+  else if (Symbol.dispose in handle) (handle as Disposable)[Symbol.dispose]();
+}
+
+/**
+ * `room` with `setup` run inside it. Its dispose releases what setup returned FIRST — a cassette's
+ * own check reads the routes the pass used — then the room. A setup that throws, or lets a host
+ * through, disposes both before the pass refuses.
+ */
+export async function withExerciseSetup(
+  room: ExerciseRoom,
+  setup: ExerciseSetup | undefined,
+): Promise<ExerciseRoom> {
+  if (setup === undefined) return room;
+  const before = new Set(captureNetwork().allowed);
+  let handle: unknown;
+  try {
+    handle = await setup();
+  } catch (error) {
+    await room[Symbol.asyncDispose]();
+    throw error;
+  }
+  const dispose = async (): Promise<void> => {
+    try {
+      await release(handle);
+    } finally {
+      await room[Symbol.asyncDispose]();
+    }
+  };
+  const opened = captureNetwork().allowed.filter((host) => !before.has(host));
+  if (opened.length > 0) {
+    await dispose();
+    throw setupUnsealed(opened);
+  }
+  return { ...room, [Symbol.asyncDispose]: dispose };
+}

package/src/exercise-subjects.ts

@@ -0,0 +1,133 @@
+// The primitives an exercise pass drives, each as one call: every registered action, query and job,
+// loaded on demand. A job is enqueued in the tenant it is called for, its input SEATED there first
+// (`exercise-job-tenant.ts`): a drawn org is a random one, and the enqueue refuses it.
+
+import type { Actor } from '@ultimat3/core';
+import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { AnyJobHandle, JobExecution } from '@ultimat3/jobs';
+import { registeredJobs } from '@ultimat3/jobs';
+import type { Policy } from '@ultimat3/policy';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { JobTenantBinding } from './exercise-job-tenant';
+import { bindJobTenant } from './exercise-job-tenant';
+import { withExerciseRequest } from './exercise-request';
+import type { RunJobs } from './fixture-jobs';
+
+/** `failure` set: the worker recorded one (a job's). Absent: answered, with `output`. */
+export interface Answer {
+  readonly failure?: unknown;
+  readonly output?: unknown;
+}
+
+/** One primitive, as the pass drives it: the schema to draw from and the one call to make. */
+export interface Subject {
+  readonly kind: 'action' | 'query' | 'job';
+  readonly name: string;
+  readonly input: StandardSchemaV1;
+  readonly policy: Policy | undefined;
+  /** Every permission the policy references — what `x policy explain` matches grants against. */
+  readonly permissions: readonly string[];
+  /** A job's handle: what the crash proof kills at every step boundary once the control reached it. */
+  readonly handle?: AnyJobHandle;
+  /** A job's: `input` naming `tenant` wherever its declared `tenant(input)` reads the org. */
+  seat?(input: unknown, tenant: string): JobTenantBinding;
+  /** Resolves to the failure a worker recorded on the row (a job's), or what the call answered. */
+  call(input: unknown, actor: Actor | null, tenant: string, jobs: RunJobs): Promise<Answer>;
+}
+
+/** `input` seated in `tenant` when the subject declares a seat and one exists; else as given. */
+export const seatIn = (subject: Pick<Subject, 'seat'>, input: unknown, tenant: string): unknown => {
+  const seat = subject.seat?.(input, tenant);
+  return seat?.kind === 'seated' ? seat.input : input;
+};
+
+/**
+ * Why a job whose org no input field moves is not run: the pass seats every primitive in a FRESH
+ * tenant of its own, and a constant org is none of them. Seeding that one org instead would hand
+ * every such job the same tenant — no fresh pair, no tenant proof — so it is reported, never run
+ * in a tenant whose rows the pass did not seed. The repair is the declaration's.
+ */
+export function fixedTenant(name: string, declared: string | undefined) {
+  const org = declared === undefined ? 'no org' : `org ${renderCauseValue(declared)}`;
+  return {
+    code: 'X_JOB_TENANT_MISMATCH',
+    reason: `its tenant(input) answers ${org} whatever its input carries, so it cannot run in the fresh tenant the pass seeded for it`,
+    fix: `tenant: (input) => input.orgId   # in job({ name: ${JSON.stringify(name)} })'s declaration: the org as input, so every enqueuer — this pass too — names it; then: x exercise ${renderFixShellArg(name, '<name>')} --json`,
+  };
+}
+
+const ANSWERED: ReadonlySet<string> = new Set(['completed', 'suspended']);
+
+/**
+ * What a failed run hands the verdict. A run whose error carried a code is that code again, so
+ * core's `exerciseDefect` judges it by the one rule an action's refusal meets: a coded refusal
+ * under 500 is the job answering "no", a 5xx or an uncoded throw is a defect. The message alone
+ * read every coded refusal — an app's 409 included — as an uncoded throw: X_CONTRACT_DEFECT.
+ */
+const jobFailure = (run: JobExecution | undefined): unknown => {
+  if (run === undefined) return 'the job never ran';
+  const message = run.error ?? `the run ended ${run.outcome}`;
+  if (run.code === undefined) return message;
+  return new UltimateError({
+    code: run.code,
+    cause: message,
+    fix: `x errors explain ${renderFixShellArg(run.code, '<code>')} --json`,
+  });
+};
+
+const jobSubject = (handle: AnyJobHandle): Subject => ({
+  kind: 'job',
+  name: handle.name,
+  input: handle.input,
+  policy: undefined,
+  permissions: [],
+  handle,
+  seat: (input, tenant) => bindJobTenant(handle, input, tenant),
+  call: async (input, actor, tenant, jobs) => {
+    const queued = await jobs.enqueue(handle, input, { tenantId: tenant });
+    const trace = await jobs.drain(actor === null ? {} : { actor });
+    const own = trace.executions.find((run) => run.jobId === queued.id);
+    // The worker's failure is on the row, never a throw: the attempt's error and its code.
+    // Suspended is a body that ran and parked (`step.sleep`, `waitForEvent`): reached.
+    return own !== undefined && ANSWERED.has(own.outcome)
+      ? { output: own.result }
+      : { failure: jobFailure(own) };
+  },
+});
+
+export async function subjectsOf(): Promise<readonly Subject[]> {
+  // On demand, as every fixture here loads them: the barrel stays off `action` and `query`.
+  const { invoke, listActions } = await import('@ultimat3/action');
+  const { listQueries, runQuery } = await import('@ultimat3/query');
+  return [
+    ...listActions().map(
+      (target): Subject => ({
+        kind: 'action',
+        name: target.name,
+        input: target.input,
+        policy: target.policy,
+        permissions: target.describe().permissions,
+        call: async (input, actor) => ({
+          output: await withExerciseRequest(target.name, actor, () =>
+            invoke(target, input, { surface: 'http' }),
+          ),
+        }),
+      }),
+    ),
+    ...listQueries().map(
+      (target): Subject => ({
+        kind: 'query',
+        name: target.name,
+        input: target.input,
+        policy: target.policy,
+        permissions: target.describe().permissions,
+        call: async (input, actor) => ({
+          output: await withExerciseRequest(target.name, actor, () =>
+            runQuery(target, input, { surface: 'http' }),
+          ),
+        }),
+      }),
+    ),
+    ...registeredJobs().map(jobSubject),
+  ];
+}

package/src/exercise-sweeps.ts

@@ -3,8 +3,6 @@
 // database). Both verdicts land on the record of the primitive that sent the statements.
 
 import type { Actor } from '@ultimat3/core';
-import type { Policy } from '@ultimat3/policy';
-import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { ExerciseOverrides } from './define-exercise';
 import type { ActorRows, RoleGrants } from './exercise-actor';
 import { asSeededRow, chooseActor } from './exercise-actor';
@@ -12,6 +10,8 @@ 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 { Subject } from './exercise-subjects';
+import { seatIn } from './exercise-subjects';
 import { sweepPlans } from './plan-sweep';
 import type { ScaleSweepOptions } from './scale-sweep-run';
 import { scaleSweep } from './scale-sweep-run';
@@ -37,13 +37,8 @@ export const actorRowsOf = (options: CallOptions, graph: SeedGraph): ActorRows |
 export const seated = (actor: Actor | null, tenant: string, rows: ActorRows | undefined) =>
   rows === undefined ? actor : asSeededRow(actor, tenant, rows);
 
-/** A primitive as a sized call needs it: its schema and its policy. */
-interface Callable {
-  readonly name: string;
-  readonly input: StandardSchemaV1;
-  readonly policy: Policy | undefined;
-  readonly permissions: readonly string[];
-}
+/** A primitive as a sized call needs it: its schema, its policy, and a job's seat. */
+type Callable = Pick<Subject, 'name' | 'input' | 'policy' | 'permissions' | 'seat'>;
 
 /** One call of `subject` in `tenant` of a sized graph: the control's actor and first input. */
 export async function sizedCall(
@@ -67,7 +62,8 @@ export async function sizedCall(
   const lookup = seededIds(graph, options.entities, { ...scope, self });
   const drawn = bindIds(drawInput(sampler, subject.input, 0, 0), lookup);
   const bindInput = overrideInput(subject.name, override);
-  return { actor, input: bindInput === undefined ? drawn : await bindInput(drawn, actor) };
+  const given = bindInput === undefined ? drawn : await bindInput(drawn, actor);
+  return { actor, input: seatIn(subject, given, tenant) };
 }
 
 /**