@ultimat3/testing 29.4.0 → 30.0.0

package/src/seed-graph-pass.ts

@@ -0,0 +1,68 @@
+// The seed graph an exercise pass writes: ONE graph for the whole pass, so a tenantless table
+// (`plans`) is seeded once and every primitive's tenants reference those rows, and each primitive
+// owns a fresh tenant pair of its own. One graph also means one set of unique keys: per-primitive
+// graphs re-inserted the shared rows and collided on their primary keys.
+
+import { isUltimateError, renderThrowable } from '@ultimat3/core';
+import { seedGraph } from './seed-graph';
+import { seedGraphUnsatisfied } from './seed-graph-error';
+import type { SeedGraph, SeedRow, SeedUpdate, SeedWriter } from './seed-graph-plan';
+import { insertSeedGraph } from './seed-graph-plan';
+import type { SeedEntity } from './seed-graph-shape';
+
+/** Tenants per primitive: the actor's own, and a second the tenant proof reads across. */
+export const TENANTS_PER_PRIMITIVE = 2;
+
+/**
+ * The database refused a row the graph generated: a rule the declaration does not carry (a
+ * trigger, a hand-written CHECK). The row is the app's to describe, so the factory is the fix.
+ * Anything else coded — `X_SEAL_KEY_MISSING`, `X_DB_UNAVAILABLE` — keeps its own code and fix.
+ */
+const ROW_REFUSALS: ReadonlySet<string> = new Set([
+  'X_DB_UNIQUE_VIOLATION',
+  'X_DB_FOREIGN_KEY_VIOLATION',
+  'X_DB_STATEMENT_FAILED',
+]);
+
+const refused = (write: SeedRow | SeedUpdate, error: unknown): unknown => {
+  if (isUltimateError(error) && !ROW_REFUSALS.has(error.code)) return error;
+  const why = isUltimateError(error) ? `${error.code}: ${error.cause}` : renderThrowable(error);
+  return seedGraphUnsatisfied({
+    entity: write.entity,
+    what: `the database refused a generated row — ${why}`,
+    columns: [],
+  });
+};
+
+/** Every write coded: a row refusal names its factory, an environment failure keeps its own fix. */
+const coded = (writer: SeedWriter): SeedWriter => ({
+  insert: (row) =>
+    writer.insert(row).catch((error: unknown) => Promise.reject(refused(row, error))),
+  update: (update) =>
+    writer.update(update).catch((error: unknown) => Promise.reject(refused(update, error))),
+  // A read, not a write: nothing a database refuses here is the generated row's fault.
+  snapshot: (rows) => writer.snapshot(rows),
+});
+
+/** The tenant pair primitive `index` (0-based, in run order) acts in. */
+export const tenantPair = (graph: SeedGraph, index: number): readonly [string, string] => [
+  graph.tenants[index * TENANTS_PER_PRIMITIVE] as string,
+  graph.tenants[index * TENANTS_PER_PRIMITIVE + 1] as string,
+];
+
+/**
+ * Plan and write the pass's graph: shared rows once, `TENANTS_PER_PRIMITIVE` tenants per
+ * primitive. Same seed, same rows. Before any primitive runs, so a failure refuses the pass.
+ */
+export async function seedPass(
+  entities: readonly SeedEntity[],
+  writer: SeedWriter,
+  options: { readonly primitives: number; readonly seed: number },
+): Promise<SeedGraph> {
+  const graph = seedGraph(Object.fromEntries(entities.map((entity) => [entity.$name, entity])), {
+    tenants: Math.max(1, options.primitives) * TENANTS_PER_PRIMITIVE,
+    seed: options.seed,
+  });
+  await insertSeedGraph(graph, coded(writer));
+  return graph;
+}

package/src/seed-graph-plan.ts

