@ultimat3/testing 30.5.0 → 30.7.0

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;
+}

package/src/plan-sweep-fix.ts

@@ -3,6 +3,8 @@
 // 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 { PlanUnservable } from './plan-sort-key';
+import { sortKeyPart } from './plan-sort-key';
 import type { SeedEntity } from './seed-graph-shape';
 
 export interface PlanFinding {
@@ -15,6 +17,12 @@ export interface PlanFinding {
   readonly table: string;
   /** The `indexes: [{ on }]` entry, by property: tenant, equality, order, range. */
   readonly index: readonly string[];
+  /**
+   * Why no index is the fix: a sort no declarable index serves, or `declared` — the index the node
+   * asks for is one the entity already holds, so declaring it again changes no plan. `index` is
+   * empty with it.
+   */
+  readonly unserved?: PlanUnservable | 'declared';
 }
 
 /** Every column set the table holds unique: the primary key, unique columns, total unique rules. */
@@ -110,24 +118,74 @@ function servedByPartial(entity: SeedEntity, verdict: PlanVerdict, order: readon
 
 const ORDER_BY = /\border by\s+(.+?)(?:\s+limit\b|\s+offset\b|\s+for\b|$)/gi;
 
+/** `a, f(b, c), d` → its three items: commas outside parentheses only. */
+function items(list: string): string[] {
+  const found: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let at = 0; at < list.length; at += 1) {
+    if (list[at] === '(') depth += 1;
+    else if (list[at] === ')') depth -= 1;
+    else if (list[at] === ',' && depth === 0) {
+      found.push(list.slice(start, at));
+      start = at + 1;
+    }
+  }
+  return [...found, list.slice(start)];
+}
+
 /**
- * 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.
+ * The outermost `order by`'s leading columns of the walked table, 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. Only as far as one index can: plain columns of this table, one direction — past
+ * them the rows arrive presorted and Postgres finishes with an incremental sort.
  */
-function orderOf(statement: string, columns: ReadonlySet<string>): readonly string[] {
+function orderOf(statement: string, columns: ReadonlySet<string>, verdict: PlanVerdict) {
   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] : [];
-  });
+  const order: string[] = [];
+  let way: string | undefined;
+  for (const item of items(clauses[clauses.length - 1]?.[1] ?? '')) {
+    const part = sortKeyPart(item);
+    const own =
+      part.column !== undefined &&
+      columns.has(part.column.name) &&
+      [undefined, verdict.table, verdict.alias].includes(part.column.qualifier);
+    if (!own || part.way === 'mixed' || (way !== undefined && part.way !== way)) break;
+    way = part.way;
+    if (part.column !== undefined) order.push(part.column.name);
+  }
+  return order;
+}
+
+/**
+ * An OR the read is bounded by and nothing else: one index per arm answers it, as a BitmapOr. An
+ * arm whose column leads a declared index is answered already — the sweep's settings discourage
+ * the BitmapOr, so the plan alone cannot say; credited, never re-proven.
+ */
+function armFindings(
+  verdict: PlanVerdict,
+  declared: readonly (readonly string[])[],
+  property: (column: string) => string | undefined,
+): readonly (readonly string[])[] {
+  const arms = new Map((verdict.arms ?? []).map((arm) => [arm.join('\u0000'), arm]));
+  return [...arms.values()]
+    .filter((arm) => !declared.some((key) => key[0] !== undefined && arm.includes(key[0])))
+    .map((arm) => arm.flatMap((column) => property(column) ?? []));
 }
 
