@ultimat3/testing 29.3.2 → 30.0.0

package/src/seed-graph.ts

@@ -0,0 +1,250 @@
+// `seedGraph(entities, { tenants, perTable, seed })`: rows for every table, in an order every foreign
+// key accepts, each child pointing at a parent of its OWN tenant, every value storable and every
+// declared rule kept. Pure: it returns the plan, `insertSeedGraph` writes it. Same seed, same bytes.
+
+import { finiteCount, finiteOption, fnv1a } from '@ultimat3/core';
+import type { ReferenceDescription } from '@ultimat3/entity';
+import { DEFAULT_SEED, seededUuid } from './determinism';
+import { seedGraphUnsatisfied } from './seed-graph-error';
+import { edgeKey, insertOrder } from './seed-graph-order';
+import type {
+  SeedCanary,
+  SeedGraph,
+  SeedGraphOptions,
+  SeedRow,
+  SeedUpdate,
+} from './seed-graph-plan';
+import { type RowProblem, solveRow, uniqueKey } from './seed-graph-row';
+import { type EntityShape, type SeedEntity, shapeOf } from './seed-graph-shape';
+import { candidatesFor, storable } from './seed-graph-values';
+
+interface Placed {
+  readonly tenant: string | null;
+  readonly row: Record<string, unknown>;
+  readonly index: number;
+}
+
+const streamSeed = (seed: number, name: string): number => fnv1a(`${seed}:${name}`) || 1;
+
+const rotate = <T>(values: readonly T[], by: number): T[] =>
+  values.map((_, i) => values[(i + by) % values.length] as T);
+
+const keyOf = (entity: SeedEntity, row: Readonly<Record<string, unknown>>) =>
+  Object.fromEntries(entity.$primaryKey.map((property) => [property, row[property]]));
+
+/**
+ * Every entity whose rows belong to one tenant: a tenant column, a tenant root, or — with neither —
+ * a reference path to one that is not cut by `shared`. The last kind is seeded per tenant under
+ * its own tenant's parent, so the tenant proof has a row of each instance to attack it through.
+ */
+function ownedByTenant(
+  shapes: ReadonlyMap<string, EntityShape>,
+  roots: ReadonlyMap<string, string>,
+): ReadonlySet<string> {
+  const owned = new Set<string>();
+  for (const shape of shapes.values()) {
+    if (roots.has(shape.name) || shape.entity.$tenantColumn !== null) owned.add(shape.name);
+  }
+  // A fixpoint over references: a grandchild is owned through its owned child.
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const shape of shapes.values()) {
+      if (owned.has(shape.name) || shape.entity.$describe().shared !== undefined) continue;
+      const reaches = [...shape.references.values()].some(
+        (reference) => reference.targetEntity !== shape.name && owned.has(reference.targetEntity),
+      );
+      if (reaches) {
+        owned.add(shape.name);
+        grew = true;
+      }
+    }
+  }
+  return owned;
+}
+
+export function seedGraph(
+  entities: Readonly<Record<string, SeedEntity>>,
+  options: SeedGraphOptions = {},
+): SeedGraph {
+  const seed = finiteOption('seedGraph', 'seed', options.seed ?? DEFAULT_SEED);
+  const tenantCount = finiteCount('seedGraph', 'tenants', options.tenants ?? 2, 1);
+  const perTable = finiteCount('seedGraph', 'perTable', options.perTable ?? 3, 1);
+  // A view entity is a relation Postgres derives: no row is ever written to it, so it is no part of
+  // the graph (`X_ENTITY_VIEW_READ_ONLY` otherwise) — the tables it reads from carry the rows. A
+  // history table is the same from this side: its trigger writes every row, from the parent's.
+  const tables = Object.values(entities).filter((entity) => {
+    const described = entity.$describe();
+    return described.view === undefined && described.historyOf === undefined;
+  });
+  const shapes = new Map(tables.map((entity) => [entity.$name, shapeOf(entity)]));
+  const { order, deferred } = insertOrder(
+    [...shapes.values()].map((shape) => ({
+      name: shape.name,
+      references: [...shape.references.values()],
+    })),
+  );
+  const tenantStream = seededUuid(streamSeed(seed, '$tenants'));
+  const tenants = Array.from({ length: tenantCount }, () => tenantStream());
+  // The entity a tenant column points at holds ONE row per tenant, keyed by the tenant itself.
+  const roots = new Map<string, string>();
+  for (const shape of shapes.values()) {
+    const tenantColumn = shape.entity.$tenantColumn;
+    const reference = tenantColumn === null ? undefined : shape.references.get(tenantColumn);
+    if (reference !== undefined && reference.targetEntity !== shape.name) {
+      roots.set(reference.targetEntity, reference.targetProperty);
+    }
+  }
+  const owned = ownedByTenant(shapes, roots);
+  const scoped = (name: string): boolean => owned.has(name);
+  for (const factory of Object.values(options.factories ?? {})) factory.reset();
+
+  const placed = new Map<string, Placed[]>();
+  const parentValues = (
+    reference: ReferenceDescription,
+    tenant: string | null,
+    index: number,
+  ): unknown[] => {
+    if (!shapes.has(reference.targetEntity)) return reference.nullable ? [null] : [];
+    const pool = (placed.get(reference.targetEntity) ?? []).filter(
+      (parent) => tenant === null || !scoped(reference.targetEntity) || parent.tenant === tenant,
+    );
+    const values =
+      pool.length === 0 ? [] : rotate(pool, index).map((p) => p.row[reference.targetProperty]);
+    return reference.nullable ? [...values, null] : values;
+  };
+  const refuseEmpty = (shape: EntityShape, property: string, tenant: string | null): never => {
+    const reference = shape.references.get(property);
+    throw seedGraphUnsatisfied({
+      entity: shape.name,
+      what:
+        reference === undefined
+          ? `no generated value is storable in ${property} — its column refuses every one`
+          : !shapes.has(reference.targetEntity)
+            ? `${property} references ${reference.targetEntity}, which is not in the set seeded — pass it too`
+            : `${property} references ${reference.targetEntity}, which has no row${tenant === null ? '' : ' in the same tenant'} to point at`,
+      columns: [property],
+    });
+  };
+
+  const inserts: SeedRow[] = [];
+  const canaries: SeedCanary[] = [];
+  for (const name of order) {
+    const shape = shapes.get(name) as EntityShape;
+    const entity = shape.entity;
+    const stream = seededUuid(streamSeed(seed, name));
+    const factory = options.factories?.[name];
+    const rows: Placed[] = [];
+    placed.set(name, rows);
+    const taken = shape.uniques.map(() => new Set<string>());
+    const rootProperty = roots.get(name);
+    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;
+      for (let index = 0; index < size; index += 1) {
+        ordinal += 1;
+        const canary = stream().replace(/-/g, '').slice(0, 10);
+        const built: Readonly<Record<string, unknown>> =
+          factory === undefined ? {} : { ...factory.build() };
+        const columns = shape.columns.map(([property, column], position) => {
+          const reference = shape.references.get(property);
+          // The tenant key points at a root row only when the root is in the set: refused like any
+          // other reference to an entity this graph does not seed.
+          const candidates =
+            property === entity.$tenantColumn &&
+            reference !== undefined &&
+            !shapes.has(reference.targetEntity)
+              ? []
+              : property === entity.$tenantColumn || property === rootProperty
+                ? [tenant]
+                : property === shape.softDelete && !Object.hasOwn(built, property)
+                  ? [null]
+                  : reference !== undefined
+                    ? deferred.has(edgeKey(name, property))
+                      ? [null]
+                      : parentValues(reference, tenant, index)
+                    : Object.hasOwn(built, property)
+                      ? storable(column, [built[property]])
+                      : candidatesFor(property, column, {
+                          ordinal,
+                          canary,
+                          position,
+                          uuid: stream,
+                        });
+          return [
+            property,
+            candidates.length === 0 ? refuseEmpty(shape, property, tenant) : candidates,
+          ] as const;
+        });
+        const problem: RowProblem = {
+          columns,
+          checks: shape.checks,
+          uniques: shape.uniques,
+          taken,
+        };
+        const solved = solveRow(problem);
+        if (!solved.ok) {
+          // A table whose unique values run out is full, not broken — as long as EVERY tenant holds a
+          // row: a tenant left empty would leave its own children no parent to point at.
+          if (solved.capacity && index > 0) break;
+          throw seedGraphUnsatisfied({
+            entity: name,
+            what:
+              solved.capacity && rows.length > 0
+                ? `${solved.broken.join(', ')} runs out of values before tenant ${bucket + 1} of ${buckets.length} holds a row — it is unique across the table, not per tenant`
+                : `no generated row keeps ${solved.broken.join(', ')}`,
+            columns: solved.properties,
+          });
+        }
+        const row = { ...solved.row };
+        shape.uniques.forEach((set, i) => {
+          const key = uniqueKey(row, set);
+          if (key !== undefined) taken[i]?.add(key);
+        });
+        rows.push({ tenant, row, index });
+        inserts.push({ entity: name, table: entity.$table, tenant, row: { ...row } });
+        canaries.push({
+          entity: name,
+          tenant,
+          key: keyOf(entity, row),
+          marker: canary,
+          columns: Object.keys(row).filter(
+            (p) => typeof row[p] === 'string' && String(row[p]).includes(canary),
+          ),
+        });
+      }
+    }
+  }
+
+  const updates: SeedUpdate[] = [];
+  for (const name of order) {
+    const shape = shapes.get(name) as EntityShape;
+    const later = shape.columns.filter(([property]) => deferred.has(edgeKey(name, property)));
+    if (later.length === 0) continue;
+    for (const { tenant, row, index } of placed.get(name) ?? []) {
+      const columns = shape.columns.map(([property]) => {
+        const reference = shape.references.get(property);
+        return reference !== undefined && deferred.has(edgeKey(name, property))
+          ? ([property, parentValues(reference, tenant, index)] as const)
+          : ([property, [row[property]]] as const);
+      });
+      const solved = solveRow({ columns, checks: shape.checks, uniques: [], taken: [] });
+      if (!solved.ok) {
+        throw seedGraphUnsatisfied({
+          entity: name,
+          what: `the key set after insert to close a cycle breaks ${solved.broken.join(', ')}`,
+          columns: solved.properties,
+        });
+      }
+      const patch = Object.fromEntries(
+        later.flatMap(([property]) =>
+          solved.row[property] === null ? [] : [[property, solved.row[property]]],
+        ),
+      );
+      if (Object.keys(patch).length === 0) continue;
+      Object.assign(row, patch);
+      updates.push({ entity: name, tenant, key: keyOf(shape.entity, row), patch });
+    }
+  }
+  return { seed, tenants, order, inserts, updates, canaries };
+}

