@ultimat3/testing 29.3.2 → 30.0.0

package/src/job-simulate.ts

@@ -0,0 +1,179 @@
+// `simulateJobs`: the jobs a test names, run by N workers over one queue, every driver call
+// interleaved by a seeded picker and faulted by it — kill, lost answer, lapsed lease, duplicate
+// claim, clock jump. Each seed runs twice and must trace the same bytes; then the app's own
+// invariant judges what happened. Off the automatic pass: only the author knows the invariant.
+
+import type { Ctx } from '@ultimat3/core';
+import { assert, finiteCount, finiteOption, renderThrowable } from '@ultimat3/core';
+import type { AnyJobHandle } from '@ultimat3/jobs';
+import { advanceClock, frozenNow } from './determinism';
+import type { SimEffect } from './job-sim-effects';
+import { JobSimInvariantError, JobSimNondeterministicError } from './job-sim-errors';
+import type { JobFaultKind } from './job-sim-schedule';
+import { ALL_FAULTS, simScheduler } from './job-sim-schedule';
+import { openSimWorld } from './job-sim-world';
+
+/** `x test job --seed <n>` hands its seed to the test process under this name: one seed, replayed. */
+export const JOB_SIM_SEED_ENV = 'ULTIMATE_JOB_SIM_SEED';
+
+export interface SimulatedJob {
+  readonly handle: AnyJobHandle;
+  readonly input: unknown;
+}
+
+/** One row as the simulation left it. */
+export interface SimulatedRun {
+  readonly job: string;
+  /** `job#1`: the order it was queued in, the same on every run of a seed. */
+  readonly id: string;
+  readonly state: string;
+  readonly attempt: number;
+  readonly lastError?: string;
+}
+
+export interface SimulationState {
+  readonly seed: number;
+  readonly effects: readonly SimEffect[];
+  readonly runs: readonly SimulatedRun[];
+  readonly faults: readonly string[];
+}
+
+export interface SimulateJobsOptions {
+  /** The first seed. Default 1; `ULTIMATE_JOB_SIM_SEED` in the environment runs that one alone. */
+  readonly seed?: number;
+  readonly seeds?: number;
+  readonly jobs: readonly SimulatedJob[];
+  readonly workers?: number;
+  readonly faults?: readonly JobFaultKind[];
+  /** The chance any one driver call carries a fault. Default 0.05. */
+  readonly faultRate?: number;
+  readonly context?: () => Ctx;
+  /** `false` or a throw is a violation; an `expect` inside reads as one. */
+  invariant(state: SimulationState): unknown;
+}
+
+export interface SimulationReport {
+  readonly seeds: readonly number[];
+}
+
+const MAX_ROUNDS = 100;
+/** Passes one worker takes per round while another is still busy: how a reclaim races a run. */
+const PASSES_PER_ROUND = 4;
+
+/** The seed `x test job --seed <n>` asked to replay, or none. */
+function replaySeed(): number | undefined {
+  const raw = Bun.env[JOB_SIM_SEED_ENV];
+  if (raw === undefined || raw === '') return undefined;
+  const seed = Number(raw);
+  return finiteCount('simulateJobs', JOB_SIM_SEED_ENV, seed);
+}
+
+async function runSeed(seed: number, options: SimulateJobsOptions) {
+  const scheduler = simScheduler({
+    seed,
+    faults: options.faults ?? ALL_FAULTS,
+    faultRate: options.faultRate ?? 0.05,
+  });
+  await using world = await openSimWorld({
+    seed,
+    decide: scheduler.decide,
+    ...(options.context === undefined ? {} : { context: options.context }),
+  });
+  for (const one of options.jobs) await world.enqueue(one.handle, one.input);
+  let spawned = 0;
+  const spawn = (): string => {
+    spawned += 1;
+    return `w${spawned}`;
+  };
+  let alive = Array.from({ length: options.workers ?? 2 }, spawn);
+  for (let round = 0; round < MAX_ROUNDS; round += 1) {
+    const busy = new Set<string>();
+    let ran = 0;
+    const loop = async (worker: string): Promise<void> => {
+      busy.add(worker);
+      for (let pass = 0; pass < PASSES_PER_ROUND && !world.sim.isDead(worker); pass += 1) {
+        const executions = await world.tick(worker);
+        ran += executions.length;
+        for (const run of executions) {
+          scheduler.trace.push(`ran ${worker} ${world.name(run.jobId)} ${run.outcome}`);
+        }
+        if (executions.length === 0 && [...busy].every((one) => one === worker)) break;
+      }
+      busy.delete(worker);
+    };
+    await scheduler.run(world, alive.map(loop));
+    // A killed process is replaced, as an orchestrator restarts it: the fleet keeps its size.
+    alive = alive.map((worker) => (world.sim.isDead(worker) ? spawn() : worker));
+    if (ran > 0) continue;
+    const due = await world.nextDue();
+    if (due === undefined) break;
+    advanceClock(Math.max(1, due - frozenNow().getTime()));
+  }
+  const runs = (await world.rows()).map(
+    (row): SimulatedRun => ({
+      job: row.name,
+      id: world.name(row.id),
+      state: row.state,
+      attempt: row.attempt,
+      ...(row.lastError === undefined ? {} : { lastError: row.lastError }),
+    }),
+  );
+  const effects = world.effects();
+  const trace = [
+    ...scheduler.trace,
+    ...effects.map((effect) => `effect ${effect.worker ?? '-'} ${effect.key}`),
+    ...runs.map((run) => `row ${run.id} ${run.job} ${run.state} ${run.attempt}`),
+  ];
+  return { trace, state: { seed, effects, runs, faults: [...scheduler.planted] } };
+}
+
+function firstDifference(a: readonly string[], b: readonly string[]): number {
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i += 1) if (a[i] !== b[i]) return i;
+  return -1;
+}
+
+export async function simulateJobs(options: SimulateJobsOptions): Promise<SimulationReport> {
+  const seeds = finiteCount('simulateJobs', 'seeds', options.seeds ?? 20, 1);
+  finiteCount('simulateJobs', 'workers', options.workers ?? 2, 1);
+  const rate = finiteOption('simulateJobs', 'faultRate', options.faultRate ?? 0.05);
+  assert(
+    rate >= 0 && rate <= 1,
+    `simulateJobs faultRate is ${rate}, and a chance is between 0 and 1`,
+    'simulateJobs({ …, faultRate: 0.05 })',
+  );
+  const first = finiteCount('simulateJobs', 'seed', options.seed ?? 1);
+  const replay = replaySeed();
+  const list = replay === undefined ? Array.from({ length: seeds }, (_, i) => first + i) : [replay];
+  for (const seed of list) {
+    const once = await runSeed(seed, options);
+    const twice = await runSeed(seed, options);
+    const at = firstDifference(once.trace, twice.trace);
+    if (at !== -1) {
+      throw new JobSimNondeterministicError({
+        seed,
+        at,
+        first: once.trace[at] ?? '<end of trace>',
+        second: twice.trace[at] ?? '<end of trace>',
+      });
+    }
+    let verdict: unknown;
+    try {
+      verdict = options.invariant(once.state);
+    } catch (error) {
+      throw new JobSimInvariantError({
+        seed,
+        faults: once.state.faults,
+        reason: renderThrowable(error),
+      });
+    }
+    if (verdict === false) {
+      throw new JobSimInvariantError({
+        seed,
+        faults: once.state.faults,
+        reason: 'the invariant answered false',
+      });
+    }
+  }
+  return { seeds: list };
+}

