@ultimat3/testing 30.6.0 → 30.7.0

package/src/exercise.ts

@@ -13,8 +13,10 @@ import type { ExerciseOverride, ExerciseOverrides } from './define-exercise';
 import { assertOverridesKnown, unknownDeclaration } from './define-exercise';
 import type { RoleGrants } from './exercise-actor';
 import { chooseActor } from './exercise-actor';
+import { seatActorUsers } from './exercise-actor-user';
 import { proveCrash } from './exercise-crash';
 import { defectDetail } from './exercise-defect';
+import { driftOverrideLine } from './exercise-drift-hint';
 import type { IdLookup, Sampler } from './exercise-input';
 import {
   bindIds,
@@ -30,6 +32,7 @@ import { overrideInput } from './exercise-override-input';
 import type {
   EffectPayload,
   ExerciseEffect,
+  ExercisePhaseMs,
   ExerciseRecord,
   ExerciseRoom,
   Observed,
@@ -61,6 +64,8 @@ export interface ExercisePassOptions {
   /** One primitive by name; unknown is `X_DECLARATION_UNKNOWN`. */
   readonly only?: string;
   readonly roles: RoleGrants;
+  /** Told once, as the pass returns: how long each phase took, so a slow pass names its slow part. */
+  readonly onPhases?: (ms: ExercisePhaseMs) => void;
 }
 
 const isOff = (overrides: ExerciseOverrides | undefined, name: string): boolean => {
@@ -110,7 +115,7 @@ interface Run {
   readonly lastInput: unknown;
 }
 
-function judged(subject: Subject, run: Run, observed: Observed) {
+function judged(subject: Subject, run: Run, observed: Observed, sampler: Sampler) {
   const idFields = (input: unknown): readonly string[] =>
     typeof input === 'object' && input !== null
       ? Object.keys(input).filter((key) => idStem(key) !== undefined)
@@ -128,7 +133,12 @@ function judged(subject: Subject, run: Run, observed: Observed) {
   }
   if (run.verdict.kind === 'pass' && run.answered) return { outcome: 'reached' as const };
   if (run.verdict.kind === 'drift') {
-    return unreached('X_CONTRACT_DRIFT', 'its input schema refused every generated value');
+    // The field no draw can fill, named: `...drawn` alone told the author nothing to write.
+    const fields = idFields(run.lastInput);
+    return {
+      ...unreached('X_CONTRACT_DRIFT', 'its input schema refused every generated value'),
+      override: driftOverrideLine(subject.name, subject.input, sampler, fields),
+    };
   }
   if (run.verdict.kind === 'defect') {
     return unreached(codeOf(run.verdict.error) ?? 'X_CONTRACT_DEFECT', run.verdict.defect);
@@ -198,7 +208,7 @@ async function control(
   const ms = Math.round(performance.now() - started);
   const observed = room.end();
   const effects = [...observed.effects, ...(await enqueued(subject, jobs))];
-  const verdictOf = judged(subject, { verdict, answered, lastError, lastInput }, observed);
+  const verdictOf = judged(subject, { verdict, answered, lastError, lastInput }, observed, sampler);
   // A 5xx's cause, statement and fields: the code alone sent the author to reproduce it by hand.
   const defect =
     verdict.kind === 'defect' && verdictOf.outcome === 'unreached'
@@ -272,10 +282,13 @@ async function exerciseOne(
   const intruder = withoutCrossTenant(
     theirs.kind === 'actor' ? seated(theirs.actor, other, rows) : null,
   );
+  // Both are users, as a request's actor always is: their `x_users` rows, before any call.
+  await seatActorUsers([actor, intruder]);
 
   const scope = { tenant, actorId: actor?.id, subject: name, actorEntity: rows?.entity.$name };
   const bindInput = overrideInput(name, override);
-  const declaredRuns = override !== undefined && 'actor' in override ? override.runs : undefined;
+  // `off` returned above: any other entry's `runs` is declared, with or without an `actor`.
+  const declaredRuns = override === undefined || 'off' in override ? undefined : override.runs;
   // A field naming the actor entity is tried as the actor's own row, then as somebody else's:
   // both readings are legitimate and only the handler knows which it meant. Same minimal draw.
   const twoWay =
@@ -311,12 +324,14 @@ async function exerciseOne(
   }
   const input = seat === undefined ? given : seat.input;
   let reachedWith: unknown;
+  const tenantStarted = performance.now();
   const record = await proveTenant({
     taint: tenantTaint(graph, tenant),
     input,
     public: publicReason(subject.policy),
     read: kind === 'query',
     sweep: kind === 'job',
+    tenantless: seat?.kind === 'none',
     attack: () => attack(subject, input, intruder, other, room),
     control: async () => {
       const done = await control(run, room, sampler);
@@ -325,10 +340,16 @@ async function exerciseOne(
     },
     snapshot: (seeded) => options.writer.snapshot(seeded),
   });
+  // The control's own call is `ms`: the tenant proof's time is everything around it.
+  const tenantMs = Math.max(0, Math.round(performance.now() - tenantStarted) - record.ms);
   // After the tenant proof, outside the room's begin/end: the crash runs' effects are their own.
-  return subject.handle === undefined || record.outcome !== 'reached'
-    ? record
-    : { ...record, crash: await proveCrash(subject.handle, reachedWith, actor) };
+  if (subject.handle === undefined || record.outcome !== 'reached') {
+    return { ...record, proofMs: { tenant: tenantMs } };
+  }
+  const crashStarted = performance.now();
+  const crash = await proveCrash(subject.handle, reachedWith, actor);
+  const proofMs = { tenant: tenantMs, crash: Math.round(performance.now() - crashStarted) };
+  return { ...record, crash, proofMs };
 }
 
 export async function runExercisePass(
@@ -349,6 +370,8 @@ export async function runExercisePass(
   const live = chosen.filter((subject) => !isOff(options.overrides, subject.name));
   const records: ExerciseRecord[] = [];
   let graph: SeedGraph;
+  const seedStarted = performance.now();
+  let primitivesStarted = seedStarted;
   try {
     // Seeded before the first primitive runs: a failure here is the pass's, never one primitive's.
     graph = await seedPass(options.entities, options.writer, {
@@ -358,6 +381,7 @@ export async function runExercisePass(
         ? {}
         : { factories: options.overrides.factories }),
     });
+    primitivesStarted = performance.now();
     // In order, one at a time: the seams the room installs are the process's, not the primitive's.
     for (const subject of chosen) {
       const index = live.indexOf(subject);
@@ -369,9 +393,11 @@ export async function runExercisePass(
     await room[Symbol.asyncDispose]();
     throw error;
   }
+  const seed = Math.round(primitivesStarted - seedStarted);
+  const primitives = Math.round(performance.now() - primitivesStarted);
   // The sweeps: every reached primitive again at two sizes, then every statement planned.
   const reached = new Set(records.filter((r) => r.outcome === 'reached').map((r) => r.name));
-  return attachSweeps(records, {
+  const swept = await attachSweeps(records, {
     subjects: chosen.filter((subject) => reached.has(subject.name)),
     entities: options.entities,
     // The sized graphs close their cycles as the pass's did: a refused deferred key stays null.
@@ -382,9 +408,13 @@ export async function runExercisePass(
     factories: options.overrides?.factories,
     setup: async (subject, sized, tenant, self) => {
       const full = chosen.find((one) => one.name === subject.name);
-      return full === undefined
-        ? undefined
-        : await sizedCall(full, options, sampler, { graph: sized, tenant, self });
+      if (full === undefined) return undefined;
+      const call = await sizedCall(full, options, sampler, { graph: sized, tenant, self });
+      // Before the sweep's room opens: the sized tenant's actor is a user too.
+      if (call !== undefined) await seatActorUsers([call.actor]);
+      return call;
     },
   });
+  options.onPhases?.({ seed, primitives, ...swept.ms });
+  return swept.records;
 }

package/src/index.ts

@@ -207,7 +207,9 @@ export type {
   EffectPayload,
   ExerciseEffect,
   ExerciseOutcome,
+  ExercisePhaseMs,
   ExerciseRecord,
+  ProofMs,
   TenantFinding,
   TenantLeg,
   TenantProof,
@@ -366,6 +368,7 @@ export {
   normalizeIslandName,
 } from './island-states-resolve';
 export { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
+export { CRASH_POINT_BOUND } from './job-crash-points';
 export type {
   CrashBoundary,
   CrashDivergence,
@@ -379,6 +382,7 @@ export type { SimEffect } from './job-sim-effects';
 export {
   crashEffectPlace,
   JobCrashDivergedError,
+  JobCrashUnboundedError,
   JobSimInvariantError,
   JobSimNondeterministicError,
 } from './job-sim-errors';

package/src/job-crash-points.ts

@@ -0,0 +1,36 @@
+// Which boundaries a crash proof kills at. A loop's steps named by row id are one point of the
+// code, not one per row: each boundary shape is killed at its first and its last occurrence, so the
+// proof costs what the job's code has, never what the database holds. Pure: labels in, indexes out.
+
+/** Kill points one mode of a proof may cost; past it the proof refuses, `X_JOB_CRASH_UNBOUNDED`. */
+export const CRASH_POINT_BOUND = 32;
+
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+/** A ULID, a hex digest, a cuid: eight or more letters and digits with a digit among them. */
+const TOKEN = /\b(?=[A-Za-z]*\d)[A-Za-z0-9]{8,}\b/g;
+const DIGITS = /\d+/g;
+
+/** `fanout:<id>`, `page-<n>`, `sleep:<n>h (sleeping)`: a boundary label with its ids taken out. */
+export const boundaryShape = (label: string): string =>
+  label.replace(UUID, '<id>').replace(TOKEN, '<id>').replace(DIGITS, '<n>');
+
+/**
+ * The 1-based positions to kill at, in order: the first and the last boundary of every shape.
+ * The first proves the code before the loop and the loop's own body; the last, every row before it
+ * replayed and the code after it — an effect between any two rows is made again at the last.
+ */
+export function crashPoints(labels: readonly string[]): readonly number[] {
+  const first = new Map<string, number>();
+  const last = new Map<string, number>();
+  labels.forEach((label, i) => {
+    const shape = boundaryShape(label);
+    if (!first.has(shape)) first.set(shape, i + 1);
+    last.set(shape, i + 1);
+  });
+  return [...new Set([...first.values(), ...last.values()])].sort((a, b) => a - b);
+}
+
+/** The distinct shapes of `labels`, first seen first — what an unbounded refusal names. */
+export const boundaryShapes = (labels: readonly string[]): readonly string[] => [
+  ...new Set(labels.map(boundaryShape)),
+];

package/src/job-crash-proof.ts

@@ -1,6 +1,6 @@
-// `crashProof(handle, input)`: one clean run, then one run killed at each boundary the clean run
-// crossed — every step write landing, every settle — and one more where that write's answer is
-// lost. Judged by the effect log: a killed run that makes an effect more often than the clean one
+// `crashProof(handle, input)`: one clean run, then one run killed at each distinct boundary the
+// clean run crossed — a step write landing, a settle; a loop's rows one point (`job-crash-points.ts`)
+// — and one more where that write's answer is lost. Judged by the effect log: a killed run that makes an effect more often than the clean one
 // is `X_JOB_CRASH_DIVERGED`; a lost answer rerunning a step is at-least-once, reported, never red.
 
 import type { Ctx } from '@ultimat3/core';
@@ -8,11 +8,12 @@ import { finiteCount } from '@ultimat3/core';
 import type { JobHandle } from '@ultimat3/jobs';
 import { COMPENSATE_PREFIX, UNWINDING_STEP } from '@ultimat3/jobs';
 import { advanceClock, frozenNow } from './determinism';
+import { boundaryShapes, CRASH_POINT_BOUND, crashPoints } from './job-crash-points';
 import type { SimDecision, SimOp } from './job-sim-driver';
 import { SEND_AND_ANSWER } from './job-sim-driver';
 import type { SimEffect } from './job-sim-effects';
 import { effectCounts } from './job-sim-effects';
-import { JobCrashDivergedError } from './job-sim-errors';
+import { JobCrashDivergedError, JobCrashUnboundedError } from './job-sim-errors';
 import type { SimWorld } from './job-sim-world';
 import { openSimWorld } from './job-sim-world';
 
@@ -47,7 +48,10 @@ export interface CrashRerun {
 }
 
 export interface CrashReport {
+  /** The boundaries killed at: each distinct one the clean run crossed, a loop's rows as one. */
   readonly boundaries: readonly CrashBoundary[];
+  /** Every boundary the clean run crossed, the forced-fail run's included: what the kills stand for. */
+  readonly crossed: number;
   readonly divergences: readonly CrashDivergence[];
   readonly reruns: readonly CrashRerun[];
 }
@@ -212,6 +216,7 @@ export async function crashProof<I>(
   const boundaries: CrashBoundary[] = [];
   const divergences: CrashDivergence[] = [];
   const reruns: CrashRerun[] = [];
+  let crossed = 0;
   const modes: readonly CrashBoundary['mode'][] = handle.compensates
     ? ['clean', 'forced-fail']
     : ['clean'];
@@ -228,7 +233,19 @@ export async function crashProof<I>(
         : await runOnce(handle, input, { forceFail }, options);
     const afterOf = (key: string): string | undefined =>
       clean.effects.find((effect) => effect.key === key)?.after;
-    for (let at = 1; at <= clean.boundaries.length; at += 1) {
+    // Judged before the first kill: a proof past its bound costs one clean run, then refuses.
+    const points = crashPoints(clean.boundaries);
+    crossed += clean.boundaries.length;
+    if (points.length > CRASH_POINT_BOUND) {
+      throw new JobCrashUnboundedError({
+        job: handle.name,
+        points: points.length,
+        bound: CRASH_POINT_BOUND,
+        crossed: clean.boundaries.length,
+        shapes: boundaryShapes(clean.boundaries),
+      });
+    }
+    for (const at of points) {
       const label = clean.boundaries[at - 1] ?? '?';
       const killed = await runOnce(handle, input, { at, fault: 'kill', forceFail }, options);
       boundaries.push({
@@ -272,5 +289,5 @@ export async function crashProof<I>(
       }
     }
   }
-  return { boundaries, divergences, reruns };
+  return { boundaries, crossed, divergences, reruns };
 }

package/src/job-sim-errors.ts

@@ -101,3 +101,27 @@ export class JobSimNondeterministicError extends UltimateError {
     });
   }
 }
+
+export interface CrashUnboundedInput {
+  readonly job: string;
+  /** Kill points the clean run's boundaries asked for, after a loop's rows were taken as one. */
+  readonly points: number;
+  readonly bound: number;
+  /** Boundaries the clean run crossed. */
+  readonly crossed: number;
+  /** The first distinct boundary shapes, in order: where the names that did not collapse are. */
+  readonly shapes: readonly string[];
+}
+
+/** Refused before the first kill: a proof that grows with the rows is one no gate can wait for. */
+export class JobCrashUnboundedError extends UltimateError {
+  constructor(input: CrashUnboundedInput) {
+    const shown = input.shapes.slice(0, 5).join(', ');
+    super({
+      code: 'X_JOB_CRASH_UNBOUNDED',
+      cause: `job ${renderCauseValue(input.job)} crossed ${input.crossed} step boundaries, ${input.points} distinct kill points against a bound of ${input.bound} — its steps are named so a loop's rows do not read as one point (first: ${renderCauseValue(shown)})`,
+      fix: `step.run(\`<name>:\${row.id}\`, async () => …)   # in job(${renderFixLiteral(input.job, '<job>')}): name a per-row step by the row's id, so its loop is one kill point; then: x test job --filter <the test file>`,
+      meta: { ...input, shapes: [...input.shapes] },
+    });
+  }
+}

package/src/plan-conditions.ts

@@ -0,0 +1,106 @@
+// A plan node's conditions, read as the columns one scanned table compares: by equality, by any
+// other way, and per arm of an OR. An OR is served by one index per arm (a BitmapOr), never by one
+// index over every column it names, so its arms are kept apart from the conjuncts around it.
+
+/** The scan whose columns are read: its table and the alias the plan qualifies it by. */
+export interface ConditionScan {
+  readonly table: string | undefined;
+  readonly alias: string | undefined;
+}
+
+export interface ConditionColumns {
+  readonly equality: string[];
+  readonly range: string[];
+  /** The first OR whose every arm compares a column of the table: each arm's columns. */
+  readonly arms?: readonly (readonly string[])[];
+}
+
+const IDENT = /(?:"?([A-Za-z_][\w$]*)"?\.)?"?([A-Za-z_][\w$]*)"?/g;
+const EQUALITY = /(?<![<>!])=(?!>)/;
+/** `IS NULL` pins one value as `=` does, and a btree serves it as an index condition. */
+const IS_NULL = /\bIS\s+NULL\b/i;
+
+/** The parts of `text` between `word`s that stand outside every parenthesis and literal. */
+function splitTop(text: string, word: 'AND' | 'OR'): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  for (let at = 0; at < text.length; at += 1) {
+    const char = text[at];
+    if (char === "'") quoted = !quoted;
+    if (quoted) continue;
+    if (char === '(') depth += 1;
+    else if (char === ')') depth -= 1;
+    else if (depth === 0 && text.startsWith(` ${word} `, at)) {
+      parts.push(text.slice(start, at));
+      start = at + word.length + 2;
+      at = start - 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts.map(unwrap);
+}
+
+/** `((a = $1))` → `a = $1`: parentheses that wrap the whole text, and only those. */
+function unwrap(text: string): string {
+  let rest = text.trim();
+  for (;;) {
+    if (!rest.startsWith('(') || !rest.endsWith(')')) return rest;
+    let depth = 0;
+    for (let at = 0; at < rest.length; at += 1) {
+      if (rest[at] === '(') depth += 1;
+      else if (rest[at] === ')') depth -= 1;
+      if (depth === 0 && at < rest.length - 1) return rest;
+    }
+    rest = rest.slice(1, -1).trim();
+  }
+}
+
+/** The columns of the table a conjunct names; a name qualified by another alias is not its. */
+function namesIn(conjunct: string, scan: ConditionScan, columns: ReadonlySet<string>): string[] {
+  const names: string[] = [];
+  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 (!names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The columns of `scan` the conditions name, split by how they are compared: `=` and `IS NULL`
+ * are equality, anything else a range. A conjunct qualified by another alias is a join's other
+ * side; an unqualified name counts when the table has the column. An OR is no conjunct of either.
+ */
+export function columnsIn(
+  conditions: readonly string[],
+  scan: ConditionScan,
+  columns: ReadonlySet<string>,
+): ConditionColumns {
+  const equality: string[] = [];
+  const range: string[] = [];
+  let arms: string[][] | undefined;
+  for (const condition of conditions) {
+    for (const conjunct of splitTop(unwrap(condition), 'AND')) {
+      const alternatives = splitTop(conjunct, 'OR');
+      if (alternatives.length > 1) {
+        const each = alternatives.map((arm) => {
+          const found = columnsIn([arm], scan, columns);
+          return [...found.equality, ...found.range];
+        });
+        if (arms === undefined && each.every((arm) => arm.length > 0)) arms = each;
+        continue;
+      }
+      const into = EQUALITY.test(conjunct) || IS_NULL.test(conjunct) ? equality : range;
+      for (const name of namesIn(conjunct, scan, columns)) {
+        if (!equality.includes(name) && !range.includes(name)) into.push(name);
+      }
+    }
+  }
+  return {
+    equality,
+    range: range.filter((name) => !equality.includes(name)),
+    ...(arms === undefined ? {} : { arms }),
+  };
+}

package/src/plan-oracle.ts

@@ -3,6 +3,10 @@
 // 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).
 
+import { columnsIn } from './plan-conditions';
+import type { PlanUnservable, SortKeyRef } from './plan-sort-key';
+import { sortKeyPart, sortUnservable } from './plan-sort-key';
+
 /** 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';
 
@@ -16,8 +20,14 @@ export interface PlanVerdict {
   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. */
+  /** The sort's columns on that table, in order. Empty for a scan, or a sort no index serves. */
   readonly order: readonly string[];
+  /** A sort no declarable index serves: why (`plan-sort-key.ts`). */
+  readonly unservable?: PlanUnservable;
+  /** The arms of an OR the read is bounded by, each its columns: one index answers each arm. */
+  readonly arms?: readonly (readonly string[])[];
+  /** The alias the plan reads the table by, when it is not the table's own name. */
+  readonly alias?: string;
 }
 
 interface PlanNode {
@@ -70,46 +80,63 @@ export function planRoot(answer: unknown): unknown {
   return record(first)?.['Plan'] ?? first;
 }
 
-const IDENT = /(?:"?([A-Za-z_][\w$]*)"?\.)?"?([A-Za-z_][\w$]*)"?/g;
-const EQUALITY = /(?<![<>!])=(?!>)/;
-/** `IS NULL` pins one value as `=` does, and a btree serves it as an index condition. */
-const IS_NULL = /\bIS\s+NULL\b/i;
+/** Every scan beneath `node` (the node itself included), of any table. */
+const scansBeneath = (node: PlanNode): readonly PlanNode[] => [
+  ...(node.table !== undefined && SCANS.has(node.type) ? [node] : []),
+  ...node.children.flatMap(scansBeneath),
+];
+
+/** Nodes that compute what is sorted: past one, the sort key is no table's stored order. */
+const COMPUTED: ReadonlySet<string> = new Set(['Aggregate', 'WindowAgg', 'Group']);
+const computedBeneath = (node: PlanNode): boolean =>
+  node.children.some((child) => COMPUTED.has(child.type) || computedBeneath(child));
 
 /**
- * The columns of `scan` a condition names, split by how they are compared: `=` and `IS NULL` are
- * equality, anything else a range. A conjunct qualified by
- * another alias is a join's other side; an unqualified name counts when the table has the column.
+ * The verdict of a `Sort` under a `Limit`. It belongs to the table its key names — a join lists
+ * its other side first, and that side's columns are not what is sorted. A key no index can hold
+ * still names a table, with no order to index; a key on a table the sweep does not judge (a
+ * declared `scan:`, a framework table) is that table's, and no verdict.
  */
-function columnsIn(
+function sortVerdict(
+  node: PlanNode,
   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) || IS_NULL.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)) };
+  tables: PlanTableColumns,
+): PlanVerdict | undefined {
+  const scans = scansBeneath(node);
+  const judged = scans.filter((scan) => scan.table !== undefined && tables.has(scan.table));
+  const scanOf = (ref: SortKeyRef): PlanNode | undefined =>
+    scans.find((scan) =>
+      ref.qualifier === undefined
+        ? scan.table !== undefined && tables.get(scan.table)?.has(ref.name) === true
+        : ref.qualifier === scan.alias || ref.qualifier === scan.table,
+    );
+  const parts = node.sortKey.map(sortKeyPart);
+  const owners = parts.flatMap((part) => part.refs).flatMap((ref) => scanOf(ref) ?? []);
+  const owner = owners[0];
+  if (owner?.table !== undefined && !tables.has(owner.table)) return undefined;
+  const scan = owner ?? judged[0];
+  const columns = scan?.table === undefined ? undefined : tables.get(scan.table);
+  if (scan?.table === undefined || columns === undefined) return undefined;
+  const plainUnowned = parts.some((part) => part.column && scanOf(part.column) === undefined);
+  const unservable: PlanUnservable | undefined =
+    parts.some((part) => part.column === undefined) && computedBeneath(node)
+      ? 'aggregate'
+      : plainUnowned
+        ? 'derived'
+        : sortUnservable(parts, (ref) => scanOf(ref)?.table);
+  const found = columnsIn([...conditions, ...scan.conditions], scan, columns);
+  const order = columnsIn(node.sortKey, scan, columns);
+  return {
+    code: 'X_QUERY_SORT_UNSERVED',
+    node: node.type,
+    table: scan.table,
+    equality: found.equality,
+    range: [],
+    order: unservable === undefined ? [...order.equality, ...order.range] : [],
+    ...(unservable === undefined ? {} : { unservable }),
+  };
 }
 
-/** 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>>;
 
@@ -135,24 +162,13 @@ export function judgePlan(answer: unknown, tables: PlanTableColumns): readonly P
           table: node.table,
           ...found,
           order: [],
+          ...(node.alias === undefined || node.alias === node.table ? {} : { alias: node.alias }),
         });
       }
     }
     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 sorted = sortVerdict(node, conditions, tables);
+      if (sorted !== undefined) verdicts.push(sorted);
     }
     const below = limited || node.type === 'Limit';
     // A join's conditions name both sides: each child keeps only the conjuncts about itself.

package/src/plan-sort-key.ts

@@ -0,0 +1,65 @@
+// A Sort node's key, read as an index would have to hold it: which table each part belongs to,
+// whether it is a plain column, and which way it runs. An index serves a sort only when every part
+// is a plain column of ONE table, all running one way — anything else no `indexes:` entry ends.
+
+/**
+ * Why no index an entity declares can serve a sort: its key is an expression (`entity()` declares
+ * no expression index), a value an aggregate or window computed, a value a subquery derived, the
+ * columns of more than one table, or columns running in different directions.
+ */
+export type PlanUnservable = 'expression' | 'aggregate' | 'derived' | 'tables' | 'directions';
+
+/** A column a sort key names, as the plan prints it: `p.created_at`, or `title` alone. */
+export interface SortKeyRef {
+  readonly qualifier: string | undefined;
+  readonly name: string;
+}
+
+export interface SortKeyPart {
+  /** The column, when the part is one column and nothing else. */
+  readonly column: SortKeyRef | undefined;
+  /** Every column the part names: the expression's too. */
+  readonly refs: readonly SortKeyRef[];
+  /** `up` is an ascending walk (nulls last), `down` the same walk backwards; `mixed` is neither. */
+  readonly way: 'up' | 'down' | 'mixed';
+}
+
+const NAME = '"?([A-Za-z_][\\w$]*)"?';
+const PLAIN = new RegExp(`^(?:${NAME}\\.)?${NAME}$`);
+const REF = new RegExp(`(?:${NAME}\\.)?${NAME}`, 'g');
+
+/**
+ * One part of a `Sort Key`. Postgres prints `DESC` and a `NULLS` that differs from the direction's
+ * default; ascending nulls last and descending nulls first are the two walks of one btree.
+ */
+export function sortKeyPart(key: string): SortKeyPart {
+  let rest = key.trim();
+  const nulls = /\s+NULLS\s+(FIRST|LAST)$/i.exec(rest);
+  if (nulls !== null) rest = rest.slice(0, nulls.index);
+  const desc = /\s+DESC$/i.test(rest);
+  rest = rest.replace(/\s+(?:DESC|ASC)$/i, '');
+  const nullsFirst = nulls === null ? desc : nulls[1]?.toUpperCase() === 'FIRST';
+  const way = desc === nullsFirst ? (desc ? 'down' : 'up') : 'mixed';
+  const plain = PLAIN.exec(rest);
+  const refs = [...rest.replace(/'[^']*'/g, '').matchAll(REF)].flatMap(([, qualifier, name]) =>
+    name === undefined ? [] : [{ qualifier, name }],
+  );
+  const column = plain?.[2] === undefined ? undefined : { qualifier: plain[1], name: plain[2] };
+  return { column, refs, way };
+}
+
+/**
+ * Why an index cannot serve these parts, given the table each column belongs to (`undefined` for
+ * one the judged tables do not hold), or `undefined` when one index on one table could.
+ */
+export function sortUnservable(
+  parts: readonly SortKeyPart[],
+  tableOf: (ref: SortKeyRef) => string | undefined,
+): PlanUnservable | undefined {
+  if (parts.some((part) => part.column === undefined)) return 'expression';
+  const tables = new Set(parts.flatMap((part) => (part.column ? [tableOf(part.column)] : [])));
+  if (tables.size > 1) return 'tables';
+  const ways = new Set(parts.map((part) => part.way));
+  if (ways.has('mixed') || ways.size > 1) return 'directions';
+  return undefined;
+}