package/src/seed-writer.ts

@@ -0,0 +1,180 @@
+// `entitySeedWriter`: the `SeedWriter` that writes a seed graph through each entity's own
+// repository, so a seed takes the same writes the app makes — Postgres through a pinned client, or
+// the driver the app reads through (memory, `testDriver()`). It reads rows back too, as digests by
+// primary key: the tenant proof's write half (`snapshot`).
+//
+// `@ultimat3/entity` loads on the first write, never on import: this module is on the barrel, and
+// the barrel stays entity-free.
+
+import type { DbClient, SqlFragment } from '@ultimat3/db';
+import { identifier, join, sql } from '@ultimat3/db';
+import type { Driver, EntityCore, Repo } from '@ultimat3/entity';
+import { SeedGraphEntityUnknownError } from './seed-graph-error';
+import type { SeedRow, SeedUpdate, SeedWriter } from './seed-graph-plan';
+
+type SeedRepo = Repo<Record<string, unknown>>;
+
+/** Stable text for one row: keys sorted, an instant as ISO, bytes as hex — never insertion order. */
+const stable = (value: unknown): unknown => {
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Uint8Array) {
+    return Array.from(value, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  }
+  if (typeof value === 'bigint') return value.toString();
+  if (Array.isArray(value)) return value.map(stable);
+  if (typeof value !== 'object' || value === null) return value;
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(
+    Object.keys(record)
+      .sort()
+      .map((key) => [key, stable(record[key])]),
+  );
+};
+
+const digestRow = (row: unknown): string =>
+  new Bun.CryptoHasher('md5').update(JSON.stringify(stable(row))).digest('hex');
+
+/** The physical columns of an entity's primary key, in key order. */
+const keyColumns = (entity: EntityCore): readonly string[] => {
+  const columns = entity.$describe().columns;
+  return entity.$primaryKey.map(
+    (property) => columns.find((column) => column.property === property)?.column ?? property,
+  );
+};
+
+/**
+ * `md5(t::text)` per row, by primary key, through the client — the whole stored row, columns no
+ * entity declares included. One statement per table for a one-column key, one per row for a
+ * composite one. Unscoped on purpose: the question is whether the row changed, not who may read it.
+ */
+async function snapshotOnClient(
+  client: DbClient,
+  rows: readonly SeedRow[],
+  entities: readonly EntityCore[],
+): Promise<readonly (string | null)[]> {
+  const out: (string | null)[] = rows.map(() => null);
+  const byEntity = new Map<EntityCore, number[]>();
+  entities.forEach((entity, i) => {
+    byEntity.set(entity, [...(byEntity.get(entity) ?? []), i]);
+  });
+  for (const [entity, indexes] of byEntity) {
+    const table = identifier(entity.$table);
+    const columns = keyColumns(entity);
+    const keyAt = (i: number, at: number) => String(rows[i]?.row[entity.$primaryKey[at] as string]);
+    const [single] = columns;
+    if (columns.length === 1 && single !== undefined) {
+      const key = identifier(single);
+      const found = await client.query<{ k: string; h: string }>(
+        sql`select ${key}::text as k, md5(t::text) as h from ${table} t where ${key}::text = any(${indexes.map((i) => keyAt(i, 0))}::text[])`,
+      );
+      const digests = new Map(found.map((one) => [one.k, one.h]));
+      for (const i of indexes) out[i] = digests.get(keyAt(i, 0)) ?? null;
+      continue;
+    }
+    for (const i of indexes) {
+      const terms: SqlFragment[] = columns.map(
+        (column, at) => sql`${identifier(column)}::text = ${keyAt(i, at)}`,
+      );
+      const one = await client.one<{ h: string }>(
+        sql`select md5(t::text) as h from ${table} t where ${join(terms, ' and ')}`,
+      );
+      out[i] = one?.h ?? null;
+    }
+  }
+  return out;
+}
+
+/** Where the rows go. One or the other, never both: two answers to one question is a compile error. */
+export type SeedWriterTarget =
+  /** Postgres (or PGlite) through this client: `postgresRepo(entity, { client })`. */
+  | { readonly client: DbClient; readonly driver?: never }
+  /** This driver's repositories. Left out: `defaultDriver()`, the one `database()` names by default. */
+  | { readonly driver?: Driver; readonly client?: never };
+
+export type EntitySeedWriterOptions = SeedWriterTarget & {
+  /** The set the plan came from — the same object handed to `seedGraph`. Keyed by anything. */
+  readonly entities: Readonly<Record<string, EntityCore>>;
+  /**
+   * The `orgId` a write runs under. Default: the row's seeded tenant on a tenant-scoped entity, and
+   * none on a tenantless one (a tenant root such as `orgs` carries its tenant but no tenant column).
+   */
+  readonly tenantOf?: (write: SeedRow | SeedUpdate) => string | undefined;
+};
+
+export function entitySeedWriter(options: EntitySeedWriterOptions): SeedWriter {
+  const byName = new Map(Object.values(options.entities).map((one) => [one.$name, one]));
+  const repos = new Map<string, SeedRepo>();
+  let resolve: Promise<(entity: EntityCore) => SeedRepo> | undefined;
+
+  const resolver = async (): Promise<(entity: EntityCore) => SeedRepo> => {
+    const { defaultDriver, postgresRepo } = await import('@ultimat3/entity');
+    const { client } = options;
+    if (client !== undefined) {
+      return (entity) => postgresRepo(entity as EntityCore<Record<string, unknown>>, { client });
+    }
+    const driver = options.driver ?? defaultDriver();
+    return (entity) => driver.repo(entity as EntityCore<Record<string, unknown>>);
+  };
+
+  const repoFor = async (name: string): Promise<{ entity: EntityCore; repo: SeedRepo }> => {
+    const entity = byName.get(name);
+    if (entity === undefined) {
+      throw new SeedGraphEntityUnknownError({ entity: name, known: [...byName.keys()].sort() });
+    }
+    resolve ??= resolver();
+    const make = await resolve;
+    let repo = repos.get(name);
+    if (repo === undefined) {
+      repo = make(entity);
+      repos.set(name, repo);
+    }
+    return { entity, repo };
+  };
+
+  const scope = (entity: EntityCore, write: SeedRow | SeedUpdate): { orgId?: string } => {
+    const orgId =
+      options.tenantOf !== undefined
+        ? options.tenantOf(write)
+        : entity.$tenantColumn === null
+          ? undefined
+          : (write.tenant ?? undefined);
+    return orgId === undefined ? {} : { orgId };
+  };
+
+  return {
+    async insert(row) {
+      const { entity, repo } = await repoFor(row.entity);
+      await repo.insert({ ...row.row }, scope(entity, row));
+    },
+    async update(update) {
+      const { entity, repo } = await repoFor(update.entity);
+      await repo.updateWhere({ ...update.key }, { ...update.patch }, scope(entity, update));
+    },
+    async snapshot(rows) {
+      const entities = await Promise.all(
+        rows.map(async (row) => (await repoFor(row.entity)).entity),
+      );
+      // Postgres hashes the whole stored row (`md5(t::text)`), columns no entity declares included.
+      if (options.client !== undefined) return snapshotOnClient(options.client, rows, entities);
+      return Promise.all(
+        rows.map(async (row, i) => {
+          const entity = entities[i] as EntityCore;
+          const { repo } = await repoFor(row.entity);
+          const where = entity.$primaryKey.map((property) => ({
+            column: property,
+            op: 'eq' as const,
+            value: row.row[property],
+          }));
+          const page = await repo.findMany({
+            where,
+            limit: 1,
+            includeDeleted: true,
+            ...scope(entity, row),
+          });
+          const found = page.rows[0];
+          return found === undefined ? null : digestRow(found);
+        }),
+      );
+    },
+  };
+}