package/src/mock-route.ts

@@ -0,0 +1,81 @@
+// What `mockFetch` registers and whether a call reaches it: the verb a match spells, the answers a
+// list gives in order, and the name a pinned dial carries. `sealed-network.ts` owns when it is asked.
+
+import { assert, peerAddressClass } from '@ultimat3/core';
+
+export type MockHandler = (request: Request) => Response | Promise<Response>;
+
+export interface MockRoute {
+  /** Exact URL, or a prefix ending in `*`, or a RegExp. */
+  readonly match: string | RegExp;
+  /** The one verb answered, uppercase. Absent answers every verb. */
+  readonly method?: string;
+  readonly handler: MockHandler;
+}
+
+/** `POST https://…`, the spelling `x shot` states use. A URL holds no space, so nothing else fits. */
+const VERB_PREFIX = /^([A-Z]+) (.+)$/;
+
+/** One handler over a list: the last answer repeats, and a clone means a repeat still has a body. */
+const inOrder = (match: string | RegExp, answers: readonly (Response | Error)[]): MockHandler => {
+  const spelled = typeof match === 'string' ? `'${match}'` : String(match);
+  assert(
+    answers.length > 0,
+    `mockFetch(${spelled}) was handed an empty answer list, so no call could be answered`,
+    `mockFetch(${spelled}, [new Response('{}')]) — one answer at least`,
+  );
+  const pending = [...answers];
+  return () => {
+    const answer = pending.length > 1 ? pending.shift() : pending[0];
+    if (answer instanceof Error) throw answer;
+    return (answer as Response).clone();
+  };
+};
+
+export function mockRoute(
+  match: string | RegExp,
+  answer: MockHandler | readonly (Response | Error)[],
+): MockRoute {
+  const handler = typeof answer === 'function' ? answer : inOrder(match, answer);
+  const verb = typeof match === 'string' ? VERB_PREFIX.exec(match) : null;
+  if (verb?.[1] === undefined || verb[2] === undefined) return { match, handler };
+  return { match: verb[2], method: verb[1], handler };
+}
+
+const urlMatches = (match: string | RegExp, url: string): boolean => {
+  if (match instanceof RegExp) {
+    // A `g`/`y` pattern's `test` resumes at `lastIndex`: without the reset, every other call missed.
+    match.lastIndex = 0;
+    return match.test(url);
+  }
+  if (match.endsWith('*')) return url.startsWith(match.slice(0, -1));
+  return match === url;
+};
+
+/**
+ * A pinned dial is an address literal carrying the name it stands for in `host`, so a mock of the
+ * name is the mock of that dial. Only a literal: a named URL's host header names nothing it dials.
+ */
+const namedUrl = (url: string, headers: Readonly<Record<string, string>>): string | undefined => {
+  const host = headers['host'];
+  if (host === undefined || !URL.canParse(url)) return undefined;
+  const named = new URL(url);
+  if (peerAddressClass(named.hostname) === undefined) return undefined;
+  named.host = host;
+  return named.href;
+};
+
+/** Whether `route` answers this call. */
+export const routeMatches = (
+  route: MockRoute,
+  call: {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+  },
+): boolean => {
+  if (route.method !== undefined && route.method !== call.method) return false;
+  if (urlMatches(route.match, call.url)) return true;
+  const named = namedUrl(call.url, call.headers);
+  return named !== undefined && urlMatches(route.match, named);
+};

