@ultimat3/testing 29.4.0 → 30.1.0

package/src/e2e-driver.ts

@@ -3,6 +3,8 @@
 // made, which is what keeps a CI box with no Chrome answering `hasE2eDriver() === false`.
 
 import { test as bunTest } from 'bun:test';
+import type { A11yOptions, A11yRun } from './e2e-a11y-run';
+import { checkAllow, startA11yRun } from './e2e-a11y-run';
 import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 import { FixtureUnavailableError } from './errors';
@@ -75,6 +77,44 @@ export const e2eFixtures = (
     ),
 });
 
+/** One suite's page and the way it runs an `e2eTest` body — audited, with the app's log on failure. */
+export interface E2eRunner {
+  readonly page: PageLike;
+  run(body: E2eBody, a11y?: A11yOptions): Promise<void>;
+}
+
+/**
+ * What `installE2eDriver` registers, without the registering: the page, and one body's run.
+ *
+ * The audit runs after every settled navigation and once more after the body — so a dialog the
+ * body opened counts — and fails the test only then, with every finding at once. A body that threw
+ * fails on its own error: the page it left is not the page it meant to show. `reported` is the
+ * suite's, so a finding one test failed on is not told again by the next (`e2e-a11y-run.ts`).
+ */
+export function e2eRunner(options: E2eDriverOptions): E2eRunner {
+  // The running test's audit, which every settled navigation feeds; none outside a test body.
+  let audit: A11yRun | undefined;
+  const page = e2ePage({ ...options, afterNavigate: () => audit?.check() ?? Promise.resolve() });
+  const reported = new Set<string>();
+  return {
+    page,
+    async run(body, a11y) {
+      // Through `withFailureContext`, as `fixtureTest` is: the failing test carries the app's log.
+      try {
+        const current = startA11yRun(options.page, checkAllow(a11y), reported);
+        audit = current;
+        await body(e2eFixtures(page, options.page, options.newBuild));
+        await current.check();
+        current.verdict();
+      } catch (error) {
+        throw withFailureContext(error);
+      } finally {
+        audit = undefined;
+      }
+    },
+  };
+}
+
 /**
  * Install the browser-backed driver for this process.
  *
@@ -93,22 +133,18 @@ export const e2eFixtures = (
  * every later file in the run.
  */
 export function installE2eDriver(options: E2eDriverOptions): () => void {
-  const page = e2ePage(options);
+  const { page, run } = e2eRunner(options);
   const newBuild = options.newBuild;
   defineFixtures({
     page: () => page,
     ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
   });
   useE2eDriver((name, body: E2eBody, test) => {
-    // Through `withFailureContext`, as `fixtureTest` is: the failing test carries the app's log.
-    const run = async (): Promise<void> => {
-      try {
-        await body(e2eFixtures(page, options.page, newBuild));
-      } catch (error) {
-        throw withFailureContext(error);
-      }
-    };
-    bunTest(name, run, test?.timeoutMs === undefined ? undefined : paced(test.timeoutMs));
+    bunTest(
+      name,
+      () => run(body, test?.a11y),
+      test?.timeoutMs === undefined ? undefined : paced(test.timeoutMs),
+    );
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-page.ts

@@ -3,6 +3,7 @@
 // may import the other — so the join is here, in the one package allowed to know about both.
 
 import { finiteCount } from '@ultimat3/core';
+import type { AxTreeNode } from './ax-node';
 import { evaluateClosure } from './e2e-evaluate';
 import { e2eLocator } from './e2e-locator';
 import type { E2eSelection } from './e2e-selection';
@@ -31,6 +32,20 @@ export interface E2eBrowserPage {
    * app's ONLINE page pass an offline test.
    */
   offline?(enabled: boolean): Promise<void>;
+  /**
+   * The document's full accessibility tree, as the browser computed it for a screen reader. A node
+   * `request.describe` picks is answered with its bounded `outerHTML` and which of
+   * `request.selectors` it matches — one round trip per such node, never per node of the tree.
+   * OPTIONAL as `offline` is, and for its reason; absent, every `e2eTest` refuses by name
+   * (`e2e-a11y-run.ts`) rather than passing a page nothing audited.
+   */
+  accessibilityTree?(request: AxTreeRequest): Promise<readonly AxTreeNode[]>;
+}
+
+/** What the audit asks of one tree read: which nodes to describe, and the selectors to test. */
+export interface AxTreeRequest {
+  readonly describe: (node: AxTreeNode) => boolean;
+  readonly selectors: readonly string[];
 }
 
 export interface E2ePageOptions {
@@ -44,6 +59,11 @@ export interface E2ePageOptions {
    * IN THE PAGE. One test raises its own with `waitForServiceWorker({ timeoutMs })`.
    */
   readonly serviceWorkerTimeoutMs?: number | undefined;
+  /**
+   * Run after every navigation this adapter makes has settled — `goto`, `reload`, `gotoStreamed`.
+   * The e2e driver's accessibility audit (`e2e-driver.ts`); a rejection fails the navigation.
+   */
+  readonly afterNavigate?: (() => Promise<void>) | undefined;
 }
 
 /** Named once, so both refusals below name the call an app's test preload actually makes. */
@@ -137,20 +157,25 @@ export function e2ePage(options: E2ePageOptions): PageLike {
   );
   const absolute = (url: string): string => new URL(url, options.baseUrl).toString();
   const locate = (selection: E2eSelection): LocatorLike => e2eLocator(page, selection);
+  const settled = async (navigation: Promise<unknown>): Promise<unknown> => {
+    const answer = await navigation;
+    await options.afterNavigate?.();
+    return answer;
+  };
 
   return {
     url: () => page.url(),
-    goto: (url) => page.goto(absolute(url), { timeout }),
+    goto: (url) => settled(page.goto(absolute(url), { timeout })),
     // The page's OWN url, re-read at call time: a reload of the url the adapter was built with
     // would navigate away from wherever the test had got to.
-    reload: () => page.goto(page.url(), { timeout }),
+    reload: () => settled(page.goto(page.url(), { timeout })),
     title: async () => {
       const title = readField(await page.evaluate(TITLE), 'title');
       return typeof title === 'string' ? title : '';
     },
     gotoStreamed: async (url) => {
       const target = absolute(url);
-      await page.goto(target, { timeout });
+      await settled(page.goto(target, { timeout }));
       const html = readField(await page.evaluate(firstFlushExpression(target)), 'html');
       return { html: typeof html === 'string' ? html : '' };
     },

package/src/e2e-run.ts

@@ -70,6 +70,7 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
     evaluate: (expression) => browser.page.evaluate(expression),
     click: (selector) => browser.page.click(selector),
     offline: (enabled) => browser.page.offline(enabled),
+    accessibilityTree: (request) => browser.page.accessibilityTree(request),
   };
   const uninstall = deps.install({ page: current, baseUrl: app.base, newBuild });
 

package/src/e2e-spawn.ts

@@ -10,7 +10,7 @@ import { get } from 'node:http';
 import { dirname, join } from 'node:path';
 import { assert, DRAIN_DEADLINE_DEFAULT_MS, READINESS_GRACE_DEFAULT_MS } from '@ultimat3/core';
 import { E2eAppFailedError } from './e2e-errors';
-import { freePort, freePortApartFrom } from './free-port';
+import { freePortApartFrom, freePortPair } from './free-port';
 
 /** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
 export type E2eAppMode = 'dev' | 'serve';
@@ -113,7 +113,8 @@ export const refuse = (step: string, output: string): E2eAppFailedError =>
 /** Spawn the app and answer once `/readyz` does; refuses with the app's own output tail. */
 export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE2eApp> {
   const deadline = options.readyTimeoutMs;
-  const port = freePort();
+  // A PAIR: `x dev` binds its sync node on `port + 1`, and a held neighbour exited the app at boot.
+  const port = freePortPair();
   // Its own scrape port too: every role opens one, the default is a fixed 9090, and a second app —
   // or a developer's `x dev` — already holding it is an app that dies at boot with X_PORT_IN_USE.
   // Apart from the web port AND its neighbour, which `x dev` binds the sync node on: the OS may hand

package/src/errors.ts

@@ -49,6 +49,26 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_ISLAND_STATE_UNKNOWN',
   'X_TEST_APP_NOT_BOOTED',
   'X_TEST_PACE_INVALID',
+  'X_SEED_GRAPH_UNSATISFIED',
+  'X_E2E_A11Y_VIOLATION',
+  'X_SEED_GRAPH_ENTITY_UNKNOWN',
+  'X_TENANT_LEAK',
+  'X_TENANT_WRITE_CROSSED',
+  'X_JOB_CRASH_DIVERGED',
+  'X_JOB_SIM_INVARIANT',
+  'X_JOB_SIM_NONDETERMINISTIC',
+  'X_DRILL_FAILED',
+  'X_DRILL_SERVICE_MISSING',
+  'X_SUBJECT_ERASE_INCOMPLETE',
+  'X_QUERY_UNINDEXED',
+  'X_QUERY_SORT_UNSERVED',
+  'X_QUERY_SCALES_WITH_ROWS',
+  'X_QUERY_PLAN_UNAVAILABLE',
+  'X_CASSETTE_MISSING',
+  'X_CASSETTE_UNUSED',
+  'X_CASSETTE_SECRET',
+  'X_CASSETTE_RECORD_REFUSED',
+  'X_TEST_MODULE_MOCK_UNRESTORABLE',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -90,6 +110,29 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_ISLAND_STATE_UNKNOWN: 'an island state manifest declares no state with that id',
   X_TEST_APP_NOT_BOOTED: 'describeApp handle read before boot',
   X_TEST_PACE_INVALID: 'ULTIMATE_TEST_PACE is not a number at or above 1',
+  X_SEED_GRAPH_UNSATISFIED: 'no generated row satisfies a table',
+  X_E2E_A11Y_VIOLATION: 'a page fails the accessibility audit',
+  X_SEED_GRAPH_ENTITY_UNKNOWN: 'a seed plan names an entity its writer was not given',
+  X_TENANT_LEAK: "another tenant's row reached a call's output or effect",
+  X_TENANT_WRITE_CROSSED: "a call by one tenant changed another tenant's row",
+  X_JOB_CRASH_DIVERGED:
+    'a job run killed at a step boundary made an effect a different number of times than a clean run',
+  X_JOB_SIM_INVARIANT: 'a simulateJobs seed broke the invariant the test stated',
+  X_JOB_SIM_NONDETERMINISTIC: 'one simulateJobs seed produced two different traces',
+  X_DRILL_FAILED: 'a fault drill property did not hold',
+  X_DRILL_SERVICE_MISSING: 'a fault drill needs a service that is not there',
+  X_SUBJECT_ERASE_INCOMPLETE: 'a value of the subject survived subjectErase',
+  X_QUERY_UNINDEXED: 'a statement no index can serve: the planner can only scan the table',
+  X_QUERY_SORT_UNSERVED: 'a limited read sorts its rows: no index serves the order',
+  X_QUERY_SCALES_WITH_ROWS:
+    'a statement shape runs once per row: its count grows with the rows seeded',
+  X_QUERY_PLAN_UNAVAILABLE:
+    'the database could not answer a generic plan, so no statement was judged',
+  X_CASSETTE_MISSING: 'a cassette replayed with no recording on disk',
+  X_CASSETTE_UNUSED: 'a cassette entry was never replayed',
+  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',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/exercise-actor.ts

@@ -0,0 +1,124 @@
+// Who a primitive runs as in the exercise pass: the first actor `x policy explain` evaluates that
+// the policy allows, minted in the primitive's own tenant. The actors are INJECTED (`RoleGrants`)
+// because the set — anonymous plus one per declared role — is `@ultimat3/cli`'s `devActors()`,
+// and a second "every role" builder here would drift from the one the policy panel shows.
+
+import type { Actor } from '@ultimat3/core';
+import type { NamedActor, Policy } from '@ultimat3/policy';
+import { policyMatrix, rolesGranting } from '@ultimat3/policy';
+import type { ExerciseOverride } from './define-exercise';
+
+/**
+ * The actors `x policy explain` evaluates, each a member of `tenant`: what `devActors()` answers,
+ * with the org set. Injected by the caller (`x exercise` passes cli's own set).
+ */
+export type RoleGrants = (tenant: string) => readonly NamedActor[];
+
+export type ActorChoice =
+  | { readonly kind: 'actor'; readonly actor: Actor | null; readonly name: string }
+  /** No actor the policy is evaluated for is allowed — refused by design, not by a guess. */
+  | { readonly kind: 'refused'; readonly reason: string };
+
+/**
+ * An override's actor, moved into the primitive's tenant: every primitive gets a fresh pair of
+ * tenants, so an actor declared once in `exercise.ts` cannot know the org it will act in.
+ */
+export const inTenant = (actor: Actor | null, tenant: string): Actor | null =>
+  actor === null ? null : Object.freeze({ ...actor, orgId: tenant });
+
+type Verdict = 'allowed' | 'denied' | 'undecidable';
+
+/**
+ * `policyMatrix` with no row and an empty input — the evaluation `x policy explain` prints. A
+ * predicate that reads the input throws there; that actor is undecidable, decided again at run.
+ */
+const verdictFor = (policy: Policy, candidate: NamedActor): Verdict => {
+  try {
+    const row = policyMatrix(policy, { actors: [candidate], input: {} }).rows[0];
+    return row?.allowed === true ? 'allowed' : 'denied';
+  } catch {
+    return 'undecidable';
+  }
+};
+
+/** Whether `actor` holds every permission, directly or through a role — the grant, not the rule. */
+const holds = (actor: Actor | null, permissions: readonly string[]): boolean =>
+  actor !== null &&
+  permissions.every(
+    (permission) =>
+      (actor.permissions ?? []).includes(permission) ||
+      rolesGranting(permission).some((role) => (actor.roles ?? []).includes(role)),
+  );
+
+/**
+ * The actor for one primitive. An override's actor wins; otherwise a signed-in actor before the
+ * anonymous one (a tenant's rows are only reachable signed in). Allowed outright first; then one
+ * that HOLDS every permission the policy names, whose predicate an empty input could not satisfy
+ * (`x policy explain` evaluates with no row, and a row rule decides again on the real call); then
+ * one the empty input could not even evaluate. None of the three is refused by design.
+ */
+export function chooseActor(
+  policy: Policy | undefined,
+  permissions: readonly string[],
+  grants: RoleGrants,
+  tenant: string,
+  override: ExerciseOverride | undefined,
+): ActorChoice {
+  if (override !== undefined && 'actor' in override) {
+    return { kind: 'actor', actor: inTenant(override.actor, tenant), name: 'override' };
+  }
+  const candidates = grants(tenant);
+  const ordered = [
+    ...candidates.filter((c) => c.actor !== null),
+    ...candidates.filter((c) => c.actor === null),
+  ];
+  // A job has no policy, and a served worker acts as nobody: the job's declared tenant is the
+  // only org its body runs under, so the pass drains exactly as production does.
+  if (policy === undefined) return { kind: 'actor', actor: null, name: 'worker' };
+  const verdicts = ordered.map((candidate) => [candidate, verdictFor(policy, candidate)] as const);
+  const pick =
+    verdicts.find(([, verdict]) => verdict === 'allowed') ??
+    verdicts.find(
+      ([candidate, verdict]) =>
+        verdict === 'denied' && permissions.length > 0 && holds(candidate.actor, permissions),
+    ) ??
+    verdicts.find(([, verdict]) => verdict === 'undecidable');
+  if (pick === undefined) {
+    return {
+      kind: 'refused',
+      reason:
+        ordered.length === 0
+          ? `no actor to evaluate ${policy.label} for: the role grants answered none`
+          : `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 };
+}
+
+/** 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[] };
+  readonly rows: readonly {
+    readonly tenant: string | null;
+    readonly row: Readonly<Record<string, unknown>>;
+  }[];
+}
+
+/**
+ * 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.
+ */
+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 own = rows.rows.filter((row) => row.tenant === tenant || row.tenant === null);
+  const roles = actor.roles ?? [];
+  const row =
+    own.find((candidate) =>
+      Object.values(candidate.row).some((v) => roles.includes(v as string)),
+    ) ?? own[0];
+  const id = row?.row[key];
+  return typeof id === 'string' ? Object.freeze({ ...actor, id }) : actor;
+}

package/src/exercise-crash.ts

@@ -0,0 +1,46 @@
+// 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
+// `.x/exercise.json` can hold. Run after the control, so its runs meet the rows the control left.
+
+import type { Actor } from '@ultimat3/core';
+import { ctxOf, isUltimateError, renderThrowable } from '@ultimat3/core';
+import type { AnyJobHandle } from '@ultimat3/jobs';
+import type { CrashFinding, CrashProof } from './exercise-report';
+import type { CrashDivergence } from './job-crash-proof';
+import { crashProof } from './job-crash-proof';
+
+const findingOf = (divergence: CrashDivergence): CrashFinding => {
+  const after = divergence.error.meta?.['after'];
+  return {
+    boundary: divergence.boundary,
+    mode: divergence.mode,
+    effect: divergence.effect,
+    clean: divergence.clean,
+    killed: divergence.killed,
+    ...(typeof after === 'string' ? { after } : {}),
+  };
+};
+
+/**
+ * `diverged` is red; `unproven` — the proof itself could not finish — is reported, never red, as
+ * the tenant proof's is: a question the pass could not ask is not an answer.
+ */
+export async function proveCrash(
+  handle: AnyJobHandle,
+  input: unknown,
+  actor: Actor | null,
+): Promise<CrashProof> {
+  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 };
+    return report.divergences.length === 0
+      ? { verdict: 'held', ...counted }
+      : { verdict: 'diverged', ...counted, findings: report.divergences.map(findingOf) };
+  } catch (error) {
+    return {
+      verdict: 'unproven',
+      reason: isUltimateError(error) ? `${error.code}: ${error.cause}` : renderThrowable(error),
+    };
+  }
+}

package/src/exercise-input.ts

@@ -0,0 +1,182 @@
+// The input one exercise run sends: 39's minimal draw (`@ultimat3/schema/sample`, the one schema
+// walker), then every id field whose stem names a seeded entity bound to a row of the actor's own
+// tenant (`postId` -> `posts`), then the app's override. A wrong guess is visible as `unreached`.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { SeedGraph } from './seed-graph-plan';
+import type { SeedEntity } from './seed-graph-shape';
+
+/** The two draws 39 ships: the minimal value, and a seeded one for every later run. */
+export interface Sampler {
+  sampleInput(schema: StandardSchemaV1): unknown;
+  arbitrary(schema: StandardSchemaV1, options: { seed: number; run: number }): unknown;
+}
+
+/** On demand: a `packages/core` test that never exercises anything must not load the walker. */
+export const loadSampler = async (): Promise<Sampler> => import('@ultimat3/schema/sample');
+
+/** Run 0 is the minimal draw; a run an override asked for beyond it is 39's seeded draw. */
+export const drawInput = (sampler: Sampler, schema: StandardSchemaV1, seed: number, run: number) =>
+  run === 0 ? sampler.sampleInput(schema) : sampler.arbitrary(schema, { seed, run });
+
+/** `postId`, `post_id` -> `post`; `id` alone names no entity. */
+export function idStem(key: string): string | undefined {
+  const match = /^(.+?)_?(?:Id|_id|ID)$/.exec(key);
+  return match?.[1] === undefined || match[1].length === 0 ? undefined : match[1];
+}
+
+/** Case and separators dropped: `blogPost` and `blog_posts` meet at `blogpost`/`blogposts`. */
+const folded = (text: string): string => text.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+const pluralsOf = (stem: string): readonly string[] => {
+  const base = folded(stem);
+  return [base, `${base}s`, `${base}es`, base.endsWith('y') ? `${base.slice(0, -1)}ies` : base];
+};
+
+/**
+ * The entity a stem names, by its declared name or its table, singular or plural — exactly, or
+ * else as the one entity whose name ENDS with it (`endpointId` -> `webhook_endpoints`). Two
+ * suffix matches name nothing: a guess between two tables is not a binding.
+ */
+export function entityForStem(
+  stem: string,
+  entities: readonly SeedEntity[],
+): SeedEntity | undefined {
+  const wanted = pluralsOf(stem);
+  const names = (entity: SeedEntity): readonly string[] => [
+    folded(entity.$name),
+    folded(entity.$table),
+  ];
+  const exact = entities.find((entity) => names(entity).some((name) => wanted.includes(name)));
+  if (exact !== undefined) return exact;
+  const suffixed = entities.filter((entity) =>
+    names(entity).some((name) => wanted.some((form) => name.endsWith(form))),
+  );
+  return suffixed.length === 1 ? suffixed[0] : undefined;
+}
+
+/**
+ * The id an `<stem>Id` field takes: the key of a seeded row of that entity the tenant sees — one
+ * that references the actor when there is one (`authorId` = the actor), since ownership is the
+ * rule a handler most often checks; else one that is not the actor's own row.
+ */
+export type IdLookup = (
+  key: string,
+) => { readonly found: true; readonly value: unknown } | undefined;
+
+const singularOf = (name: string): string =>
+  name.endsWith('ies') ? `${name.slice(0, -3)}y` : name.endsWith('s') ? name.slice(0, -1) : name;
+
+/**
+ * A bare `id` names the entity the PRIMITIVE is named after (`movePostStatus` -> `posts`): the
+ * longest singular entity name inside the primitive's own name. A tie is no binding.
+ */
+export function entityForSubject(
+  subject: string,
+  entities: readonly SeedEntity[],
+): SeedEntity | undefined {
+  const name = folded(subject);
+  const named = entities
+    .map((entity) => [entity, singularOf(folded(entity.$name))] as const)
+    .filter(([, singular]) => singular.length > 0 && name.includes(singular))
+    .sort((a, b) => b[1].length - a[1].length);
+  const [first, second] = named;
+  return first === undefined || second?.[1].length === first[1].length ? undefined : first[0];
+}
+
+export interface IdScope {
+  readonly tenant: string;
+  /** The acting row's id: a row referencing it is preferred. */
+  readonly actorId?: string | undefined;
+  /** The primitive's name, for a bare `id`. */
+  readonly subject: string;
+  /** The entity whose rows are the actors (`defineExercise(…, { actor })`). */
+  readonly actorEntity?: string | undefined;
+  /**
+   * For a field naming the actor entity itself: the actor's OWN row (`memberId` on a preference)
+   * or somebody else's (`userId` on a block). Both are legitimate, so the pass tries each.
+   */
+  readonly self?: boolean;
+}
+
+/** The entity an input key names, if any: `<stem>Id`, or a bare `id` by the primitive's name. */
+const entityForField = (
+  key: string,
+  entities: readonly SeedEntity[],
+  subject: string,
+): SeedEntity | undefined => {
+  if (key === 'id') return entityForSubject(subject, entities);
+  const stem = idStem(key);
+  return stem === undefined ? undefined : entityForStem(stem, entities);
+};
+
+/** Whether any string field of the drawn value names the actor entity — a two-run input. */
+export function namesActorEntity(
+  drawn: unknown,
+  entities: readonly SeedEntity[],
+  scope: Pick<IdScope, 'subject' | 'actorEntity'>,
+): boolean {
+  if (scope.actorEntity === undefined || !isPlainObject(drawn)) return false;
+  return Object.keys(drawn).some((key) =>
+    typeof drawn[key] === 'string'
+      ? entityForField(key, entities, scope.subject)?.$name === scope.actorEntity
+      : namesActorEntity(drawn[key], entities, scope),
+  );
+}
+
+export function seededIds(
+  graph: SeedGraph,
+  entities: readonly SeedEntity[],
+  scope: IdScope,
+): IdLookup {
+  const { tenant, actorId } = scope;
+  // A tenant column's own field (`orgId`) is the tenant the actor stands in, whatever entity it
+  // happens to name: a policy comparing it with `actor.orgId` refuses any other id.
+  const tenantKeys = new Set(entities.map((entity) => entity.$tenantColumn));
+  return (key) => {
+    if (tenantKeys.has(key)) return { found: true, value: tenant };
+    const entity = entityForField(key, entities, scope.subject);
+    if (entity === undefined || entity.$primaryKey.length !== 1) return undefined;
+    const property = entity.$primaryKey[0] as string;
+    const seen = graph.inserts.filter(
+      (insert) =>
+        insert.entity === entity.$name && (insert.tenant === null || insert.tenant === tenant),
+    );
+    const own = (insert: (typeof seen)[number]) => insert.row[property] === actorId;
+    const references = (insert: (typeof seen)[number]) =>
+      !own(insert) && Object.values(insert.row).includes(actorId);
+    const other = seen.find((insert) => !own(insert));
+    // The actor entity itself: the actor's own row on the `self` run, somebody else's otherwise.
+    // Any other entity: a row the actor owns (`authorId`) first, then anyone but the actor.
+    const row =
+      actorId === undefined
+        ? seen[0]
+        : entity.$name === scope.actorEntity
+          ? scope.self === true
+            ? (seen.find(own) ?? seen[0])
+            : (other ?? seen[0])
+          : (seen.find(references) ?? other ?? seen[0]);
+    return row === undefined ? undefined : { found: true, value: row.row[property] };
+  };
+}
+
+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;
+};
+
+/**
+ * The drawn value with every id field bound, at any depth of plain objects. A walk of the VALUE,
+ * not the schema: the draw already decided which keys exist. Own keys only, into a fresh object.
+ */
+export function bindIds(drawn: unknown, lookup: IdLookup): unknown {
+  if (Array.isArray(drawn)) return drawn.map((item) => bindIds(item, lookup));
+  if (!isPlainObject(drawn)) return drawn;
+  const bound: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Object.keys(drawn)) {
+    const hit = typeof drawn[key] === 'string' ? lookup(key) : undefined;
+    bound[key] = hit === undefined ? bindIds(drawn[key], lookup) : hit.value;
+  }
+  return bound;
+}

package/src/exercise-override-input.ts

@@ -0,0 +1,34 @@
+// An override's `input`, as the exercise pass applies it: AWAITED, and run inside the request the
+// call itself runs in — so `useContext().actor` is the seated actor that call acts as. That is how
+// an input the draw cannot forge (a signed passkey answer, a challenge issued to THIS actor) is
+// computed from the pass's own state, by one mechanism and no per-primitive case.
+
+import type { Actor } from '@ultimat3/core';
+import { bindDrawn } from '@ultimat3/core';
+import type { ExerciseOverride } from './define-exercise';
+import { withExerciseRequest } from './exercise-request';
+
+/** `(drawn, actor) => input`, or `undefined` when the override binds nothing. */
+export type OverrideInput = (drawn: unknown, actor: Actor | null) => Promise<unknown>;
+
+export function overrideInput(
+  name: string,
+  override: ExerciseOverride | undefined,
+): OverrideInput | undefined {
+  const bind = bindDrawn(
+    override !== undefined && 'actor' in override ? override.input : undefined,
+  );
+  if (bind === undefined) return undefined;
+  return (drawn, actor) => withExerciseRequest(name, actor, async () => bind(drawn));
+}
+
+/**
+ * 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:
+ * a plain function RETURNING a promise passes it, and `drill-writes.ts` catches that one at its draw.
+ */
+export const isAsyncInput = (override: ExerciseOverride | undefined): boolean =>
+  override !== undefined &&
+  'actor' in override &&
+  override.input !== undefined &&
+  Object.prototype.toString.call(override.input) === '[object AsyncFunction]';