@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/deploy-kit/templates.mjs

@@ -0,0 +1,31 @@
+import { access, mkdir, readdir, copyFile, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assert } from './validation.mjs';
+const base = resolve(dirname(fileURLToPath(import.meta.url)),'../..');
+/** Generate alongside an edition. The existing edition tree is never an output directory. */
+export async function createTemplates({destination,project,sourcePaths,commands,loops=[]}) {
+  assert(/^[a-z0-9-]+\/[a-z0-9-]+$/.test(project),'invalid-project');
+  assert(Array.isArray(sourcePaths) && sourcePaths.length && sourcePaths.every(x => typeof x === 'string' && x.length),'missing-actual-source-paths');
+  const root = resolve(destination);
+  await mkdir(root,{recursive:false});
+  // A new directory only: callers add actual edition sources then run the lock command.
+  const scripts = join(root,'scripts'); await mkdir(scripts);
+  await mkdir(join(scripts,'edition-authoring'));
+  for (const name of ['operations.mjs','project-operations.mjs']) await copyFile(join(base,'operations',name),join(scripts,name),constants.COPYFILE_EXCL);
+  for (const name of await readdir(join(base,'edition-authoring'))) if (name.endsWith('.mjs') && !name.endsWith('.test.mjs')) await copyFile(join(base,'edition-authoring',name),join(scripts,'edition-authoring',name),constants.COPYFILE_EXCL);
+  await writeFile(join(root,'OPERATIONS.json'),JSON.stringify({version:2,project,runtime:{requirements:[{name:'node',version:'>=22.12.0'}]},requiredEnvironment:[],commands,loops},null,2)+'\n',{flag:'wx'});
+  await writeFile(join(root,'edition.json'),JSON.stringify({schemaVersion:1,id:project,toolchain:{id:'runeditrun/edition-authoring',version:'1.1.0'},parent:null,components:[{id:project,role:'edition',source:{kind:'local',paths:sourcePaths}}]},null,2)+'\n',{flag:'wx'});
+  return {root,lock:['node','scripts/edition-authoring/cli.mjs','lock'],check:['node','scripts/edition-authoring/cli.mjs','check']};
+}
+/** Actual authoring tool creates the lock and retained sources; no hand-forged lock template. */
+export async function lockTemplates(root) {
+  try { await access(join(root,'sources.lock.json')); throw new Error('existing-source-lock-refused'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const env = {PATH:process.env.PATH,HOME:process.env.HOME};
+  for (const command of ['lock','check']) {
+    try { execFileSync(process.execPath,[join(base,'edition-authoring/cli.mjs'),command],{cwd:root,env,stdio:'pipe',timeout:60000,maxBuffer:1024*1024}); }
+    catch { throw new Error('edition-authoring-failed'); }
+  }
+}

package/modules/deploy-kit/validation.mjs

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+export const hash = value => createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : stable(value)).digest('hex');
+export function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export function assert(value, code) { if (!value) throw new Error(code); }
+export const identifier = value => typeof value === 'string' && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value);
+export const resourceName = value => typeof value === 'string' && /^[a-z][a-z0-9-]{2,62}$/.test(value);
+export const uuid = value => typeof value === 'string' && /^(?!00000000-0000-0000-0000-000000000000)[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(value);
+export const hexId = value => typeof value === 'string' && /^[a-f0-9]{32}$/i.test(value) && !/^0+$/.test(value);
+export function localPath(value) { assert(typeof value === 'string' && value.length && !value.startsWith('/') && !value.includes('\\') && value.split('/').every(x => x && x !== '.' && x !== '..') && !/[\x00-\x1f]/.test(value), 'invalid-local-path'); return value; }
+/** Declared KV namespaces; absent means none. */
+export const kvOf = plan => plan.kv ?? [];
+export function validatePlan(plan) {
+  assert(plan?.version === 1 && resourceName(plan.worker) && /^\d{4}-\d{2}-\d{2}$/.test(plan.compatibilityDate), 'invalid-plan');
+  for (const key of ['d1','r2','queues','durableObjects','secrets','crons']) assert(Array.isArray(plan[key]), 'invalid-plan-resources');
+  // KV is optional so plans written before KV support keep their exact shape.
+  assert(plan.kv === undefined || Array.isArray(plan.kv), 'invalid-plan-resources');
+  const kv = kvOf(plan);
+  const bindings = new Set(['RER_DEPLOY_SOURCE','RER_DEPLOY_FINGERPRINT','RER_VERSION']);
+  // Service bindings and the workers.dev opt-out are optional so earlier plans keep their exact shape.
+  assert(plan.services === undefined || Array.isArray(plan.services) && plan.services.length, 'invalid-plan-resources');
+  assert(plan.workersDev === undefined || plan.workersDev === false, 'invalid-plan');
+  for (const entry of [...plan.d1,...plan.r2,...kv,...plan.queues,...plan.durableObjects,...plan.secrets,...(plan.services ?? [])]) {
+    assert(identifier(entry.binding) && !bindings.has(entry.binding), 'duplicate-or-invalid-binding'); bindings.add(entry.binding);
+  }
+  for (const entry of [...plan.d1,...plan.r2,...kv,...plan.queues]) assert(resourceName(entry.name), 'invalid-resource-name');
+  for (const list of [plan.d1,plan.r2,kv,plan.queues]) assert(new Set(list.map(x => x.name)).size === list.length, 'duplicate-resource-name');
+  for (const entry of plan.d1) assert(Array.isArray(entry.migrations), 'invalid-migrations');
+  for (const entry of plan.durableObjects) assert(identifier(entry.className) && ['sqlite','classic'].includes(entry.storage), 'invalid-durable-object');
+  for (const secret of plan.secrets) assert(identifier(secret.environment), 'invalid-secret-environment');
+  for (const item of plan.services ?? []) assert(Object.keys(item).every(k => ['binding','service','entrypoint','props','grant'].includes(k)) && resourceName(item.service) && item.service !== plan.worker
+    && (item.entrypoint === undefined || identifier(item.entrypoint))
+    && (item.props === undefined || Object.keys(item.props).join() === 'allowedHosts' && Array.isArray(item.props.allowedHosts)
+      && item.props.allowedHosts.every(host => typeof host === 'string' && /^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(host))), 'invalid-service-binding');
+  for (const item of plan.services ?? []) if (item.grant !== undefined) {
+    const grant = item.grant;
+    assert(item.entrypoint && !item.props && grant && Object.keys(grant).sort().join() === 'allowedHosts,fingerprint,provider,sourceSha'
+      && /^[a-f0-9]{40}$/.test(grant.sourceSha) && /^[a-f0-9]{64}$/.test(grant.fingerprint)
+      && grant.provider && Object.keys(grant.provider).sort().join() === 'deploymentId,etag,versionId'
+      && uuid(grant.provider.versionId) && uuid(grant.provider.deploymentId) && typeof grant.provider.etag === 'string' && grant.provider.etag.length > 0
+      && (grant.allowedHosts === null || Array.isArray(grant.allowedHosts) && new Set(grant.allowedHosts).size === grant.allowedHosts.length
+        && grant.allowedHosts.every(host => typeof host === 'string' && /^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(host))), 'invalid-service-grant');
+  }
+  for (const cron of plan.crons) assert(typeof cron === 'string' && /^[\d*/,-]+(?: [\d*/,-]+){4}$/.test(cron), 'invalid-cron');
+  assert(new Set(plan.crons).size === plan.crons.length, 'duplicate-cron');
+  for (const [key,value] of Object.entries(plan.vars ?? {})) assert(identifier(key) && !bindings.has(key) && typeof value === 'string', 'invalid-public-variable');
+  for (const queue of plan.queues) {
+    if (queue.deadLetterQueue !== undefined) assert(queue.consumer && resourceName(queue.deadLetterQueue) && queue.deadLetterQueue !== queue.name && plan.queues.some(x => x.name === queue.deadLetterQueue && !x.consumer), 'invalid-dead-letter-queue');
+    if (queue.consumer) {
+    assert(Object.keys(queue.consumer).every(k => ['batch_size','max_retries','max_wait_time_ms','max_concurrency','retry_delay'].includes(k)), 'invalid-consumer-setting');
+    assert(Object.values(queue.consumer).every(x => Number.isSafeInteger(x) && x >= 0), 'invalid-consumer-setting');
+  }
+  }
+  return plan;
+}

package/modules/deploy-kit/worker.mjs

@@ -0,0 +1,105 @@
+import { extname } from 'node:path';
+import { assert, hash, hexId, uuid } from './validation.mjs';
+import { moduleType, assetType } from './artifact.mjs';
+import { RUN_WORKER_FIRST } from './render.mjs';
+
+export async function activeWorker(api, worker) {
+  let settings;
+  try { settings = await api.request(`/workers/scripts/${worker}/settings`); }
+  catch (error) { if (error.status === 404) return null; throw error; }
+  assert(Array.isArray(settings.bindings),'invalid-worker-settings');
+  const result = await api.request(`/workers/scripts/${worker}/deployments`);
+  assert(Array.isArray(result.deployments) && result.deployments.length > 0, 'invalid-deployments');
+  const deployment = result.deployments[0];
+  assert(uuid(deployment.id) && deployment.versions?.length === 1 && deployment.versions[0].percentage === 100 && uuid(deployment.versions[0].version_id), 'mixed-or-invalid-deployment');
+  const versionId = deployment.versions[0].version_id;
+  const version = await api.request(`/workers/scripts/${worker}/versions/${versionId}`);
+  assert(version.id === versionId && typeof version.resources?.script?.etag === 'string' && version.resources.script.etag.length > 0, 'invalid-active-version');
+  return {settings,versionId,deploymentId:deployment.id,etag:version.resources.script.etag,version};
+}
+/** Read authenticated runtime detection, never infer handlers from uploaded source text. */
+export function verifyScheduledHandler(active, plan) {
+  if (plan.crons.length) assert(Array.isArray(active?.version?.resources?.script?.handlers) && active.version.resources.script.handlers.includes('scheduled'), 'missing-scheduled-handler');
+}
+/** The build fingerprint a Worker's settings (or an upload's metadata) carry as a plain-text binding. */
+export const deployedFingerprint = settings => settings?.bindings?.find(x => x.type === 'plain_text' && x.name === 'RER_DEPLOY_FINGERPRINT')?.text;
+export async function durableNamespaces(api, plan, { requireAll = false } = {}) {
+  if (!plan.durableObjects.length) return [];
+  const rows = await api.list('/workers/durable_objects/namespaces');
+  return plan.durableObjects.map(item => {
+    const selected = rows.filter(x => x.script === plan.worker && x.class === item.className);
+    assert(selected.length <= 1, 'ambiguous-durable-object');
+    if (!selected.length) { assert(!requireAll,'missing-durable-object'); return {...item,id:null}; }
+    const row = selected[0]; assert(hexId(row.id) && row.use_sqlite === (item.storage === 'sqlite'), 'incompatible-durable-object');
+    return {...item,id:row.id};
+  });
+}
+export function durableMigration(namespaces, current) {
+  const missing = namespaces.filter(x => !x.id);
+  if (!missing.length) return undefined;
+  assert(missing.every(x => x.storage === 'sqlite'),'new-durable-objects-require-sqlite');
+  const old = current?.settings.migration_tag ?? '';
+  return {old_tag:old,new_tag:`rer-${hash({old,classes:missing.map(x => x.className)}).slice(0,24)}`,new_sqlite_classes:missing.map(x => x.className)};
+}
+export async function secretBindings(api, worker, plan, env, exists) {
+  const present = exists ? await api.request(`/workers/scripts/${worker}/secrets`) : [];
+  assert(Array.isArray(present) && present.every(x => typeof x.name === 'string' && x.type === 'secret_text'),'invalid-secret-list');
+  const bindings = []; const names = present.map(x => x.name);
+  for (const item of plan.secrets) {
+    if (names.includes(item.binding)) bindings.push({type:'inherit',name:item.binding});
+    else {
+      assert(typeof env[item.environment] === 'string' && env[item.environment].trim(), `missing-secret-${item.environment}`);
+      bindings.push({type:'secret_text',name:item.binding,text:env[item.environment]});
+    }
+  }
+  return {bindings,names,missing:plan.secrets.filter(x => !names.includes(x.binding)).map(x => x.binding)};
+}
+export async function uploadAssets(api, worker, files) {
+  const manifest = {}; const byHash = new Map();
+  for (const file of files) {
+    const digest = hash(file.base64 + extname(file.path).slice(1)).slice(0,32);
+    manifest[`/${file.path}`] = {hash:digest,size:Buffer.from(file.base64,'base64').length};
+    byHash.set(digest,file);
+  }
+  const session = await api.request(`/workers/scripts/${worker}/assets-upload-session`,{method:'POST',body:{manifest}});
+  assert(typeof session.jwt === 'string' && session.jwt && Array.isArray(session.buckets),'invalid-asset-session');
+  let completion = session.buckets.length ? null : session.jwt;
+  const seen = new Set();
+  for (const bucket of session.buckets) {
+    assert(Array.isArray(bucket) && bucket.length,'invalid-asset-bucket');
+    const data = new FormData();
+    for (const key of bucket) {
+      assert(byHash.has(key) && !seen.has(key),'invalid-asset-request'); seen.add(key);
+      const file = byHash.get(key); data.set(key,new Blob([file.base64],{type:assetType(file.path)}),file.path.split('/').at(-1));
+    }
+    const uploaded = await api.request('/workers/assets/upload?base64=true',{method:'POST',body:data,assetToken:session.jwt});
+    if (uploaded.jwt) completion = uploaded.jwt;
+  }
+  assert(typeof completion === 'string' && completion,'incomplete-asset-upload');
+  return completion;
+}
+export async function uploadWorker(api, {plan,artifact,bindings,secrets,migration,fingerprint}) {
+  const data = new FormData();
+  const metadata = {main_module:artifact.main,compatibility_date:plan.compatibilityDate,compatibility_flags:plan.compatibilityFlags ?? [],bindings:[...bindings,...secrets.bindings],keep_bindings:['secret_text'],annotations:{'workers/message':`rer-deploy:${fingerprint}`}};
+  if (migration) metadata.migrations = migration;
+  if (artifact.assets.length) { metadata.assets = {jwt:await uploadAssets(api,plan.worker,artifact.assets),config:{run_worker_first:RUN_WORKER_FIRST}}; }
+  data.set('metadata',new Blob([JSON.stringify(metadata)],{type:'application/json'}));
+  for (const file of artifact.modules) data.set(file.path,new Blob([Buffer.from(file.base64,'base64')],{type:moduleType(file.path)}),file.path);
+  await api.request(`/workers/scripts/${plan.worker}?bindings_inherit=strict`,{method:'PUT',body:data});
+}
+/** The workers.dev origin, enabling it when allowed. With `workersDev: false` the route is kept
+ * off (a Worker reached only through service bindings) and there is no origin. */
+export async function workerOrigin(api, worker, { enable = false, workersDev = true } = {}) {
+  if (!workersDev) {
+    const state = await api.request(`/workers/scripts/${worker}/subdomain`);
+    assert(typeof state.enabled === 'boolean','invalid-worker-subdomain');
+    if (state.enabled) { assert(enable,'worker-subdomain-enabled'); await api.request(`/workers/scripts/${worker}/subdomain`,{method:'POST',body:{enabled:false,previews_enabled:false}}); }
+    return null;
+  }
+  const result = await api.request('/workers/subdomain');
+  assert(typeof result.subdomain === 'string' && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(result.subdomain),'invalid-account-subdomain');
+  const state = await api.request(`/workers/scripts/${worker}/subdomain`);
+  assert(typeof state.enabled === 'boolean','invalid-worker-subdomain');
+  if (!state.enabled) { assert(enable,'worker-subdomain-disabled'); await api.request(`/workers/scripts/${worker}/subdomain`,{method:'POST',body:{enabled:true,previews_enabled:false}}); }
+  return `https://${worker}.${result.subdomain}.workers.dev`;
+}

package/modules/erasure/CONTRACT.md

@@ -0,0 +1,90 @@
+# Erasure contract v1
+
+The module erases one subject (an entity that holds personal data) and everything
+declared as depending on it, for BASE-DATA-003. It keeps audit records with an
+anonymised reference, as BASE-OPS-005 requires. Public signatures are in
+`index.d.mts`. The seed owns authorization, confirmation UI, holds and any effect
+outside D1 and R2.
+
+- **ERASE-001 — Declared graph.** A seed declares one root table per entity and
+  the edges that reach its dependents: column equality (`on`) or a bound SQL
+  predicate (`where` + `params` taken from the parent row). A table may be
+  reached through several edges, and the closure runs to a fixed point. Kept
+  rows that must lose columns are declared as `redact` with a reason. Audit
+  references are declared as `audit`. `root.redact` keeps an opaque anonymous
+  root with a reason and explicit replacements for every non-identity column.
+  The same transaction advances the maintained portability redaction checkpoint;
+  old archives are refused with a trusted later journal, and post-redaction
+  archives preserve anonymous attribution. Structural identities are verified.
+  Root-return edges and cyclic deletion dependencies are refused before mutation.
+- **ERASE-002 — No silent dependents.** Before preview or erasure, every table
+  with a foreign key into a tracked table, including a redacted root, must be declared (as an edge, a
+  redaction, an audit reference or a retained exception). Otherwise the call
+  refuses with `undeclared_dependent:<child>:<parent>` (409) and changes
+  nothing. This includes product tables named `rer_*`. Destructive FK actions
+  into retained/redacted/audit rows are refused; retained keys are verified
+  after effects, so `ON DELETE` actions never remove a promised retained row.
+- **ERASE-003 — Preview without values.** `preview` returns counts per deleted,
+  redacted and audited table, the blob count, the retained exceptions, a hold
+  reason if any, and a plan hash. It never returns a stored value.
+- **ERASE-004 — Cascade and fence in one commit.** Every deleted row (dependents
+  leaves-first, the subject row last) is deleted in a D1 batch that also holds
+  portability's `erasureStatements(table, key)` for that row and
+  `invalidateTransfersStatements()`. A batch holds at most `rows` dependents, so
+  deletion work is bounded. Scope/audit and completeness checks also read the
+  declared closure; their cost grows with that closure. A guard on the operation's step
+  counter makes a concurrent runner fail with `erasure_busy` (409) instead of
+  committing twice.
+- **ERASE-005 — Blobs after the commit.** For a declared `blob` edge, each row's
+  object key is recorded in the same batch that deletes the row. Objects are
+  deleted only after that commit. Each recorded key is checked with a read, and
+  leaves the work list only once the object is gone. Repeating the blob phase is
+  safe.
+- **ERASE-006 — Complete means complete.** A receipt reads `deleting` while rows
+  remain, `blobs` once every row is committed but some object may remain, and
+  `complete` only when the final fenced transaction has re-read every declared
+  dependent and audit path, retained/root-redacted rows have been verified, and
+  the blob work list is empty. New dependents restart collection; a persistently
+  changing scope refuses with `erasure_scope_unstable` and remains resumable. `completedAt` and `seconds` are
+  set only at `complete`.
+- **ERASE-007 — Untraceable audit label.** Declared audit references are
+  replaced with one label per erasure, `erased:<128 random bits>`. The label is
+  not derived from the subject, so nobody who holds the database or an older
+  archive can recompute it or test a guess against it. Declared `clear` columns
+  are overwritten. Audit rows for selected dependents are relabelled in every batch. Temporary
+  scope preserves earlier keys until the final pass, catching audit rows written
+  after those dependents disappeared; that scope is then removed atomically.
+- **ERASE-008 — Value-free receipt.** The receipt row holds the entity name,
+  label, planned and deleted counts per table, retained exceptions with reasons,
+  blob totals and times. It holds the subject key only while rows are still
+  being deleted, and clears it when the subject row commits.
+- **ERASE-009 — Declared exceptions.** A table kept on purpose is declared in
+  `retain` with a reason. Preview and receipt list it, including a root redaction reason. Nothing is skipped
+  without a declaration.
+- **ERASE-010 — One open erasure per subject.** `start` for a subject that has an
+  open erasure in `deleting` returns that erasure unchanged. Once the subject row
+  is gone, `start` answers `subject_not_found` (404) and changes nothing.
+- **ERASE-011 — Seed policy hooks.** `hold` can refuse with a reason
+  (`held:<reason>`, 409). `statements` adds product statements to the batch that
+  commits the subject row, after deletion. `beforeStatements` adds durable
+  pre-deletion policy effects in the first batch. Hooks run in the seed's code.
+- **ERASE-012 — import-kit composition.** `nativeStatements(entity, subject)`
+  returns the whole D1 phase as import-kit `D1Sql` (`{sql, params}`), opening
+  the receipt in the same statements. These are passed to
+  `eraseD1ImportTarget(kind, id, nativeStatements, context)`, so kit custody,
+  the product cascade and the fence commit in one batch. `deleteBlobs` then runs
+  as usual. `retireD1ImportCustody` takes the same statements for a whole
+  person's import custody and its erasure journal.
+- **ERASE-013 — Stated limits.** An old archive restored into a brand-new store
+  that has no journal cannot be recognised. Raw database imports bypass every
+  product fence. Copies outside the installation are out of reach: downloaded
+  archives, delivered mail, provider records and platform backups.
+- **ERASE-014 — Attributable counters.** A counter or rate row keyed by a person id,
+  email or digest is written with a `rer_erasure_rates` correlation in the same D1
+  batch (`rateWrite` / `rateCorrelation`), guarded on the subject row existing and,
+  for a redacted root, on its `live` predicate: a declaration with a redacted root
+  and a rate edge on it is refused without one, and erasure refuses a redaction that
+  leaves it true, so no write is admitted after erasure in either mode.
+  `rateEdges` declares the correlation and the counter rows it names as edges, so one
+  erasure plan deletes both and completion re-reads them. Uncorrelated aggregates are
+  untouched. A key that was never correlated cannot be found.

package/modules/erasure/README.md

@@ -0,0 +1,221 @@
+# Subject erasure
+
+This dependency-free source module erases one subject (a person, contact,
+requester, booking and so on) and everything a seed declares as depending on
+it, for BASE-DATA-003. Audit records survive with an anonymised reference
+(BASE-OPS-005). It was generalised from the erasure code of Penny, Orbit, Dial,
+HappyToHelp, Cradle and Slate. Each seed keeps its own authorization, confirmation UI, holds,
+retained exceptions and effects outside D1 and R2. Clauses are in
+[CONTRACT.md](CONTRACT.md).
+
+## Declaring an entity
+
+```js
+import { defineErasure, createErasure } from './vendor/base/modules/erasure/index.mjs';
+export const person = defineErasure({
+  entity: 'person',
+  root: { table: 'people' },
+  edges: [
+    { table: 'person_notes', from: 'people', on: { person_id: 'id' } },
+    { table: 'person_files', from: 'people', on: { person_id: 'id' }, blob: { bucket: 'FILES', keyColumn: 'storage_key' } },
+    { table: 'signals', from: 'people', where: 'instr(payload_json,?)>0', params: ['email'] },
+  ],
+  redact: [{ table: 'messages', from: 'people', on: { author_id: 'id' }, set: { body: '' }, reason: 'transcript order is kept' }],
+  audit: [{ table: 'audit_events', column: 'entity_id', of: 'people', where: "entity_type='person'", clear: { details: '{}' } }],
+  retain: [{ table: 'opt_out_hashes', reason: 'keyed hash prevents re-contact' }],
+  hold: async ({ db, subject }) => null,         // or a reason string: refuses with 409
+  beforeStatements: async ({ db, subject, label }) => [], // durable copy/unlink before the first child batch
+  statements: async ({ db, subject, label }) => [], // product SQL committed with the subject row
+});
+```
+
+| Part | Meaning |
+| --- | --- |
+| `root` | The subject's table; optional `redact: {set, reason, identityColumns?}` keeps an anonymous root. `set` overwrites every non-key, non-identity column with declared constants, or a function of `{subject,anonymousId}`. `identityColumns` may contain only opaque structural links (e.g. project/workspace IDs), never personal fields. Keys come from its primary key (`{rowid}` for keyless tables). |
+| `edges` | Rows deleted with the subject. `on` maps child columns to parent columns. `where` is a bound SQL predicate whose `params` name parent columns. A table may appear in several edges. Overlapping paths are deduplicated and ordered by dependency. A cyclic deletion graph is refused before mutation; unlink cycles in seed policy before using this helper. |
+| `blob` | On an edge: the R2 binding and the column holding the object key. Keys should be opaque (no file names). |
+| `redact` | Kept rows whose columns are overwritten, each with a reason. |
+| `audit` | Audit columns referencing rows of a deleted table (single-column key). They receive the erasure's label, and `clear` columns are overwritten. |
+| `retain` | Tables kept on purpose, with reasons. Listed in preview and receipt. |
+| `hold`, `beforeStatements`, `statements` | Refusal, durable pre-deletion effects (first batch), and final effects (after deletes). |
+
+Any table with a foreign key into a deleted table must be declared. Otherwise
+preview and erasure refuse with `undeclared_dependent:<child>:<parent>`, because a
+`CASCADE` would remove a row that erasure never fenced. This includes `rer_*` product
+tables. A destructive FK action into a retained/redacted/audit table is refused
+with `unsafe_retained_fk:<child>:<parent>`. This is a schema-level refusal, even
+when current links are null. Migrate such retained links to non-destructive
+`NO ACTION` FKs and detach them before admission, or keep a redacted parent. Retained keys are
+verified after each batch and before completion.
+
+## Phases
+
+```js
+const erasure = createErasure({ db: env.DB, buckets: { FILES: env.FILES }, portability, declarations: [person] });
+const preview = await erasure.preview('person', { id });          // counts, blob count, retained, planHash
+const opened = await erasure.start('person', { id }, { planHash }); // receipt, phase 'deleting'
+const receipt = await erasure.run(opened.id, { until: Date.now() + 20_000 });
+if (receipt.phase !== 'complete') await env.JOBS.send({ erasure: opened.id }); // continue later
+```
+
+`portability` is the seed's `createPortability({db,buckets,policy})` service.
+`commit(id,{rows,until})` runs only the D1 phase: bounded atomic batches of at
+most `rows` dependents (default 500), leaves first, with the subject row last.
+Each deleted row's `erasureStatements` and `invalidateTransfersStatements()` go
+in the same batch. `deleteBlobs(id,{until})` runs only the blob phase, after the
+commit. `run` does both within the time budget. Every phase is safe to repeat,
+and a concurrent runner gets `erasure_busy` (409). The receipt says `complete`
+only after the completion transaction re-reads every declared dependent and audit path
+inside the fence, then every recorded object has been deleted and read back as
+absent. Scope changes roll back that step and resume collection. Temporary scope
+remembers earlier parents through blob cleanup, so rows or audits added after the
+first D1 fence return to deletion before completion. It is scrubbed atomically
+with completion. A root deleted outside the helper is refused rather than reported complete.
+
+For retained attribution, use `root: {table: 'operators', redact: {reason: 'stable
+anonymous attribution', set: ({anonymousId}) => ({email: anonymousId + '@removed.invalid',
+name: 'Removed operator', status: 'removed'})}}` and explicitly set any other
+non-identity columns in that schema. Only opaque IDs survive; root redaction also
+advances portability's redaction checkpoint; completion verifies the replacements
+and preserved structural IDs. Older archives are refused when the destination or
+a supplied trusted later journal knows that checkpoint, while a post-redaction
+archive can restore the anonymous row. The portability adapter must forward
+`redactionStatements()` for this mode.
+`anonymousId` is independent of the audit label, so retained root values cannot
+link that label back to the opaque identity. Root setters must be deterministic
+for their input and must not read or copy personal data.
+
+A subject too large for one request continues through the seed's queue, and a
+scheduled sweep picks up any erasure whose message was lost. The default seed's
+`src/core/features/people/routes.ts` shows both. The receipt (`receipt(id)`)
+holds entity, label, planned and deleted counts, retained exceptions, blob totals
+and times, and never a stored value. The subject key is held only while rows
+are still being deleted.
+
+## Attributable counters
+
+A rate limit or counter whose key is a person id, an email or a digest of one is
+personal data, and a hashed key cannot be traced back to its person afterwards. So the
+write records who the key belongs to, in the same D1 batch as the counter upsert, and
+the declaration erases both together.
+
+```js
+import { rateEdges, rateWrite } from './vendor/base/modules/erasure/index.mjs';
+const root = { table: 'people', column: 'id' };
+// in the declaration
+edges: [...rateEdges({ entity: 'person', root, counters: [{ table: 'rate_limits', keyColumn: 'key' }] })],
+// at every write whose key identifies a known person
+const [counted] = await rateWrite(db, { entity: 'person', root, subject: person.id, rateTable: 'rate_limits', rateKey: key },
+  [db.prepare('INSERT INTO rate_limits(key,window,count) VALUES(?,?,1) ON CONFLICT(key) DO UPDATE SET count=count+1 RETURNING count').bind(key, window)]);
+```
+
+`rateWrite` returns the results of your statements (so admission still reads `count`).
+Where the seed owns its batch, put `rateCorrelation(db, spec)` (three statements) first
+in that batch instead. They abort the batch when the subject row is already gone, so a
+write admitted after erasure writes nothing and `rateWrite` refuses `subject_gone`
+(409); a write admitted while an erasure runs is caught by the completion re-read.
+
+A redacted root (retained attribution, above) keeps its row under the same id, so "the row
+exists" no longer means "the person is still here". Give that root a `live` predicate
+over its row, false once redacted, and use the same `root` in `rateEdges` and every
+`rateWrite`/`rateCorrelation`:
+
+```js
+const root = { table: 'operators', column: 'id', live: "status<>'removed'" };
+```
+
+The write guard then requires the row and the predicate. `defineErasure` refuses a
+declaration with a redacted root and a rate edge on that root but no `live`
+(`rate_root_live:<edge>`), and admission refuses (`rate_root_live`, 409) when the
+predicate is still true for the redaction's `set` values, or names a column the
+redaction does not set. A deleted root needs no `live`.
+Preview and receipt count `rer_erasure_rates` and the counter table like any edge.
+
+Seed adoption note:
+
+1. Apply `schema/erasure-rates.sql` as the next numbered migration, after the erasure
+   migrations. Add `rer_erasure_rates` and each counter table to the portability
+   policy's `excludeTables` (rate windows are ephemeral).
+2. Spread `rateEdges(...)` into the declaration of the entity the key identifies, one
+   `counters` item per rate table. Every counter table needs a primary key.
+3. Route each write whose key is derived from a known person through `rateWrite` or
+   `rateCorrelation`. Keys that identify nobody (client IP, global or route scope)
+   are written directly and survive as aggregates; never correlate those.
+4. One key must identify one person. Erasing a person deletes every counter row their
+   correlation names.
+
+Limits: a row written before the person existed, or for an address with no person
+record, has no subject and is not found; use an expiring window for it or key it by
+something that identifies nobody. Rows written before adoption have no correlation:
+the seed retires them in its own migration.
+
+## Seams
+
+- **Portability.** This module adds no second fence. It calls the service's
+  `erasureStatements` for every deleted row (children and files included, not
+  only the subject), so an older archive that contains any of those rows is
+  refused on restore. The fence's own limit stays: an old archive offered to a
+  brand-new store that has no journal cannot be recognised. Supply the owner's
+  later journal there (`rer import --journal LATER_ARCHIVE`).
+- **import-kit.** `nativeStatements(entity, subject)` returns the whole D1 phase
+  as `{sql, params}` statements for `eraseD1ImportTarget(kind, id,
+  nativeStatements, context)`. Kit custody, the product cascade and the fence
+  then commit in one batch. Afterwards call `deleteBlobs(operationId)`. This
+  path is unbounded (one batch), so use it for imported targets of ordinary size.
+  To erase a person (not one record), pass the same statements to
+  `retireD1ImportCustody({ target, values }, nativeStatements, context)`: it also
+  retires imports whose headers hold the person's exact identifiers and writes
+  the import erasure journal (import-kit `src/d1/README.md`).
+
+## Adopting
+
+Copy these files byte for byte to a folder the Worker build serves, such as
+`src/modules/erasure/`. A seed made by `rer` export also receives them under
+`scripts/base-cli/modules/erasure/`, but `vite dev` serves only `src`, `public`
+and `node_modules`, so runtime imports must not reach into `scripts/`. The
+standalone default seed copies this module and portability into `src/modules/`.
+The files are:
+
+```text
+modules/erasure/index.mjs
+modules/erasure/index.d.mts
+modules/erasure/declaration.mjs
+modules/erasure/plan.mjs
+modules/erasure/order.mjs
+modules/erasure/root.mjs
+modules/erasure/scope.mjs
+modules/erasure/completion.mjs
+modules/erasure/verification.mjs
+modules/erasure/cascade.mjs
+modules/erasure/blobs.mjs
+modules/erasure/audit.mjs
+modules/erasure/receipt.mjs
+modules/erasure/fence.mjs
+modules/erasure/sql.mjs
+modules/erasure/schema/erasure.sql
+modules/erasure/rate.mjs
+modules/erasure/schema/erasure-rates.sql   # only when the seed keeps attributable counters
+```
+
+Apply `schema/erasure.sql` as the seed's next numbered migration, after
+portability's. For existing installations apply the scope/guard additions as a new migration
+(default-seed `0017_erasure_scope.sql`), leaving applied migrations unchanged.
+Finish or reconcile open operations with the old helper before upgrading. Older
+operations that discarded their scope refuse `erasure_scope_missing`; the helper
+cannot prove completeness without the earlier parent keys.
+Add `rer_erasure_blobs`, `rer_erasure_guard`, and `rer_erasure_scope` to the portability
+policy's `excludeTables`. Receipts (`rer_erasure_operations`) travel in
+archives; the blob work list does not.
+
+## Historical measurements before the review fixes
+
+Through the default seed's route in a local `rer dev` Worker, a subject with
+10,000 dependent rows (9,500 notes and 500 file rows) and 500 R2 blobs was
+erased in 10.7 s in one run and 15.0 s in another. That is one request: 20
+bounded D1 steps, then the blob phase, with no queue continuation needed. The
+full proof table is kept with the consolidation evidence for this change.
+These pre-fix measurements do not establish the performance of the corrected
+helper. They are local Miniflare measurements, not production capacity claims. Real D1
+statement, CPU and request limits decide `rows` per step and the request budget.
+Larger subjects continue on the queue, and the receipt stays `deleting` or
+`blobs` until done.

package/modules/erasure/audit.mjs

@@ -0,0 +1,23 @@
+import { statement, quote, chunks, randomHex } from './sql.mjs';
+
+/** A fresh random label per erasure: it is not derived from the subject, so
+ * nobody holding the database (or an old archive) can recompute or test it. */
+export const newLabel = () => 'erased:' + randomHex(16);
+
+export function auditStatements(db, d, plan, label, { only } = {}) {
+  const out = [];
+  for (const item of d.audit) {
+    if (only && item.of !== only) continue;
+    const keys = [...plan.known.get(item.of).values()].map(row => row[plan.keys.get(item.of).pk[0]]);
+    const clear = Object.entries(item.clear ?? {});
+    const set = [`${quote(item.column)}=?`, ...clear.map(([c]) => `${quote(c)}=?`)].join(',');
+    // A previously relabelled row is still this operation's audit: a writer
+    // may have changed its detail after the first cleanup.
+    out.push(statement(db, `UPDATE ${quote(item.table)} SET ${set} WHERE ${quote(item.column)}=?${item.where ? ` AND (${item.where})` : ''}`, label, ...clear.map(([, v]) => v), label));
+    for (const part of chunks(keys, 200)) {
+      out.push(statement(db, `UPDATE ${quote(item.table)} SET ${set} WHERE ${quote(item.column)} IN (SELECT value FROM json_each(?))${item.where ? ` AND (${item.where})` : ''}`,
+        label, ...clear.map(([, v]) => v), JSON.stringify(part)));
+    }
+  }
+  return out;
+}

package/modules/erasure/blobs.mjs

@@ -0,0 +1,45 @@
+import { all, statement, insist } from './sql.mjs';
+import { settle } from './completion.mjs';
+
+/** Runs only after the D1 commit recorded every key. Deleting an absent object
+ * succeeds, so an interrupted run repeats safely; a key leaves the work list
+ * only after a read shows the object gone. */
+export async function deleteBlobs(ctx, d, id, { until = Infinity, page = 1000 } = {}) {
+  const { db, buckets } = ctx;
+  const op = await statement(db, 'SELECT phase FROM rer_erasure_operations WHERE id=?', id).first();
+  insist(op, 'erasure_not_found', 404);
+  if (op.phase !== 'blobs') return op.phase;
+  if (!(await all(db, "SELECT 1 FROM rer_erasure_scope WHERE operation=? AND kind='graph' AND table_name=? LIMIT 1", id, d.root.table)).length) {
+    const current = await statement(db, 'SELECT phase FROM rer_erasure_operations WHERE id=?', id).first();
+    if (current?.phase === 'complete') return 'complete';
+    insist(false, 'erasure_scope_missing', 409);
+  }
+  let changes = 0;
+  for (;;) {
+    const rows = await all(db, 'SELECT bucket,key FROM rer_erasure_blobs WHERE operation=? ORDER BY bucket,key LIMIT ?', id, page);
+    if (!rows.length) {
+      const phase = await settle(ctx, d, id);
+      if (phase === 'complete' || phase === 'deleting') return phase;
+      if (phase === 'changed') insist(++changes < 3, 'erasure_scope_unstable', 409);
+      else changes = 0;
+      if (Date.now() > until) return 'blobs';
+      continue;
+    }
+    for (const name of new Set(rows.map(r => r.bucket))) {
+      const bucket = buckets[name];
+      insist(bucket && typeof bucket.delete === 'function', 'missing_bucket:' + name, 500);
+      const keys = rows.filter(r => r.bucket === name).map(r => r.key);
+      await bucket.delete(keys);
+      for (let i = 0; i < keys.length; i += 16) {
+        const left = await Promise.all(keys.slice(i, i + 16).map(k => bucket.head(k)));
+        insist(left.every(x => x === null), 'blob_remains', 503);
+      }
+      await db.batch([
+        statement(db, 'DELETE FROM rer_erasure_blobs WHERE operation=? AND bucket=? AND key IN (SELECT value FROM json_each(?))', id, name, JSON.stringify(keys)),
+        // Derived from what remains, so a concurrent or repeated run cannot double count.
+        statement(db, 'UPDATE rer_erasure_operations SET blobs_deleted=blobs_total-(SELECT count(*) FROM rer_erasure_blobs WHERE operation=?) WHERE id=?', id, id),
+      ]);
+    }
+    if (Date.now() > until) return 'blobs';
+  }
+}