@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/erasure/cascade.mjs

@@ -0,0 +1,91 @@
+import { statement, quote, guard, insist, ErasureError } from './sql.mjs';
+import { rootStatements } from './root.mjs';
+import { readScope, scopeStatements } from './scope.mjs';
+import { verificationStatements, childAbsenceStatements } from './verification.mjs';
+import { collect, matchSql, checkDeclared } from './plan.mjs';
+import { auditStatements } from './audit.mjs';
+import { progressStatement, committedStatement } from './receipt.mjs';
+
+const where = (keys, table) => keys.get(table).pk.map(c => `${c === 'rowid' ? 'rowid' : quote(c)}=?`).join(' AND ');
+const values = e => Object.values(e.key);
+
+function redactStatements(db, d, plan) {
+  const out = [];
+  for (const item of d.redact) {
+    const set = Object.keys(item.set).map(c => `${quote(c)}=?`).join(',');
+    for (const m of matchSql(item, [...plan.known.get(item.from).values()])) {
+      out.push(statement(db, `UPDATE ${quote(item.table)} SET ${set} WHERE ${m.where}`, ...Object.values(item.set), ...m.values));
+    }
+  }
+  return out;
+}
+
+/** Deletes each entry with its blob key captured first and its portability tombstone beside it. */
+export async function deletionStatements(ctx, d, plan, entries, id, deleted) {
+  const { db, fence } = ctx, out = [];
+  for (const e of entries) {
+    const match = where(plan.keys, e.table);
+    out.push(...childAbsenceStatements(db, plan, e));
+    for (const blob of new Map(d.edges.filter(x => x.table === e.table && x.blob).map(x => [x.blob.bucket + '\0' + x.blob.keyColumn, x.blob])).values()) {
+      out.push(statement(db, `INSERT OR IGNORE INTO rer_erasure_blobs(operation,bucket,key) SELECT ?,?,${quote(blob.keyColumn)} FROM ${quote(e.table)} WHERE ${match} AND ${quote(blob.keyColumn)} IS NOT NULL`, id, blob.bucket, ...values(e)));
+    }
+    out.push(statement(db, `DELETE FROM ${quote(e.table)} WHERE ${match}`, ...values(e)), ...await fence.row(e.table, e.key));
+    deleted[e.table] = (deleted[e.table] ?? 0) + 1;
+  }
+  return out;
+}
+export async function firstStatements(ctx, d, plan, label) {
+  return d.beforeStatements ? await d.beforeStatements({ db: ctx.db, subject: plan.subject, label }) : [];
+}
+export const cleanupStatements = (ctx, d, plan, label) => [...redactStatements(ctx.db, d, plan), ...auditStatements(ctx.db, d, plan, label)];
+/** Commits with the subject row: a second redaction/audit pass catches rows written
+ * during a long erasure. Verify before removing the root (so triggers cannot hide
+ * new children through CASCADE), then after final policy effects. */
+export async function finalStatements(ctx, d, plan, id, label, now, deleted) {
+  const { db } = ctx, out = [];
+  if (plan) out.push(...cleanupStatements(ctx, d, plan, label), ...await rootStatements(ctx, d, plan, id));
+  out.push(...await verificationStatements(db, d, plan, id, label, { final: true }));
+  if (!d.root.redact) out.push(...await deletionStatements(ctx, d, plan, [plan.root], id, deleted));
+  if (plan && d.statements) out.push(...await d.statements({ db, subject: plan.subject, label }));
+  out.push(...cleanupStatements(ctx, d, plan, label));
+  out.push(...await verificationStatements(db, d, plan, id, label, { final: true }));
+  out.push(statement(db, 'UPDATE rer_erasure_operations SET blobs_total=(SELECT count(*) FROM rer_erasure_blobs WHERE operation=?) WHERE id=?', id, id), committedStatement(db, id, now));
+  return out;
+}
+
+/** One bounded, atomic D1 commit of up to `rows` dependents, leaves first. The
+ * subject row commits with the last step. A concurrent runner loses the guard. */
+export async function step(ctx, d, id, { rows = 500 } = {}) {
+  const { db, fence } = ctx;
+  const op = await statement(db, 'SELECT * FROM rer_erasure_operations WHERE id=?', id).first();
+  insist(op && op.entity === d.entity, 'erasure_not_found', 404);
+  if (op.phase !== 'deleting') return false;
+  const now = new Date().toISOString(), deleted = JSON.parse(op.deleted);
+  await checkDeclared(db, d);
+  insist(Number.isInteger(rows) && rows > 0, 'batch_rows');
+  const remembered = await readScope(db, id);
+  insist(op.step === 0 || remembered.some(e => e.table === d.root.table), 'erasure_scope_missing', 409);
+  const plan = await collect(db, d, JSON.parse(op.subject), remembered);
+  insist(plan && plan.root, 'subject_removed_outside_erasure', 409);
+  const batch = [db.prepare('PRAGMA defer_foreign_keys=ON'),
+    guard(db, "EXISTS(SELECT 1 FROM rer_erasure_operations WHERE id=? AND step=? AND phase='deleting')", id, op.step),
+    ...await fence.transfers()];
+  const take = plan.order.slice(0, rows), final = take.length === plan.order.length;
+  batch.push(...await scopeStatements(db, d, plan, id, [...take, plan.root]));
+  if (op.step === 0) batch.push(...await firstStatements(ctx, d, plan, op.label));
+  batch.push(...await verificationStatements(db, d, plan, id, op.label));
+  batch.push(...cleanupStatements(ctx, d, plan, op.label));
+  batch.push(...await deletionStatements(ctx, d, plan, take, id, deleted));
+  if (final) batch.push(...await finalStatements(ctx, d, plan, id, op.label, now, deleted));
+  else batch.push(...await verificationStatements(db, d, plan, id, op.label, { intake: false }));
+
+  batch.push(progressStatement(db, id, op.step, deleted), db.prepare('DELETE FROM rer_erasure_guard'));
+  try { await db.batch(batch); }
+  catch (error) {
+    if (/erasure_scope_changed/.test(String(error?.message ?? error))) return 'changed';
+    if (/erasure_retained_missing/.test(String(error?.message ?? error))) throw new ErasureError('retained_row_missing', 409);
+    if (/CHECK constraint failed/.test(String(error?.message ?? error))) throw new ErasureError('erasure_busy', 409);
+    throw error;
+  }
+  return !final;
+}