package/src/subject-proof-error.ts

@@ -0,0 +1,23 @@
+// `X_SUBJECT_ERASE_INCOMPLETE`: the subject proof found the person's seeded value after the erase.
+// Apart from ./errors, which owns the code, its title and the one registration, because that
+// catalogue is at its ceiling. Names the table and the column, never the value.
+
+import { renderFixLiteral, UltimateError } from '@ultimat3/core';
+import './errors';
+
+export class SubjectEraseIncompleteError extends UltimateError {
+  constructor(input: {
+    readonly subject: string;
+    readonly table: string;
+    readonly column: string;
+    readonly what: string;
+  }) {
+    const table = renderFixLiteral(input.table, '<table>');
+    super({
+      code: 'X_SUBJECT_ERASE_INCOMPLETE',
+      cause: `after subjectErase of one ${input.subject}, ${input.table}.${input.column} ${input.what}: the table is untreated, an anonymize left this column, or it holds a copy of the value with no key to the subject`,
+      fix: `x exercise --json   # after tables: { ${table}: 'delete' } (or anonymize: { ${input.column}: <value> }) in defineSubject(${input.subject}, …) — or columns: { ${table}: '<column holding the key>' } for a copy with no foreign key`,
+      meta: { subject: input.subject, table: input.table, column: input.column },
+    });
+  }
+}

