@ultimat3/jobs 29.3.2 → 30.0.0

package/src/steps.ts

@@ -5,6 +5,7 @@
 //
 // Suspension (sleep / waitForEvent) unwinds the run by throwing a StepSuspension. The worker
 // catches it and re-queues the job for `resumeAt` instead of holding a process for three days.
+// `waitForEvent` is `steps-wait.ts`; compensation, `steps-unwind.ts`; both over `steps-core.ts`.
 
 import type { Clock } from '@ultimat3/core';
 import { finiteOption, isUltimateError, logger, renderThrowable } from '@ultimat3/core';
@@ -12,114 +13,38 @@ import { expectedQueryLoop } from '@ultimat3/db';
 import type { DurationInput } from './clock';
 import { finiteDurationMs, nowMs } from './clock';
 import { JobAbortedError, JobTimeoutError, StepDuplicateError } from './errors';
-import { createRunSignal } from './run-signal';
 import {
-  isStepSuspension,
-  isWaitTimedOut,
-  StepSuspension,
-  WAIT_TIMED_OUT,
-} from './steps-suspension';
+  isReservedStepName,
+  StepCompensateUndeclaredError,
+  StepNameReservedError,
+  StepOutcomeUnknownError,
+  UNWINDING_STEP,
+} from './errors-saga';
+import { createRunSignal } from './run-signal';
+import type { EventLookup, StepApi, StepRunOptions } from './steps-api';
+import { DEFAULT_EVENT_POLL_MS, WAKING_EVENT_POLL_MS } from './steps-api';
+import type { RunnerCore } from './steps-core';
+import type { StepOutput } from './steps-output';
+import { jsonForm } from './steps-output';
+import type { StepFence, StepRecord, StepStore } from './steps-store';
+import { isStepSuspension, StepSuspension, UnwindReached } from './steps-suspension';
 import { withStepTimeout } from './steps-timeout';
-
+import { compensationStack } from './steps-unwind';
+import { waitForEventStep } from './steps-wait';
+
+export type {
+  CompensateContext,
+  EventLookup,
+  StepApi,
+  StepRunOptions,
+  WaitForEventOptions,
+} from './steps-api';
+export { DEFAULT_EVENT_POLL_MS, WAKING_EVENT_POLL_MS } from './steps-api';
+export type { StepOutput } from './steps-output';
+export type { StepFence, StepRecord, StepStatus, StepStore } from './steps-store';
+export { isStepStatus, STEP_STATUSES } from './steps-store';
 export { isStepSuspension, StepSuspension } from './steps-suspension';
 
