@ultimat3/testing 30.5.0 → 30.6.0

package/CLAUDE.md

@@ -46,10 +46,10 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | 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 }])` |
-| 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) |
+| 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). Committed: job bodies escape transactions |
+| 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 |
 | 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 |

package/package.json

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

package/src/exercise-job-run.ts

@@ -0,0 +1,68 @@
+// A job primitive's one execution, as the exercise pass runs it: ALONE, on a queue that holds nothing
+// else, for one worker pass. What it enqueues is handed back to the caller's queue unrun, exactly as
+// an action's enqueues are — counted there as `enqueue` effects, searched by the tenant proof, and
+// never executed inside the subject's room, so a child's statements are never the subject's.
+
+import type { Actor } from '@ultimat3/core';
+import { assert } from '@ultimat3/core';
+import type { AnyJobHandle, JobExecution, JobRecord } from '@ultimat3/jobs';
+import { jobCursor, jobDriver, MAX_JOB_PAGE, registeredJobs } from '@ultimat3/jobs';
+import type { RunJobs } from './fixture-jobs';
+import { testJobs } from './fixture-jobs';
+
+const QUEUED: ReadonlySet<string> = new Set(['ready', 'delayed']);
+
+/** Every row the AMBIENT driver holds, page by page: what a fixture's queue has, finished or not. */
+export async function ambientJobRows(): Promise<readonly JobRecord[]> {
+  const introspect = jobDriver()?.introspect;
+  if (introspect === undefined) return [];
+  const records: JobRecord[] = [];
+  for (let after: string | undefined; ; ) {
+    const page = await introspect.list({
+      limit: MAX_JOB_PAGE,
+      ...(after === undefined ? {} : { after }),
+    });
+    records.push(...page);
+    const last = page[page.length - 1];
+    if (last === undefined || page.length < MAX_JOB_PAGE) break;
+    after = jobCursor(last);
+  }
+  return records;
+}
+
+/**
+ * `handle` run once with `input` in `tenant`, as `actor`'s worker: enqueued on a fresh queue and
+ * claimed by ONE pass, so the only run is its own — never a job `into` already held (an earlier
+ * call's, an earlier primitive's) and never one it queued. Those it queued land on `into`, unrun.
+ */
+export async function runJobAlone(
+  handle: AnyJobHandle,
+  input: unknown,
+  at: { readonly actor: Actor | null; readonly tenant: string },
+  into: RunJobs,
+): Promise<JobExecution | undefined> {
+  let own: JobExecution | undefined;
+  let queued: readonly JobRecord[];
+  {
+    await using alone = await testJobs();
+    const row = await alone.enqueue(handle, input, { tenantId: at.tenant });
+    const trace = await alone.tick(at.actor === null ? {} : { actor: at.actor });
+    own = trace.executions.find((run) => run.jobId === row.id);
+    queued = (await ambientJobRows()).filter(
+      (record) => record.id !== row.id && QUEUED.has(record.state),
+    );
+  }
+  const handles = new Map(registeredJobs().map((one) => [one.name, one]));
+  for (const record of queued) {
+    const child = handles.get(record.name);
+    assert(
+      child !== undefined,
+      `job "${handle.name}" queued job "${record.name}" but nothing registered it`,
+      `import the module that declares job("${record.name}") from the app's api module — the registry is populated by the import, not by the queue`,
+    );
+    await into.enqueue(child, record.input, {
+      ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+    });
+  }
+  return own;
+}

package/src/exercise-subjects.ts

@@ -1,6 +1,7 @@
 // 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.
+// (`exercise-job-tenant.ts`): a drawn org is a random one, and the enqueue refuses it. It runs
+// alone (`exercise-job-run.ts`): what it queues is left queued, as an action's is.
 
 import type { Actor } from '@ultimat3/core';
 import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
@@ -8,6 +9,7 @@ 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 { runJobAlone } from './exercise-job-run';
 import type { JobTenantBinding } from './exercise-job-tenant';
 import { bindJobTenant } from './exercise-job-tenant';
 import { withExerciseRequest } from './exercise-request';