package/src/module-mock-boundary.ts

@@ -0,0 +1,85 @@
+// `mock.module` undone at the file boundary. Bun keeps a module mock for the life of the process,
+// past `mock.restore()` and past the file, so on a shared (`--no-isolate`) worker the NEXT file read
+// the fake — a verdict that depended on which file the worker ran first. The preload wraps the call:
+// a file's first mock of a module snapshots the real namespace, and the boundary mocks it back.
+
+import { beforeEach, jest, mock, vi } from 'bun:test';
+// why: Bun ships no path-join primitive; a relative specifier is resolved against its caller.
+import { dirname, join } from 'node:path';
+import { inTestFile, onFileBoundary } from './file-boundary';
+import type { UnrestorableMock } from './module-mock-error';
+import { ModuleMockUnrestorableError } from './module-mock-error';
+
+type MockModule = (id: string, factory: () => unknown) => unknown;
+
+/** The calling file, from a stack captured above `wrapper`: `at fn (/path/a.test.ts:3:5)`. */
+export function callerFile(stack: string | undefined): string | undefined {
+  const frame = stack?.split('\n')[1];
+  const match =
+    frame === undefined ? null : /\(?((?:[A-Za-z]:)?[/\\][^()]*?):\d+:\d+\)?\s*$/.exec(frame);
+  return match?.[1];
+}
+
+let installed = false;
+
+/** Called by the preload once per process; idempotent. */
+export function installModuleMockBoundary(): void {
+  if (installed) return;
+  installed = true;
+  const original = mock.module.bind(mock) as MockModule;
+  const real = new Map<string, Readonly<Record<string, unknown>>>();
+  const unrestorable: UnrestorableMock[] = [];
+  let inherited: UnrestorableMock[] = [];
+
+  const wrapper: MockModule = (id, factory) => {
+    const holder: { stack?: string } = {};
+    Error.captureStackTrace(holder, wrapper);
+    const file = callerFile(holder.stack) ?? process.cwd();
+    const dir = dirname(file);
+    let url = id.startsWith('./') || id.startsWith('../') ? join(dir, id) : id;
+    let missing: unknown;
+    try {
+      url = Bun.resolveSync(id, dir);
+    } catch (reason) {
+      // A virtual module is legal to mock; with no real one there is nothing to put back.
+      missing = reason;
+    }
+    // A preload's mock is every file's environment, never one file's to undo.
+    const tracked = real.has(url) || unrestorable.some((each) => each.url === url);
+    if (inTestFile() && !tracked) {
+      if (missing !== undefined) unrestorable.push({ file, url, reason: missing });
+      else {
+        try {
+          // why: `require` is the one synchronous load; the snapshot must exist before the fake does.
+          real.set(url, { ...(require(url) as Record<string, unknown>) });
+        } catch (reason) {
+          unrestorable.push({ file, url, reason });
+        }
+      }
+    }
+    // The resolved path, so the mock and the boundary's restore name one module.
+    return original(url, factory);
+  };
+
+  for (const host of [mock, vi, jest] as const) {
+    Object.defineProperty(host, host === mock ? 'module' : 'mock', {
+      value: wrapper,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  onFileBoundary(() => {
+    for (const [url, namespace] of real) original(url, () => namespace);
+    real.clear();
+    inherited = [...inherited, ...unrestorable.splice(0)];
+  });
+
+  // The boundary's hooks cannot fail a run, so the next file's first test carries the verdict.
+  beforeEach(() => {
+    if (inherited.length === 0) return;
+    const mocks = inherited;
+    inherited = [];
+    throw new ModuleMockUnrestorableError(mocks);
+  });
+}

package/src/module-mock-error.ts

@@ -0,0 +1,28 @@
+// `X_TEST_MODULE_MOCK_UNRESTORABLE`'s message: which file mocked which module whose real source
+// could not be loaded for its snapshot. The CODE is registered in `errors.ts`; the boundary that
+// raises it is `module-mock-boundary.ts`. Every value here is uncontrolled, so it is rendered.
+
+import { renderCauseValue, renderThrowable, UltimateError } from '@ultimat3/core';
+
+export interface UnrestorableMock {
+  /** The test file that called `mock.module`. */
+  readonly file: string;
+  /** The module it mocked, as resolved (or as written, when it did not resolve). */
+  readonly url: string;
+  /** Why the real module could not be snapshotted. */
+  readonly reason: unknown;
+}
+
+export class ModuleMockUnrestorableError extends UltimateError {
+  constructor(mocks: readonly UnrestorableMock[]) {
+    const each = mocks.map(
+      (mock) =>
+        `${renderCauseValue(mock.file)} mocked ${renderCauseValue(mock.url)}, whose real module failed to load (${renderThrowable(mock.reason)})`,
+    );
+    super({
+      code: 'X_TEST_MODULE_MOCK_UNRESTORABLE',
+      cause: `${each.join('; ')} — so nothing could be put back, and this file on the same worker saw the fake`,
+      fix: 'x test unit --isolate   # or hand the mocked dependency to the code under test as a parameter, so no module is mocked',
+    });
+  }
+}

package/src/plan-oracle.ts

@@ -0,0 +1,164 @@
+// The plan oracle: one `explain (format json)` plan, taken with sequential scans, bitmap scans and
+// sorts disabled, in; the nodes no index could replace, out. Under those settings the planner picks
+// a scan or a sort only when nothing else answers, so the verdict reads the schema, not the rows.
+// Pure: JSON in, verdicts out (plan 101, 40-next-query-plans).
+
+/** What a red node is: a whole-table read, or rows sorted for a limited read. */
+export type PlanVerdictCode = 'X_QUERY_UNINDEXED' | 'X_QUERY_SORT_UNSERVED';
+
+export interface PlanVerdict {
+  readonly code: PlanVerdictCode;
+  /** `Seq Scan`, `Index Scan`, `Index Only Scan`, `Sort`. */
+  readonly node: string;
+  /** The physical table the node reads, or the one under the sort. */
+  readonly table: string;
+  /** Physical columns the statement compares by equality on that table, in the order seen. */
+  readonly equality: readonly string[];
+  /** Physical columns it compares any other way (a range, a pattern). */
+  readonly range: readonly string[];
+  /** The sort's columns on that table, in order. Empty for a scan. */
+  readonly order: readonly string[];
+}
+
+interface PlanNode {
+  readonly type: string;
+  readonly table: string | undefined;
+  readonly alias: string | undefined;
+  readonly conditions: readonly string[];
+  readonly sortKey: readonly string[];
+  readonly indexCond: boolean;
+  readonly filter: boolean;
+  readonly children: readonly PlanNode[];
+}
+
+const SCANS: ReadonlySet<string> = new Set(['Seq Scan', 'Index Scan', 'Index Only Scan']);
+/** Conditions a join or a recheck carries for the scans beneath it. */
+const CONDITION_KEYS = ['Index Cond', 'Filter', 'Hash Cond', 'Merge Cond', 'Join Filter'] as const;
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+function nodeOf(value: unknown): PlanNode | undefined {
+  const raw = record(value);
+  const type = text(raw?.['Node Type']);
+  if (raw === undefined || type === undefined) return undefined;
+  const plans = Array.isArray(raw['Plans']) ? raw['Plans'] : [];
+  const sortKey = Array.isArray(raw['Sort Key'])
+    ? raw['Sort Key'].flatMap((k) => text(k) ?? [])
+    : [];
+  return {
+    type,
+    table: text(raw['Relation Name']),
+    alias: text(raw['Alias']),
+    conditions: CONDITION_KEYS.flatMap((key) => text(raw[key]) ?? []),
+    sortKey,
+    indexCond: text(raw['Index Cond']) !== undefined,
+    filter: text(raw['Filter']) !== undefined,
+    children: plans.flatMap((child) => nodeOf(child) ?? []),
+  };
+}
+
+/** The root node of `explain (format json)`'s answer: `[{ "Plan": { … } }]`, or the bare plan. */
+export function planRoot(answer: unknown): unknown {
+  const parsed = typeof answer === 'string' ? (JSON.parse(answer) as unknown) : answer;
+  const first = Array.isArray(parsed) ? parsed[0] : parsed;
+  return record(first)?.['Plan'] ?? first;
+}
+
+const IDENT = /(?:"?([A-Za-z_][\w$]*)"?\.)?"?([A-Za-z_][\w$]*)"?/g;
+const EQUALITY = /(?<![<>!])=(?!>)/;
+
+/**
+ * The columns of `scan` a condition names, split by how they are compared. A conjunct qualified by
+ * another alias is a join's other side; an unqualified name counts when the table has the column.
+ */
+function columnsIn(
+  conditions: readonly string[],
+  scan: PlanNode,
+  columns: ReadonlySet<string>,
+): { readonly equality: string[]; readonly range: string[] } {
+  const equality: string[] = [];
+  const range: string[] = [];
+  for (const condition of conditions) {
+    for (const conjunct of condition.split(/\bAND\b/)) {
+      const into = EQUALITY.test(conjunct) ? equality : range;
+      for (const [, qualifier, name] of conjunct.replace(/'[^']*'/g, '').matchAll(IDENT)) {
+        if (name === undefined || !columns.has(name)) continue;
+        if (qualifier !== undefined && qualifier !== scan.alias && qualifier !== scan.table)
+          continue;
+        if (!equality.includes(name) && !range.includes(name)) into.push(name);
+      }
+    }
+  }
+  return { equality, range: range.filter((name) => !equality.includes(name)) };
+}
+
+/** The first scan beneath `node` (the node itself included) that reads one of `tables`. */
+const scanBeneath = (node: PlanNode, tables: PlanTableColumns): PlanNode | undefined =>
+  node.table !== undefined && SCANS.has(node.type) && tables.has(node.table)
+    ? node
+    : node.children.reduce<PlanNode | undefined>(
+        (found, child) => found ?? scanBeneath(child, tables),
+        undefined,
+      );
+
+/** Physical table → its physical columns: only these tables are judged. */
+export type PlanTableColumns = ReadonlyMap<string, ReadonlySet<string>>;
+
+/**
+ * Every red node of one plan. `Seq Scan` on a judged table; an index scan with no `Index Cond`,
+ * unless a `Limit` above it stops it early and no `Filter` makes it walk on; a `Sort` under a
+ * `Limit`. A join's conditions are handed down, so the scan of its inner side names its key.
+ */
+export function judgePlan(answer: unknown, tables: PlanTableColumns): readonly PlanVerdict[] {
+  const root = nodeOf(planRoot(answer));
+  if (root === undefined) return [];
+  const verdicts: PlanVerdict[] = [];
+  const walk = (node: PlanNode, limited: boolean, inherited: readonly string[]): void => {
+    const conditions = [...inherited, ...node.conditions];
+    const columns = node.table === undefined ? undefined : tables.get(node.table);
+    if (node.table !== undefined && columns !== undefined && SCANS.has(node.type)) {
+      const unbounded = node.type === 'Seq Scan' || (!node.indexCond && (!limited || node.filter));
+      if (unbounded) {
+        const found = columnsIn(conditions, node, columns);
+        verdicts.push({
+          code: 'X_QUERY_UNINDEXED',
+          node: node.type,
+          table: node.table,
+          ...found,
+          order: [],
+        });
+      }
+    }
+    if (node.type === 'Sort' && limited) {
+      const scan = scanBeneath(node, tables);
+      const scanColumns = scan?.table === undefined ? undefined : tables.get(scan.table);
+      if (scan?.table !== undefined && scanColumns !== undefined) {
+        const found = columnsIn([...conditions, ...scan.conditions], scan, scanColumns);
+        const order = columnsIn(node.sortKey, scan, scanColumns);
+        verdicts.push({
+          code: 'X_QUERY_SORT_UNSERVED',
+          node: node.type,
+          table: scan.table,
+          equality: found.equality,
+          range: [],
+          order: [...order.equality, ...order.range],
+        });
+      }
+    }
+    const below = limited || node.type === 'Limit';
+    // A join's conditions name both sides: each child keeps only the conjuncts about itself.
+    const handed =
+      node.type.includes('Join') || node.type === 'Nested Loop' || node.type === 'Hash'
+        ? conditions
+        : [];
+    for (const child of node.children) walk(child, below, handed);
+  };
+  walk(root, false, []);
+  return verdicts;
+}

package/src/plan-sweep-fix.ts

@@ -0,0 +1,123 @@
+// From the oracle's red nodes to what an author pastes: the entity, and the `indexes: [{ on }]`
+// entry by property. Pure. Also where a red node is argued away by the declaration itself: a
+// lookup that pins a unique key reads one row whatever the planner walked to find it.
+
+import type { PlanVerdict, PlanVerdictCode } from './plan-oracle';
+import type { SeedEntity } from './seed-graph-shape';
+
+export interface PlanFinding {
+  readonly code: PlanVerdictCode;
+  /** The statement as sent, whitespace collapsed, parameters still `$n`. */
+  readonly statement: string;
+  /** `Seq Scan`, `Index Scan`, `Sort`. */
+  readonly node: string;
+  readonly entity: string;
+  readonly table: string;
+  /** The `indexes: [{ on }]` entry, by property: tenant, equality, order, range. */
+  readonly index: readonly string[];
+}
+
+/** Every column set the table holds unique: the primary key, unique columns, total unique rules. */
+function uniqueKeys(entity: SeedEntity): readonly (readonly string[])[] {
+  const description = entity.$describe();
+  return [
+    description.primaryKey,
+    ...description.columns.filter((column) => column.unique).map((column) => [column.column]),
+    ...description.indexes
+      .filter((index) => index.unique && index.where === null)
+      .map((index) => index.columns),
+    ...description.invariants
+      .filter((rule) => rule.kind === 'unique' && rule.where === null)
+      .map((rule) => rule.columns),
+  ].filter((key) => key.length > 0);
+}
+
+const IDENTIFIER = /"([A-Za-z_][\w$]*)"|\b([A-Za-z_][\w$]*)\b/g;
+
+/**
+ * A partial index the planner may use once it sees the bound value: its predicate compares only
+ * columns the statement compares by equality (`where "state" = 'pending'` against `state = $1`),
+ * and every column it holds is one the statement filters or orders by, the first among them. A
+ * generic plan cannot match a predicate to a parameter, so the oracle sees a scan; Postgres plans
+ * such a statement per value and keeps the index. Credited, never re-proven.
+ */
+function servedByPartial(entity: SeedEntity, verdict: PlanVerdict, order: readonly string[]) {
+  const description = entity.$describe();
+  const columns = new Set(description.columns.map((column) => column.column));
+  const used = new Set([...verdict.equality, ...order, ...verdict.range]);
+  return description.indexes.some((index) => {
+    if (index.where === null) return false;
+    const predicate = [...index.where.matchAll(IDENTIFIER)].flatMap(([, quoted, bare]) => {
+      const name = quoted ?? bare;
+      return name !== undefined && columns.has(name) ? [name] : [];
+    });
+    const lead = index.columns[0];
+    return (
+      predicate.length > 0 &&
+      predicate.every((column) => verdict.equality.includes(column)) &&
+      index.columns.every((column) => used.has(column)) &&
+      lead !== undefined &&
+      (verdict.equality.includes(lead) || order[0] === lead)
+    );
+  });
+}
+
+const ORDER_BY = /\border by\s+(.+?)(?:\s+limit\b|\s+offset\b|\s+for\b|$)/gi;
+
+/**
+ * The outermost `order by`'s columns, read off the text: an index walk avoids a sort and carries no
+ * sort key of its own, yet the index that ends the walk has to hold the order too.
+ */
+function orderOf(statement: string, columns: ReadonlySet<string>): readonly string[] {
+  const clauses = [...statement.matchAll(ORDER_BY)];
+  const last = clauses[clauses.length - 1]?.[1] ?? '';
+  return [...last.matchAll(IDENTIFIER)].flatMap(([, quoted, bare]) => {
+    const name = quoted ?? bare;
+    return name !== undefined && columns.has(name) ? [name] : [];
+  });
+}
+
+/**
+ * The findings one statement's verdicts make. A verdict whose equality columns pin a unique key is
+ * dropped: one row at most. A table's sort verdict makes its scan verdict redundant — the index it
+ * names leads with the same equality columns. The tenant column leads the index only when the
+ * statement compares it: a read across tenants is served by no index that leads with one.
+ */
+export function planFindings(
+  statement: string,
+  verdicts: readonly PlanVerdict[],
+  byTable: ReadonlyMap<string, SeedEntity>,
+): readonly PlanFinding[] {
+  const sorted = new Set(
+    verdicts.filter((v) => v.code === 'X_QUERY_SORT_UNSERVED').map((v) => v.table),
+  );
+  return verdicts.flatMap((verdict): PlanFinding[] => {
+    const entity = byTable.get(verdict.table);
+    if (entity === undefined) return [];
+    if (verdict.code === 'X_QUERY_UNINDEXED' && sorted.has(verdict.table)) return [];
+    const pinned = uniqueKeys(entity).some((key) =>
+      key.every((column) => verdict.equality.includes(column)),
+    );
+    if (pinned) return [];
+    const description = entity.$describe();
+    const byColumn = new Map(description.columns.map((c) => [c.column, c.property]));
+    const walked = verdict.code === 'X_QUERY_UNINDEXED' && verdict.node !== 'Seq Scan';
+    const order = walked
+      ? orderOf(statement, new Set(description.columns.map((c) => c.column)))
+      : verdict.order;
+    if (servedByPartial(entity, verdict, order)) return [];
+    const tenant = description.columns.find((c) => c.property === entity.$tenantColumn)?.column;
+    const lead = tenant !== undefined && verdict.equality.includes(tenant) ? [tenant] : [];
+    const columns = [...new Set([...lead, ...verdict.equality, ...order, ...verdict.range])];
+    return [
+      {
+        code: verdict.code,
+        statement,
+        node: verdict.node,
+        entity: entity.$name,
+        table: verdict.table,
+        index: columns.flatMap((column) => byColumn.get(column) ?? []),
+      },
+    ];
+  });
+}