package/modules/erasure/completion.mjs

@@ -0,0 +1,62 @@
+import { statement, guard, insist, ErasureError } from './sql.mjs';
+import { collect, checkDeclared } from './plan.mjs';
+import { readScope, readRedaction, scopeStatements, forgetScope } from './scope.mjs';
+import { rootValues, rootStatements } from './root.mjs';
+import { cleanupStatements, deletionStatements } from './cascade.mjs';
+import { verificationStatements, rootGoneStatement } from './verification.mjs';
+import { progressStatement, completeStatement } from './receipt.mjs';
+
+/** Reconcile the declared graph after the first D1 fence, using the remembered
+ * parents even when the root is gone. Completion and the last audit/retention
+ * checks share one transaction; late rows return to deletion and blob cleanup. */
+export async function settle(ctx, d, id) {
+  const { db, fence } = ctx;
+  const op = await statement(db, 'SELECT * FROM rer_erasure_operations WHERE id=?', id).first();
+  insist(op && op.entity === d.entity, 'erasure_not_found', 404);
+  if (op.phase !== 'blobs') return op.phase;
+  const remembered = await readScope(db, id), saved = remembered.find(e => e.table === d.root.table);
+  if (!saved) {
+    const current = await statement(db, 'SELECT phase FROM rer_erasure_operations WHERE id=?', id).first();
+    if (current?.phase === 'complete') return 'complete';
+    // Older helpers discarded this information. Never claim an unprovable
+    // legacy operation complete or invent the erased person's key.
+    insist(false, 'erasure_scope_missing', 409);
+  }
+  await checkDeclared(db, d);
+  const plan = await collect(db, d, saved.key, remembered);
+  insist(plan, 'erasure_scope_missing', 409);
+  if (d.root.redact) {
+    const saved = await readRedaction(db, id);
+    insist(plan.root && saved.identity && /^[a-f0-9]{32}$/.test(saved.redaction?.anonymousId ?? ''), 'erasure_redaction_scope_missing', 409);
+    plan.anonymousId = saved.redaction.anonymousId; plan.rootIdentity = saved.identity;
+    plan.rootSet = await rootValues(d, plan.keys.get(d.root.table), plan.subject, plan.anonymousId);
+  }
+  const deleted = JSON.parse(op.deleted), take = plan.order.slice(0, 500), final = take.length === plan.order.length;
+  const newBlobs = take.some(e => d.edges.some(edge => edge.table === e.table && edge.blob && e.row[edge.blob.keyColumn] != null));
+  const batch = [db.prepare('PRAGMA defer_foreign_keys=ON'), guard(db, "EXISTS(SELECT 1 FROM rer_erasure_operations WHERE id=? AND step=? AND phase='blobs')", id, op.step),
+    ...await fence.transfers(), ...await scopeStatements(db, d, plan, id, [...take, ...(plan.root ? [plan.root] : [])]),
+    ...await verificationStatements(db, d, plan, id, op.label), ...cleanupStatements(ctx, d, plan, op.label),
+    ...await deletionStatements(ctx, d, plan, take, id, deleted)];
+  if (final) {
+    if (d.root.redact) batch.push(...await rootStatements(ctx, d, plan, id));
+    else if (plan.root) batch.push(...await deletionStatements(ctx, d, plan, [plan.root], id, deleted));
+    batch.push(...cleanupStatements(ctx, d, plan, op.label), ...await verificationStatements(db, d, plan, id, op.label, { final: true }));
+    if (!d.root.redact) batch.push(rootGoneStatement(db, d, plan));
+  } else batch.push(...await verificationStatements(db, d, plan, id, op.label, { intake: false }));
+  batch.push(statement(db, 'UPDATE rer_erasure_operations SET blobs_total=blobs_deleted+(SELECT count(*) FROM rer_erasure_blobs WHERE operation=?) WHERE id=?', id, id), progressStatement(db, id, op.step, deleted));
+  if (final && !newBlobs) {
+    batch.push(guard(db, 'NOT EXISTS(SELECT 1 FROM rer_erasure_blobs WHERE operation=?)', id), completeStatement(db, id, new Date().toISOString()),
+      ...cleanupStatements(ctx, d, plan, op.label), ...await verificationStatements(db, d, plan, id, op.label, { final: true }));
+    if (!d.root.redact) batch.push(rootGoneStatement(db, d, plan));
+    batch.push(forgetScope(db, id));
+  }
+  batch.push(db.prepare('DELETE FROM rer_erasure_guard'));
+  try { await db.batch(batch); }
+  catch (error) {
+    if (/erasure_scope_changed/.test(String(error?.message ?? error))) return 'changed';
+    if (/erasure_retained_missing/.test(String(error?.message ?? error))) throw new ErasureError('retained_row_missing', 409);
+    if (/CHECK constraint failed/.test(String(error?.message ?? error))) throw new ErasureError('erasure_busy', 409);
+    throw error;
+  }
+  return (await statement(db, 'SELECT phase FROM rer_erasure_operations WHERE id=?', id).first()).phase;
+}

