@ewhauser/world-celld 0.1.0

package/dist/index.js

@@ -0,0 +1,949 @@
+import { a as stringify, i as parse, n as rpcParse, r as rpcStringify, t as compact } from "./util-BvWlkqgV.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) {
+	return {
+		fleetUrl: config?.fleetUrl ?? process.env.CELLD_FLEET_URL,
+		secret: config?.secret ?? process.env.CELLD_WORLD_SECRET,
+		env: config?.env,
+		deploymentId: config?.deploymentId ?? process.env.CELLD_DEPLOYMENT_ID ?? "celld-default",
+		baseUrl: config?.baseUrl,
+		queueShards: config?.queueShards ?? 1,
+		readPollMs: config?.readPollMs ?? 250,
+		rpcTimeoutMs: config?.rpcTimeoutMs ?? 3e4
+	};
+}
+//#endregion
+//#region src/remote/errors.ts
+/**
+* Reconstruct a typed error from a router error payload. `@workflow/errors`
+* matches with name-based `.is()` checks, so a WorkflowWorldError with the
+* original name (and status) restored behaves identically to the source
+* error for every consumer in the workflow runtime.
+*/
+function reconstructError(wire, httpStatus) {
+	const message = wire?.message ?? `world-celld rpc failed with HTTP ${httpStatus}`;
+	const error = new WorkflowWorldError(message, { status: wire?.status ?? httpStatus });
+	if (wire?.name) error.name = wire.name;
+	return error;
+}
+/** Transport-level failure (fleet unreachable, malformed response). */
+var FleetTransportError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "FleetTransportError";
+	}
+};
+//#endregion
+//#region src/remote/rpc-client.ts
+/** Statuses that mean "the fleet couldn't take the request" (safe to retry reads). */
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	502,
+	503,
+	504
+]);
+const DEFAULT_TIMEOUT_MS = 3e4;
+function delayMs(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Invoke one DO method through the worker router.
+*
+* Mutating calls run exactly once from the client's perspective: a blind
+* retry of e.g. applyEvent would turn commit-then-network-fail into a
+* spurious ENTITY_CONFLICT. The workflow runtime already gets at-least-once
+* via queue redelivery. Read-only calls retry on transport failures.
+*/
+async function callDO(transport, binding, name, method, args, opts) {
+	const doFetch = transport.fetchImpl ?? fetch;
+	const url = `${transport.fleetUrl.replace(/\/$/, "")}/v1/rpc/${binding}/${encodeURIComponent(name)}/${method}`;
+	const attempts = opts?.idempotent ? 3 : 1;
+	let lastError;
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		if (attempt > 1) await delayMs(100 * attempt + Math.random() * 200);
+		let response;
+		try {
+			response = await doFetch(url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${transport.secret}`
+				},
+				body: rpcStringify(args),
+				signal: AbortSignal.timeout(Math.max(1, transport.timeoutMs ?? DEFAULT_TIMEOUT_MS))
+			});
+		} catch (error) {
+			lastError = new FleetTransportError(`world-celld: fleet unreachable at ${url}`, error);
+			continue;
+		}
+		if (response.ok) try {
+			return rpcParse(await response.text());
+		} catch (error) {
+			lastError = new FleetTransportError(`world-celld: malformed successful response from ${url}`, error);
+			if (attempt < attempts) continue;
+			throw lastError;
+		}
+		const text = await response.text();
+		let wire;
+		try {
+			wire = JSON.parse(text).error;
+		} catch {
+			wire = { message: text || `HTTP ${response.status}` };
+		}
+		if (RETRYABLE_STATUSES.has(response.status) && attempt < attempts) {
+			lastError = reconstructError(wire, response.status);
+			continue;
+		}
+		throw reconstructError(wire, response.status);
+	}
+	throw lastError instanceof Error ? lastError : new FleetTransportError("world-celld: rpc failed", lastError);
+}
+//#endregion
+//#region src/remote/namespaces.ts
+const RUNS = {
+	methods: [
+		"applyEvent",
+		"getRun",
+		"getStep",
+		"getEvent",
+		"listEvents",
+		"listSteps",
+		"listHooks"
+	],
+	mutating: /* @__PURE__ */ new Set(["applyEvent"])
+};
+const STREAMS = {
+	methods: [
+		"writeChunk",
+		"closeStream",
+		"getChunks",
+		"getInfo",
+		"registerStream",
+		"listStreams"
+	],
+	mutating: /* @__PURE__ */ new Set([
+		"writeChunk",
+		"closeStream",
+		"registerStream"
+	])
+};
+const QUEUE = {
+	methods: [
+		"enqueue",
+		"stats",
+		"listDeadLetters",
+		"redriveDeadLetter",
+		"purgeDeadLetters",
+		"rearmAlarm"
+	],
+	mutating: /* @__PURE__ */ new Set([
+		"enqueue",
+		"redriveDeadLetter",
+		"purgeDeadLetters",
+		"rearmAlarm"
+	])
+};
+function makeStub(transport, binding, name, spec) {
+	const stub = {};
+	for (const method of spec.methods) stub[method] = (...args) => callDO(transport, binding, name, method, args, { idempotent: !spec.mutating.has(method) });
+	return stub;
+}
+function makeNamespace(transport, binding, spec) {
+	return {
+		idFromName(name) {
+			return { toString: () => name };
+		},
+		get(id) {
+			return makeStub(transport, binding, id.toString(), spec);
+		}
+	};
+}
+/** The IndexDO is a single well-known cell. */
+const INDEX_CELL_NAME = "index";
+function makeIndexNamespace(transport) {
+	const call = (method, args, idempotent) => callDO(transport, "index", INDEX_CELL_NAME, method, args, { idempotent });
+	return {
+		get: (key) => call("get", [key], true),
+		put: (key, value) => call("put", [key, value], false),
+		delete: (key) => call("delete", [key], false),
+		list: (options) => call("list", [options], true),
+		reserveHookToken: (token, owner) => call("reserveHookToken", [token, owner], false),
+		finalizeHookIndexes: (token, hookId, serializedHook, owner) => call("finalizeHookIndexes", [
+			token,
+			hookId,
+			serializedHook,
+			owner
+		], false),
+		releaseHookToken: (token, owner) => call("releaseHookToken", [token, owner], false),
+		deleteHookIndexes: (token, hookId, owner) => call("deleteHookIndexes", [
+			token,
+			hookId,
+			owner
+		], false)
+	};
+}
+function createRemoteEnv(transport) {
+	return {
+		WORKFLOW_DB: makeNamespace(transport, "runs", RUNS),
+		WORKFLOW_STREAMS: makeNamespace(transport, "streams", STREAMS),
+		WORKFLOW_INDEX: makeIndexNamespace(transport),
+		WORKFLOW_QUEUE: makeNamespace(transport, "queue", QUEUE)
+	};
+}
+//#endregion
+//#region src/vendor/shared/debug.ts
+/**
+* Creates a namespaced debug logger.
+* Logs to stderr to avoid corrupting CLI JSON output on stdout.
+*
+* Control via WORKFLOW_DEBUG environment variable:
+*   WORKFLOW_DEBUG=1                       // Enable all
+*   WORKFLOW_DEBUG=mysql-world             // Specific namespace
+*   WORKFLOW_DEBUG=mysql-world,redis-world // Multiple namespaces
+*
+* Vendored from vinnymac/worlds packages/shared, modified: guarded for
+* non-Node runtimes (celld/workerd), where `process` may be absent or
+* stubbed — falls back to console.error.
+*/
+function createDebugLogger(namespace) {
+	return (...args) => {
+		const debug = typeof process === "undefined" ? void 0 : process.env?.WORKFLOW_DEBUG;
+		if (!debug) return;
+		if (!(debug === "1" || debug === "true" || debug === "*" || debug.split(",").some((ns) => ns.trim() === namespace))) return;
+		const prefix = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${namespace}]`;
+		const message = args.map((arg) => typeof arg === "object" ? JSON.stringify(arg, null, 2) : String(arg)).join(" ");
+		if (typeof process.stderr?.write === "function") process.stderr.write(`${prefix} ${message}\n`);
+		else console.error(`${prefix} ${message}`);
+	};
+}
+//#endregion
+//#region src/util.ts
+const debug = createDebugLogger("celld-world");
+//#endregion
+//#region src/queue.ts
+/**
+* Queue implementation for the celld world.
+*
+* Vendored from vinnymac/worlds packages/world-cloudflare/src/queue.ts
+* (Apache-2.0, see NOTICE), modified for celld:
+*
+* - The Cloudflare Queues producer is replaced by an `enqueue` RPC to a
+*   QueueDO cell (`q:<shard>`), which owns the message lifecycle: scheduling
+*   via durable alarms, delivery via outbound fetch, retries with capped
+*   backoff, and a dead-letter table.
+* - The consumer-side claim-DO idempotency mechanism is gone: a queue cell is
+*   a single serialized writer, so idempotencyKey dedup happens inside the
+*   cell (at enqueue and across the delivery state machine).
+* - `createQueueHandler` has ONE dialect — the x-vqs wire format the test
+*   pump has always used — extended so permanent errors surface as their
+*   HTTP statuses. QueueDO deliveries and the in-process test pump hit the
+*   exact same handler path.
+*/
+/**
+* HTTP status codes that indicate permanent (non-retryable) failures.
+* Deliveries with these statuses are dropped immediately instead of retried.
+*
+* - 404: Resource not found (e.g., run was deleted)
+* - 409: Conflict (e.g., duplicate event that can't be replayed)
+* - 410: Gone (e.g., run was already terminal)
+* - 422: Unprocessable entity (e.g., invalid payload structure)
+*/
+const PERMANENT_ERROR_STATUSES = /* @__PURE__ */ new Set([
+	404,
+	409,
+	410,
+	422
+]);
+function isPermanentError(err) {
+	if (err instanceof WorkflowWorldError && err.status !== void 0) return PERMANENT_ERROR_STATUSES.has(err.status);
+	return false;
+}
+/** Caps at 60 seconds. */
+function computeBackoff(attempt) {
+	return Math.min(60, 2 ** attempt);
+}
+const QUEUE_PATHNAMES = {
+	workflow: "flow",
+	step: "step"
+};
+function isTestMode() {
+	if (process.env.CELLD_QUEUE_MODE === "cells") return false;
+	return process.env.VITEST === "true" || process.env.NODE_ENV === "test";
+}
+function resolveBaseUrl(config) {
+	if (config.baseUrl) return config.baseUrl;
+	if (process.env.WORKFLOW_BASE_URL) return process.env.WORKFLOW_BASE_URL;
+	return `http://localhost:${process.env.PORT ?? "3000"}`;
+}
+/**
+* FNV-1a hash for shard selection. All messages sharing an idempotencyKey
+* land on the same cell so dedup stays strictly consistent.
+*/
+function shardFor(key, shards) {
+	if (shards <= 1) return 0;
+	let hash = 2166136261;
+	for (let i = 0; i < key.length; i++) {
+		hash ^= key.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	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}`.
+*
+* Mirrors world-local's idempotency semantics: messages are deduplicated on
+* `idempotencyKey` while a message with the same key is in flight, and the
+* key is released only when the message is fully handled (success or drop).
+*
+* Modified vs upstream: permanent-error statuses (404/409/410/422) from the
+* handler drop the message immediately instead of burning retry budget —
+* matching QueueDO's production semantics.
+*/
+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: []
+	};
+	/** Inflight messageIds by idempotencyKey (world-local queue.js semantics). */
+	const inflightMessages = /* @__PURE__ */ new Map();
+	let running = false;
+	function release(envelope) {
+		if (envelope.idempotencyKey) inflightMessages.delete(envelope.idempotencyKey);
+	}
+	function enqueue(pathname, envelope) {
+		queues[pathname].push(envelope);
+		wakers[pathname].shift()?.();
+	}
+	async function take(pathname) {
+		const existing = queues[pathname].shift();
+		if (existing) return existing;
+		return new Promise((resolve) => {
+			wakers[pathname].push(() => resolve(queues[pathname].shift() ?? null));
+		});
+	}
+	async function dispatch(envelope, pathname) {
+		const url = `${resolveBaseUrl(config)}/.well-known/workflow/v1/${pathname}`;
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"x-vqs-queue-name": envelope.queueName,
+				"x-vqs-message-id": envelope.messageId,
+				"x-vqs-message-attempt": String(envelope.attempt)
+			},
+			body: stringify(envelope.message),
+			signal: AbortSignal.timeout(httpTimeoutMs)
+		});
+		if (response.ok) {
+			release(envelope);
+			return;
+		}
+		const text = await response.text();
+		if (response.status === 503) {
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				parsed = null;
+			}
+			const timeoutSeconds = parsed?.timeoutSeconds;
+			if (typeof timeoutSeconds === "number") {
+				setTimeout$1(timeoutSeconds * 1e3).then(() => enqueue(pathname, envelope));
+				return;
+			}
+		}
+		if (PERMANENT_ERROR_STATUSES.has(response.status)) {
+			release(envelope);
+			debug(`[world-celld test pump] dropping ${envelope.messageId}: permanent HTTP ${response.status}: ${text}`);
+			return;
+		}
+		if (envelope.attempt < maxAttempts) {
+			const next = {
+				...envelope,
+				attempt: envelope.attempt + 1
+			};
+			const backoff = baseBackoffMs * 2 ** (next.attempt - 1);
+			setTimeout$1(backoff).then(() => enqueue(pathname, next));
+		} else {
+			release(envelope);
+			console.error(`[world-celld test pump] dropping ${envelope.messageId} after ${envelope.attempt} attempts: HTTP ${response.status}: ${text}`);
+		}
+	}
+	async function loop(pathname) {
+		while (true) {
+			if (!running) return;
+			const envelope = await take(pathname);
+			if (!envelope) continue;
+			try {
+				await dispatch(envelope, pathname);
+			} catch (err) {
+				release(envelope);
+				console.error(`[world-celld test pump] dispatch error on ${pathname}:`, err);
+			}
+		}
+	}
+	return {
+		/** Returns the inflight messageId when the key is already claimed. */
+		inflight(idempotencyKey) {
+			return idempotencyKey ? inflightMessages.get(idempotencyKey) : void 0;
+		},
+		push(pathname, envelope, delaySeconds) {
+			if (envelope.idempotencyKey) inflightMessages.set(envelope.idempotencyKey, MessageId.parse(envelope.messageId));
+			if (delaySeconds && delaySeconds > 0) setTimeout$1(delaySeconds * 1e3).then(() => enqueue(pathname, envelope));
+			else enqueue(pathname, envelope);
+		},
+		async start() {
+			if (running) return;
+			running = true;
+			loop("flow");
+			loop("step");
+		},
+		stop() {
+			running = false;
+			for (const list of Object.values(wakers)) for (const w of list) w();
+		}
+	};
+}
+function createQueue(config) {
+	const { env, deploymentId } = config;
+	const queueShards = config.queueShards ?? 1;
+	const generateMessageId = monotonicFactory();
+	const testPump = createTestPump(config);
+	const getQueueStub = (shard) => {
+		const id = env.WORKFLOW_QUEUE.idFromName(`q:${shard}`);
+		return env.WORKFLOW_QUEUE.get(id);
+	};
+	return {
+		async queue(queueName, message, opts) {
+			const { kind } = parseQueueName(queueName);
+			if (isTestMode()) {
+				const existing = testPump.inflight(opts?.idempotencyKey);
+				if (existing) return { messageId: existing };
+				const messageId = MessageId.parse(`msg_${generateMessageId()}`);
+				testPump.push(QUEUE_PATHNAMES[kind], {
+					messageId,
+					queueName,
+					attempt: 1,
+					message,
+					idempotencyKey: opts?.idempotencyKey
+				}, opts?.delaySeconds);
+				return { messageId };
+			}
+			const messageId = MessageId.parse(`msg_${generateMessageId()}`);
+			const shard = shardFor(opts?.idempotencyKey ?? messageId, queueShards);
+			const outcome = await getQueueStub(shard).enqueue({
+				messageId,
+				queueName,
+				pathname: QUEUE_PATHNAMES[kind],
+				body: stringify(message),
+				idempotencyKey: opts?.idempotencyKey,
+				delaySeconds: opts?.delaySeconds,
+				config: {
+					targetBaseUrl: resolveBaseUrl(config),
+					queueShards
+				}
+			});
+			if (!outcome.ok) throw new WorkflowWorldError(outcome.message, { status: 409 });
+			return { messageId: MessageId.parse(outcome.messageId) };
+		},
+		createQueueHandler(queueNamePrefix, handler) {
+			return async (req) => {
+				const reqQueueName = req.headers.get("x-vqs-queue-name");
+				const reqMessageId = req.headers.get("x-vqs-message-id");
+				const attemptStr = req.headers.get("x-vqs-message-attempt");
+				if (!reqQueueName || !reqMessageId || !attemptStr || !req.body) return Response.json({ error: "Missing required headers or body" }, { status: 400 });
+				if (!reqQueueName.startsWith(queueNamePrefix)) return Response.json({ error: "Unhandled queue" }, { status: 400 });
+				const attempt = Number.parseInt(attemptStr, 10);
+				try {
+					const result = await handler(parse(await req.text()), {
+						attempt,
+						queueName: reqQueueName,
+						messageId: reqMessageId
+					});
+					if (result && typeof result.timeoutSeconds === "number") return Response.json({ timeoutSeconds: result.timeoutSeconds }, {
+						status: 503,
+						headers: { "Retry-After": String(result.timeoutSeconds) }
+					});
+					return Response.json({ ok: true });
+				} catch (error) {
+					if (isPermanentError(error)) {
+						debug("[world-celld queue handler] permanent error:", {
+							status: error.status,
+							error: String(error)
+						});
+						return Response.json({
+							error: String(error),
+							permanent: true
+						}, { status: error.status });
+					}
+					const backoffSeconds = computeBackoff(attempt);
+					debug("[world-celld queue handler] transient error, will retry:", {
+						error: String(error),
+						backoffSeconds
+					});
+					return Response.json({
+						error: String(error),
+						retryAfter: backoffSeconds
+					}, {
+						status: 500,
+						headers: { "Retry-After": String(backoffSeconds) }
+					});
+				}
+			};
+		},
+		async getDeploymentId() {
+			return deploymentId;
+		},
+		async start() {
+			if (isTestMode()) await testPump.start();
+		}
+	};
+}
+//#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,
+		hookId: hook.hookId
+	};
+}
+/**
+* Filter data based on ResolveData parameter.
+* When resolveData is 'none', strips specified keys to reduce data transfer.
+*/
+function filterData(data, resolveData, keysToStrip) {
+	if (resolveData === "none") {
+		const newData = { ...data };
+		for (const key of keysToStrip) if (key in newData) delete newData[key];
+		return newData;
+	}
+	return data;
+}
+/**
+* Filter hook data based on resolveData parameter
+*/
+function filterHookData(hook, resolveData) {
+	if (resolveData === "none" && "metadata" in hook) {
+		const { metadata: _, ...rest } = hook;
+		return {
+			metadata: void 0,
+			...rest
+		};
+	}
+	return hook;
+}
+/**
+* Convert a structured applyEvent failure back into the typed error the
+* runtime matches on (via error-name based `.is()` checks). Typed errors
+* cannot cross the DO RPC boundary intact, which is why the DO returns
+* outcome objects instead of throwing.
+*/
+function throwOutcomeError(outcome, runId, data) {
+	switch (outcome.code) {
+		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 "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 createStorage(config) {
+	const { env } = config;
+	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();
+		if (!run) throw new WorkflowRunNotFoundError(runId);
+		return filterData(parseRun(run), params?.resolveData, ["input", "output"]);
+	};
+	return {
+		runs: {
+			get: runsGet,
+			async list(params) {
+				const limit = params?.pagination?.limit ?? 20;
+				const prefix = params?.workflowName ? `run:${params.workflowName}:` : "runall:";
+				const reverse = params?.pagination?.sortOrder === "desc";
+				const matches = [];
+				let scanCursor = params?.pagination?.cursor;
+				let exhausted = false;
+				while (matches.length <= limit && !exhausted) {
+					const kvList = await env.WORKFLOW_INDEX.list({
+						prefix,
+						limit: Math.min(1e3, Math.max(50, limit)),
+						cursor: scanCursor,
+						reverse
+					});
+					if (kvList.keys.length === 0) {
+						exhausted = true;
+						break;
+					}
+					for (const key of kvList.keys) {
+						const meta = await env.WORKFLOW_INDEX.get(key.name);
+						if (!meta) continue;
+						const { runId } = JSON.parse(meta);
+						try {
+							const run = await runsGet(runId, { resolveData: params?.resolveData });
+							if (!params?.status || run.status === params.status) {
+								matches.push({
+									key: key.name,
+									run
+								});
+								if (matches.length > limit) break;
+							}
+						} catch (error) {
+							if (!WorkflowRunNotFoundError.is(error)) throw error;
+						}
+					}
+					exhausted = kvList.list_complete;
+					scanCursor = kvList.cursor ?? kvList.keys.at(-1)?.name;
+				}
+				const hasMore = matches.length > limit;
+				const page = matches.slice(0, limit);
+				return {
+					data: page.map(({ run }) => run),
+					cursor: hasMore ? page.at(-1)?.key ?? null : null,
+					hasMore
+				};
+			}
+		},
+		events: {
+			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 });
+				else effectiveRunId = runId;
+				const stub = getRunDO(effectiveRunId);
+				let tokenHolder;
+				let hookReservation;
+				if (data.eventType === "hook_created") {
+					hookReservation = {
+						runId: effectiveRunId,
+						hookId: data.correlationId
+					};
+					const reservation = await env.WORKFLOW_INDEX.reserveHookToken(data.eventData.token, hookReservation);
+					tokenHolder = reservation.claimed ? null : reservation.holder;
+				}
+				let outcome;
+				try {
+					outcome = await stub.applyEvent({
+						runId: effectiveRunId,
+						data,
+						tokenHolder
+					});
+				} catch (error) {
+					if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
+					throw error;
+				}
+				if (!outcome.ok) {
+					if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
+					throwOutcomeError(outcome, effectiveRunId, data);
+				}
+				if (outcome.run) {
+					const meta = JSON.stringify({
+						runId: effectiveRunId,
+						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);
+				}
+				if (outcome.hookToIndex) {
+					const serialized = stringify(outcome.hookToIndex);
+					await env.WORKFLOW_INDEX.finalizeHookIndexes(outcome.hookToIndex.token, outcome.hookToIndex.hookId, serialized, hookOwner(outcome.hookToIndex));
+				} else if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
+				for (const released of outcome.releasedHooks) await env.WORKFLOW_INDEX.deleteHookIndexes(released.token, released.hookId, {
+					runId: effectiveRunId,
+					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({
+						runId: effectiveRunId,
+						eventId: outcome.event.eventId
+					}));
+				}
+				return {
+					event: outcome.event,
+					run: outcome.run,
+					step: outcome.step,
+					hook: outcome.hook,
+					events: outcome.events
+				};
+			},
+			async get(runId, eventId, _params) {
+				const event = 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({
+					limit,
+					cursor: params?.pagination?.cursor || void 0,
+					sortOrder: params.pagination?.sortOrder || "asc"
+				});
+				return {
+					data: result.data.map(parseEvent),
+					cursor: result.cursor,
+					hasMore: result.hasMore
+				};
+			},
+			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"
+				});
+				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
+				};
+			}
+		},
+		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);
+				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({
+					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,
+					hasMore: result.hasMore
+				};
+			}
+		},
+		hooks: {
+			async get(hookId, params) {
+				const raw = await env.WORKFLOW_INDEX.get(`hookid:${hookId}`);
+				if (!raw) throw new HookNotFoundError(hookId);
+				return filterHookData(parseHook(parse(raw)), params?.resolveData ?? "all");
+			},
+			async getByToken(token, params) {
+				const raw = await env.WORKFLOW_INDEX.get(`hook:${token}`);
+				if (!raw) throw new HookNotFoundError(token);
+				return filterHookData(parseHook(parse(raw)), params?.resolveData ?? "all");
+			},
+			async list(params) {
+				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({
+					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,
+					hasMore: result.hasMore
+				};
+			}
+		}
+	};
+}
+//#endregion
+//#region src/streamer.ts
+/** Default poll interval while waiting for new chunks on a live stream. */
+const READ_POLL_MS = 100;
+/** Chunks fetched per DO round-trip while reading. */
+const READ_BATCH_SIZE = 32;
+/** Default / maximum page sizes for getStreamChunks. */
+const DEFAULT_CHUNK_PAGE_SIZE = 32;
+const MAX_CHUNK_PAGE_SIZE = 32;
+function toBytes(chunk) {
+	return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+}
+function createStreamer(config) {
+	const { env } = config;
+	const readPollMs = config.readPollMs ?? READ_POLL_MS;
+	const getStreamDO = (streamName) => {
+		const id = env.WORKFLOW_STREAMS.idFromName(`stream:${streamName}`);
+		return env.WORKFLOW_STREAMS.get(id);
+	};
+	const getRunRegistryDO = (runId) => {
+		const id = env.WORKFLOW_STREAMS.idFromName(`run-streams:${runId}`);
+		return env.WORKFLOW_STREAMS.get(id);
+	};
+	/** Per-isolate cache so each (runId, stream) pair registers only once. */
+	const registeredStreams = /* @__PURE__ */ new Set();
+	async function registerStreamForRun(name, runId) {
+		const cacheKey = `${runId}\0${name}`;
+		if (registeredStreams.has(cacheKey)) return;
+		await getRunRegistryDO(runId).registerStream(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));
+					}
+				},
+				cancel() {
+					cancelled = true;
+				}
+			});
+		},
+		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
+			};
+		},
+		async getStreamInfo(name, _runId) {
+			return getStreamDO(name).getInfo();
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @ewhauser/world-celld — celld World implementation for the Vercel Workflow
+* DevKit. Modeled on vinnymac/worlds packages/world-cloudflare/src/index.ts
+* (Apache-2.0, see NOTICE).
+*/
+function createCelldWorld(config) {
+	const resolved = resolveConfig(config);
+	let env = resolved.env;
+	if (!env) {
+		const globalEnv = globalThis.CELLD_ENV;
+		if (globalEnv) env = globalEnv;
+	}
+	if (!env) {
+		if (resolved.fleetUrl) {
+			if (!resolved.secret) throw new Error("world-celld: config.secret (or CELLD_WORLD_SECRET) is required with fleetUrl");
+			env = createRemoteEnv({
+				fleetUrl: resolved.fleetUrl,
+				secret: resolved.secret,
+				timeoutMs: resolved.rpcTimeoutMs
+			});
+		}
+	}
+	if (!env) throw new Error("celld environment not configured. Provide config.fleetUrl + config.secret (or CELLD_FLEET_URL / CELLD_WORLD_SECRET), or pass config.env with WORKFLOW_DB, WORKFLOW_INDEX, WORKFLOW_QUEUE, WORKFLOW_STREAMS");
+	const storage = createStorage({
+		env: {
+			WORKFLOW_DB: env.WORKFLOW_DB,
+			WORKFLOW_INDEX: env.WORKFLOW_INDEX
+		},
+		deploymentId: resolved.deploymentId
+	});
+	const queue = createQueue({
+		env: { WORKFLOW_QUEUE: env.WORKFLOW_QUEUE },
+		deploymentId: resolved.deploymentId,
+		baseUrl: resolved.baseUrl,
+		queueShards: resolved.queueShards
+	});
+	const streamer = createStreamer({
+		env: { WORKFLOW_STREAMS: env.WORKFLOW_STREAMS },
+		readPollMs: resolved.readPollMs
+	});
+	return {
+		...storage,
+		...queue,
+		...streamer,
+		specVersion: SPEC_VERSION_CURRENT
+	};
+}
+//#endregion
+export { createCelldWorld, createCelldWorld as createWorld };
+
+//# sourceMappingURL=index.js.map