package/src/subject-proof.ts

@@ -0,0 +1,180 @@
+// `subjectProof(subject)`: the subject erase PROVED on generated data. Seed every table with
+// canaries, pick one person, run the erase's table passes as a worker in that person's tenant,
+// then search every table's stored rows for that person's canaries and deleted keys. Anything
+// left outside a declared `retain` is `X_SUBJECT_ERASE_INCOMPLETE`, naming the table and column.
+
+import type { UltimateError } from '@ultimat3/core';
+import { ctxOf, finiteOption, runWithContext, serviceActor } from '@ultimat3/core';
+import type { Subject, SubjectPlan } from '@ultimat3/jobs';
+import { memoryStepStore, planSubject, stepRunner, subjectEraseTables } from '@ultimat3/jobs';
+import { seedGraph } from './seed-graph';
+import type { SeedGraph, SeedWriter } from './seed-graph-plan';
+import { insertSeedGraph } from './seed-graph-plan';
+import type { SeedEntity } from './seed-graph-shape';
+import { SubjectEraseIncompleteError } from './subject-proof-error';
+
+type Stored = Readonly<Record<string, unknown>>;
+
+export interface SubjectProofOptions {
+  /** Every entity to seed and search — the same set `seedGraph` takes. */
+  readonly entities: readonly SeedEntity[];
+  readonly writer: SeedWriter;
+  /** Every stored row of one table, as the database holds it, unscoped. */
+  readonly read: (entity: SeedEntity) => Promise<readonly Stored[]>;
+  readonly seed?: number;
+}
+
+export interface SubjectProofResult {
+  readonly subject: string;
+  /** The person erased, by key; absent when the plan refused before a row was seeded. */
+  readonly key?: string;
+  readonly problems: readonly UltimateError[];
+}
+
+interface Reached {
+  readonly entity: string;
+  readonly row: Stored;
+  readonly marker: string | undefined;
+}
+
+const ownKey = (entity: string, row: Stored, primaryKey: readonly string[]): string =>
+  `${entity}|${JSON.stringify(primaryKey.map((property) => row[property]))}`;
+
+/** The seeded rows of the person, table by table, walked as the plan walks them: parents first. */
+function reachedRows(
+  graph: SeedGraph,
+  plan: SubjectPlan,
+  entities: ReadonlyMap<string, SeedEntity>,
+  subjectRow: Stored,
+) {
+  const markers = new Map<string, string>();
+  graph.inserts.forEach((insert, i) => {
+    const entity = entities.get(insert.entity);
+    const marker = graph.canaries[i]?.marker;
+    if (entity !== undefined && marker !== undefined) {
+      markers.set(ownKey(insert.entity, insert.row, entity.$primaryKey), marker);
+    }
+  });
+  const rowsOf = (entity: string) =>
+    graph.inserts.filter((i) => i.entity === entity).map((i) => i.row);
+  const selected = new Map<string, readonly Stored[]>([[plan.subject, [subjectRow]]]);
+  for (const step of [...plan.steps].reverse()) {
+    if (step.entity === plan.subject) continue;
+    selected.set(
+      step.entity,
+      rowsOf(step.entity).filter((row) =>
+        step.via.some((via) =>
+          (selected.get(via.parent) ?? []).some(
+            (parent) => parent[via.parentKey] === row[via.property],
+          ),
+        ),
+      ),
+    );
+  }
+  const reached: Reached[] = [];
+  for (const [entity, rows] of selected) {
+    const core = entities.get(entity);
+    for (const row of rows) {
+      reached.push({
+        entity,
+        row,
+        marker: core === undefined ? undefined : markers.get(ownKey(entity, row, core.$primaryKey)),
+      });
+    }
+  }
+  return reached;
+}
+
+const asText = (value: unknown): string =>
+  typeof value === 'string' ? value : (JSON.stringify(value) ?? '');
+
+const physical = (entity: SeedEntity, property: string): string =>
+  entity.$describe().columns.find((column) => column.property === property)?.column ?? property;
+
+export async function subjectProof<I>(
+  subject: Subject<I>,
+  options: SubjectProofOptions,
+): Promise<SubjectProofResult> {
+  const { registeredEntities } = await import('@ultimat3/entity');
+  const { plan, problems } = planSubject({
+    subject: subject.entity,
+    tables: subject.init.tables,
+    columns: subject.init.columns,
+    entries: registeredEntities(),
+  });
+  if (problems.length > 0) return { subject: subject.entity, problems };
+  const entities = new Map(options.entities.map((entity) => [entity.$name, entity]));
+  const graph = seedGraph(Object.fromEntries(entities), {
+    seed: finiteOption('subjectProof', 'seed', options.seed ?? 1),
+    tenants: 2,
+  });
+  await insertSeedGraph(graph, options.writer);
+  const tenant = graph.tenants[0] ?? null;
+  const person = graph.inserts.find(
+    (i) => i.entity === subject.entity && (i.tenant === tenant || i.tenant === null),
+  );
+  const root = entities.get(subject.entity);
+  if (person === undefined || root === undefined) return { subject: subject.entity, problems: [] };
+  const key = String(person.row[plan.key]);
+  const reached = reachedRows(graph, plan, entities, person.row);
+
+  const treatments = new Map(Object.entries(subject.init.tables));
+  const kept = (entity: string) => {
+    const treatment = treatments.get(entity);
+    return typeof treatment === 'object' && treatment !== null && 'retain' in treatment;
+  };
+  const step = stepRunner({
+    runId: `subject-proof:${key}`,
+    jobName: 'subject-proof',
+    store: memoryStepStore(),
+  }).step;
+  const actor = serviceActor({
+    id: 'subject-proof',
+    ...(tenant === null ? {} : { orgId: tenant }),
+  });
+  await runWithContext(ctxOf({ role: 'worker', actor }), () =>
+    subjectEraseTables(subject, key, step),
+  );
+
+  const markers = new Set(
+    reached.flatMap((r) => (kept(r.entity) || r.marker === undefined ? [] : [r.marker])),
+  );
+  const gone = reached.filter((r) => treatments.get(r.entity) === 'delete');
+  const found: UltimateError[] = [];
+  for (const entity of options.entities) {
+    if (kept(entity.$name) || entity.$describe().view !== undefined) continue;
+    const rows = await options.read(entity);
+    const keyColumns = entity.$primaryKey.map((property) => physical(entity, property));
+    const deleted = new Set(
+      gone
+        .filter((r) => r.entity === entity.$name)
+        .map((r) => JSON.stringify(entity.$primaryKey.map((p) => String(r.row[p])))),
+    );
+    for (const row of rows) {
+      if (deleted.has(JSON.stringify(keyColumns.map((column) => String(row[column]))))) {
+        found.push(
+          new SubjectEraseIncompleteError({
+            subject: subject.entity,
+            table: entity.$name,
+            column: keyColumns.join(', '),
+            what: 'a row the erase deletes is still stored',
+          }),
+        );
+      }
+      for (const [column, value] of Object.entries(row)) {
+        const text = asText(value);
+        if ([...markers].some((marker) => text.includes(marker))) {
+          found.push(
+            new SubjectEraseIncompleteError({
+              subject: subject.entity,
+              table: entity.$name,
+              column,
+              what: 'still holds a seeded value of the subject',
+            }),
+          );
+        }
+      }
+    }
+  }
+  return { subject: subject.entity, key, problems: found };
+}