package/modules/erasure/declaration.mjs

@@ -0,0 +1,51 @@
+import { insist } from './sql.mjs';
+
+const name = value => typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const match = (item, tables, where) => {
+  insist(tables.has(item.from), `unknown_from:${where}:${item.from}`);
+  insist((item.on === undefined) !== (item.where === undefined), `edge_match:${where}`);
+  if (item.on) insist(Object.keys(item.on).length > 0 && Object.entries(item.on).every(([a, b]) => name(a) && name(b)), `edge_columns:${where}`);
+  if (item.where !== undefined) insist(text(item.where) && Array.isArray(item.params ?? []) && (item.params ?? []).every(name), `edge_predicate:${where}`);
+};
+
+/** Validates one entity's erasure graph. Policy hooks stay functions owned by the seed. */
+export function defineErasure(input) {
+  const d = { edges: [], redact: [], audit: [], retain: [], ...input };
+  insist(typeof d.entity === 'string' && /^[a-z][a-z0-9_-]{0,63}$/.test(d.entity), 'entity_name');
+  insist(d.root && name(d.root.table), 'root_table');
+  for (const key of ['edges', 'redact', 'audit', 'retain']) insist(Array.isArray(d[key]), `${key}_list`);
+  // A table may be reached through several edges (cycles such as request <-> evidence).
+  for (const [i, edge] of d.edges.entries()) insist(name(edge.table) && edge.table !== d.root.table, `edge_table:${i}`);
+  const tables = new Set([d.root.table, ...d.edges.map(e => e.table)]);
+  for (const [i, edge] of d.edges.entries()) {
+    match(edge, tables, `edges[${i}]`);
+    if (edge.blob) insist(name(edge.blob.bucket) && name(edge.blob.keyColumn), `edge_blob:${i}`);
+  }
+  for (const [i, item] of d.redact.entries()) {
+    insist(name(item.table) && !tables.has(item.table), `redact_table:${i}`);
+    match(item, tables, `redact[${i}]`);
+    insist(item.set && Object.keys(item.set).length > 0 && Object.keys(item.set).every(name), `redact_set:${i}`);
+    insist(text(item.reason), `redact_reason:${i}`);
+  }
+  for (const [i, item] of d.audit.entries()) {
+    insist(name(item.table) && name(item.column) && tables.has(item.of), `audit:${i}`);
+    insist(item.where === undefined || text(item.where), `audit_where:${i}`);
+    insist(item.clear === undefined || Object.keys(item.clear).every(name), `audit_clear:${i}`);
+  }
+  for (const [i, item] of d.retain.entries()) insist(name(item.table) && !tables.has(item.table) && text(item.reason), `retain:${i}`);
+  if (d.root.redact) {
+    insist(text(d.root.redact.reason), 'root_redact_reason');
+    insist(Array.isArray(d.root.redact.identityColumns ?? []) && (d.root.redact.identityColumns ?? []).every(name), 'root_identity_columns');
+    insist(typeof d.root.redact.set === 'function' || (d.root.redact.set && Object.keys(d.root.redact.set).length > 0 && Object.keys(d.root.redact.set).every(name)), 'root_redact_set');
+    // The retained root keeps its key, so rate writes naming it need a liveness
+    // predicate the redaction ends (rateEdges root.live).
+    for (const [i, edge] of d.edges.entries()) if (edge.rate && edge.from === d.root.table) insist(text(edge.rate.live), `rate_root_live:${i}`);
+  }
+  for (const hook of ['hold', 'beforeStatements', 'statements']) insist(d[hook] === undefined || typeof d[hook] === 'function', `${hook}_hook`);
+  return Object.freeze({ ...d, tracked: [...tables], deleted: [...tables].filter(t => t !== d.root.table || !d.root.redact) });
+}
+
+export function buckets(declarations) {
+  return [...new Set(declarations.flatMap(d => d.edges.filter(e => e.blob).map(e => e.blob.bucket)))];
+}

package/modules/erasure/fence.mjs

@@ -0,0 +1,19 @@
+import { insist } from './sql.mjs';
+
+/** The restore fence is portability's: every deleted row gets that service's
+ * erasureStatements, and every commit drops in-flight transfer copies. */
+export function fenceCalls(portability) {
+  insist(portability && typeof portability.erasureStatements === 'function' && typeof portability.invalidateTransfersStatements === 'function', 'portability_service');
+  return {
+    row: (table, key) => portability.erasureStatements(table, key),
+    redaction: () => portability.redactionStatements(),
+    transfers: () => portability.invalidateTransfersStatements(),
+  };
+}
+
+/** import-kit takes `{sql, params}` (its D1Sql). Workers' D1 prepared statements
+ * carry their text and bindings as `statement` and `params`; refuse anything else. */
+export function toD1Sql(prepared) {
+  insist(prepared && typeof prepared.statement === 'string' && Array.isArray(prepared.params), 'statement_not_convertible');
+  return { sql: prepared.statement, params: [...prepared.params] };
+}

