@ultimat3/testing 30.6.0 → 30.7.0

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.

package/src/seed-graph.ts

@@ -63,6 +63,33 @@ function ownedByTenant(
   return owned;
 }
 
+/**
+ * Every untenanted entity (`shared`, or of no tenant) a tenant-owned table points at through a key
+ * unique across the TABLE — a unique set holding the reference and not the tenant column. Each
+ * tenant's children then take parent rows no other tenant may reuse, so the parent seeds
+ * `perTable` rows per tenant: `perTable` alone ran out before tenant 2 (`X_SEED_GRAPH_UNSATISFIED`).
+ */
+function fannedOut(
+  shapes: ReadonlyMap<string, EntityShape>,
+  scoped: (name: string) => boolean,
+): ReadonlySet<string> {
+  const out = new Set<string>();
+  for (const shape of shapes.values()) {
+    if (!scoped(shape.name)) continue;
+    const tenantColumn = shape.entity.$tenantColumn;
+    const tableWide = [...shape.uniques, ...shape.partialUniques].filter(
+      (set) => tenantColumn === null || !set.includes(tenantColumn),
+    );
+    for (const reference of shape.references.values()) {
+      if (scoped(reference.targetEntity) || reference.targetEntity === shape.name) continue;
+      if (tableWide.some((set) => set.includes(reference.property))) {
+        out.add(reference.targetEntity);
+      }
+    }
+  }
+  return out;
+}
+
 export function seedGraph(
   entities: Readonly<Record<string, SeedEntity>>,
   options: SeedGraphOptions = {},
@@ -108,6 +135,7 @@ export function seedGraph(
   }
   const owned = ownedByTenant(shapes, roots);
   const scoped = (name: string): boolean => owned.has(name);
+  const fanned = fannedOut(shapes, scoped);
   for (const factory of Object.values(options.factories ?? {})) factory.reset();
 
   const placed = new Map<string, Placed[]>();
@@ -170,7 +198,8 @@ export function seedGraph(
     const buckets: readonly (string | null)[] = scoped(name) ? tenants : [null];
     let ordinal = 0;
     for (const [bucket, tenant] of buckets.entries()) {
-      const size = rootProperty === undefined ? perTable : 1;
+      const size =
+        rootProperty !== undefined ? 1 : fanned.has(name) ? perTable * tenantCount : perTable;
       for (let index = 0; index < size; index += 1) {
         ordinal += 1;
         const canary = stream().replace(/-/g, '').slice(0, 10);

package/src/tenant-proof-report.ts

@@ -34,10 +34,19 @@ export function tenantFindingLines(records: readonly ExerciseRecord[]): readonly
   );
 }
 
+/**
+ * B sends A's own first input, A's ids bound in only where it takes any: `{ occurrenceMs }` carries
+ * none, and B still crosses when a statement it ran names no tenant. Both readings, always.
+ */
 const causeOf = (record: ExerciseRecord, finding: TenantFinding): string =>
   finding.code === 'X_TENANT_LEAK'
-    ? `${record.kind} ${record.name}, called by tenant B with tenant A's ids ${LEG[finding.leg]}, handed back A's seeded data at ${where(finding)}: a read reached A's row by an id the caller chose, past the tenant guard`
-    : `${record.kind} ${record.name}, called by tenant B with tenant A's ids ${LEG[finding.leg]}, changed A's ${where(finding)}: a write reached A's row by an id the caller chose, past the tenant guard`;
+    ? `${record.kind} ${record.name}, called by tenant B with A's own input ${LEG[finding.leg]}, handed back A's seeded data at ${where(finding)}: a read reached A's row past the tenant guard — by an id the caller chose, or by a statement no tenant predicate scopes`
+    : `${record.kind} ${record.name}, called by tenant B with A's own input ${LEG[finding.leg]}, changed A's ${where(finding)}: a write reached A's row past the tenant guard — by an id the caller chose, or by a statement no tenant predicate scopes`;
+
+const fixOf = (name: string, finding: TenantFinding): string =>
+  finding.code === 'X_TENANT_LEAK'
+    ? `x exercise ${name} --json — then read the row behind ${where(finding)} through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement`
+    : `x exercise ${name} --json — then write ${where(finding)} through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement`;
 
 /**
  * One coded finding per tenant finding. The fix reruns the one primitive: what it reads or writes
@@ -54,7 +63,7 @@ export function tenantProofFindings(
       (finding): TenantProofFinding => ({
         code: finding.code,
         cause: causeOf(record, finding),
-        fix: `x exercise ${name} --json — then read ${finding.code === 'X_TENANT_LEAK' ? 'the row behind ' : ''}${where(finding)} through the repository scoped to ctx.actor, never by the input id alone`,
+        fix: fixOf(name, finding),
         at: `${record.kind} ${record.name}`,
       }),
     );

package/src/tenant-proof.ts

@@ -79,6 +79,12 @@ export interface TenantAttack {
    * half is skipped. An action or a query answers B directly, so a declared scope excuses nothing.
    */
   readonly sweep: boolean;
+  /**
+   * A job declaring `tenant: 'none'` (`bindJobTenant`'s `none`): no org reaches its run. Handed
+   * nothing of A's, B's run is A's run — what it writes to A's rows it writes for every enqueuer,
+   * so the write half's premise, B choosing A's row, cannot hold: skipped (`tenantlessReason`).
+   */
+  readonly tenantless: boolean;
   attack(leg: TenantLeg): Promise<LegAnswer>;
   /** A's positive control: today's exercise of the primitive, and what A's last answer was. */
   control(): Promise<{ readonly record: ExerciseRecord; readonly output: unknown }>;
@@ -129,11 +135,25 @@ export function sweepReason(
   return `crossTenant(${JSON.stringify(reason)}) declares this job reads across tenants, and B's input named nothing of A's: read half skipped, write half kept`;
 }
 
+/**
+ * The reason the write half is skipped, or `undefined`: a `tenant: 'none'` job whose input carries
+ * none of A's marks — no org and no id of B's choosing reaches the run. Handed one of A's ids, B
+ * chose A's row and the write half stands. An action or a query runs as B's actor, so B's org
+ * reaches it: a write to A's row with no id handed is an unscoped statement, crossed as ever.
+ */
+export function tenantlessReason(
+  plan: Pick<TenantAttack, 'tenantless' | 'taint'>,
+  hunted: readonly string[],
+): string | undefined {
+  if (!plan.tenantless || hunted.length !== plan.taint.marks.length) return undefined;
+  return "tenant: 'none' runs this job under no org, and B's input named nothing of A's: B's run is A's run, so what it writes it writes for every enqueuer — write half skipped, read half kept";
+}
+
 const verdictOf = (
   plan: TenantAttack,
   control: { readonly record: ExerciseRecord; readonly output: unknown },
   findings: readonly TenantFinding[],
-  swept: string | undefined,
+  skipped: readonly string[],
 ): TenantProof => {
   const { record } = control;
   if (findings.length > 0) return { verdict: 'crossed', findings };
@@ -144,7 +164,7 @@ const verdictOf = (
     };
   }
   if (plan.public !== undefined) return { verdict: 'public', reason: plan.public };
-  if (swept !== undefined) return { verdict: 'public', reason: swept };
+  if (skipped.length > 0) return { verdict: 'public', reason: skipped.join('; ') };
   // Every mark of A's, handed ones included: A was handed its own ids, and reading them is the point.
   if (plan.read && findTaint(control.output, 'output', plan.taint.marks).length === 0) {
     return {
@@ -159,12 +179,19 @@ const verdictOf = (
 export async function proveTenant(plan: TenantAttack): Promise<ExerciseRecord> {
   const marks = huntedMarks(plan.taint, plan.input);
   const findings: TenantFinding[] = [];
+  const unwritten = tenantlessReason(plan, marks);
   let swept: string | undefined;
-  const leg = async (name: TenantLeg): Promise<void> => {
+  /** B's call, between two snapshots unless the write half is skipped: then none is read. */
+  const watched = async (name: TenantLeg): Promise<LegAnswer> => {
+    if (unwritten !== undefined) return plan.attack(name);
     const before = await plan.snapshot(plan.taint.rows);
     const answer = await plan.attack(name);
     const after = await plan.snapshot(plan.taint.rows);
     findings.push(...crossedWrites(name, plan.taint, before, after));
+    return answer;
+  };
+  const leg = async (name: TenantLeg): Promise<void> => {
+    const answer = await watched(name);
     if (plan.public !== undefined) return;
     const sweep = sweepReason(plan, answer, marks);
     if (sweep === undefined) findings.push(...leaksIn(name, answer, marks));
@@ -173,5 +200,6 @@ export async function proveTenant(plan: TenantAttack): Promise<ExerciseRecord> {
   await leg('before');
   const control = await plan.control();
   await leg('after');
-  return { ...control.record, tenant: verdictOf(plan, control, findings, swept) };
+  const skipped = [swept, unwritten].filter((reason) => reason !== undefined);
+  return { ...control.record, tenant: verdictOf(plan, control, findings, skipped) };
 }