+/**
+ * The plan was taken with every declared index in place: one that leads with exactly these
+ * columns is already there, and printing it as the fix would change nothing.
+ */
+const held = (keys: readonly (readonly string[])[], columns: readonly string[]): boolean =>
+  columns.length > 0 && keys.some((key) => columns.every((column, at) => key[at] === column));
+
 /**
  * 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.
+ * statement compares it: a read across tenants is served by no index that leads with one. A sort
+ * no declarable index serves, or an index the entity already holds, is red with no index to paste.
  */
 export function planFindings(
   statement: string,
@@ -145,31 +203,39 @@ export function planFindings(
       key.every((column) => verdict.equality.includes(column)),
     );
     if (pinned) return [];
+    const finding = {
+      code: verdict.code,
+      statement,
+      node: verdict.node,
+      entity: entity.$name,
+      table: verdict.table,
+    };
+    if (verdict.unservable !== undefined) {
+      return [{ ...finding, index: [], unserved: verdict.unservable }];
+    }
     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';
     // A walk filtered by a range already has its order: what it lacks is the bound. A btree serves
     // no order after a range column, so the index is the equality columns, then the range.
     const ranged = walked && verdict.range.length > 0;
-    if (ranged && servedByRange(declaredIndexes(entity, statement), verdict)) return [];
+    const declared = declaredIndexes(entity, statement);
+    const bounded = verdict.equality.length > 0 || verdict.range.length > 0;
+    if (!bounded && verdict.arms !== undefined && verdict.code === 'X_QUERY_UNINDEXED') {
+      const arms = armFindings(verdict, declared, (column) => byColumn.get(column));
+      return arms.map((index) => ({ ...finding, index }));
+    }
+    if (ranged && servedByRange(declared, verdict)) return [];
     const order = ranged
       ? []
       : walked
-        ? orderOf(statement, new Set(description.columns.map((c) => c.column)))
+        ? orderOf(statement, new Set(description.columns.map((c) => c.column)), verdict)
         : 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) ?? []),
-      },
-    ];
+    if (held(declared, columns)) return [{ ...finding, index: [], unserved: 'declared' }];
+    return [{ ...finding, index: columns.flatMap((column) => byColumn.get(column) ?? []) }];
   });
 }

package/src/plan-sweep-report.ts

@@ -4,6 +4,7 @@
 
 import { renderCauseValue, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
 import type { ExerciseRecord } from './exercise-report';
+import type { PlanUnservable } from './plan-sort-key';
 import type { PlanFinding } from './plan-sweep-fix';
 
 export interface SweepFinding {
@@ -41,7 +42,47 @@ function wholeRead(finding: PlanFinding, senders: readonly ExerciseRecord[]): Sw
   };
 }
 