package/modules/erasure/index.d.mts

@@ -0,0 +1,62 @@
+export type Cell = null | string | number;
+export type Key = Record<string, Cell>;
+type Match = { from: string; on: Record<string, string>; where?: never; params?: never } | { from: string; where: string; params?: string[]; on?: never };
+export type Edge = Match & { table: string; blob?: { bucket: string; keyColumn: string } };
+export type Redaction = Match & { table: string; set: Record<string, Cell>; reason: string };
+export interface AuditReference { table: string; column: string; of: string; where?: string; clear?: Record<string, Cell> }
+export interface Retained { table: string; reason: string }
+export type PolicyInput = { db: D1Database; subject: Key; label: string };
+export type RootRedaction = { identityColumns?: string[]; set: Record<string, Cell> | ((input: { subject: Key; anonymousId: string }) => Record<string, Cell> | Promise<Record<string, Cell>>); reason: string };
+export interface Declaration {
+  entity: string;
+  root: { table: string; redact?: RootRedaction };
+  edges?: Edge[];
+  redact?: Redaction[];
+  audit?: AuditReference[];
+  retain?: Retained[];
+  /** Seed policy: a reason refuses the erasure (409 `held:<reason>`). */
+  hold?: (input: { db: D1Database; subject: Key }) => string | null | undefined | Promise<string | null | undefined>;
+  /** Durable policy SQL before the first dependent deletion; also used by nativeStatements. */
+  beforeStatements?: (input: PolicyInput) => D1PreparedStatement[] | Promise<D1PreparedStatement[]>;
+  /** Final policy effects after graph deletion, before verification and the receipt. */
+  statements?: (input: { db: D1Database; subject: Key; label: string }) => D1PreparedStatement[] | Promise<D1PreparedStatement[]>;
+}
+export interface Defined extends Readonly<Required<Omit<Declaration, 'hold' | 'beforeStatements' | 'statements'>>> { hold?: Declaration['hold']; beforeStatements?: Declaration['beforeStatements']; statements?: Declaration['statements']; deleted: string[]; tracked: string[] }
+export interface Preview {
+  entity: string; planHash: string; blobs: number; hold: string | null;
+  deleted: Record<string, number>; redacted: Record<string, number>; audited: Record<string, number>; retained: Retained[];
+}
+export interface Receipt {
+  id: string; entity: string; phase: 'deleting' | 'blobs' | 'complete'; label: string;
+  planned: Record<string, number>; deleted: Record<string, number>; retained: Retained[];
+  blobs: { total: number; deleted: number };
+  requestedAt: string; committedAt: string | null; completedAt: string | null; seconds: number | null;
+}
+export interface D1Sql { sql: string; params: unknown[] }
+export interface PortabilityFence {
+  erasureStatements(table: string, primaryKey: Key): Promise<D1PreparedStatement[]>;
+  /** Required when any declaration uses root.redact. */
+  redactionStatements?(): Promise<D1PreparedStatement[]>;
+  invalidateTransfersStatements(): Promise<D1PreparedStatement[]>;
+}
+export interface Erasure {
+  preview(entity: string, subject: Key): Promise<Preview>;
+  start(entity: string, subject: Key, options?: { planHash?: string }): Promise<Receipt>;
+  commit(id: string, options?: { rows?: number; until?: number }): Promise<Receipt>;
+  deleteBlobs(id: string, options?: { until?: number; page?: number }): Promise<Receipt>;
+  run(id: string, options?: { rows?: number; until?: number }): Promise<Receipt>;
+  receipt(id: string): Promise<Receipt>;
+  nativeStatements(entity: string, subject: Key): Promise<{ operationId: string; statements: D1Sql[] }>;
+}
+export function defineErasure(declaration: Declaration): Defined;
+export function createErasure(options: { db: D1Database; buckets?: Record<string, R2Bucket>; portability: PortabilityFence; declarations: (Declaration | Defined)[] }): Erasure;
+export function toD1Sql(statement: D1PreparedStatement): D1Sql;
+export class ErasureError extends Error { code: string; status: number; constructor(code: string, status?: number) }
+/** Attributable rate-limit or counter rows: see README "Attributable counters". */
+/** `live`: SQL predicate over the root row, true while the subject may be counted.
+ * Required when the declaration's root is redacted (it must be false after redaction). */
+export interface RateRoot { table: string; column: string; live?: string }
+export interface RateSpec { entity: string; root: RateRoot; subject: Cell; rateTable: string; rateKey: string }
+export function rateEdges(options: { entity: string; root: RateRoot; counters: { table: string; keyColumn: string }[] }): Edge[];
+export function rateCorrelation(db: D1Database, spec: RateSpec): D1PreparedStatement[];
+export function rateWrite(db: D1Database, spec: RateSpec, statements: D1PreparedStatement[]): Promise<D1Result[]>;

package/modules/erasure/index.mjs

