@ewhauser/world-celld 0.1.1 → 0.3.0

package/dist/index.js

@@ -1,10 +1,13 @@
-import { a as stringify, i as parse, n as rpcParse, r as rpcStringify, t as compact } from "./util-BvWlkqgV.js";
+import { c as globalRunIndexKey, d as workflowRunIndexKey, f as compact, g as stringify, h as parse, m as rpcStringify, o as correlationIndexKey, p as rpcParse } from "./retention-bLY1vcOu.js";
 import { EventSchema, HookSchema, MessageId, SPEC_VERSION_CURRENT, StepSchema, WorkflowRunSchema, parseQueueName } from "@workflow/world";
 import { EntityConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, TooEarlyError, WorkflowRunNotFoundError, WorkflowWorldError } from "@workflow/errors";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { monotonicFactory } from "ulid";
 //#region src/config.ts
 function resolveConfig(config) {
+	const retentionRaw = config?.runRetentionMs ?? process.env.CELLD_RUN_RETENTION_MS ?? 0;
+	const runRetentionMs = typeof retentionRaw === "number" ? retentionRaw : Number.parseInt(retentionRaw, 10);
+	if (!Number.isSafeInteger(runRetentionMs) || runRetentionMs < 0) throw new Error("world-celld: runRetentionMs must be a non-negative safe integer");
 	return {
 		fleetUrl: config?.fleetUrl ?? process.env.CELLD_FLEET_URL,
 		secret: config?.secret ?? process.env.CELLD_WORLD_SECRET,
@@ -12,6 +15,7 @@ function resolveConfig(config) {
 		deploymentId: config?.deploymentId ?? process.env.CELLD_DEPLOYMENT_ID ?? "celld-default",
 		baseUrl: config?.baseUrl,
 		queueShards: config?.queueShards ?? 1,
+		runRetentionMs,
 		readPollMs: config?.readPollMs ?? 250,
 		rpcTimeoutMs: config?.rpcTimeoutMs ?? 3e4
 	};
@@ -113,9 +117,18 @@ const RUNS = {
 		"getEvent",
 		"listEvents",
 		"listSteps",
-		"listHooks"
+		"listHooks",
+		"getCleanupStatus",
+		"scheduleCleanup",
+		"cleanupNow",
+		"rearmCleanup"
 	],
-	mutating: /* @__PURE__ */ new Set(["applyEvent"])
+	mutating: /* @__PURE__ */ new Set([
+		"applyEvent",
+		"scheduleCleanup",
+		"cleanupNow",
+		"rearmCleanup"
+	])
 };
 const STREAMS = {
 	methods: [
@@ -124,12 +137,18 @@ const STREAMS = {
 		"getChunks",
 		"getInfo",
 		"registerStream",
-		"listStreams"
+		"listStreams",
+		"expireRegistry",
+		"finalizeRegistry",
+		"expireStream"
 	],
 	mutating: /* @__PURE__ */ new Set([
 		"writeChunk",
 		"closeStream",
-		"registerStream"
+		"registerStream",
+		"expireRegistry",
+		"finalizeRegistry",
+		"expireStream"
 	])
 };
 const QUEUE = {
@@ -139,13 +158,15 @@ const QUEUE = {
 		"listDeadLetters",
 		"redriveDeadLetter",
 		"purgeDeadLetters",
-		"rearmAlarm"
+		"rearmAlarm",
+		"expireRun"
 	],
 	mutating: /* @__PURE__ */ new Set([
 		"enqueue",
 		"redriveDeadLetter",
 		"purgeDeadLetters",
-		"rearmAlarm"
+		"rearmAlarm",
+		"expireRun"
 	])
 };
 function makeStub(transport, binding, name, spec) {
@@ -171,6 +192,12 @@ function makeIndexNamespace(transport) {
 		get: (key) => call("get", [key], true),
 		put: (key, value) => call("put", [key, value], false),
 		delete: (key) => call("delete", [key], false),
+		putOwned: (runId, key, value) => call("putOwned", [
+			runId,
+			key,
+			value
+		], false),
+		expireRun: (request) => call("expireRun", [request], false),
 		list: (options) => call("list", [options], true),
 		reserveHookToken: (token, owner) => call("reserveHookToken", [token, owner], false),
 		finalizeHookIndexes: (token, hookId, serializedHook, owner) => call("finalizeHookIndexes", [
@@ -267,10 +294,7 @@ function isPermanentError(err) {
 function computeBackoff(attempt) {
 	return Math.min(60, 2 ** attempt);
 }
-const QUEUE_PATHNAMES = {
-	workflow: "flow",
-	step: "step"
-};
+const QUEUE_PATHNAME = "flow";
 function isTestMode() {
 	if (process.env.CELLD_QUEUE_MODE === "cells") return false;
 	return process.env.VITEST === "true" || process.env.NODE_ENV === "test";
@@ -294,9 +318,8 @@ function shardFor(key, shards) {
 	return (hash >>> 0) % shards;
 }
 /**
-* In-process test pump. Holds two in-memory FIFOs and HTTP-dispatches
-* envelopes to the user's server at
-* `${baseUrl}/.well-known/workflow/v1/{flow|step}`.
+* In-process test pump. Holds an in-memory FIFO and HTTP-dispatches envelopes
+* to the user's server at `${baseUrl}/.well-known/workflow/v1/flow`.
 *
 * Mirrors world-local's idempotency semantics: messages are deduplicated on
 * `idempotencyKey` while a message with the same key is in flight, and the
@@ -310,14 +333,8 @@ function createTestPump(config) {
 	const httpTimeoutMs = config.httpTimeoutMs ?? 3e5;
 	const maxAttempts = config.maxAttempts ?? 5;
 	const baseBackoffMs = config.backoffDelayMs ?? 1e3;
-	const queues = {
-		flow: [],
-		step: []
-	};
-	const wakers = {
-		flow: [],
-		step: []
-	};
+	const queues = { flow: [] };
+	const wakers = { flow: [] };
 	/** Inflight messageIds by idempotencyKey (world-local queue.js semantics). */
 	const inflightMessages = /* @__PURE__ */ new Map();
 	let running = false;
@@ -410,7 +427,6 @@ function createTestPump(config) {
 			if (running) return;
 			running = true;
 			loop("flow");
-			loop("step");
 		},
 		stop() {
 			running = false;
@@ -429,12 +445,13 @@ function createQueue(config) {
 	};
 	return {
 		async queue(queueName, message, opts) {
-			const { kind } = parseQueueName(queueName);
+			parseQueueName(queueName);
+			const runId = "runId" in message && typeof message.runId === "string" ? message.runId : void 0;
 			if (isTestMode()) {
 				const existing = testPump.inflight(opts?.idempotencyKey);
 				if (existing) return { messageId: existing };
 				const messageId = MessageId.parse(`msg_${generateMessageId()}`);
-				testPump.push(QUEUE_PATHNAMES[kind], {
+				testPump.push(QUEUE_PATHNAME, {
 					messageId,
 					queueName,
 					attempt: 1,
@@ -448,8 +465,9 @@ function createQueue(config) {
 			const outcome = await getQueueStub(shard).enqueue({
 				messageId,
 				queueName,
-				pathname: QUEUE_PATHNAMES[kind],
+				pathname: QUEUE_PATHNAME,
 				body: stringify(message),
+				runId,
 				idempotencyKey: opts?.idempotencyKey,
 				delaySeconds: opts?.delaySeconds,
 				config: {
@@ -457,7 +475,10 @@ function createQueue(config) {
 					queueShards
 				}
 			});
-			if (!outcome.ok) throw new WorkflowWorldError(outcome.message, { status: 409 });
+			if (!outcome.ok) {
+				if (outcome.code === "RUN_EXPIRED") throw new RunExpiredError(outcome.message);
+				throw new WorkflowWorldError(outcome.message, { status: 409 });
+			}
 			return { messageId: MessageId.parse(outcome.messageId) };
 		},
 		createQueueHandler(queueNamePrefix, handler) {
@@ -515,15 +536,6 @@ function createQueue(config) {
 }
 //#endregion
 //#region src/storage.ts
-function sortableTimestamp(date) {
-	return date.getTime().toString().padStart(13, "0");
-}
-function workflowRunIndexKey(run) {
-	return `run:${run.workflowName}:${sortableTimestamp(run.createdAt)}:${run.runId}`;
-}
-function globalRunIndexKey(run) {
-	return `runall:${sortableTimestamp(run.createdAt)}:${run.runId}`;
-}
 function hookOwner(hook) {
 	return {
 		runId: hook.runId,
@@ -566,26 +578,34 @@ function throwOutcomeError(outcome, runId, data) {
 		case "RUN_NOT_FOUND": throw new WorkflowRunNotFoundError(runId);
 		case "STEP_NOT_FOUND": throw new WorkflowWorldError(outcome.message, { status: 404 });
 		case "HOOK_NOT_FOUND": throw new HookNotFoundError(data.correlationId ?? runId);
+		case "WAIT_NOT_FOUND": throw new WorkflowWorldError(outcome.message, { status: 404 });
 		case "ENTITY_CONFLICT": throw new EntityConflictError(outcome.message);
 		case "RUN_EXPIRED": throw new RunExpiredError(outcome.message);
 		case "TOO_EARLY": throw new TooEarlyError(outcome.message, { retryAfter: outcome.retryAfterSeconds });
 		case "RUN_NOT_SUPPORTED": throw new RunNotSupportedError(outcome.runSpecVersion ?? 0, SPEC_VERSION_CURRENT);
-		case "LEGACY_RUN_NOT_SUPPORTED": throw new WorkflowWorldError(outcome.message, { status: 422 });
 	}
 }
 const parseRun = (run) => WorkflowRunSchema.parse(compact(run));
 const parseStep = (step) => StepSchema.parse(compact(step));
 const parseHook = (hook) => HookSchema.parse(compact(hook));
 const parseEvent = (event) => EventSchema.parse(compact(event));
+function unwrapRead(outcome) {
+	if (!outcome.ok) throw new RunExpiredError(outcome.message);
+	return outcome.value;
+}
 function createStorage(config) {
 	const { env } = config;
+	const cleanup = {
+		retentionMs: config.runRetentionMs ?? 0,
+		queueShards: config.queueShards ?? 1
+	};
 	const ulid = monotonicFactory();
 	const getRunDO = (runId) => {
 		const id = env.WORKFLOW_DB.idFromName(runId);
 		return env.WORKFLOW_DB.get(id);
 	};
 	const runsGet = async (runId, params) => {
-		const run = await getRunDO(runId).getRun();
+		const run = unwrapRead(await getRunDO(runId).getRun());
 		if (!run) throw new WorkflowRunNotFoundError(runId);
 		return filterData(parseRun(run), params?.resolveData, ["input", "output"]);
 	};
@@ -624,7 +644,7 @@ function createStorage(config) {
 								if (matches.length > limit) break;
 							}
 						} catch (error) {
-							if (!WorkflowRunNotFoundError.is(error)) throw error;
+							if (!WorkflowRunNotFoundError.is(error) && !RunExpiredError.is(error)) throw error;
 						}
 					}
 					exhausted = kvList.list_complete;
@@ -640,7 +660,7 @@ function createStorage(config) {
 			}
 		},
 		events: {
-			async create(runId, data, _params) {
+			async create(runId, data, params) {
 				let effectiveRunId;
 				if (data.eventType === "run_created" && (!runId || runId === "")) effectiveRunId = `wrun_${ulid()}`;
 				else if (!runId) throw new WorkflowWorldError("runId is required for non-run_created events", { status: 400 });
@@ -661,7 +681,9 @@ function createStorage(config) {
 					outcome = await stub.applyEvent({
 						runId: effectiveRunId,
 						data,
-						tokenHolder
+						params,
+						tokenHolder,
+						cleanup
 					});
 				} catch (error) {
 					if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
@@ -677,8 +699,8 @@ function createStorage(config) {
 						createdAt: outcome.run.createdAt.toISOString(),
 						status: outcome.run.status
 					});
-					await env.WORKFLOW_INDEX.put(workflowRunIndexKey(outcome.run), meta);
-					await env.WORKFLOW_INDEX.put(globalRunIndexKey(outcome.run), meta);
+					await env.WORKFLOW_INDEX.putOwned(effectiveRunId, workflowRunIndexKey(outcome.run), meta);
+					await env.WORKFLOW_INDEX.putOwned(effectiveRunId, globalRunIndexKey(outcome.run), meta);
 				}
 				if (outcome.hookToIndex) {
 					const serialized = stringify(outcome.hookToIndex);
@@ -689,33 +711,41 @@ function createStorage(config) {
 					hookId: released.hookId
 				});
 				if (outcome.event?.correlationId) {
-					const correlationKey = `correlation:${encodeURIComponent(outcome.event.correlationId)}:${sortableTimestamp(outcome.event.createdAt)}:${outcome.event.eventId}:${effectiveRunId}`;
-					await env.WORKFLOW_INDEX.put(correlationKey, JSON.stringify({
+					const correlationKey = correlationIndexKey(outcome.event.correlationId, outcome.event.createdAt, outcome.event.eventId, effectiveRunId);
+					await env.WORKFLOW_INDEX.putOwned(effectiveRunId, correlationKey, JSON.stringify({
 						runId: effectiveRunId,
 						eventId: outcome.event.eventId
 					}));
 				}
+				const eventPage = outcome.events === void 0 ? {} : {
+					events: outcome.events,
+					cursor: outcome.cursor ?? null,
+					hasMore: outcome.hasMore ?? false
+				};
 				return {
 					event: outcome.event,
 					run: outcome.run,
 					step: outcome.step,
 					hook: outcome.hook,
-					events: outcome.events
+					wait: outcome.wait,
+					stepCreated: outcome.stepCreated,
+					maxEvents: outcome.maxEvents,
+					...eventPage
 				};
 			},
 			async get(runId, eventId, _params) {
-				const event = await getRunDO(runId).getEvent(eventId);
+				const event = unwrapRead(await getRunDO(runId).getEvent(eventId));
 				if (!event) throw new WorkflowWorldError(`Event not found: ${eventId}`, { status: 404 });
 				return parseEvent(event);
 			},
 			async list(params) {
 				const { runId } = params;
 				const limit = params?.pagination?.limit ?? 100;
-				const result = await getRunDO(runId).listEvents({
+				const result = unwrapRead(await getRunDO(runId).listEvents({
 					limit,
 					cursor: params?.pagination?.cursor || void 0,
 					sortOrder: params.pagination?.sortOrder || "asc"
-				});
+				}));
 				return {
 					data: result.data.map(parseEvent),
 					cursor: result.cursor,
@@ -724,40 +754,48 @@ function createStorage(config) {
 			},
 			async listByCorrelationId(params) {
 				const limit = params.pagination?.limit ?? 100;
-				const prefix = `correlation:${encodeURIComponent(params.correlationId)}:`;
-				const listed = await env.WORKFLOW_INDEX.list({
-					prefix,
-					limit,
-					cursor: params.pagination?.cursor,
-					reverse: params.pagination?.sortOrder === "desc"
-				});
+				const stub = getRunDO(params.runId);
+				const matches = [];
+				let scanCursor = params.pagination?.cursor;
+				let exhausted = false;
+				while (matches.length <= limit && !exhausted) {
+					const page = unwrapRead(await stub.listEvents({
+						limit: Math.min(1e3, Math.max(50, limit + 1)),
+						cursor: scanCursor,
+						sortOrder: params.pagination?.sortOrder ?? "asc"
+					}));
+					for (const event of page.data) if (event.correlationId === params.correlationId) {
+						matches.push(event);
+						if (matches.length > limit) break;
+					}
+					exhausted = !page.hasMore;
+					scanCursor = page.cursor ?? page.data.at(-1)?.eventId;
+					if (page.data.length === 0) exhausted = true;
+				}
+				const hasMore = matches.length > limit;
+				const data = matches.slice(0, limit);
 				return {
-					data: (await Promise.all(listed.keys.map(async ({ name }) => {
-						const raw = await env.WORKFLOW_INDEX.get(name);
-						if (!raw) return null;
-						const { runId, eventId } = JSON.parse(raw);
-						return getRunDO(runId).getEvent(eventId);
-					}))).filter((event) => event !== null).map(parseEvent),
-					cursor: listed.list_complete ? null : listed.cursor ?? null,
-					hasMore: !listed.list_complete
+					data: data.map(parseEvent),
+					cursor: hasMore ? data.at(-1)?.eventId ?? null : null,
+					hasMore
 				};
 			}
 		},
 		steps: {
 			async get(runId, stepId, params) {
 				if (!runId) throw new WorkflowWorldError("runId is required for Cloudflare step lookup", { status: 400 });
-				const step = await getRunDO(runId).getStep(stepId);
+				const step = unwrapRead(await getRunDO(runId).getStep(stepId));
 				if (!step) throw new WorkflowWorldError(`Step not found: ${stepId}`, { status: 404 });
 				return filterData(parseStep(step), params?.resolveData, ["input", "output"]);
 			},
 			async list(params) {
 				const { runId } = params;
 				const limit = params?.pagination?.limit ?? 20;
-				const result = await getRunDO(runId).listSteps({
+				const result = unwrapRead(await getRunDO(runId).listSteps({
 					limit,
 					cursor: params?.pagination?.cursor || void 0,
 					sortOrder: params?.pagination?.sortOrder ?? "asc"
-				});
+				}));
 				return {
 					data: result.data.map((s) => filterData(parseStep(s), params?.resolveData, ["input", "output"])),
 					cursor: result.cursor,
@@ -780,11 +818,11 @@ function createStorage(config) {
 				if (!params.runId) throw new WorkflowWorldError("runId is required for listing hooks", { status: 400 });
 				const runId = params.runId;
 				const limit = params?.pagination?.limit ?? 100;
-				const result = await getRunDO(runId).listHooks({
+				const result = unwrapRead(await getRunDO(runId).listHooks({
 					limit,
 					cursor: params?.pagination?.cursor || void 0,
 					sortOrder: params?.pagination?.sortOrder ?? "asc"
-				});
+				}));
 				return {
 					data: result.data.map((h) => filterHookData(parseHook(h), params?.resolveData ?? "all")),
 					cursor: result.cursor,
@@ -822,76 +860,90 @@ function createStreamer(config) {
 	async function registerStreamForRun(name, runId) {
 		const cacheKey = `${runId}\0${name}`;
 		if (registeredStreams.has(cacheKey)) return;
-		await getRunRegistryDO(runId).registerStream(name);
+		await getRunRegistryDO(runId).registerStream(runId, name);
 		registeredStreams.add(cacheKey);
 	}
-	return {
-		async writeToStream(name, runId, chunk) {
-			await registerStreamForRun(name, await runId);
-			await getStreamDO(name).writeChunk(toBytes(chunk));
-		},
-		async closeStream(name, runId) {
-			await registerStreamForRun(name, await runId);
-			await getStreamDO(name).closeStream();
-		},
-		async readFromStream(name, startIndex = 0) {
-			const stub = getStreamDO(name);
-			let nextIndex;
-			if (startIndex < 0) {
-				const info = await stub.getInfo();
-				nextIndex = Math.max(0, info.tailIndex + 1 + startIndex);
-			} else nextIndex = startIndex;
-			let cancelled = false;
-			return new ReadableStream({
-				async pull(controller) {
-					while (true) {
-						if (cancelled) return;
-						const { chunks, done } = await stub.getChunks({
-							startIndex: nextIndex,
-							limit: READ_BATCH_SIZE
-						});
-						if (chunks.length > 0) {
-							for (const chunk of chunks) controller.enqueue(chunk);
-							nextIndex += chunks.length;
-							return;
-						}
-						if (done) {
-							controller.close();
-							return;
-						}
-						await new Promise((resolve) => setTimeout(resolve, readPollMs));
+	const writeToStream = async (name, runId, chunk) => {
+		const resolvedRunId = await runId;
+		await registerStreamForRun(name, resolvedRunId);
+		await getStreamDO(name).writeChunk(resolvedRunId, toBytes(chunk));
+	};
+	const closeStream = async (name, runId) => {
+		const resolvedRunId = await runId;
+		await registerStreamForRun(name, resolvedRunId);
+		await getStreamDO(name).closeStream(resolvedRunId);
+	};
+	const readFromStream = async (name, startIndex = 0) => {
+		const stub = getStreamDO(name);
+		let nextIndex;
+		if (startIndex < 0) {
+			const info = await stub.getInfo();
+			nextIndex = Math.max(0, info.tailIndex + 1 + startIndex);
+		} else nextIndex = startIndex;
+		let cancelled = false;
+		return new ReadableStream({
+			async pull(controller) {
+				while (true) {
+					if (cancelled) return;
+					const { chunks, done } = await stub.getChunks({
+						startIndex: nextIndex,
+						limit: READ_BATCH_SIZE
+					});
+					if (chunks.length > 0) {
+						for (const chunk of chunks) controller.enqueue(chunk);
+						nextIndex += chunks.length;
+						return;
 					}
-				},
-				cancel() {
-					cancelled = true;
+					if (done) {
+						controller.close();
+						return;
+					}
+					await new Promise((resolve) => setTimeout(resolve, readPollMs));
 				}
-			});
-		},
-		async listStreamsByRunId(runId) {
-			return getRunRegistryDO(runId).listStreams();
-		},
-		async getStreamChunks(name, _runId, options) {
-			const limit = Math.min(options?.limit ?? DEFAULT_CHUNK_PAGE_SIZE, MAX_CHUNK_PAGE_SIZE);
-			const startIndex = options?.cursor ? Number.parseInt(options.cursor, 10) : 0;
-			if (Number.isNaN(startIndex) || startIndex < 0) throw new Error(`Invalid stream cursor: ${options?.cursor}`);
-			const result = await getStreamDO(name).getChunks({
-				startIndex,
-				limit: limit + 1
-			});
-			const hasMore = result.chunks.length > limit;
-			return {
-				data: result.chunks.slice(0, limit).map((chunk, offset) => ({
-					index: startIndex + offset,
-					data: chunk
-				})),
-				cursor: hasMore ? String(startIndex + limit) : null,
-				hasMore,
-				done: result.done
-			};
+			},
+			cancel() {
+				cancelled = true;
+			}
+		});
+	};
+	const listStreamsByRunId = (runId) => getRunRegistryDO(runId).listStreams();
+	const getStreamChunks = async (name, _runId, options) => {
+		const limit = Math.min(options?.limit ?? DEFAULT_CHUNK_PAGE_SIZE, MAX_CHUNK_PAGE_SIZE);
+		const startIndex = options?.cursor ? Number.parseInt(options.cursor, 10) : 0;
+		if (Number.isNaN(startIndex) || startIndex < 0) throw new Error(`Invalid stream cursor: ${options?.cursor}`);
+		const result = await getStreamDO(name).getChunks({
+			startIndex,
+			limit: limit + 1
+		});
+		const hasMore = result.chunks.length > limit;
+		return {
+			data: result.chunks.slice(0, limit).map((chunk, offset) => ({
+				index: startIndex + offset,
+				data: chunk
+			})),
+			cursor: hasMore ? String(startIndex + limit) : null,
+			hasMore,
+			done: result.done
+		};
+	};
+	const getStreamInfo = (name, _runId) => getStreamDO(name).getInfo();
+	return {
+		streams: {
+			write: (runId, name, chunk) => writeToStream(name, runId, chunk),
+			close: (runId, name) => closeStream(name, runId),
+			get: (runId, name, startIndex) => {
+				return readFromStream(name, startIndex);
+			},
+			list: listStreamsByRunId,
+			getChunks: (runId, name, options) => getStreamChunks(name, runId, options),
+			getInfo: (runId, name) => getStreamInfo(name, runId)
 		},
-		async getStreamInfo(name, _runId) {
-			return getStreamDO(name).getInfo();
-		}
+		writeToStream,
+		closeStream,
+		readFromStream,
+		listStreamsByRunId,
+		getStreamChunks,
+		getStreamInfo
 	};
 }
 //#endregion
@@ -924,7 +976,9 @@ function createCelldWorld(config) {
 			WORKFLOW_DB: env.WORKFLOW_DB,
 			WORKFLOW_INDEX: env.WORKFLOW_INDEX
 		},
-		deploymentId: resolved.deploymentId
+		deploymentId: resolved.deploymentId,
+		runRetentionMs: resolved.runRetentionMs,
+		queueShards: resolved.queueShards
 	});
 	const queue = createQueue({
 		env: { WORKFLOW_QUEUE: env.WORKFLOW_QUEUE },
@@ -936,10 +990,27 @@ function createCelldWorld(config) {
 		env: { WORKFLOW_STREAMS: env.WORKFLOW_STREAMS },
 		readPollMs: resolved.readPollMs
 	});
+	const runStub = (runId) => env.WORKFLOW_DB.get(env.WORKFLOW_DB.idFromName(runId));
+	const retention = {
+		getStatus: (runId) => runStub(runId).getCleanupStatus(),
+		schedule: (runId) => {
+			if (resolved.runRetentionMs === 0) throw new Error("world-celld: runRetentionMs must be greater than zero to schedule cleanup");
+			return runStub(runId).scheduleCleanup({
+				retentionMs: resolved.runRetentionMs,
+				queueShards: resolved.queueShards
+			});
+		},
+		cleanupNow: (runId) => runStub(runId).cleanupNow({
+			retentionMs: Math.max(1, resolved.runRetentionMs),
+			queueShards: resolved.queueShards
+		}),
+		rearm: (runId) => runStub(runId).rearmCleanup()
+	};
 	return {
 		...storage,
 		...queue,
 		...streamer,
+		retention,
 		specVersion: SPEC_VERSION_CURRENT
 	};
 }