@@ -0,0 +1,81 @@
+// The plan `seedGraph` returns and the one way it is written: every insert in order, then every
+// key a cycle deferred. Data only, so a caller can diff two plans, print one, or hand it to a
+// writer over any driver — the graph itself never touches a database.
+
+/** A factory the app wrote, structurally: what it builds wins over anything generated. */
+export interface SeedFactory {
+  build(): object;
+  reset(): void;
+}
+
+export interface SeedGraphOptions {
+  /** Tenants to seed, each with its own copy of every tenant-scoped table. Default 2. */
+  readonly tenants?: number;
+  /** Rows per table, per tenant for a tenant-scoped one. Default 3. */
+  readonly perTable?: number;
+  readonly seed?: number;
+  /** By entity name. A column the factory builds takes its value; keys stay the graph's. */
+  readonly factories?: Readonly<Record<string, SeedFactory>>;
+}
+
+export interface SeedRow {
+  readonly entity: string;
+  readonly table: string;
+  /**
+   * The tenant instance the row belongs to: its tenant column's, the root row's own, or — for a
+   * child with no tenant column and no `shared` reason — the tenant of the parent it hangs off.
+   * `null` only for a row of no tenant. The tenant proof's per-instance id list is this field.
+   */
+  readonly tenant: string | null;
+  /** As INSERTED: a key deferred to break a cycle is null here and set by an update. */
+  readonly row: Readonly<Record<string, unknown>>;
+}
+
+export interface SeedUpdate {
+  readonly entity: string;
+  readonly tenant: string | null;
+  /** The row's primary key, by property. */
+  readonly key: Readonly<Record<string, unknown>>;
+  readonly patch: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * One per row: the marker its text columns carry, so a later read can say whose row it saw. One
+ * marker per ROW, every text column carrying it: a find names the path, the row is the marker's.
+ * A column whose format cannot hold it (uuid, enum, a short char) is absent from `columns`.
+ */
+export interface SeedCanary {
+  readonly entity: string;
+  readonly tenant: string | null;
+  readonly key: Readonly<Record<string, unknown>>;
+  readonly marker: string;
+  readonly columns: readonly string[];
+}
+
+export interface SeedGraph {
+  readonly seed: number;
+  readonly tenants: readonly string[];
+  readonly order: readonly string[];
+  readonly inserts: readonly SeedRow[];
+  readonly updates: readonly SeedUpdate[];
+  /** One per insert, in the same order: `canaries[i]` is `inserts[i]`'s. */
+  readonly canaries: readonly SeedCanary[];
+}
+
+/** Where `insertSeedGraph` writes. One insert per row, in order, then one update per deferred key. */
+export interface SeedWriter {
+  insert(row: SeedRow): Promise<void>;
+  update(update: SeedUpdate): Promise<void>;
+  /**
+   * Each row read back by its primary key, as one digest per row in the order given — `null` for
+   * a row no longer there. Equal digests mean an unchanged row; the tenant proof's write half
+   * compares two snapshots. Soft-deleted rows are read too, so a soft delete is a change.
+   */
+  snapshot(rows: readonly SeedRow[]): Promise<readonly (string | null)[]>;
+}
+
+/** Writes the plan in order: every insert, then every deferred key. Sequential, so it replays. */
+export async function insertSeedGraph(graph: SeedGraph, writer: SeedWriter): Promise<void> {
+  for (const row of graph.inserts) await writer.insert(row);
+  for (const update of graph.updates) await writer.update(update);
+}

package/src/seed-graph-row.ts

@@ -0,0 +1,134 @@
+// One row of a seed graph, solved: every column has an ordered candidate list, and the first
+// combination that keeps every declared rule (the entity's invariants, its keys and unique columns)
+// wins. Only the columns a broken rule reads are varied, so the search stays a handful of tries.
+
+export interface RowCheck {
+  readonly name: string;
+  /** The properties the rule reads — the only columns worth varying when it breaks. */
+  readonly properties: readonly string[];
+  holds(row: Readonly<Record<string, unknown>>): boolean;
+}
+
+export interface RowProblem {
+  /** In declaration order; every list non-empty, first entry the most plausible. */
+  readonly columns: readonly (readonly [string, readonly unknown[]])[];
+  readonly checks: readonly RowCheck[];
+  /** Property sets no two rows of the table may share: the key, unique columns, unique rules. */
+  readonly uniques: readonly (readonly string[])[];
+  /** Per entry of `uniques`, the keys earlier rows already hold. */
+  readonly taken: readonly ReadonlySet<string>[];
+}
+
+export type RowSolution =
+  | { readonly ok: true; readonly row: Readonly<Record<string, unknown>> }
+  | {
+      readonly ok: false;
+      /** The rules the most plausible row breaks, by name. */
+      readonly broken: readonly string[];
+      readonly properties: readonly string[];
+      /** Only uniqueness is out of reach: the table is full, not unsatisfiable. */
+      readonly capacity: boolean;
+    };
+
+/** Past this many tries a rule is reported, not searched: the answer is a factory, not patience. */
+const MAX_TRIES = 4096;
+const ROUNDS = 3;
+
+/** `undefined` when any part is null: Postgres never compares two NULLs equal in a unique key. */
+export const uniqueKey = (
+  row: Readonly<Record<string, unknown>>,
+  properties: readonly string[],
+): string | undefined => {
+  // Own properties only: a column named `constructor` must not read the prototype's.
+  const parts = properties.map((property) =>
+    Object.hasOwn(row, property) ? row[property] : undefined,
+  );
+  return parts.some((part) => part === null || part === undefined)
+    ? undefined
+    : JSON.stringify(parts);
+};
+
+interface Broken {
+  readonly names: readonly string[];
+  readonly properties: ReadonlySet<string>;
+}
+
+const brokenBy = (problem: RowProblem, row: Record<string, unknown>, unique: boolean): Broken => {
+  const names: string[] = [];
+  const properties = new Set<string>();
+  for (const check of problem.checks) {
+    if (check.holds(row)) continue;
+    names.push(check.name);
+    for (const property of check.properties) properties.add(property);
+  }
+  if (unique) {
+    problem.uniques.forEach((set, index) => {
+      const key = uniqueKey(row, set);
+      if (key === undefined || problem.taken[index]?.has(key) !== true) return;
+      names.push(`unique (${set.join(', ')})`);
+      for (const property of set) properties.add(property);
+    });
+  }
+  return { names, properties };
+};
+
+const build = (problem: RowProblem, picks: readonly number[]): Record<string, unknown> => {
+  const row: Record<string, unknown> = {};
+  problem.columns.forEach(([property, candidates], index) => {
+    row[property] = candidates[picks[index] ?? 0];
+  });
+  return row;
+};
+
+/** Odometer over the varied columns, last one fastest: deterministic and exhaustive up to the cap. */
+function* combinations(problem: RowProblem, vary: readonly number[]): Generator<number[]> {
+  const picks = problem.columns.map(() => 0);
+  for (let tries = 0; tries < MAX_TRIES; tries += 1) {
+    yield [...picks];
+    let slot = vary.length - 1;
+    for (; slot >= 0; slot -= 1) {
+      const column = vary[slot] as number;
+      const size = problem.columns[column]?.[1].length ?? 1;
+      picks[column] = ((picks[column] ?? 0) + 1) % size;
+      if (picks[column] !== 0) break;
+    }
+    if (slot < 0) return;
+  }
+}
+
+const search = (problem: RowProblem, unique: boolean): RowSolution => {
+  const zero = problem.columns.map(() => 0);
+  const first = brokenBy(problem, build(problem, zero), unique);
+  const failed: RowSolution = {
+    ok: false,
+    broken: first.names,
+    properties: [...first.properties],
+    capacity: false,
+  };
+  if (first.names.length === 0) return { ok: true, row: build(problem, zero) };
+  const variable = (properties: ReadonlySet<string>): number[] =>
+    problem.columns.flatMap(([property, candidates], index) =>
+      properties.has(property) && candidates.length > 1 ? [index] : [],
+    );
+  let wanted = new Set(first.properties);
+  for (let round = 0; round < ROUNDS; round += 1) {
+    const vary = variable(wanted);
+    const grown = new Set(wanted);
+    for (const picks of combinations(problem, vary)) {
+      const row = build(problem, picks);
+      const broken = brokenBy(problem, row, unique);
+      if (broken.names.length === 0) return { ok: true, row };
+      for (const property of broken.properties) grown.add(property);
+    }
+    if (variable(grown).length === vary.length) return failed;
+    wanted = grown;
+  }
+  return failed;
+};
+
+/** The first row that keeps every rule; failing that, whether only uniqueness stood in the way. */
+export function solveRow(problem: RowProblem): RowSolution {
+  const found = search(problem, true);
+  if (found.ok) return found;
+  return search(problem, false).ok ? { ...found, capacity: true } : found;
+}

package/src/seed-graph-shape.ts

@@ -0,0 +1,104 @@
+// What the seed graph reads off one entity, structurally — the value `entity()` returns, with no
+// runtime import of `@ultimat3/entity` (this barrel must not load its registry). The rules a row
+// must keep come from the entity's own declaration: invariants, key, unique columns and indexes.
+
+import type { EntityDescription, Invariant, ReferenceDescription } from '@ultimat3/entity';
+import type { RowCheck } from './seed-graph-row';
+import type { SeedColumn } from './seed-graph-values';
+
+/** The members of `entity()`'s value a seed graph reads. A real entity satisfies it as is. */
+export interface SeedEntity {
+  readonly $name: string;
+  readonly $table: string;
+  readonly $columns: Readonly<Record<string, SeedColumn>>;
+  /** Property keys. */
+  readonly $primaryKey: readonly string[];
+  readonly $tenantColumn: string | null;
+  readonly $invariants: readonly Invariant<unknown>[];
+  $describe(): EntityDescription;
+  $references(): readonly ReferenceDescription[];
+}
+
+export interface EntityShape {
+  readonly entity: SeedEntity;
+  readonly name: string;
+  readonly columns: readonly (readonly [string, SeedColumn])[];
+  readonly references: ReadonlyMap<string, ReferenceDescription>;
+  readonly checks: readonly RowCheck[];
+  readonly uniques: readonly (readonly string[])[];
+  /**
+   * The soft-delete property, or `null`. Seeded null unless a factory builds it: a row born deleted
+   * is invisible to every read.
+   */
+  readonly softDelete: string | null;
+}
+
+/**
+ * `@ultimat3/entity`'s `SOFT_DELETE_COLUMN`, restated because this module type-imports entity only.
+ * `seed-graph.test.ts` holds the two equal, so a rename there fails here.
+ */
+export const SEED_SOFT_DELETE_PROPERTY = 'deletedAt';
+
+/** Physical column -> property. A money property owns all of its physical columns. */
+const propertiesByColumn = (entity: SeedEntity): ReadonlyMap<string, string> => {
+  const map = new Map<string, string>();
+  const declared = Object.keys(entity.$columns);
+  for (const column of entity.$describe().columns) {
+    const owner = declared.includes(column.property)
+      ? column.property
+      : declared.find(
+          (property) =>
+            entity.$columns[property]?.$meta.kind === 'money' &&
+            column.property.startsWith(property),
+        );
+    if (owner !== undefined) map.set(column.column, owner);
+  }
+  return map;
+};
+
+const dedupe = (sets: readonly (readonly string[])[]): readonly (readonly string[])[] => {
+  const seen = new Set<string>();
+  return sets.filter((set) => {
+    const key = [...set].sort().join('\u0000');
+    if (set.length === 0 || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+
+export function shapeOf(entity: SeedEntity): EntityShape {
+  const byColumn = propertiesByColumn(entity);
+  const toProperties = (columns: readonly string[]): readonly string[] =>
+    columns.flatMap((column) => {
+      const property = byColumn.get(column);
+      return property === undefined ? [] : [property];
+    });
+  const description = entity.$describe();
+  const checks = entity.$invariants
+    .filter((invariant) => invariant.kind !== 'unique')
+    .map(
+      (invariant): RowCheck => ({
+        name: invariant.name,
+        properties: toProperties(invariant.columns),
+        holds: (row) => invariant.holds(row),
+      }),
+    );
+  // A partial unique (`where`) is treated as total: stricter than the table, never looser.
+  const uniques = dedupe([
+    entity.$primaryKey,
+    ...description.columns.filter((column) => column.unique).map((c) => toProperties([c.column])),
+    ...entity.$invariants
+      .filter((invariant) => invariant.kind === 'unique')
+      .map((invariant) => toProperties(invariant.columns)),
+    ...description.indexes.filter((index) => index.unique).map((i) => toProperties(i.columns)),
+  ]);
+  return {
+    entity,
+    name: entity.$name,
+    columns: Object.entries(entity.$columns),
+    references: new Map(entity.$references().map((reference) => [reference.property, reference])),
+    checks,
+    uniques,
+    softDelete: description.softDelete ? SEED_SOFT_DELETE_PROPERTY : null,
+  };
+}

package/src/seed-graph-values.ts

@@ -0,0 +1,135 @@
+// A value for one column, read off the column's own declaration — its kind, nullability, enumerated
+// values, length, money parts and default — never off its name. Every candidate is run through the
+// column's `$parse`, which refuses exactly what its CHECK refuses, so what survives is storable.
+
+import type { ColumnMeta } from '@ultimat3/entity';
+
+/** A column as `entity()` declares it, structurally: this barrel never loads `@ultimat3/entity`. */
+export interface SeedColumn {
+  readonly $meta: ColumnMeta;
+  $parse(value: unknown): unknown;
+}
+
+/** What one row lends every column it generates: its place, its canary and its id stream. */
+export interface ValueContext {
+  /** 1-based and unique per table, so a value derived from it is unique per table. */
+  readonly ordinal: number;
+  /** The row's canary: lower-case hex, so it survives a slug or a handle pattern. */
+  readonly canary: string;
+  /** Declaration position of the column, so two instants on one row are ordered as declared. */
+  readonly position: number;
+  uuid(): string;
+}
+
+/** Fixed, never `Date.now()`: the same seed must produce the same bytes on any day. */
+const BASE_INSTANT = Date.UTC(2026, 0, 1);
+const HOUR = 3_600_000;
+const MINUTE = 60_000;
+
+/** ISO-4217 codes a money column is offered, in order; a rule pairing it with an enum picks one. */
+const CURRENCIES = ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD'] as const;
+
+export const isSeedColumn = (value: unknown): value is SeedColumn =>
+  typeof value === 'object' &&
+  value !== null &&
+  '$meta' in value &&
+  typeof value.$meta === 'object' &&
+  value.$meta !== null &&
+  '$parse' in value &&
+  typeof value.$parse === 'function';
+
+const rotate = <T>(values: readonly T[], by: number): readonly T[] =>
+  values.length === 0 ? values : values.map((_, i) => values[(i + by) % values.length] as T);
+
+/**
+ * Shapes, not guesses: the declared rule (a pattern, `contains('@')`) picks among them, and the
+ * property only makes the value readable. Each carries the canary, so each is unique per row.
+ */
+const textCandidates = (property: string, meta: ColumnMeta, ctx: ValueContext): unknown[] => {
+  const word = property.toLowerCase().replace(/[^a-z0-9]/g, '') || 'value';
+  const kebab = property
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '');
+  const shapes = [
+    `${kebab || word}-${ctx.canary}`,
+    `${word}${ctx.canary}`,
+    `${word}_${ctx.canary}`,
+    `${word}.${ctx.canary}@seed.test`,
+    `https://seed.test/${word}/${ctx.canary}`,
+    ctx.canary,
+  ];
+  return meta.length === undefined ? shapes : [...shapes, ctx.canary.slice(0, meta.length)];
+};
+
+const byKind = (property: string, meta: ColumnMeta, ctx: ValueContext): unknown[] => {
+  const n = ctx.ordinal;
+  if (meta.values !== undefined) return [...rotate(meta.values, n - 1)];
+  switch (meta.kind) {
+    case 'uuid':
+      return [ctx.uuid()];
+    case 'text':
+    case 'char':
+      return textCandidates(property, meta, ctx);
+    case 'boolean':
+      return [false, true];
+    case 'integer':
+      return [n, 1, 0];
+    case 'bigint':
+      return [String(n), '1', '0'];
+    case 'numeric':
+      return [String(n), '1', '0'];
+    case 'timestamptz':
+      return [new Date(BASE_INSTANT + n * HOUR + ctx.position * MINUTE)];
+    case 'date':
+      return [`2026-01-${String((n % 28) + 1).padStart(2, '0')}`];
+    case 'jsonb':
+      return [{}, []];
+    case 'bytea':
+      return [new Uint8Array([n % 256])];
+    case 'array':
+      return [[]];
+    case 'money':
+      return CURRENCIES.map((currency) => ({ minor: n * 100, currency }));
+  }
+};
+
+const parsed = (column: SeedColumn, value: unknown): { readonly ok: unknown } | undefined => {
+  try {
+    return { ok: column.$parse(value) };
+  } catch {
+    // A refusal is the answer "not this one": the next candidate is tried, and an empty list is
+    // the caller's X_SEED_GRAPH_UNSATISFIED.
+    return undefined;
+  }
+};
+
+/**
+ * Every storable value for this column, most plausible first: the declared default, then what the
+ * kind offers, then `null` when the column allows it. Empty means nothing generated is storable.
+ */
+export function candidatesFor(
+  property: string,
+  column: SeedColumn,
+  ctx: ValueContext,
+): readonly unknown[] {
+  const meta = column.$meta;
+  const declared = meta.default?.kind === 'value' ? [meta.default.value] : [];
+  const raw = [...declared, ...byKind(property, meta, ctx), ...(meta.notNull ? [] : [null])];
+  const out: unknown[] = [];
+  for (const value of raw) {
+    const result = parsed(column, value);
+    if (result !== undefined && !out.some((seen) => Bun.deepEquals(seen, result.ok))) {
+      out.push(result.ok);
+    }
+  }
+  return out;
+}
+
+/** Candidates offered verbatim (a factory's value), kept only where the column stores them. */
+export function storable(column: SeedColumn, values: readonly unknown[]): readonly unknown[] {
+  return values.flatMap((value) => {
+    const result = parsed(column, value);
+    return result === undefined ? [] : [result.ok];
+  });
+}