@@ -0,0 +1,85 @@
+import { defineErasure, buckets as declaredBuckets } from './declaration.mjs';
+import { collect, counts, planHash, checkDeclared } from './plan.mjs';
+import { step, firstStatements, cleanupStatements, deletionStatements, finalStatements } from './cascade.mjs';
+import { verificationStatements } from './verification.mjs';
+import { scopeStatements } from './scope.mjs';
+import { deleteBlobs } from './blobs.mjs';
+import { newLabel } from './audit.mjs';
+import { receipt, activeFor, openStatement, progressStatement } from './receipt.mjs';
+import { fenceCalls, toD1Sql } from './fence.mjs';
+import { insist, randomHex } from './sql.mjs';
+export { defineErasure } from './declaration.mjs';
+export { ErasureError } from './sql.mjs';
+export { toD1Sql } from './fence.mjs';
+export { rateEdges, rateCorrelation, rateWrite } from './rate.mjs';
+
+export function createErasure({ db, buckets = {}, portability, declarations }) {
+  const list = declarations.map(d => d.deleted ? d : defineErasure(d));
+  insist(new Set(list.map(d => d.entity)).size === list.length, 'duplicate_entity');
+  for (const name of declaredBuckets(list)) insist(buckets[name] && typeof buckets[name].delete === 'function' && typeof buckets[name].head === 'function', 'missing_bucket:' + name);
+  if (list.some(d => d.root.redact)) insist(typeof portability?.redactionStatements === 'function', 'portability_redaction_service');
+  const ctx = { db, buckets, fence: fenceCalls(portability) };
+  const entity = name => { const d = list.find(x => x.entity === name); insist(d, 'unknown_entity', 404); return d; };
+  const subjectPlan = async (d, subject) => { const plan = await collect(db, d, subject); insist(plan, 'subject_not_found', 404); await checkDeclared(db, d); return plan; };
+  async function summary(d, plan) {
+    const totals = await counts(db, d, plan);
+    return { ...totals, retained: [...d.retain.map(({ table, reason }) => ({ table, reason })), ...(d.root.redact ? [{ table: d.root.table, reason: d.root.redact.reason }] : [])], planHash: await planHash(d, plan, totals) };
+  }
+  async function opened(id) { return entity((await receipt(db, id)).entity); }
+  const service = {
+    /** Counts only: no stored value of the subject or its dependents is returned. */
+    async preview(name, subject) {
+      const d = entity(name), plan = await subjectPlan(d, subject), result = await summary(d, plan);
+      return { entity: d.entity, ...result, hold: d.hold ? await d.hold({ db, subject: plan.subject }) ?? null : null };
+    },
+    /** Opens (or returns the already open) erasure for one subject. */
+    async start(name, subject, { planHash: expected } = {}) {
+      const d = entity(name), active = await activeFor(db, d, subject);
+      if (active) return active;
+      const plan = await subjectPlan(d, subject), totals = await summary(d, plan);
+      if (expected !== undefined) insist(expected === totals.planHash, 'plan_changed', 409);
+      const reason = d.hold ? await d.hold({ db, subject: plan.subject }) : null;
+      insist(!reason, 'held:' + reason, 409);
+      const id = randomHex(16);
+      try { await openStatement(db, d, { id, subject: plan.subject, label: newLabel(), planned: totals.deleted, blobs: totals.blobs, now: new Date().toISOString() }).run(); }
+      catch (error) { const raced = await activeFor(db, d, subject); if (raced) return raced; throw error; }
+      return receipt(db, id);
+    },
+    /** D1 phase: bounded atomic steps until every row is gone or `until` passes. */
+    async commit(id, { rows, until = Infinity } = {}) {
+      const d = await opened(id);
+      let changes = 0;
+      for (;;) {
+        const result = await step(ctx, d, id, { rows });
+        if (result === 'changed') {
+          insist(++changes < 3, 'erasure_scope_unstable', 409);
+        } else changes = 0;
+        if (!result || Date.now() > until) break;
+      }
+      return receipt(db, id);
+    },
+    /** Blob phase: separately callable, resumable, complete only when every object is gone. */
+    async deleteBlobs(id, options) { await deleteBlobs(ctx, await opened(id), id, options); return receipt(db, id); },
+    async run(id, { rows, until = Infinity } = {}) {
+      const after = await service.commit(id, { rows, until });
+      return after.phase === 'blobs' && Date.now() <= until ? service.deleteBlobs(id, { until }) : after;
+    },
+    receipt: id => receipt(db, id),
+    /** The whole D1 phase as import-kit `D1Sql`, for `eraseD1ImportTarget(kind,id,nativeStatements,ctx)`.
+     * Run `deleteBlobs(operationId)` after that batch commits. */
+    async nativeStatements(name, subject) {
+      const d = entity(name);
+      insist(!await activeFor(db, d, subject), 'erasure_open', 409);
+      const plan = await subjectPlan(d, subject), totals = await summary(d, plan);
+      const reason = d.hold ? await d.hold({ db, subject: plan.subject }) : null;
+      insist(!reason, 'held:' + reason, 409);
+      const id = randomHex(16), label = newLabel(), now = new Date().toISOString(), deleted = {};
+      const statements = [...await ctx.fence.transfers(), openStatement(db, d, { id, subject: plan.subject, label, planned: totals.deleted, blobs: totals.blobs, now }),
+        ...await scopeStatements(db, d, plan, id), ...await firstStatements(ctx, d, plan, label), ...await verificationStatements(db, d, plan, id, label), ...cleanupStatements(ctx, d, plan, label), ...await deletionStatements(ctx, d, plan, plan.order, id, deleted),
+        ...await finalStatements(ctx, d, plan, id, label, now, deleted), progressStatement(db, id, 0, deleted), db.prepare('DELETE FROM rer_erasure_guard')];
+      return { operationId: id, statements: statements.map(toD1Sql) };
+    },
+  };
+  return service;
+}
+

package/modules/erasure/order.mjs