@@ -84,9 +86,9 @@ const jobSubject = (handle: AnyJobHandle): Subject => ({
   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);
+    // Its own execution and nothing else: a drain of `jobs` ran what it queued (one child per row,
+    // which the scale sweep read as the job's loop) and whatever an earlier call had left there.
+    const own = await runJobAlone(handle, input, { actor, tenant }, jobs);
     // 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)

package/src/exercise.ts

@@ -8,7 +8,6 @@
 
 import type { Actor, ExerciseAttempt, ExerciseVerdict } from '@ultimat3/core';
 import { isUltimateError, renderThrowable, runExercise } from '@ultimat3/core';
-import type { JobExecution, JobRecord } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
 import type { ExerciseOverride, ExerciseOverrides } from './define-exercise';
 import { assertOverridesKnown, unknownDeclaration } from './define-exercise';
@@ -25,6 +24,7 @@ import {
   namesActorEntity,
   seededIds,
 } from './exercise-input';
+import { ambientJobRows } from './exercise-job-run';
 import type { OverrideInput } from './exercise-override-input';
 import { overrideInput } from './exercise-override-input';
 import type {
@@ -76,13 +76,15 @@ const codeOf = (error: unknown): string | undefined => {
 const reasonOf = (error: unknown): string =>
   isUltimateError(error) ? error.cause : typeof error === 'string' ? error : renderThrowable(error);
 
-/** Jobs queued or run by the primitive, the primitive's own job excepted. */
-async function enqueued(subject: Subject, jobs: RunJobs, runs: readonly JobExecution[]) {
+/**
+ * Jobs the primitive queued, its own job excepted. Never run: a job's children are left queued as
+ * an action's are (`exercise-job-run.ts`), so their statements are theirs, never this record's.
+ */
+async function enqueued(subject: Subject, jobs: RunJobs) {
   const effects: ExerciseEffect[] = [];
   for (const handle of registeredJobs()) {
     if (subject.kind === 'job' && handle.name === subject.name) continue;
-    const ran = new Set(runs.filter((run) => run.job === handle.name).map((r) => r.jobId)).size;
-    const count = ran + (await jobs.depth(handle));
+    const count = await jobs.depth(handle);
     if (count > 0) effects.push({ kind: 'enqueue', job: handle.name, count });
   }
   return effects;
@@ -93,21 +95,7 @@ async function enqueued(subject: Subject, jobs: RunJobs, runs: readonly JobExecu
  * input is what B was handed. Read off the leg's own queue, page by page.
  */
 async function queuedPayloads(subject: Subject): Promise<readonly EffectPayload[]> {
-  const jobs = await import('@ultimat3/jobs');
-  const introspect = jobs.jobDriver()?.introspect;
-  if (introspect === undefined) return [];
-  const records: JobRecord[] = [];
-  for (let after: string | undefined; ; ) {
-    const page = await introspect.list({
-      limit: jobs.MAX_JOB_PAGE,
-      ...(after === undefined ? {} : { after }),
-    });
-    records.push(...page);
-    const last = page[page.length - 1];
-    if (last === undefined || page.length < jobs.MAX_JOB_PAGE) break;
-    after = jobs.jobCursor(last);
-  }
-  return records
+  return (await ambientJobRows())
     .filter((record) => !(subject.kind === 'job' && record.name === subject.name))
     .map((record, i) => ({
       path: `effect.enqueue[${i}]`,
@@ -174,7 +162,6 @@ async function control(
   let lastError: unknown;
   let lastInput: unknown;
   let output: unknown;
-  let executions: readonly JobExecution[] = [];
   room.begin(name);
   const started = performance.now();
   const verdict = await runExercise({
@@ -209,9 +196,8 @@ async function control(
     statusOf: (await import('@ultimat3/http')).statusFor,
   });
   const ms = Math.round(performance.now() - started);
-  if (kind === 'job') executions = (await jobs.drain()).executions;
   const observed = room.end();
-  const effects = [...observed.effects, ...(await enqueued(subject, jobs, executions))];
+  const effects = [...observed.effects, ...(await enqueued(subject, jobs))];
   const verdictOf = judged(subject, { verdict, answered, lastError, lastInput }, observed);
   // A 5xx's cause, statement and fields: the code alone sent the author to reproduce it by hand.
   const defect =

package/src/fixture-jobs.ts

@@ -69,6 +69,11 @@ export interface RunJobs extends AsyncDisposable {
   enqueue<I>(handle: JobHandle<I>, input: I, options?: JobEnqueueAs): Promise<EnqueueResult>;
   /** Claim and execute everything due at the current instant, until nothing is. */
   drain(options?: JobDrainAs): Promise<JobRunTrace>;
+  /**
+   * ONE worker pass: what is due now runs, and what those runs enqueue waits for the next pass —
+   * "it queued one child per row" asserted without running a child.
+   */
+  tick(options?: JobDrainAs): Promise<JobRunTrace>;
   /** Live jobs — ready, delayed, running or suspended — optionally for one job only. */
   depth(handle?: AnyJobHandle): Promise<number>;
   /** Live jobs claimable right now. `clock.advance()` is what turns delayed into due. */
@@ -194,14 +199,20 @@ export async function testJobs(): Promise<RunJobs> {
   /** Every execution this fixture has driven, because the trace is cumulative. */
   const history: JobExecution[] = [];
 
+  const ctxFor = (options: JobDrainAs): Ctx =>
+    options.actor === undefined ? anonymousWorker : ctxOf({ role: 'worker', actor: options.actor });
+  const traced = (): JobRunTrace => ({ executions: [...history], steps: tallyOf(history) });
+
+  const tick = async (options: JobDrainAs = {}): Promise<JobRunTrace> => {
+    history.push(...(await round(ctxFor(options))));
+    return traced();
+  };
+
   const drain = async (options: JobDrainAs = {}): Promise<JobRunTrace> => {
-    const ctx =
-      options.actor === undefined
-        ? anonymousWorker
-        : ctxOf({ role: 'worker', actor: options.actor });
+    const ctx = ctxFor(options);
     for (let rounds = 0; rounds < MAX_ROUNDS; rounds += 1) {
       const batch = await round(ctx);
-      if (batch.length === 0) return { executions: [...history], steps: tallyOf(history) };
+      if (batch.length === 0) return traced();
       history.push(...batch);
     }
     assert(
@@ -239,6 +250,7 @@ export async function testJobs(): Promise<RunJobs> {
   return Object.assign(enqueueThenDrain, {
     enqueue,
     drain,
+    tick,
     depth: async (handle?: AnyJobHandle) => (await live(handle?.name)).length,
     due: async () =>
       (await live()).filter(

package/src/job-crash-proof.ts

@@ -134,7 +134,10 @@ async function runOnce<I>(
     if (op.step.startsWith(COMPENSATE_PREFIX)) compensated.push(op.step);
     else if (op.step !== UNWINDING_STEP) forward.add(op.step);
   };
+  // Alone: a child the job queues is its enqueue effect, never run — the clean run that ran it
+  // first wrote its rows, and every killed run after found them there (0× against 6×).
   await using world = await openSimWorld({
+    alone: true,
     seed: finiteCount('crashProof', 'seed', options.seed ?? 1),
     decide,
     landed,

package/src/job-sim-world.ts

@@ -31,6 +31,8 @@ export const SIM_VISIBILITY_MS = 30_000;
 const RENEW_MS = 1;
 const CLAIM_LIMIT = 64;
 const LIVE: ReadonlySet<string> = new Set(['ready', 'delayed', 'running', 'suspended']);
+/** Where an `alone` world files the harness's row: no body enqueues here, so no worker claims theirs. */
+const HARNESS_QUEUE = 'x-sim-harness';
 
 export interface SimWorldOptions {
   /** Seeds `Math.random` for the run: a body's jitter and draws are the seed's. */
@@ -40,6 +42,11 @@ export interface SimWorldOptions {
   decide(op: SimOp): SimDecision | Promise<SimDecision>;
   /** Told every landed call, after the world has read it. */
   landed?(op: SimOp, answer: unknown): void;
+  /**
+   * Only the row the harness filed is ever claimed: what a body enqueues lands, dedupes and is an
+   * `enqueue:` effect, and never runs — its effects are its own job's, not this run's.
+   */
+  readonly alone?: boolean;
 }
 
 export interface SimWorld extends AsyncDisposable {
@@ -115,9 +122,11 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
   const anonymous = ctxOf({ role: 'worker' });
   const context = options.context ?? (() => anonymous);
 
-  const queues = (): readonly string[] => [
-    ...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)]),
-  ];
+  const queues = (): readonly string[] =>
+    options.alone === true
+      ? [HARNESS_QUEUE]
+      : [...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)])];
+  const claimable = new Set(queues());
 
   const rows = async (): Promise<readonly JobRecord[]> => {
     const all: JobRecord[] = [];
@@ -146,7 +155,7 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
     enqueue: async (handle, input) => {
       const result = await base.enqueue({
         name: handle.name,
-        queue: handle.queue,
+        queue: options.alone === true ? HARNESS_QUEUE : handle.queue,
         input,
         idempotencyKey: handle.idempotencyKeyFor(input),
         maxAttempts: jobs.enqueuedAttempts(handle.retry, handle.compensates),
@@ -179,7 +188,9 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
     rows,
     nextDue: async () => {
       const due = (await rows())
-        .filter((row) => LIVE.has(row.state))
+        .filter(
+          (row) => LIVE.has(row.state) && (options.alone !== true || claimable.has(row.queue)),
+        )
         .map((row) => (row.state === 'running' ? (row.visibleAt ?? row.runAt) : row.runAt));
       return due.length === 0 ? undefined : Math.min(...due);
     },