@classytic/arc 2.23.0 → 2.28.0

package/dist/cleanup/index.mjs

@@ -0,0 +1,1267 @@
+import { g as getUserId } from "../types-CSyCxl2V.mjs";
+import { t as defineResource } from "../defineResource-2zvVVpxg.mjs";
+import { t as defineModule } from "../module-_-M7C5ES.mjs";
+import { createPurgeEvidence } from "@classytic/primitives/retention";
+import { canonicalJson, sha256Hex } from "@classytic/primitives/canonical";
+//#region src/cleanup/errors.ts
+/**
+* A framework error carrying BOTH `status` (read directly in code/tests) and
+* `statusCode` (the Fastify convention arc's global error handler recognizes,
+* step 4 of its classifier — a numeric `statusCode` + a separatored domain
+* `code` maps to that exact status + code on the wire, never `arc.internal_error`).
+*/
+var CleanupError = class extends Error {
+	code;
+	status;
+	/** Alias of {@link status} — the property arc's error handler classifies on. */
+	statusCode;
+	meta;
+	constructor(code, status, message, meta) {
+		super(message);
+		this.name = "CleanupError";
+		this.code = code;
+		this.status = status;
+		this.statusCode = status;
+		if (meta) this.meta = meta;
+	}
+};
+/**
+* Internal control-flow signal thrown by `throwIfCancelled()` when a run's
+* durable `cancelRequested` flag is set. NOT a wire error — `processRun`
+* catches it and CAS-transitions the run to `cancelled`.
+*/
+var CleanupCancelled = class extends Error {
+	runId;
+	constructor(runId) {
+		super(`Cleanup run ${runId} was cancelled.`);
+		this.name = "CleanupCancelled";
+		this.runId = runId;
+	}
+};
+const CleanupErrors = {
+	unknownRecipe(id) {
+		return new CleanupError("CLEANUP_UNKNOWN_RECIPE", 404, `No cleanup recipe registered under id '${id}'.`, { id });
+	},
+	duplicateRecipe(id) {
+		return new CleanupError("CLEANUP_DUPLICATE_RECIPE", 500, `Duplicate cleanup recipe id '${id}' — recipe ids must be unique in a registry.`, { id });
+	},
+	unavailable(id, reason) {
+		return new CleanupError("CLEANUP_RECIPE_UNAVAILABLE", 409, `Cleanup recipe '${id}' is unavailable: ${reason}`, {
+			id,
+			reason
+		});
+	},
+	confirmationRequired(phrase) {
+		return new CleanupError("CLEANUP_CONFIRMATION_REQUIRED", 400, "This destructive cleanup requires the exact confirmation phrase.", { confirmationPhrase: phrase });
+	},
+	reasonRequired() {
+		return new CleanupError("CLEANUP_REASON_REQUIRED", 400, "A non-empty reason is required.");
+	},
+	blocked(blockers) {
+		return new CleanupError("CLEANUP_BLOCKED", 409, `Cleanup plan has unresolved blockers and cannot run: ${blockers.join(", ")}.`, { blockers: [...blockers] });
+	},
+	planTooLarge(detail) {
+		return new CleanupError("CLEANUP_PLAN_TOO_LARGE", 413, `Cleanup plan exceeds a size limit: ${detail}.`, { detail });
+	},
+	actorRequired() {
+		return new CleanupError("CLEANUP_ACTOR_REQUIRED", 401, "A destructive cleanup requires an authenticated actor; none could be resolved.");
+	},
+	planChanged(expected, actual) {
+		return new CleanupError("CLEANUP_PLAN_CHANGED", 409, "The cleanup plan changed since preview — re-preview and confirm the new plan.", {
+			expectedDigest: expected,
+			actualDigest: actual
+		});
+	},
+	alreadyRunning(runId) {
+		return new CleanupError("CLEANUP_ALREADY_RUNNING", 409, "Another destructive cleanup run is already in progress. Only one runs at a time.", { runId });
+	},
+	runNotFound(id) {
+		return new CleanupError("CLEANUP_RUN_NOT_FOUND", 404, `Cleanup run '${id}' not found.`, { id });
+	},
+	invalidAction(action, status) {
+		return new CleanupError("CLEANUP_INVALID_ACTION", 409, `Action '${action}' is not valid for a run in status '${status}'.`, {
+			action,
+			status
+		});
+	},
+	forbidden(operation) {
+		return new CleanupError("CLEANUP_FORBIDDEN", 403, `Not authorized to ${operation} cleanup.`, { operation });
+	}
+};
+//#endregion
+//#region src/cleanup/compose.ts
+const ALWAYS_AVAILABLE = { available: true };
+/** Build a step context from an arc cleanup context + the sealed parameters. */
+function stepContextOf(ctx, parameters) {
+	return {
+		now: ctx.now,
+		signal: ctx.signal,
+		ambient: ctx.ambient,
+		parameters,
+		logger: ctx.logger
+	};
+}
+function errMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Infrastructure failure inside the adapter's own progress plumbing (e.g. the
+* run store rejecting a progress write). Distinguished from a DOMAIN step
+* failure: it propagates out of `execute` so the service records an
+* infrastructure failure for the run, instead of blaming the domain step.
+*/
+var CleanupProgressInfraError = class extends Error {
+	constructor(cause) {
+		super(`progress persistence failed: ${errMessage(cause)}`);
+		this.name = "CleanupProgressInfraError";
+	}
+};
+function recipeFromSteps(input) {
+	const { id, label, version, confirmationPhrase, steps } = input;
+	const destructive = input.destructive ?? steps.some((s) => s.destructive);
+	return {
+		id,
+		label,
+		destructive,
+		evidenceStrategy: input.evidenceStrategy ?? (destructive ? "hard" : "soft"),
+		...version !== void 0 ? { version } : {},
+		available(ctx) {
+			return input.available ? input.available(ctx) : Promise.resolve(ALWAYS_AVAILABLE);
+		},
+		async plan(cleanupInput, ctx) {
+			const stepCtx = stepContextOf(ctx, cleanupInput.parameters ?? {});
+			const items = [];
+			const blockers = /* @__PURE__ */ new Set();
+			const retains = new Set(input.retains ?? []);
+			const rebuildActions = /* @__PURE__ */ new Set();
+			const warnings = new Set(input.warnings ?? []);
+			for (const step of steps) {
+				const est = await step.estimate(stepCtx);
+				items.push({
+					resource: est.resource,
+					estimated: est.estimated,
+					...est.retained !== void 0 ? { retained: est.retained } : {},
+					...est.blockers && est.blockers.length > 0 ? { blockers: est.blockers } : {}
+				});
+				for (const b of est.blockers ?? []) blockers.add(b);
+				for (const w of est.warnings ?? []) warnings.add(w);
+				if (est.retained) retains.add(est.retained);
+				for (const r of step.rebuildActions ?? []) rebuildActions.add(r);
+			}
+			return {
+				items,
+				blockers: [...blockers],
+				retains: [...retains],
+				rebuildActions: [...rebuildActions],
+				warnings: [...warnings],
+				...confirmationPhrase !== void 0 ? { confirmationPhrase } : {}
+			};
+		},
+		async execute(plan, ctx) {
+			const parameters = plan.parameters ?? {};
+			const results = [];
+			for (const step of steps) {
+				await ctx.throwIfCancelled();
+				let reported = 0;
+				const execCtx = {
+					...stepContextOf(ctx, parameters),
+					throwIfCancelled: () => ctx.throwIfCancelled(),
+					async onProgress(update) {
+						const delta = update.processed - reported;
+						if (delta > 0) {
+							reported = update.processed;
+							try {
+								await ctx.onStep({
+									resource: update.resource,
+									processed: delta,
+									ok: true,
+									...update.cursor !== void 0 ? { cursor: update.cursor } : {}
+								});
+							} catch (err) {
+								throw new CleanupProgressInfraError(err);
+							}
+						}
+					}
+				};
+				let outcome;
+				try {
+					outcome = await step.execute(execCtx);
+				} catch (err) {
+					if (err instanceof CleanupCancelled || err instanceof CleanupProgressInfraError) throw err;
+					outcome = {
+						resource: step.resource,
+						processed: reported,
+						ok: false,
+						error: errMessage(err)
+					};
+				}
+				const tail = outcome.processed - reported;
+				if (tail > 0 || !outcome.ok) await ctx.onStep({
+					resource: outcome.resource,
+					processed: tail > 0 ? tail : 0,
+					ok: outcome.ok,
+					...outcome.error !== void 0 ? { error: outcome.error } : {},
+					...outcome.cursor !== void 0 ? { cursor: outcome.cursor } : {}
+				});
+				results.push({
+					resource: outcome.resource,
+					processed: outcome.processed,
+					ok: outcome.ok,
+					...outcome.error !== void 0 ? { error: outcome.error } : {},
+					...outcome.cursor !== void 0 ? { cursor: outcome.cursor } : {}
+				});
+				if (!outcome.ok) break;
+			}
+			const allOk = results.every((r) => r.ok);
+			const anyOk = results.some((r) => r.ok);
+			return {
+				status: allOk ? "completed" : anyOk ? "partial" : "failed",
+				results
+			};
+		},
+		async verify(plan, ctx) {
+			const stepCtx = stepContextOf(ctx, plan.parameters ?? {});
+			const checks = [];
+			for (const step of steps) {
+				if (!step.verify) continue;
+				const stepChecks = await step.verify(stepCtx);
+				for (const c of stepChecks) checks.push({
+					name: c.name,
+					ok: c.ok,
+					...c.detail !== void 0 ? { detail: c.detail } : {}
+				});
+			}
+			return {
+				ok: checks.every((c) => c.ok),
+				checks
+			};
+		}
+	};
+}
+//#endregion
+//#region src/cleanup/types.ts
+/** Terminal states — no further transition is valid. */
+const CLEANUP_TERMINAL_STATUSES = [
+	"completed",
+	"failed",
+	"cancelled"
+];
+const DEFAULT_CLEANUP_LIMITS = {
+	maxPlanItems: 500,
+	maxResults: 1e3,
+	maxChecks: 200,
+	maxReasonLength: 2e3,
+	maxParamDepth: 8
+};
+//#endregion
+//#region src/cleanup/memory.ts
+/**
+* In-memory {@link CleanupRunStore}. Single-process only — see the module
+* docblock for the production caveat.
+*/
+var MemoryCleanupRunStore = class {
+	/** Live run state, keyed by run id. Exposed for tests/inspection. */
+	runs = /* @__PURE__ */ new Map();
+	#now;
+	constructor(now = () => /* @__PURE__ */ new Date()) {
+		this.#now = now;
+	}
+	/** Another NON-TERMINAL run already holding the same concurrency key. */
+	#keyConflict(run) {
+		if (!run.concurrencyKey) return void 0;
+		for (const other of this.runs.values()) if (other.id !== run.id && other.concurrencyKey === run.concurrencyKey && !CLEANUP_TERMINAL_STATUSES.includes(other.status)) return other;
+	}
+	#read(id) {
+		return this.runs.get(id);
+	}
+	/** Store `next` and hand back a copy the caller may freely mutate. */
+	#commit(next) {
+		this.runs.set(next.id, next);
+		return { ...next };
+	}
+	async createIfPermitted(run) {
+		const conflict = this.#keyConflict(run);
+		if (conflict) return {
+			created: false,
+			activeRunId: conflict.id
+		};
+		this.runs.set(run.id, run);
+		return { created: true };
+	}
+	async get(id) {
+		const run = this.#read(id);
+		return run ? { ...run } : null;
+	}
+	async claim(id, lease) {
+		const current = this.#read(id);
+		if (!current || CLEANUP_TERMINAL_STATUSES.includes(current.status)) return null;
+		const leaseLive = current.leaseExpiresAt !== void 0 && current.leaseExpiresAt.getTime() > this.#now().getTime();
+		if (!(current.status === "queued" || (current.status === "running" || current.status === "finalizing") && !leaseLive)) return null;
+		return this.#commit({
+			...current,
+			leaseToken: lease.token,
+			leaseExpiresAt: lease.expiresAt,
+			attempt: current.attempt + 1
+		});
+	}
+	async compareAndTransition(id, expected, to, patch, leaseToken) {
+		const current = this.#read(id);
+		if (!current || !expected.includes(current.status)) return null;
+		if (leaseToken !== void 0 && current.leaseToken !== leaseToken) return null;
+		return this.#commit({
+			...current,
+			...patch ?? {},
+			status: to
+		});
+	}
+	async reArmIfPermitted(id, patch) {
+		const current = this.#read(id);
+		if (!current || current.status !== "failed" && current.status !== "cancelled") return null;
+		if (this.#keyConflict(current)) return null;
+		return this.#commit({
+			...current,
+			...patch,
+			status: "queued",
+			cancelRequested: false,
+			cancelRequestedBy: void 0,
+			cancelReason: void 0,
+			cancelRequestedAt: void 0,
+			leaseToken: void 0,
+			leaseExpiresAt: void 0,
+			finalization: void 0
+		});
+	}
+	async requestCancel(id, request) {
+		const current = this.#read(id);
+		if (!current) return null;
+		return this.#commit({
+			...current,
+			cancelRequested: true,
+			cancelRequestedBy: current.cancelRequestedBy ?? request?.actor,
+			cancelReason: current.cancelReason ?? request?.reason,
+			cancelRequestedAt: current.cancelRequestedAt ?? request?.requestedAt
+		});
+	}
+	async saveProgress(id, progress, lease) {
+		const current = this.#read(id);
+		if (!current) return;
+		if (lease && current.leaseToken !== lease.token) return;
+		this.#commit({
+			...current,
+			progress,
+			...lease ? { leaseExpiresAt: lease.expiresAt } : {}
+		});
+	}
+};
+/**
+* In-memory {@link CleanupEvidenceStore} — idempotent by
+* `evidence.operationId`, exactly as the port requires.
+*/
+var MemoryCleanupEvidenceStore = class {
+	evidence = [];
+	manifests = [];
+	#seenOperations = /* @__PURE__ */ new Set();
+	async finalize(input) {
+		const operationId = input.evidence.operationId ?? "";
+		if (this.#seenOperations.has(operationId)) return;
+		this.#seenOperations.add(operationId);
+		this.evidence.push(input.evidence);
+		this.manifests.push(input.manifest);
+	}
+};
+/**
+* A MANUAL in-memory {@link CleanupJobQueue}: it records enqueued jobs and runs
+* nothing on its own, so a test drives the worker deterministically
+* (`for (const job of queue.jobs) await service.processRun(job.runId)`).
+*
+* Note this is NOT the service's default queue — omitting `jobQueue` entirely
+* gives you a microtask-deferred in-process queue that DOES auto-run
+* `processRun` off the request path.
+*/
+var MemoryCleanupJobQueue = class {
+	jobs = [];
+	async enqueue(job) {
+		this.jobs.push(job);
+	}
+	/** Take everything enqueued so far, clearing the buffer. */
+	drain() {
+		return this.jobs.splice(0, this.jobs.length);
+	}
+};
+//#endregion
+//#region src/cleanup/registry.ts
+/**
+* Cleanup recipe registry — the framework's boot-time integrity gate.
+*
+* Validates recipe-id uniqueness at construction (fail fast, never at run
+* time), exposes typed lookup, and produces the introspection payload the
+* UI/SDK renders as recipe cards. Pure — no I/O, no Fastify.
+*/
+/**
+* Build a registry from a recipe list. Throws `CLEANUP_DUPLICATE_RECIPE` at
+* construction if two recipes share an id — a boot-time failure, never a
+* silent last-wins overwrite.
+*/
+function createCleanupRegistry(recipes) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const recipe of recipes) {
+		if (byId.has(recipe.id)) throw CleanupErrors.duplicateRecipe(recipe.id);
+		byId.set(recipe.id, recipe);
+	}
+	return {
+		get(id) {
+			const recipe = byId.get(id);
+			if (!recipe) throw CleanupErrors.unknownRecipe(id);
+			return recipe;
+		},
+		find(id) {
+			return byId.get(id);
+		},
+		all() {
+			return [...byId.values()];
+		},
+		introspect() {
+			return [...byId.values()].map((r) => ({
+				id: r.id,
+				label: r.label,
+				destructive: r.destructive
+			}));
+		}
+	};
+}
+//#endregion
+//#region src/cleanup/plan-digest.ts
+/**
+* Deterministic integrity checksums for plans + manifests.
+*
+* The operator previews a plan, then confirms by echoing its digest. At execute
+* time the server RE-PLANS and compares digests: if the world changed between
+* preview and confirm (more rows, a new blocker), the digest differs and the
+* run is refused with `CLEANUP_PLAN_CHANGED` (§7 "Execute"). So the digest MUST
+* be a stable function of the plan's MATERIAL content only — invariant to
+* object key order, and excluding volatile/advisory fields.
+*
+* These are integrity CHECKSUMS (accidental-corruption + drift detection), NOT
+* tamper-proof seals: plain SHA-256 does not stop an actor with write access
+* from replacing a record and recomputing its digest. Pair with access control
+* / keyed signatures where that matters.
+*
+* The canonicalizer + hash are the shared `@classytic/primitives/canonical`
+* implementation (`Date`-explicit, strict-reject of `undefined`/`NaN`/`BigInt`/
+* `function`/`symbol`/`Map`/`Set`/cyclic). Two domains consume it — cleanup
+* manifests here + financial-close evidence manifests in arc-accounting — so it
+* lives in primitives, not duplicated per package. `canonicalJson` is re-exported
+* for existing importers; peer floor `@classytic/primitives >= 0.17.0`.
+*/
+/**
+* The material content of a plan — everything an operator is consenting to.
+* Deliberately EXCLUDES `digest` (self-reference) and advisory `warnings`.
+*/
+function planMaterial(plan) {
+	return {
+		recipeId: plan.recipeId,
+		parameters: plan.parameters,
+		items: plan.items.map((i) => ({
+			resource: i.resource,
+			estimated: i.estimated,
+			retained: i.retained ?? null,
+			blockers: [...i.blockers ?? []].sort()
+		})).sort((a, b) => a.resource < b.resource ? -1 : a.resource > b.resource ? 1 : a.estimated - b.estimated),
+		retains: [...plan.retains].sort(),
+		blockers: [...plan.blockers].sort(),
+		rebuildActions: [...plan.rebuildActions].sort(),
+		estimatedTotal: plan.estimatedTotal,
+		confirmationPhrase: plan.confirmationPhrase
+	};
+}
+/** `sha256(canonical(planMaterial))` as a hex digest. */
+function computePlanDigest(plan) {
+	return sha256Hex(canonicalJson(planMaterial(plan)));
+}
+/**
+* Integrity checksum of a completed manifest (§5). Excludes the digest field
+* itself. Dates (e.g. `completedAt`) participate via the strict canonicalizer.
+*/
+function computeManifestDigest(manifest) {
+	const { manifestDigest: _drop, ...rest } = manifest;
+	return sha256Hex(canonicalJson(rest));
+}
+//#endregion
+//#region src/cleanup/service.ts
+/**
+* Cleanup orchestration service — the framework's use-case core.
+*
+* Split into a REQUEST path and a WORKER path so the durability guarantees the
+* ports promise actually hold:
+*
+*   preview()      → re-plan, seal a digest, surface blockers/retains/confirmation
+*   execute()      → validate (availability, digest, confirmation, reason,
+*                    blockers, limits), ATOMICALLY create the run (admission
+*                    guard by concurrencyKey), persist the sealed operation,
+*                    ENQUEUE `{ runId }`, and RETURN. It does NOT run the recipe.
+*   processRun()   → the worker entrypoint. Takes an EXCLUSIVE LEASE on the run
+*                    (`claim` — a live lease refuses duplicate workers), then
+*                    branches: a `finalizing` run RECOVERS finalization from the
+*                    persisted payload (never re-executes); a `queued` run (or a
+*                    crashed `running` run whose lease expired) executes the
+*                    recipe with cooperative cancellation, verifies, persists
+*                    the finalization payload, and finalizes idempotently.
+*   cancel()       → durable cancel request (+ actor/reason audit) + CAS a
+*                    not-yet-running run straight to `cancelled` WITH evidence.
+*                    A running run stops cooperatively and leaves evidence of
+*                    the committed chunks.
+*   retry()        → reload the SAME sealed operation, re-check availability +
+*                    recipe version + digest against a fresh plan (refuse if the
+*                    world changed), re-arm ATOMICALLY under the same admission
+*                    guard as creation, re-enqueue.
+*
+* Every status change goes through `compareAndTransition` (CAS) carrying the
+* worker's lease token, so a late `completed` write from a stalled ex-owner can
+* never clobber the new owner's `cancelled`/`running` state.
+*/
+const EMPTY_PROGRESS = {
+	processed: 0,
+	steps: 0
+};
+/** Admission key serializing every destructive run behind one slot. */
+const GLOBAL_DESTRUCTIVE_KEY = "global-destructive";
+function paramDepth(value, depth = 0) {
+	if (value === null || typeof value !== "object" || value instanceof Date) return depth;
+	let max = depth;
+	for (const v of Array.isArray(value) ? value : Object.values(value)) max = Math.max(max, paramDepth(v, depth + 1));
+	return max;
+}
+/** Failures first, so a `maxChecks` cap can never hide a failing check. */
+function orderChecksFailuresFirst(verification, maxChecks) {
+	if (verification.checks.length <= maxChecks) return {
+		verification,
+		checksTruncated: 0
+	};
+	const ordered = [...verification.checks].sort((a, b) => Number(a.ok) - Number(b.ok));
+	return {
+		verification: {
+			ok: verification.ok,
+			checks: ordered.slice(0, maxChecks)
+		},
+		checksTruncated: verification.checks.length - maxChecks
+	};
+}
+/** The terminal run status a finalization payload deterministically maps to. */
+function terminalStatusOf(payload) {
+	if (payload.status === "cancelled") return "cancelled";
+	if (payload.status === "completed" && payload.verification.ok && !payload.failureReason) return "completed";
+	return "failed";
+}
+function createCleanupService(deps) {
+	const { registry, runStore, evidenceStore } = deps;
+	const writeFence = deps.writeFence;
+	const logger = deps.logger;
+	const generateId = deps.generateId ?? (() => globalThis.crypto.randomUUID());
+	const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	const limits = {
+		...DEFAULT_CLEANUP_LIMITS,
+		...deps.limits
+	};
+	const leaseMs = deps.leaseMs ?? 300 * 1e3;
+	const progressThrottleMs = deps.progressThrottleMs ?? 0;
+	const jobQueue = deps.jobQueue ?? { enqueue: async (job) => {
+		queueMicrotask(() => {
+			processRun(job.runId).catch(() => {});
+		});
+	} };
+	function context(input, signal) {
+		return {
+			actor: input.actor,
+			now: now(),
+			signal,
+			ambient: input.ambient,
+			logger
+		};
+	}
+	function freshLease() {
+		return {
+			token: generateId(),
+			expiresAt: new Date(now().getTime() + leaseMs)
+		};
+	}
+	async function seal(recipe, input, ctx) {
+		const draft = await recipe.plan({ parameters: input.parameters }, ctx);
+		const items = draft.items;
+		if (items.length > limits.maxPlanItems) throw CleanupErrors.planTooLarge(`${items.length} items > maxPlanItems ${limits.maxPlanItems}`);
+		const estimatedTotal = items.reduce((sum, i) => sum + i.estimated, 0);
+		const blockers = new Set(draft.blockers ?? []);
+		for (const item of items) for (const b of item.blockers ?? []) blockers.add(b);
+		const unsealed = {
+			recipeId: recipe.id,
+			parameters: input.parameters ?? {},
+			items,
+			retains: [...draft.retains ?? []],
+			blockers: [...blockers],
+			rebuildActions: [...draft.rebuildActions ?? []],
+			warnings: [...draft.warnings ?? []],
+			estimatedTotal,
+			confirmationPhrase: draft.confirmationPhrase ?? recipe.id
+		};
+		return {
+			...unsealed,
+			digest: computePlanDigest(unsealed)
+		};
+	}
+	async function ensureAvailable(recipe, ctx) {
+		const availability = await recipe.available(ctx);
+		if (!availability.available) throw CleanupErrors.unavailable(recipe.id, availability.reason ?? "unavailable");
+	}
+	async function preview(input) {
+		const recipe = registry.get(input.recipeId);
+		const ctx = context(input);
+		await ensureAvailable(recipe, ctx);
+		return seal(recipe, input, ctx);
+	}
+	async function enqueueOrFail(run) {
+		try {
+			await jobQueue.enqueue({ runId: run.id });
+		} catch (err) {
+			await runStore.compareAndTransition(run.id, ["queued"], "failed", {
+				completedAt: now(),
+				failureReason: `enqueue failed: ${errMsg(err)}`
+			});
+			throw err;
+		}
+	}
+	async function execute(input) {
+		const recipe = registry.get(input.recipeId);
+		const ctx = context(input);
+		if ((input.reason ?? "").length > limits.maxReasonLength) throw CleanupErrors.planTooLarge(`reason length > ${limits.maxReasonLength}`);
+		if (input.parameters && paramDepth(input.parameters) > limits.maxParamDepth) throw CleanupErrors.planTooLarge(`parameters nested deeper than ${limits.maxParamDepth}`);
+		await ensureAvailable(recipe, ctx);
+		const sealed = await seal(recipe, input, ctx);
+		if (sealed.digest !== input.planDigest) throw CleanupErrors.planChanged(sealed.digest, input.planDigest);
+		if (recipe.destructive && input.confirmation !== sealed.confirmationPhrase) throw CleanupErrors.confirmationRequired(sealed.confirmationPhrase);
+		if (!input.reason || input.reason.trim().length === 0) throw CleanupErrors.reasonRequired();
+		if (sealed.blockers.length > 0) throw CleanupErrors.blocked(sealed.blockers);
+		const run = {
+			id: generateId(),
+			recipeId: recipe.id,
+			recipeVersion: recipe.version ?? "1",
+			status: "queued",
+			planDigest: sealed.digest,
+			sealedPlan: sealed,
+			parameters: input.parameters ?? {},
+			actor: input.actor,
+			ambient: input.ambient,
+			requestedBy: input.actor.ref,
+			reason: input.reason,
+			operationId: generateId(),
+			destructive: recipe.destructive,
+			...recipe.destructive ? { concurrencyKey: GLOBAL_DESTRUCTIVE_KEY } : {},
+			attempt: 0,
+			progress: EMPTY_PROGRESS,
+			cancelRequested: false,
+			queuedAt: now()
+		};
+		const created = await runStore.createIfPermitted(run);
+		if (!created.created) throw CleanupErrors.alreadyRunning(created.activeRunId);
+		await enqueueOrFail(run);
+		return await runStore.get(run.id) ?? run;
+	}
+	async function processRun(runId) {
+		const existing = await runStore.get(runId);
+		if (!existing) throw CleanupErrors.runNotFound(runId);
+		if (CLEANUP_TERMINAL_STATUSES.includes(existing.status)) return;
+		const lease = freshLease();
+		const run = await runStore.claim(runId, lease);
+		if (!run) return;
+		const recipe = registry.get(run.recipeId);
+		if (run.status === "finalizing") {
+			await recoverFinalization(run, recipe, lease);
+			return;
+		}
+		const running = await runStore.compareAndTransition(run.id, ["queued", "running"], "running", { startedAt: run.startedAt ?? now() }, lease.token);
+		if (!running) return;
+		if (running.cancelRequested) {
+			await settleCancelled(running, recipe, lease, []);
+			return;
+		}
+		let fenceToken;
+		let fenceHeld = false;
+		if (writeFence) try {
+			const token = await writeFence.acquire(run.operationId);
+			fenceToken = typeof token === "string" ? token : void 0;
+			fenceHeld = true;
+		} catch (err) {
+			await failRun(running, recipe, lease, `write fence acquire failed: ${errMsg(err)}`);
+			return;
+		}
+		try {
+			await runOperation(running, recipe, running.sealedPlan, lease);
+		} finally {
+			if (writeFence && fenceHeld) try {
+				await writeFence.release(run.operationId, fenceToken);
+			} catch (relErr) {
+				logger?.error?.("cleanup write fence release failed", {
+					runId: run.id,
+					operationId: run.operationId,
+					error: errMsg(relErr)
+				});
+			}
+		}
+	}
+	/** Execute → verify → persist finalization payload → finalize, all leased. */
+	async function runOperation(run, recipe, plan, lease) {
+		const controller = new AbortController();
+		let processed = 0;
+		let steps = 0;
+		let failed = 0;
+		let cancelled = false;
+		let lastSummary = run.progress ?? EMPTY_PROGRESS;
+		let lastPersistMs = 0;
+		const refreshCancel = async () => {
+			if ((await runStore.get(run.id))?.cancelRequested) {
+				cancelled = true;
+				controller.abort();
+				return true;
+			}
+			return false;
+		};
+		const renewedLease = () => ({
+			token: lease.token,
+			expiresAt: new Date(now().getTime() + leaseMs)
+		});
+		const execCtx = {
+			actor: run.actor,
+			now: now(),
+			signal: controller.signal,
+			ambient: run.ambient,
+			logger,
+			runId: run.id,
+			operationId: run.operationId,
+			async onStep(step) {
+				steps += 1;
+				processed += step.processed;
+				if (!step.ok) failed += 1;
+				const summary = {
+					processed,
+					steps,
+					failed,
+					currentResource: step.resource,
+					...step.cursor !== void 0 ? { lastCursor: step.cursor } : {},
+					heartbeatAt: now()
+				};
+				lastSummary = summary;
+				const nowMs = now().getTime();
+				if (!step.ok || progressThrottleMs === 0 || nowMs - lastPersistMs >= progressThrottleMs) {
+					lastPersistMs = nowMs;
+					await runStore.saveProgress(run.id, summary, renewedLease());
+					await refreshCancel();
+				}
+			},
+			async throwIfCancelled() {
+				if (cancelled || controller.signal.aborted || await refreshCancel()) throw new CleanupCancelled(run.id);
+			}
+		};
+		let result;
+		try {
+			result = await recipe.execute(plan, execCtx);
+		} catch (err) {
+			if (err instanceof CleanupCancelled || cancelled || controller.signal.aborted) {
+				await settleCancelled(run, recipe, lease, [], lastSummary);
+				return;
+			}
+			await failRun(run, recipe, lease, `execute threw: ${errMsg(err)}`);
+			return;
+		}
+		if (cancelled || await refreshCancel()) {
+			await settleCancelled(run, recipe, lease, result.results, lastSummary);
+			return;
+		}
+		const results = result.results.length > limits.maxResults ? result.results.slice(0, limits.maxResults) : result.results;
+		const anyFailed = results.some((r) => !r.ok) || result.results.length > results.length;
+		const effectiveStatus = anyFailed && result.status === "completed" ? "partial" : result.status;
+		let verification = {
+			ok: !anyFailed,
+			checks: []
+		};
+		if (effectiveStatus !== "failed") try {
+			verification = await recipe.verify(plan, {
+				actor: run.actor,
+				now: now(),
+				signal: controller.signal,
+				ambient: run.ambient,
+				logger
+			});
+		} catch (err) {
+			await failRun(run, recipe, lease, `verify threw: ${errMsg(err)}`, results);
+			return;
+		}
+		const capped = orderChecksFailuresFirst(verification, limits.maxChecks);
+		const success = effectiveStatus === "completed" && verification.ok;
+		const payload = {
+			status: effectiveStatus,
+			results,
+			verification: capped.verification,
+			...capped.checksTruncated > 0 ? { checksTruncated: capped.checksTruncated } : {},
+			...success ? {} : { failureReason: effectiveStatus === "partial" ? "partial results" : effectiveStatus === "failed" ? "execution failed" : "verification failed" }
+		};
+		const finalizing = await runStore.compareAndTransition(run.id, ["running"], "finalizing", { finalization: payload }, lease.token);
+		if (!finalizing) return;
+		await settleFromPayload(finalizing, recipe, lease, payload, { progress: {
+			...lastSummary,
+			processed,
+			steps,
+			failed,
+			heartbeatAt: now()
+		} });
+	}
+	/** Record a hard failure with failure evidence, CAS → failed (leased). */
+	async function failRun(run, recipe, lease, reason, results = []) {
+		const payload = {
+			status: "failed",
+			results,
+			verification: {
+				ok: false,
+				checks: []
+			},
+			failureReason: reason
+		};
+		const failing = await runStore.compareAndTransition(run.id, ["running"], "finalizing", {
+			failureReason: reason,
+			finalization: payload
+		}, lease.token);
+		if (!failing) return;
+		await settleFromPayload(failing, recipe, lease, payload);
+	}
+	/**
+	* Cancel settlement — cancellation is an AUDITED outcome, not a silent state
+	* flip: committed chunks remain in the database, so the run leaves evidence
+	* recording how much work had been committed, who cancelled, and that
+	* verification never ran.
+	*/
+	async function settleCancelled(run, recipe, lease, results, summary) {
+		const fresh = await runStore.get(run.id) ?? run;
+		const payload = {
+			status: "cancelled",
+			results,
+			verification: {
+				ok: false,
+				checks: [{
+					name: "verification.skipped",
+					ok: false,
+					detail: `run cancelled${fresh.cancelRequestedBy ? ` by ${fresh.cancelRequestedBy.ref}` : ""}${fresh.cancelReason ? `: ${fresh.cancelReason}` : ""} — post-state not verified; committed chunks remain`
+				}]
+			},
+			failureReason: "cancelled"
+		};
+		const finalizing = await runStore.compareAndTransition(run.id, ["running"], "finalizing", {
+			finalization: payload,
+			...summary ? { progress: summary } : {}
+		}, lease.token);
+		if (!finalizing) return;
+		await settleFromPayload(finalizing, recipe, lease, payload);
+	}
+	/**
+	* ── Failure domain 3: finalization ──────────────────────────────────────────
+	* Persist evidence + manifest from the DURABLE payload, then CAS to the
+	* terminal status. On an evidence-store failure the run STAYS `finalizing`
+	* (payload intact) and is re-enqueued so a worker replays finalization only.
+	*/
+	async function settleFromPayload(run, recipe, lease, payload, extraPatch = {}) {
+		try {
+			await finalize(run, recipe, run.sealedPlan, payload);
+		} catch (err) {
+			logger?.error?.("cleanup finalization failed — run left recoverable in finalizing", {
+				runId: run.id,
+				operationId: run.operationId,
+				error: errMsg(err)
+			});
+			try {
+				await jobQueue.enqueue({ runId: run.id });
+			} catch {}
+			return;
+		}
+		const terminal = terminalStatusOf(payload);
+		await runStore.compareAndTransition(run.id, ["finalizing"], terminal, {
+			completedAt: now(),
+			...payload.failureReason && terminal !== "completed" ? { failureReason: payload.failureReason } : {},
+			...extraPatch.progress ? { progress: extraPatch.progress } : {}
+		}, lease.token);
+	}
+	/** Recovery entry for a claimed `finalizing` run: NEVER re-executes. */
+	async function recoverFinalization(run, recipe, lease) {
+		const payload = run.finalization;
+		if (!payload) {
+			await settleFromPayload(run, recipe, lease, {
+				status: "failed",
+				results: [],
+				verification: {
+					ok: false,
+					checks: []
+				},
+				failureReason: "finalizing run has no persisted finalization payload"
+			});
+			return;
+		}
+		await settleFromPayload(run, recipe, lease, payload);
+		if (writeFence && run.destructive) try {
+			await writeFence.release(run.operationId);
+		} catch (err) {
+			logger?.error?.("cleanup fence release during finalization recovery failed", {
+				runId: run.id,
+				operationId: run.operationId,
+				error: errMsg(err)
+			});
+		}
+	}
+	/** Idempotently persist evidence + manifest for the run (keyed by operationId). */
+	async function finalize(run, recipe, plan, payload) {
+		const completedAt = now();
+		const { status, results, verification, checksTruncated, failureReason } = payload;
+		const processed = results.reduce((sum, r) => sum + r.processed, 0);
+		const evidence = createPurgeEvidence({
+			operationId: run.operationId,
+			subject: {
+				ref: `recipe:${recipe.id}`,
+				model: "CleanupRun"
+			},
+			scope: `recipe:${recipe.id}`,
+			strategy: recipe.evidenceStrategy ?? "hard",
+			status: status === "cancelled" ? "partial" : status,
+			measuresRetained: plan.retains.length > 0,
+			processed,
+			startedAt: run.startedAt ?? run.queuedAt,
+			completedAt,
+			occurredAt: completedAt,
+			actor: run.actor,
+			reason: buildEvidenceReason(run, status, failureReason),
+			results: results.map((r) => ({
+				resource: r.resource,
+				processed: r.processed,
+				ok: r.ok,
+				...r.error ? { error: r.error } : {}
+			})),
+			verification: {
+				ok: verification.ok,
+				checks: verification.checks.length,
+				...verification.checks.length || checksTruncated ? { note: [verification.checks.map((c) => `${c.name}:${c.ok ? "ok" : "fail"}`).join(", "), checksTruncated ? `(+${checksTruncated} checks truncated)` : ""].filter(Boolean).join(" ") } : {}
+			}
+		});
+		const manifestBase = {
+			runId: run.id,
+			recipeId: recipe.id,
+			recipeVersion: run.recipeVersion,
+			operationId: run.operationId,
+			planDigest: plan.digest,
+			status,
+			actor: run.actor,
+			reason: run.reason,
+			results,
+			verification,
+			...checksTruncated ? { checksTruncated } : {},
+			completedAt
+		};
+		const manifest = {
+			...manifestBase,
+			manifestDigest: computeManifestDigest(manifestBase)
+		};
+		await evidenceStore.finalize({
+			evidence,
+			manifest
+		});
+	}
+	function buildEvidenceReason(run, status, failureReason) {
+		const parts = [run.reason];
+		if (status === "cancelled") {
+			const by = run.cancelRequestedBy ? ` by ${run.cancelRequestedBy.ref}` : "";
+			const why = run.cancelReason ? `: ${run.cancelReason}` : "";
+			parts.push(`(cancelled${by}${why})`);
+		} else if (failureReason) parts.push(`(${failureReason})`);
+		return parts.join(" ");
+	}
+	async function getRun(id) {
+		const run = await runStore.get(id);
+		if (!run) throw CleanupErrors.runNotFound(id);
+		return run;
+	}
+	async function cancel(id, input) {
+		const run = await getRun(id);
+		if (CLEANUP_TERMINAL_STATUSES.includes(run.status)) throw CleanupErrors.invalidAction("cancel", run.status);
+		await runStore.requestCancel(id, {
+			actor: input?.actor,
+			reason: input?.reason,
+			requestedAt: now()
+		});
+		const immediate = await runStore.compareAndTransition(id, ["queued", "planned"], "cancelled", { completedAt: now() });
+		if (immediate) {
+			const recipe = registry.get(immediate.recipeId);
+			const payload = {
+				status: "cancelled",
+				results: [],
+				verification: {
+					ok: false,
+					checks: [{
+						name: "verification.skipped",
+						ok: false,
+						detail: "run cancelled before execution — no data was changed"
+					}]
+				},
+				failureReason: "cancelled"
+			};
+			try {
+				await finalize(immediate, recipe, immediate.sealedPlan, payload);
+			} catch (err) {
+				logger?.error?.("cleanup cancel evidence write failed", {
+					runId: id,
+					error: errMsg(err)
+				});
+			}
+		}
+		return getRun(id);
+	}
+	async function retry(id) {
+		const run = await getRun(id);
+		if (run.status !== "failed" && run.status !== "cancelled") throw CleanupErrors.invalidAction("retry", run.status);
+		const recipe = registry.get(run.recipeId);
+		const ctx = {
+			actor: run.actor,
+			now: now(),
+			ambient: run.ambient,
+			logger
+		};
+		await ensureAvailable(recipe, ctx);
+		if ((recipe.version ?? "1") !== run.recipeVersion) throw CleanupErrors.planChanged(recipe.version ?? "1", run.recipeVersion);
+		const fresh = await seal(recipe, {
+			recipeId: run.recipeId,
+			actor: run.actor,
+			parameters: run.parameters,
+			ambient: run.ambient
+		}, ctx);
+		if (fresh.digest !== run.planDigest) throw CleanupErrors.planChanged(fresh.digest, run.planDigest);
+		const requeued = await runStore.reArmIfPermitted(run.id, {
+			queuedAt: now(),
+			cancelRequested: false
+		});
+		if (!requeued) {
+			const current = await getRun(id);
+			if (current.status !== "failed" && current.status !== "cancelled") throw CleanupErrors.invalidAction("retry", current.status);
+			throw CleanupErrors.alreadyRunning("another-active-run");
+		}
+		await enqueueOrFail(requeued);
+		return getRun(id);
+	}
+	return {
+		preview,
+		execute,
+		processRun,
+		getRun,
+		cancel,
+		retry
+	};
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/cleanup/module.ts
+function defaultResolveActor(req) {
+	const id = (req.scope ? getUserId(req.scope) : void 0) ?? req.user?.id;
+	if (!id) throw CleanupErrors.actorRequired();
+	return {
+		ref: `user:${id}`,
+		kind: "user"
+	};
+}
+const recipeIdSchema = {
+	type: "string",
+	minLength: 1,
+	maxLength: 200
+};
+const parametersSchema = {
+	type: "object",
+	additionalProperties: true
+};
+const previewBodySchema = {
+	type: "object",
+	required: ["recipe"],
+	additionalProperties: false,
+	properties: {
+		recipe: recipeIdSchema,
+		parameters: parametersSchema
+	}
+};
+const runsBodySchema = {
+	type: "object",
+	required: [
+		"recipe",
+		"planDigest",
+		"reason"
+	],
+	additionalProperties: false,
+	properties: {
+		recipe: recipeIdSchema,
+		parameters: parametersSchema,
+		planDigest: {
+			type: "string",
+			minLength: 1,
+			maxLength: 128
+		},
+		reason: {
+			type: "string",
+			minLength: 1,
+			maxLength: 2e3
+		},
+		confirmation: {
+			type: "string",
+			maxLength: 500
+		}
+	}
+};
+const runIdParamsSchema = {
+	type: "object",
+	required: ["id"],
+	properties: { id: {
+		type: "string",
+		minLength: 1,
+		maxLength: 128
+	} }
+};
+const actionBodySchema = {
+	type: "object",
+	required: ["action"],
+	additionalProperties: false,
+	properties: {
+		action: {
+			type: "string",
+			enum: ["cancel", "retry"]
+		},
+		/** Optional cancel justification — persisted on the run + evidence. */
+		reason: {
+			type: "string",
+			maxLength: 2e3
+		}
+	}
+};
+/**
+* Build the Data Cleanup Center Arc module. The module's public export is the
+* live {@link CleanupService} (so other modules / tests can drive it directly).
+*/
+function createDataCleanupModule(deps) {
+	const registry = createCleanupRegistry(deps.recipes);
+	const service = createCleanupService({
+		registry,
+		runStore: deps.runStore,
+		evidenceStore: deps.evidenceStore,
+		writeFence: deps.writeFence,
+		jobQueue: deps.jobQueue,
+		limits: deps.limits,
+		leaseMs: deps.leaseMs,
+		progressThrottleMs: deps.progressThrottleMs,
+		generateId: deps.generateId,
+		now: deps.now
+	});
+	const prefix = deps.prefix ?? "/governance/data-cleanup";
+	const resolveActor = deps.resolveActor ?? defaultResolveActor;
+	const resolveAmbient = deps.resolveAmbient;
+	const view = deps.permissions.view;
+	const execute = deps.permissions.execute;
+	const manage = deps.permissions.manage ?? deps.permissions.execute;
+	const resource = defineResource({
+		name: deps.moduleName ?? "data-cleanup",
+		displayName: "Data Cleanup Center",
+		tag: "Governance",
+		prefix,
+		customRoutesOnly: true,
+		routes: [
+			{
+				method: "GET",
+				path: "/recipes",
+				summary: "List available cleanup recipes",
+				permissions: view,
+				raw: true,
+				handler: async (_req, reply) => {
+					return reply.send({ recipes: registry.introspect() });
+				}
+			},
+			{
+				method: "POST",
+				path: "/preview",
+				summary: "Preview a cleanup plan (no mutation)",
+				permissions: view,
+				raw: true,
+				schema: { body: previewBodySchema },
+				handler: async (req, reply) => {
+					const r = req;
+					const body = req.body;
+					const plan = await service.preview({
+						recipeId: body.recipe,
+						parameters: body.parameters,
+						actor: resolveActor(r),
+						ambient: resolveAmbient?.(r)
+					});
+					return reply.send(plan);
+				}
+			},
+			{
+				method: "POST",
+				path: "/runs",
+				summary: "Execute a confirmed cleanup plan",
+				permissions: execute,
+				raw: true,
+				schema: { body: runsBodySchema },
+				handler: async (req, reply) => {
+					const r = req;
+					const body = req.body;
+					const run = await service.execute({
+						recipeId: body.recipe,
+						parameters: body.parameters,
+						planDigest: body.planDigest,
+						reason: body.reason,
+						confirmation: body.confirmation,
+						actor: resolveActor(r),
+						ambient: resolveAmbient?.(r)
+					});
+					return reply.status(202).send(run);
+				}
+			},
+			{
+				method: "GET",
+				path: "/runs/:id",
+				summary: "Observe a cleanup run",
+				permissions: view,
+				raw: true,
+				schema: { params: runIdParamsSchema },
+				handler: async (req, reply) => {
+					const { id } = req.params;
+					return reply.send(await service.getRun(id));
+				}
+			},
+			{
+				method: "POST",
+				path: "/runs/:id/action",
+				summary: "Cancel or retry a cleanup run",
+				permissions: manage,
+				raw: true,
+				schema: {
+					params: runIdParamsSchema,
+					body: actionBodySchema
+				},
+				handler: async (req, reply) => {
+					const actionActor = resolveActor(req);
+					const { id } = req.params;
+					const { action, reason } = req.body;
+					if (action === "cancel") return reply.send(await service.cancel(id, {
+						actor: actionActor,
+						reason
+					}));
+					return reply.send(await service.retry(id));
+				}
+			}
+		]
+	});
+	return defineModule({
+		name: deps.moduleName ?? "data-cleanup",
+		...deps.owns ? { owns: deps.owns } : {},
+		bootstrap: () => service,
+		resources: () => [resource]
+	});
+}
+//#endregion
+export { CLEANUP_TERMINAL_STATUSES, CleanupCancelled, CleanupError, CleanupErrors, DEFAULT_CLEANUP_LIMITS, GLOBAL_DESTRUCTIVE_KEY, MemoryCleanupEvidenceStore, MemoryCleanupJobQueue, MemoryCleanupRunStore, canonicalJson, computeManifestDigest, computePlanDigest, createCleanupRegistry, createCleanupService, createDataCleanupModule, recipeFromSteps };