@@ -0,0 +1,56 @@
+import { all, canonicalJson, insist, quote } from './sql.mjs';
+import { matching } from './plan.mjs';
+
+/** Topological row order across every path, not the depth of the first visit.
+ * Actual FK links also constrain order, even if a row was reached by another edge. */
+export async function deletionOrder(db, d, plan) {
+  const id = e => e.table + '\0' + canonicalJson(e.key);
+  const selected = plan.entries.filter(e => d.deleted.includes(e.table));
+  const entries = new Map(selected.map(e => [id(e), e]));
+  const children = new Map(selected.map(e => [id(e), new Set()]));
+  const link = (parent, child) => {
+    if (id(parent) !== id(child) && children.has(id(parent)) && entries.has(id(child))) children.get(id(parent)).add(id(child));
+  };
+  for (const edge of d.edges) for (const parent of plan.rows.get(edge.from).values()) {
+    const keys = plan.keys.get(edge.table).pk;
+    for (const row of await matching(db, edge, [parent.row], keys.map(c => c === 'rowid' ? 'rowid AS rowid' : quote(c)).join(','))) {
+      const child = entries.get(edge.table + '\0' + canonicalJson(Object.fromEntries(keys.map(c => [c, row[c]]))));
+      if (child) link(parent, child);
+    }
+  }
+  plan.foreignKeys = [];
+  for (const table of d.deleted) {
+    const groups = new Map();
+    for (const fk of await all(db, `PRAGMA foreign_key_list(${quote(table)})`)) {
+      if (!groups.has(fk.id)) groups.set(fk.id, []);
+      groups.get(fk.id).push(fk);
+    }
+    for (const group of groups.values()) {
+      const parentTable = d.deleted.find(name => name.toLowerCase() === group[0].table.toLowerCase());
+      const parents = parentTable && plan.rows.get(parentTable);
+      if (parentTable) plan.foreignKeys.push({ table, parentTable, group });
+      if (!parents) continue;
+      for (const parent of parents.values()) {
+        const parentKeys = plan.keys.get(parent.table).pk;
+        // Read the actual join: FK columns need not be part of a declared edge's projection.
+        const cols = plan.keys.get(table).pk;
+        const found = await all(db, `SELECT ${cols.map(c => c === 'rowid' ? 'rowid AS rowid' : quote(c)).join(',')} FROM ${quote(table)} WHERE ${group.map(f => `${quote(f.from)}=(SELECT ${quote(f.to || parentKeys[f.seq])} FROM ${quote(parent.table)} WHERE ${parentKeys.map(c => `${quote(c)}=?`).join(' AND ')})`).join(' AND ')}`, ...group.flatMap(() => parentKeys.map(c => parent.key[c])));
+        for (const row of found) {
+          const child = entries.get(table + '\0' + canonicalJson(Object.fromEntries(cols.map(c => [c, row[c]]))));
+          insist(child, `unreached_dependent:${table}:${parent.table}`, 409);
+          link(parent, child);
+        }
+      }
+    }
+  }
+  const remaining = new Map([...children].map(([key, deps]) => [key, deps.size]));
+  const parents = new Map(selected.map(e => [id(e), []]));
+  for (const [parent, deps] of children) for (const child of deps) parents.get(child).push(parent);
+  const queue = [...remaining].filter(([, n]) => n === 0).map(([key]) => key), result = [];
+  for (let i = 0; i < queue.length; i++) {
+    const key = queue[i]; result.push(entries.get(key));
+    for (const parent of parents.get(key)) { remaining.set(parent, remaining.get(parent) - 1); if (remaining.get(parent) === 0) queue.push(parent); }
+  }
+  insist(result.length === entries.size, 'cyclic_deletion_graph', 409);
+  return result.filter(e => e !== plan.root);
+}

package/modules/erasure/plan.mjs