package/src/template-db-roles.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the template database of a `database.rowSecurity` app — the two roles
+// `@ultimat3/db` declares, made able to log in, the migrator migrating and the app role serving. The
+// bootstrap user (`ultimate`, a superuser) would see every tenant's rows, so a suite never serves as it.
+
+import { APP_ROLE, MIGRATOR_ROLE, rowSecurityRolesSql } from '@ultimat3/db';
+import type { SqlRunner } from './template-db';
+
+type RowSecurityRole = typeof APP_ROLE | typeof MIGRATOR_ROLE;
+
+/**
+ * Test-services credentials only — the role's own name as its password, as `ultimate:ultimate` is.
+ * A production role's credentials are the operator's and never written by the framework.
+ */
+export const loginSql = (role: RowSecurityRole): string =>
+  `ALTER ROLE "${role}" LOGIN PASSWORD '${role}'`;
+
+/** `url` with its credentials swapped for `role`'s, database and parameters kept. */
+export function asRole(url: string, role: RowSecurityRole): string {
+  const next = new URL(url);
+  next.username = role;
+  next.password = role;
+  return next.toString();
+}
+
+/**
+ * Run in the TEMPLATE, before it is migrated: roles are the cluster's, but the schema grants and
+ * the default privileges that make a migrator's later table reachable live in the database, and
+ * every clone inherits them.
+ */
+export async function prepareRowSecurity(
+  connect: (url: string) => SqlRunner,
+  templateUrl: string,
+): Promise<void> {
+  const runner = connect(templateUrl);
+  try {
+    for (const statement of rowSecurityRolesSql()) await runner.exec(statement);
+    await runner.exec(loginSql(APP_ROLE));
+    await runner.exec(loginSql(MIGRATOR_ROLE));
+  } finally {
+    await runner.close();
+  }
+}
+
+/** Where `migrate` runs and where a suite connects, with row security on and off. */
+export const rowSecurityUrls = (
+  enabled: boolean,
+  url: string,
+): { readonly migrate: string; readonly serve: string } =>
+  enabled
+    ? { migrate: asRole(url, MIGRATOR_ROLE), serve: asRole(url, APP_ROLE) }
+    : { migrate: url, serve: url };