+/** Why no index serves a sort, as the cause says it. */
+const UNSERVED_SORT: Readonly<Record<PlanUnservable, string>> = {
+  expression: 'an expression over its columns, and entity() declares no expression index',
+  aggregate: 'a value an aggregate or window computes, which no stored order holds',
+  derived: 'a value a subquery or CTE derives, which no index on a table holds',
+  tables: 'columns of more than one table, and one index holds one table',
+  directions: 'columns in different directions, and an index declares one order for all of them',
+};
+
+/**
+ * A red node no `indexes:` entry ends: a sort no declarable index holds, or one whose index the
+ * entity already declares. Printing an index would change no plan, so the fix is the rewrite that
+ * lets one apply, or the stated reason the rows stay few.
+ */
+function unservedRead(
+  finding: PlanFinding,
+  unserved: PlanUnservable | 'declared',
+  senders: readonly ExerciseRecord[],
+): SweepFinding {
+  const by = senders.map(primitive).join(', ');
+  const entity = renderFixLiteral(finding.entity, '<entity>');
+  const rerun = renderFixShellArg(senders[0]?.name ?? '', '<primitive>');
+  const sent = `${by} sent ${renderCauseValue(excerpt(finding.statement))}`;
+  const cause =
+    unserved === 'declared'
+      ? `${sent}, which reads ${finding.table} unbounded (${finding.node}) though entity(${entity}) already declares the index that would bound it: declaring it again changes no plan, the statement as written cannot use it`
+      : `${sent}, which sorts its rows to answer a limited read (${finding.node} under Limit) by ${UNSERVED_SORT[unserved]}: no index on ${finding.table} serves that sort, so it slows with every row the table gains`;
+  const rewrite =
+    unserved === 'declared'
+      ? "the read compares the index's leading column by = or a range, no function around it"
+      : `an order by of plain ${finding.table} columns, all one direction (the rerun names their index)`;
+  return {
+    code: finding.code,
+    cause,
+    fix: `x exercise ${rerun} --json   # after ${rewrite}, or expectedSeqScan('<why the rows stay few>', fn) around the read`,
+    at: senders[0] === undefined ? finding.entity : primitive(senders[0]),
+  };
+}
+
 function planFinding(finding: PlanFinding, senders: readonly ExerciseRecord[]): SweepFinding {
+  if (finding.unserved !== undefined) return unservedRead(finding, finding.unserved, senders);
   if (finding.index.length === 0) return wholeRead(finding, senders);
   const by = senders.map(primitive).join(', ');
   const entity = renderFixLiteral(finding.entity, '<entity>');
@@ -67,7 +108,8 @@ export function planSweepFindings(records: readonly ExerciseRecord[]): readonly
   const groups = new Map<string, { finding: PlanFinding; senders: ExerciseRecord[] }>();
   for (const record of records) {
     for (const finding of record.plans?.findings ?? []) {
-      const key = `${finding.code}\u0000${finding.table}\u0000${finding.statement}`;
+      // An OR's arms are one finding each, on one statement: the index is part of what is red.
+      const key = [finding.code, finding.table, finding.statement, ...finding.index].join('\u0000');
       const group = groups.get(key) ?? { finding, senders: [] };
       group.senders.push(record);
       groups.set(key, group);
@@ -91,9 +133,11 @@ export function planSweepFindings(records: readonly ExerciseRecord[]): readonly
 export function planSweepLines(records: readonly ExerciseRecord[]): readonly string[] {
   return records.flatMap((record) => [
     ...(record.plans?.findings ?? []).map((finding) =>
-      finding.index.length === 0
-        ? `${primitive(record)} · ${finding.code} ${finding.table}, every row (no column to index)`
-        : `${primitive(record)} · ${finding.code} ${finding.table} on [${finding.index.join(', ')}]`,
+      finding.unserved !== undefined
+        ? `${primitive(record)} · ${finding.code} ${finding.table}, no index serves it (${finding.unserved})`
+        : finding.index.length === 0
+          ? `${primitive(record)} · ${finding.code} ${finding.table}, every row (no column to index)`
+          : `${primitive(record)} · ${finding.code} ${finding.table} on [${finding.index.join(', ')}]`,
     ),
     ...(record.scale?.verdict === 'grows' ? record.scale.shapes : []).map(
       (shape) =>

package/src/seed-graph-values.ts

@@ -6,7 +6,6 @@
 import { fnv1a } from '@ultimat3/core';
 import type { ColumnMeta } from '@ultimat3/entity';
 import type * as Sample from '@ultimat3/schema/sample';
-import { patternSamples } from './seed-pattern-sample';
 
 /** A column as `entity()` declares it, structurally: this barrel never loads `@ultimat3/entity`. */
 export interface SeedColumn {
@@ -72,19 +71,11 @@ const textCandidates = (property: string, meta: ColumnMeta, ctx: ValueContext):
   return [...sized, ...fromPatterns(property, ctx)];
 };
 
-/** Strings drawn from each declared pattern, kept only where every other pattern agrees. */
-const fromPatterns = (property: string, ctx: ValueContext): string[] => {
-  const patterns = ctx.patterns ?? [];
-  return patterns
-    .flatMap((pattern) => patternSamples(pattern, `${property}:${ctx.canary}`))
-    .filter((sample) => patterns.every((pattern) => pattern.test(sample)));
-};
-
 let loadedSampler: typeof Sample | undefined;
 
 /**
- * `@ultimat3/schema/sample`, loaded on the first `json(schema)` column and never at import: this
- * module is on the barrel, and the walker is a dynamic-only dependency there (`CLAUDE.md`).
+ * `@ultimat3/schema/sample`, loaded on the first pattern or `json(schema)` column, never at import:
+ * this module is on the barrel, and the walker is a dynamic-only dependency there (`CLAUDE.md`).
  * `require` and not `import()` because every caller of `candidatesFor` is synchronous.
  */
 const sampler = (): typeof Sample => {
@@ -92,6 +83,24 @@ const sampler = (): typeof Sample => {
   return loadedSampler;
 };
 
+/**
+ * Strings drawn from each declared pattern by schema's one generator (`patternSamples`), kept only
+ * where every other pattern agrees. The text seed hashes with the pattern, so two columns differ.
+ */
+const fromPatterns = (property: string, ctx: ValueContext): string[] => {
+  const patterns = ctx.patterns ?? [];
+  if (patterns.length === 0) return [];
+  const { patternSamples } = sampler();
+  return patterns
+    .flatMap((pattern) =>
+      patternSamples(
+        pattern,
+        fnv1a(`${pattern.source}/${pattern.flags}:${property}:${ctx.canary}`) || 1,
+      ),
+    )
+    .filter((sample) => patterns.every((pattern) => pattern.test(sample)));
+};
+
 /**
  * Values the column's own schema accepts, seeded by the row so two rows differ and a rerun does
  * not; then the bare `{}`/`[]`, which a schema-less `jsonb` column stores.