@@ -0,0 +1,121 @@
+import { deletionOrder } from './order.mjs';
+import { rootValues } from './root.mjs';
+import { redactionEndsRates } from './rate.mjs';
+import { all, statement, quote, insist, canonicalJson, sha256, chunks } from './sql.mjs';
+
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+
+export async function tableKeys(db, table) {
+  const columns = await all(db, `PRAGMA table_info(${quote(table)})`);
+  insist(columns.length > 0, 'unknown_table:' + table);
+  const pk = columns.filter(c => c.pk).sort((a, b) => a.pk - b.pk).map(c => c.name);
+  return { columns: columns.map(c => c.name), pk: pk.length ? pk : ['rowid'] };
+}
+
+/** Every table holding a foreign key into a deleted table must itself be declared,
+ * so an ON DELETE action can never remove (or orphan) a row erasure did not fence. */
+export async function checkDeclared(db, d) {
+  const declared = new Set([...d.tracked, ...d.redact.map(r => r.table), ...d.audit.map(a => a.table), ...d.retain.map(r => r.table)].map(t => t.toLowerCase()));
+  const tables = await all(db, "SELECT name,sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL ORDER BY name");
+  for (const table of tables.filter(t => /\bREFERENCES\b/i.test(t.sql))) {
+    for (const fk of await all(db, `PRAGMA foreign_key_list(${quote(table.name)})`)) {
+      if (d.tracked.some(t => same(t, fk.table))) {
+        insist(declared.has(table.name.toLowerCase()), `undeclared_dependent:${table.name}:${fk.table}`, 409);
+        if (d.deleted.some(t => same(t, fk.table)) && !d.deleted.some(t => same(t, table.name))) insist(!['CASCADE', 'SET NULL', 'SET DEFAULT'].includes(fk.on_delete), `unsafe_retained_fk:${table.name}:${fk.table}`, 409);
+      }
+    }
+  }
+}
+
+function needed(d, keys) {
+  const columns = new Map(d.tracked.map(t => [t, new Set(keys.get(t).pk)]));
+  for (const c of d.root.redact?.identityColumns ?? []) columns.get(d.root.table).add(c);
+  for (const item of [...d.edges, ...d.redact]) for (const c of item.on ? Object.values(item.on) : item.params ?? []) columns.get(item.from).add(c);
+  for (const edge of d.edges.filter(e => e.blob)) columns.get(edge.table).add(edge.blob.keyColumn);
+  return columns;
+}
+const projection = columns => [...columns].map(c => c === 'rowid' ? 'rowid AS rowid' : quote(c)).join(',');
+
+export function matchSql(item, parents) {
+  if (!item.on) return parents.map(p => ({ where: `(${item.where})`, values: (item.params ?? []).map(c => p[c]) }));
+  const pairs = Object.entries(item.on);
+  const tuples = parents.map(p => pairs.map(([, parent]) => p[parent])).filter(t => t.every(v => v !== null && v !== undefined));
+  const where = `EXISTS(SELECT 1 FROM json_each(?) j WHERE ${pairs.map(([child], i) => `${quote(item.table)}.${quote(child)}=json_extract(j.value,'$[${i}]')`).join(' AND ')})`;
+  return chunks(tuples, 200).map(part => ({ where, values: [JSON.stringify(part)] }));
+}
+
+/** Reads rows of the item's table reachable from `parents` through one edge. */
+export async function matching(db, item, parents, select) {
+  const found = [];
+  for (const m of matchSql(item, parents)) found.push(...await all(db, `SELECT ${select} FROM ${quote(item.table)} WHERE ${m.where}`, ...m.values));
+  return found;
+}
+
+/** Closes the declared graph from one subject to a fixed point. Rows carry only
+ * key, linking and blob-key columns: no personal value leaves this function. */
+export async function collect(db, d, subject, remembered = []) {
+  const keys = new Map();
+  for (const t of new Set([...d.tracked, ...d.redact.map(r => r.table)])) keys.set(t, await tableKeys(db, t));
+  for (const item of d.audit) insist(keys.get(item.of).pk.length === 1, 'audit_composite_key:' + item.of);
+  const columns = needed(d, keys), rootKey = keys.get(d.root.table).pk;
+  if (d.root.redact) await redactionEndsRates(db, d, await rootValues(d, keys.get(d.root.table), subject, 'erased:admission'));
+  insist(subject && typeof subject === 'object' && canonicalJson(Object.keys(subject).sort()) === canonicalJson([...rootKey].sort()), 'subject_key');
+  const rows = new Map(d.tracked.map(t => [t, new Map()]));
+  const keyOf = (table, row) => Object.fromEntries(keys.get(table).pk.map(c => [c, row[c]]));
+  const root = await statement(db, `SELECT ${projection(columns.get(d.root.table))} FROM ${quote(d.root.table)} WHERE ${rootKey.map(c => `${c === 'rowid' ? 'rowid' : quote(c)}=?`).join(' AND ')}`, ...rootKey.map(c => subject[c])).first();
+  if (!root && !remembered.length) return null;
+  if (root) rows.get(d.root.table).set(canonicalJson(keyOf(d.root.table, root)), { table: d.root.table, key: keyOf(d.root.table, root), row: root, depth: 0 });
+  const known = new Map(d.tracked.map(t => [t, new Map()]));
+  const remember = (table, row) => known.get(table).set(canonicalJson(row), row);
+  for (const e of remembered) remember(e.table, e.row);
+  for (const [table, old] of known) {
+    const pk = keys.get(table).pk;
+    for (const part of chunks([...old.values()], 200)) {
+      const found = await all(db, `SELECT ${projection(columns.get(table))} FROM ${quote(table)} WHERE EXISTS(SELECT 1 FROM json_each(?) j WHERE ${pk.map((c, i) => `${quote(c)} IS json_extract(j.value,'$[${i}]')`).join(' AND ')})`, JSON.stringify(part.map(row => pk.map(c => row[c]))));
+      for (const row of found) { remember(table, row); const key = keyOf(table, row); rows.get(table).set(canonicalJson(key), { table, key, row, depth: 1 }); }
+    }
+  }
+  if (root) remember(d.root.table, root);
+  let frontier = new Map([...known].filter(([, r]) => r.size).map(([t, r]) => [t, [...r.values()]])), depth = 0;
+  while (frontier.size) {
+    const next = new Map(); depth++;
+    for (const edge of d.edges) {
+      const parents = frontier.get(edge.from);
+      if (!parents?.length) continue;
+      for (const row of await matching(db, edge, parents, projection(columns.get(edge.table)))) {
+        const key = keyOf(edge.table, row), id = canonicalJson(key);
+        if (rows.get(edge.table).has(id)) continue;
+        remember(edge.table, row);
+        rows.get(edge.table).set(id, { table: edge.table, key, row, depth });
+        if (!next.has(edge.table)) next.set(edge.table, []);
+        next.get(edge.table).push(row);
+      }
+    }
+    frontier = next;
+  }
+  const entries = [...rows.values()].flatMap(m => [...m.values()]);
+  const plan = { subject, root: root ? rows.get(d.root.table).get(canonicalJson(subject)) : null, keys, rows, entries, known };
+  plan.order = await deletionOrder(db, d, plan);
+  return plan;
+}
+
+export async function counts(db, d, plan) {
+  const deleted = Object.fromEntries(d.deleted.map(t => [t, plan.rows.get(t).size]).filter(([, n]) => n));
+  const parents = table => [...plan.rows.get(table).values()].map(e => e.row);
+  const redacted = d.root.redact ? { [d.root.table]: plan.rows.get(d.root.table).size } : {}, audited = {};
+  for (const item of d.redact) for (const m of matchSql(item, parents(item.from))) {
+    redacted[item.table] = (redacted[item.table] ?? 0) + (await statement(db, `SELECT count(*) AS n FROM ${quote(item.table)} WHERE ${m.where}`, ...m.values).first()).n;
+  }
+  for (const item of d.audit) for (const part of chunks([...plan.rows.get(item.of).values()].map(e => Object.values(e.key)[0]), 200)) {
+    audited[item.table] = (audited[item.table] ?? 0) + (await statement(db, `SELECT count(*) AS n FROM ${quote(item.table)} WHERE ${quote(item.column)} IN (SELECT value FROM json_each(?))${item.where ? ` AND (${item.where})` : ''}`, JSON.stringify(part)).first()).n;
+  }
+  const blobKeys = new Set();
+  for (const e of d.edges.filter(e => e.blob)) for (const x of plan.rows.get(e.table).values()) if (x.row[e.blob.keyColumn] != null) blobKeys.add(canonicalJson([e.blob.bucket, x.row[e.blob.keyColumn]]));
+  const blobs = blobKeys.size;
+  return { deleted, redacted, audited, blobs };
+}
+
+export async function planHash(d, plan, summary) {
+  const rows = Object.fromEntries([...plan.rows].map(([t, m]) => [t, [...m.keys()].sort()]));
+  return sha256(canonicalJson({ entity: d.entity, subject: plan.subject, rows, summary }));
+}