-/**
- * The runtime list is the declaration and `StepStatus` is derived from it, the shape
- * `BACKFILL_STATUSES` and `PRIMITIVE_KINDS` already have. A bare union cannot narrow a `text`
- * column, so `driver-pg-rows.ts` cast one instead — and a cast that lands an unknown status on a
- * record makes `stepRun`'s `existing?.status === 'completed'` false, which RE-EXECUTES a step
- * this file promises runs once.
- */
-export const STEP_STATUSES = ['completed', 'sleeping', 'waiting', 'failed'] as const;
-
-export type StepStatus = (typeof STEP_STATUSES)[number];
-
-/** Narrows a status read back out of a store. Never a cast — the list decides. */
-export const isStepStatus = (value: string): value is StepStatus =>
-  (STEP_STATUSES as readonly string[]).includes(value);
-
-export interface StepRecord {
-  readonly runId: string;
-  readonly name: string;
-  readonly status: StepStatus;
-  /** The memoized return value. Present only when `status === 'completed'`. */
-  readonly output?: unknown;
-  readonly startedAt: number;
-  readonly completedAt?: number;
-  /** Epoch ms at which a sleeping/waiting step becomes runnable. */
-  readonly wakeAt?: number;
-  readonly event?: string;
-  readonly correlationKey?: string;
-  readonly attempts: number;
-  readonly error?: string;
-}
-
-/** The claim a step write is made under: `claimOf(claimed)`, plus the row it names. */
-export interface StepFence {
-  readonly job: string;
-  readonly jobId: string;
-  readonly workerId: string;
-  readonly claim: number;
-}
-
-export interface StepStore {
-  get(runId: string, name: string): Promise<StepRecord | undefined>;
-  /**
-   * With `by`, the write lands only while that claim still holds the row (`running`, same worker,
-   * same claim ordinal — `SQL_ACK`'s fence) and is `X_JOB_LEASE_LOST` otherwise: the in-process
-   * signal cannot stop a body in ANOTHER process whose lease lapsed. Without it the write is
-   * unfenced — a transfer (`x jobs drain`) or a runner driven by hand, with no row to hold.
-   */
-  put(record: StepRecord, by?: StepFence): Promise<void>;
-  list(runId: string): Promise<readonly StepRecord[]>;
-  del(runId: string, name: string): Promise<void>;
-  clear(runId: string): Promise<void>;
-}
-
-/** The slice of the event bus a waiting step needs. Implemented by `events.ts`. */
-export interface EventLookup {
-  /**
-   * The bus's OWN clock, in epoch ms: what a publish issued now would be stamped with. A consumer
-   * that wants "published after I asked" takes its "asked at" from here and never from its own
-   * process — `publishedAt` is this clock's, and two clocks compared is a skew between pods
-   * deciding which answers count. `waitForEvent` stamps a NEW wait with it.
-   */
-  now(): Promise<number>;
-  find(
-    event: string,
-    correlationKey: string | undefined,
-    afterMs: number,
-  ): Promise<{ readonly payload: unknown; readonly publishedAt: number } | undefined>;
-}
-
-export interface WaitForEventOptions {
-  /** How long to wait before giving up. Default 24h. */
-  readonly timeout?: DurationInput;
-  /** Correlation key the published event must carry — usually an entity id. */
-  readonly match?: string;
-  /** Default false: a timeout resolves `undefined`. `true` fails the job with X_JOB_TIMEOUT. */
-  readonly required?: boolean;
-}
-
-export interface StepApi {
-  /**
-   * Run once, ever. On replay the persisted output is returned and `fn` is not called.
-   *
-   * `fn` receives the step's `AbortSignal` — the run's cancellation and this step's own ceiling,
-   * whichever fires first. Hand it to `fetch`, or read `.aborted` in a loop: past it, this step
-   * may no longer write, because the attempt that replaced this one owns the run.
-   */
-  run<T>(name: string, fn: (signal: AbortSignal) => Promise<T> | T): Promise<T>;
-  /** Suspend the run. `sleep(duration)` derives the step name from the duration. */
-  sleep(name: string, duration: DurationInput): Promise<void>;
-  sleep(duration: DurationInput): Promise<void>;
-  waitForEvent<T>(
-    name: string,
-    event: string,
-    options?: WaitForEventOptions,
-  ): Promise<T | undefined>;
-}
-
 export interface StepRunnerOptions {
   readonly runId: string;
   readonly jobName: string;
@@ -128,8 +53,19 @@ export interface StepRunnerOptions {
   readonly fence?: StepFence;
   readonly clock?: Clock;
   readonly events?: EventLookup;
-  /** How long a waiting step stays parked between event polls. Default 30s. */
+  /**
+   * How long a waiting step stays parked between event polls. Default `DEFAULT_EVENT_POLL_MS`
+   * (30 s), or `WAKING_EVENT_POLL_MS` (15 min) when `events.wakes`: a publish then brings the run
+   * forward, and the poll is only the backstop. A value set here wins either way.
+   */
   readonly eventPollMs?: number;
+  /** The job declares `compensates: true`: `step.run(…, { compensate })` is legal. */
+  readonly compensates?: boolean;
+  /**
+   * This attempt is past the policy's last (`isUnwindAttempt`): the run is unwinding whether or
+   * not `unwinding` was written — the final attempt crashed before it could be.
+   */
+  readonly unwind?: boolean;
   /** Per-step ceiling; the job-level timeout is enforced by the worker. */
   readonly stepTimeoutMs?: number;
   /**
@@ -157,6 +93,13 @@ export interface StepRunner {
   usedNames(): readonly string[];
   /** Names that were served from storage instead of executed. Bounded the same way. */
   replayedNames(): readonly string[];
+  /** Whether the run is unwinding: `options.unwind`, or `unwinding` found among its steps. */
+  unwinding(): Promise<boolean>;
+  /**
+   * Run this attempt's registered compensators, last-in first-out (`steps-unwind.ts`). Answers
+   * the failure the run unwinds from — the one already recorded, else `failure`.
+   */
+  unwind(failure: string): Promise<string>;
 }
 
 /** Stands in for an absent run signal, so the fence has one shape and no `undefined` branch. */
@@ -182,7 +125,12 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
   const used: string[] = [];
   const replayed: string[] = [];
   const clock = options.clock;
-  const pollMs = finiteOption('step.waitForEvent', 'eventPollMs', options.eventPollMs ?? 30_000);
+  const pollMs = finiteOption(
+    'step.waitForEvent',
+    'eventPollMs',
+    options.eventPollMs ??
+      (options.events?.wakes === true ? WAKING_EVENT_POLL_MS : DEFAULT_EVENT_POLL_MS),
+  );
   // `job()` refuses a non-finite `stepTimeout` at declaration (`job.ts`); screened again here, where
   // it is read, because this runner is also built directly and `withStepTimeout` reads a `NaN`
   // ceiling as none at all — the backstop `pollMs` above already is.
@@ -203,23 +151,39 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
    * Sound because the fence in `put()` is: only the attempt that owns the run may write to it, so
    * within one attempt an absent name stays absent unless this runner writes it. Writes go into
    * the map as they go into the store, never the other way round — the store is still the record.
+   *
+   * The PROMISE is the memo, and the map is published only when the list has answered: a map
+   * assigned before the await let a second caller read it empty, so `Promise.all` over completed
+   * steps re-ran one on replay and answered a value the store did not hold. A rejected list clears
+   * the memo, so the next call asks again rather than this attempt failing on one blip for good.
    */
   let hydrated: Map<string, StepRecord> | undefined;
-
-  const load = async (name: string): Promise<StepRecord | undefined> => {
-    if (hydrated === undefined) {
-      hydrated = new Map();
-      for (const record of await store.list(runId)) hydrated.set(record.name, record);
-    }
-    return hydrated.get(name);
+  let hydrating: Promise<Map<string, StepRecord>> | undefined;
+
+  const hydrate = (): Promise<Map<string, StepRecord>> => {
+    if (hydrating !== undefined) return hydrating;
+    const pending = (async () => {
+      const records = await store.list(runId);
+      hydrated = new Map(records.map((record) => [record.name, record]));
+      return hydrated;
+    })();
+    hydrating = pending;
+    pending.catch(() => {
+      if (hydrating === pending) hydrating = undefined;
+    });
+    return pending;
   };
 
-  /** Keep the hydrated view in step with what was just persisted. */
+  const load = async (name: string): Promise<StepRecord | undefined> => (await hydrate()).get(name);
+
+  /** Keep the hydrated view in step. Every write follows a `load`, so the list has answered. */
   const remember = (record: StepRecord): void => {
     hydrated?.set(record.name, record);
   };
 
   const claimName = (name: string): void => {
+    // Refused for EVERY job, so one that gains `compensates` later cannot meet a step it wrote.
+    if (isReservedStepName(name)) throw new StepNameReservedError({ job: jobName, step: name });
     // The Set decides, the array only reports. `Array.includes` made a long run quadratic —
     // `backfill({ batch: 50 })` over a million rows is 20,000 steps and ~200M string compares.
     if (claimed.has(name)) throw new StepDuplicateError({ job: jobName, step: name });
@@ -291,14 +255,25 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
 
   const now = (): number => nowMs(clock);
 
-  async function run<T>(name: string, fn: (signal: AbortSignal) => Promise<T> | T): Promise<T> {
-    claimName(name);
-    const existing = await load(name);
-    if (existing?.status === 'completed') {
-      trace(replayed, name);
-      return existing.output as T;
-    }
+  /**
+   * The run is unwinding: this attempt is past the policy's last, or `unwinding` is among the
+   * steps the first `load` hydrated. Sticky — once true for an attempt it stays true.
+   */
+  let unwindMode = options.unwind === true;
+  const unwinding = async (): Promise<boolean> => {
+    if (!unwindMode) unwindMode = (await hydrate()).has(UNWINDING_STEP);
+    return unwindMode;
+  };
 
+  /**
+   * One step body, run under its ceiling and recorded: `completed` before it returns, `failed` on
+   * the way out. Shared by `step.run` and by every compensator (`steps-unwind.ts`).
+   */
+  const execute = async <T>(
+    name: string,
+    existing: StepRecord | undefined,
+    fn: (signal: AbortSignal) => Promise<T> | T,
+  ): Promise<StepOutput<T>> => {
     const startedAt = existing?.startedAt ?? now();
     const attempts = (existing?.attempts ?? 0) + 1;
     // The step's own ceiling, folded into the run's cancellation so the body reads ONE signal and
@@ -319,24 +294,31 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
         fn(signal),
         stepTimeoutMs,
         deadline,
-        () => new JobTimeoutError({ job: jobName, step: name, timeoutMs: stepTimeoutMs ?? 0 }),
+        () =>
+          new JobTimeoutError({
+            job: jobName,
+            step: name,
+            timeoutMs: stepTimeoutMs ?? 0,
+            fix: `job({ name: '${jobName}', stepTimeout: '5m' })   # raises the ceiling; or split step.run('${name}', …) into smaller steps`,
+          }),
       );
+      // What goes in the store is what comes back, so both attempts see one value.
+      const stored = jsonForm(output as T, { job: jobName, step: name });
       // Persist BEFORE returning: a crash one line later must not re-run this step.
       await put({
         runId,
         name,
         status: 'completed',
-        output,
+        output: stored,
         startedAt,
         completedAt: now(),
         attempts,
       });
-      return output;
+      return stored;
     } catch (error) {
       if (isStepSuspension(error)) throw error;
       // The failure is this run's own history, so it is recorded on the way out — unless the
-      // attempt was cancelled, in which case the history is no longer ours to write. The original
-      // error is what the caller has to see, never one raised by the bookkeeping.
+      // attempt was cancelled, in which case the history is no longer ours to write.
       if (!cancelled()) {
         // Deliberately NOT through `put`: the caller has to see the original error, never one
         // raised by the bookkeeping. The hydrated view is updated by hand for the same reason.
@@ -365,6 +347,68 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
       // settled leaves its signal in whatever state it ended in.
       composed?.dispose();
     }
+  };
+
+  const core: RunnerCore = {
+    runId,
+    jobName,
+    events: options.events,
+    pollMs,
+    claim: claimName,
+    load,
+    put,
+    now,
+    replayed: (name) => trace(replayed, name),
+    forwardOnly: async (name) => {
+      if (await unwinding()) throw new UnwindReached(name);
+    },
+  };
+  const compensations = compensationStack(core, execute);
+
+  async function run<T>(
+    name: string,
+    fn: (signal: AbortSignal) => Promise<T> | T,
+    runOptions: StepRunOptions<T> = {},
+  ): Promise<StepOutput<T>> {
+    const { compensate, once = false } = runOptions;
+    if (compensate !== undefined && options.compensates !== true) {
+      throw new StepCompensateUndeclaredError({ job: jobName, step: name });
+    }
+    claimName(name);
+    const undo =
+      compensate === undefined
+        ? undefined
+        : (output: StepOutput<T>) => async (signal: AbortSignal) => {
+            // A compensator's answer is not the run's to keep: `null` is what its step records.
+            await compensate(output, { signal });
+            return null;
+          };
+    const existing = await load(name);
+    if (existing?.status === 'completed') {
+      trace(replayed, name);
+      const output = existing.output as StepOutput<T>;
+      if (undo !== undefined) compensations.done(name, undo(output));
+      return output;
+    }
+    // `started` or `failed` and never `completed`: a crash or a throw, and nobody knows which side
+    // of the side effect it stopped on. `cleared` is an operator's "it did not run".
+    const unknown = once && (existing?.status === 'started' || existing?.status === 'failed');
+    if (unknown && undo !== undefined) compensations.unknown(name);
+    await core.forwardOnly(name);
+    if (unknown) throw new StepOutcomeUnknownError({ job: jobName, step: name });
+    if (once) {
+      // BEFORE `fn`: from here on, a replay cannot tell whether `fn` ran, and so never runs it.
+      await put({
+        runId,
+        name,
+        status: 'started',
+        startedAt: existing?.startedAt ?? now(),
+        attempts: existing?.attempts ?? 0,
+      });
+    }
+    const output = await execute(name, once ? await load(name) : existing, fn);
+    if (undo !== undefined) compensations.done(name, undo(output));
+    return output;
   }
 
   async function sleep(a: string | DurationInput, b?: DurationInput): Promise<void> {
@@ -378,6 +422,7 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
       trace(replayed, name);
       return;
     }
+    await core.forwardOnly(name);
 
     const at = now();
     if (existing?.status === 'sleeping' && existing.wakeAt !== undefined) {
@@ -401,98 +446,17 @@ export function stepRunner(options: StepRunnerOptions): StepRunner {
     throw new StepSuspension({ step: name, resumeAt: wakeAt, reason: 'sleep' });
   }
 
-  async function waitForEvent<T>(
-    name: string,
-    event: string,
-    waitOptions: WaitForEventOptions = {},
-  ): Promise<T | undefined> {
-    claimName(name);
-    const existing = await load(name);
-    if (existing?.status === 'completed') {
-      trace(replayed, name);
-      return isWaitTimedOut(existing.output) ? undefined : (existing.output as T | undefined);
-    }
-
-    const at = now();
-    // A NEW wait is stamped by the bus, whose clock stamps every `publishedAt` it is compared
-    // with; the runner's own only when there is no bus to ask. A re-poll keeps what it persisted.
-    const startedAt = existing?.startedAt ?? (await options.events?.now()) ?? at;
-    const deadline =
-      startedAt +
-      finiteDurationMs(waitOptions.timeout ?? 86_400_000, 'step.waitForEvent', 'timeout');
-    const correlationKey = waitOptions.match;
-
-    const hit = await options.events?.find(event, correlationKey, startedAt);
-    if (hit !== undefined) {
-      await put({
-        runId,
-        name,
-        status: 'completed',
-        output: hit.payload,
-        startedAt,
-        completedAt: at,
-        event,
-        attempts: (existing?.attempts ?? 0) + 1,
-        ...(correlationKey === undefined ? {} : { correlationKey }),
-      });
-      return hit.payload as T;
-    }
-
-    // `deadline` is on the BUS's clock, so the bus calls the timeout: asked only once this runner
-    // believes the time is up, which costs a wait one statement at its end. A runner AHEAD of the
-    // bus used to give up early by the skew — on an answer still inside its window. (A runner
-    // BEHIND waits the skew longer; knowing that sooner would cost a round trip on every poll.)
-    let remaining = deadline - at;
-    if (remaining <= 0) remaining = deadline - ((await options.events?.now()) ?? at);
-    if (remaining <= 0) {
-      if (waitOptions.required === true) {
-        throw new JobTimeoutError({
-          job: jobName,
-          step: name,
-          timeoutMs: finiteDurationMs(
-            waitOptions.timeout ?? 86_400_000,
-            'step.waitForEvent',
-            'timeout',
-          ),
-        });
-      }
-      logger.warn('jobs.step.wait-timeout', { job: jobName, step: name, event });
-      await put({
-        runId,
-        name,
-        status: 'completed',
-        output: WAIT_TIMED_OUT,
-        startedAt,
-        completedAt: at,
-        event,
-        attempts: (existing?.attempts ?? 0) + 1,
-      });
-      return undefined;
-    }
-
-    const resumeAt = at + Math.min(remaining, pollMs);
-    await put({
-      runId,
-      name,
-      status: 'waiting',
-      startedAt,
-      wakeAt: resumeAt,
-      event,
-      attempts: (existing?.attempts ?? 0) + 1,
-      ...(correlationKey === undefined ? {} : { correlationKey }),
-    });
-    throw new StepSuspension({ step: name, resumeAt, reason: 'event' });
-  }
-
   const step: StepApi = {
     run,
     sleep: sleep as StepApi['sleep'],
-    waitForEvent,
+    waitForEvent: waitForEventStep(core),
   };
 
   return {
     step,
     usedNames: () => [...used],
     replayedNames: () => [...replayed],
+    unwinding,
+    unwind: (failure) => compensations.unwind(failure),
   };
 }

package/src/subject-erase-pass.ts

@@ -0,0 +1,134 @@
+// One `subjectErase()` pass: the framework targets first (they read the subject's row), then every
+// loop-closing key cleared, then each table children first, the subject last. Every page of
+// parent keys is its own step, so a killed run resumes at the page it stopped on; each statement
+// is an equality on one key, so a replayed step deletes or overwrites nothing twice.
+
+import type { StepApi } from './steps-api';
+import type { SubjectRef, SubjectTarget, SubjectTargetEntry } from './subject';
+import { isRetainedTarget } from './subject';
+import type { SubjectStep } from './subject-plan';
+import type { SubjectReader } from './subject-select';
+import { rowIdentity } from './subject-select';
+
+/** What one table or target went through. Bounded and JSON-safe: it is the job's result. */
+export interface SubjectTally {
+  readonly deleted: number;
+  readonly anonymized: number;
+  readonly retained: number;
+}
+
+export interface SubjectEraseReport {
+  readonly tables: Readonly<Record<string, SubjectTally>>;
+}
+
+const tally = (deleted: number, anonymized: number, retained: number): SubjectTally => ({
+  deleted,
+  anonymized,
+  retained,
+});
+
+/** The subject as a target reads it, fresh: its row is never written into a checkpoint. */
+const refOf = async (reader: SubjectReader): Promise<SubjectRef> => ({
+  key: reader.key,
+  row: (await reader.rootRow()) ?? {},
+});
+
+async function eraseTarget(step: StepApi, reader: SubjectReader, target: SubjectTarget) {
+  let total = 0;
+  for (let n = 0; ; n += 1) {
+    const removed = await step.run(`target:${target.name}:${n}`, async () =>
+      target.erase(await refOf(reader), reader.size),
+    );
+    total += removed;
+    if (removed < reader.size) return total;
+  }
+}
+
+/** One write per parent key in the page: `deleteWhere`/`updateWhere`, the repository's own. */
+async function treatPage(
+  reader: SubjectReader,
+  step: SubjectStep,
+  property: string,
+  values: readonly unknown[],
+): Promise<number> {
+  const table = reader.table(step.entity);
+  let count = 0;
+  for (const value of values) {
+    const filter = { [property]: value };
+    count +=
+      step.treatment === 'delete'
+        ? await table.deleteWhere(filter)
+        : typeof step.treatment === 'object' && 'anonymize' in step.treatment
+          ? await table.updateWhere(filter, step.treatment.anonymize)
+          : 0;
+  }
+  return count;
+}
+
+async function countRows(reader: SubjectReader, entity: string): Promise<number> {
+  const core = reader.core(entity);
+  const seen = new Set<string>();
+  for await (const page of reader.pages(entity)) {
+    for (const row of page) seen.add(rowIdentity(core, row));
+  }
+  return seen.size;
+}
+
+async function eraseTable(
+  stepApi: StepApi,
+  reader: SubjectReader,
+  step: SubjectStep,
+): Promise<SubjectTally> {
+  const { entity, treatment } = step;
+  if (typeof treatment === 'object' && 'retain' in treatment) {
+    return tally(0, 0, await stepApi.run(`retain:${entity}`, () => countRows(reader, entity)));
+  }
+  let count = 0;
+  if (entity === reader.plan.subject) {
+    count = await stepApi.run(`${entity}:subject`, () =>
+      treatPage(reader, step, reader.plan.key, [reader.key]),
+    );
+  }
+  for (const via of step.via) {
+    let n = 0;
+    for await (const values of reader.parentKeys(via)) {
+      count += await stepApi.run(`${entity}.${via.property}:${n}`, () =>
+        treatPage(reader, step, via.property, values),
+      );
+      n += 1;
+    }
+  }
+  return treatment === 'delete' ? tally(count, 0, 0) : tally(0, count, 0);
+}
+
+export async function subjectErasePass(
+  stepApi: StepApi,
+  reader: SubjectReader,
+  targets: readonly SubjectTargetEntry[],
+): Promise<SubjectEraseReport> {
+  const tables = new Map<string, SubjectTally>();
+  for (const entry of targets) {
+    if (isRetainedTarget(entry)) {
+      tables.set(entry.target.name, tally(0, 0, 0));
+      continue;
+    }
+    tables.set(entry.name, tally(await eraseTarget(stepApi, reader, entry), 0, 0));
+  }
+  for (const unlink of reader.plan.unlink) {
+    let n = 0;
+    for await (const values of reader.parentKeys(unlink)) {
+      await stepApi.run(`unlink:${unlink.entity}.${unlink.property}:${n}`, async () => {
+        const table = reader.table(unlink.entity);
+        for (const value of values) {
+          await table.updateWhere({ [unlink.property]: value }, { [unlink.property]: null });
+        }
+        return null;
+      });
+      n += 1;
+    }
+  }
+  for (const step of reader.plan.steps) {
+    tables.set(step.entity, await eraseTable(stepApi, reader, step));
+  }
+  return { tables: Object.fromEntries(tables) };
+}

package/src/subject-errors.ts

@@ -0,0 +1,48 @@
+// The three `X_SUBJECT_*` refusals a subject's plan can end on — each a refusal of the
+// DECLARATION, so a run raises the first and `x exercise` lists every one. The codes, titles and
+// retry classes are `error-codes.ts`'s; the values printed are entity and column names, never data.
+
+import { renderFixShellArg, UltimateError } from '@ultimat3/core';
+
+/** A table reaches the subject and `tables:` gives it no treatment. `path` is how it reaches. */
+export class SubjectTableUndeclaredError extends UltimateError {
+  constructor(input: { subject: string; table: string; path: readonly string[] }) {
+    super({
+      code: 'X_SUBJECT_TABLE_UNDECLARED',
+      cause: `${input.table} reaches the subject ${input.subject} (${input.path.join(' <- ')}) and defineSubject(${input.subject}) gives it no treatment, so an erase would leave its rows and an export would miss them`,
+      fix: `tables: { ${input.table}: 'delete' }   # in defineSubject(${input.subject}, …) — or { anonymize: { <column>: <value> } }, or { retain: '<why it is kept>' }`,
+      meta: { subject: input.subject, table: input.table, path: [...input.path] },
+    });
+  }
+}
+
+/** A treatment that cannot be carried out. `field` names what to change. */
+export class SubjectTreatmentInvalidError extends UltimateError {
+  constructor(input: {
+    subject: string;
+    table: string;
+    field: string;
+    reason: string;
+    /** The treatment the repair is: `'delete'` for a kept row a delete would block. */
+    instead?: string;
+  }) {
+    super({
+      code: 'X_SUBJECT_TREATMENT_INVALID',
+      cause: `defineSubject(${input.subject}) treats ${input.table}: ${input.field} ${input.reason}`,
+      fix: `tables: { ${input.table}: ${input.instead ?? "{ retain: '<why it is kept>' }"} }   # in defineSubject(${input.subject}, …), or correct ${input.field} as the cause says`,
+      meta: { subject: input.subject, table: input.table, field: input.field },
+    });
+  }
+}
+
+/** Tables the erase deletes reference each other through keys that are all `not null`. */
+export class SubjectCycleError extends UltimateError {
+  constructor(input: { subject: string; table: string; column: string; parent: string }) {
+    super({
+      code: 'X_SUBJECT_CYCLE',
+      cause: `${input.table}.${input.column} references ${input.parent}, which the erase of ${input.subject} also deletes, and closes a loop — the key is not nullable, so neither side can go first`,
+      fix: `x db gen ${renderFixShellArg(`nullable ${input.table} ${input.column}`, '<description>')}   # after ${input.column}: uuid().nullable() in entity('${input.table}'): the erase clears it before deleting either side`,
+      meta: { subject: input.subject, table: input.table, column: input.column },
+    });
+  }
+}