package/modules/erasure/rate.mjs

@@ -0,0 +1,57 @@
+import { ErasureError, guard, insist, quote } from './sql.mjs';
+
+const LINKS = 'rer_erasure_rates';
+const ident = value => typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value);
+const entityName = value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,63}$/.test(value);
+
+// `root.live` is an SQL predicate over the root row that is true while its
+// subject may still be counted. A redacted root survives erasure under the same
+// key, so its declaration must give one that the redaction makes false.
+const live = root => root.live === undefined || (typeof root.live === 'string' && root.live.trim().length > 0);
+const present = root => `SELECT 1 FROM ${quote(root.table)} WHERE ${quote(root.column)}=?${root.live ? ` AND (${root.live})` : ''}`;
+
+/** Edges for a declaration's `edges`: the correlation rows of one subject, then
+ * every counter row they name. Counters are deleted before their links. */
+export function rateEdges({ entity, root, counters }) {
+  insist(entityName(entity) && ident(root?.table) && ident(root?.column) && live(root), 'rate_root');
+  insist(Array.isArray(counters) && counters.length > 0 && counters.every(c => ident(c.table) && ident(c.keyColumn)), 'rate_counters');
+  return [
+    { table: LINKS, from: root.table, where: `entity='${entity}' AND subject=?`, params: [root.column], rate: { live: root.live ?? null } },
+    ...counters.map(c => ({ table: c.table, from: LINKS, where: `${quote(c.keyColumn)}=? AND ?='${c.table}'`, params: ['rate_key', 'rate_table'] })),
+  ];
+}
+
+/** Statements to put before the counter upsert in the SAME batch: they abort the
+ * batch when the subject row is already gone or no longer live, then record who
+ * the counter key belongs to. */
+export function rateCorrelation(db, { entity, root, subject, rateTable, rateKey }) {
+  insist(entityName(entity) && ident(root?.table) && ident(root?.column) && live(root) && ident(rateTable), 'rate_root');
+  insist(subject !== null && subject !== undefined && typeof rateKey === 'string' && rateKey.length > 0, 'rate_subject');
+  return [
+    guard(db, `EXISTS(${present(root)})`, subject),
+    db.prepare('DELETE FROM rer_erasure_guard'),
+    db.prepare(`INSERT OR IGNORE INTO ${LINKS}(rate_table,rate_key,entity,subject) VALUES(?,?,?,?)`).bind(rateTable, rateKey, entity, String(subject)),
+  ];
+}
+
+/** Runs `statements` (the seed's counter upserts) with their correlation in one
+ * batch and returns their results. A subject erased before the write refuses with
+ * `subject_gone` (409) and nothing is written. */
+export async function rateWrite(db, spec, statements) {
+  const link = rateCorrelation(db, spec);
+  try { return (await db.batch([...link, ...statements])).slice(link.length); }
+  catch (error) {
+    if (!await db.prepare(present(spec.root)).bind(spec.subject).first()) throw new ErasureError('subject_gone', 409);
+    throw error;
+  }
+}
+
+/** Refuses a root redaction that would leave a rate root live: correlated writes
+ * naming the retained key would then still be admitted after erasure. */
+export async function redactionEndsRates(db, d, set) {
+  for (const edge of d.edges.filter(e => e.rate && e.from === d.root.table)) {
+    const columns = Object.keys(set);
+    const live = await db.prepare(`SELECT 1 AS live FROM (SELECT ${columns.map(c => `? AS ${quote(c)}`).join(',')}) WHERE (${edge.rate.live})`).bind(...Object.values(set)).first().catch(() => ({ live: 1 }));
+    insist(!live, 'rate_root_live', 409);
+  }
+}