@ewhauser/world-celld 0.4.0 → 0.4.1

package/dist/index.js

@@ -1,15 +1,11 @@
-import { C as decodeStreamReadResult, D as encodeStreamWriteBatch, S as STREAM_BATCH_CONTENT_TYPE, T as decodeStreamWriteResult, _ as MAX_STREAM_ERROR_BYTES, a as stringify, b as MAX_STREAM_READ_CHUNKS, g as MAX_STREAM_CHUNK_BYTES, h as MAX_STREAM_BATCH_BYTES, i as parse, k as normalizeStreamError, n as rpcParse, o as createWorkflowIndex, r as rpcStringify, t as compact, u as MAX_FLEET_RPC_TIMEOUT_MS, v as MAX_STREAM_LONG_POLL_MS, x as MAX_STREAM_WRITE_CHUNKS, y as MAX_STREAM_READ_BYTES } from "./util-ya3V_FTA.js";
-import { EventSchema, HookSchema, MessageId, SPEC_VERSION_CURRENT, StepSchema, WorkflowRunSchema, isTerminalWorkflowRunStatus, parseQueueName } from "@workflow/world";
+import { A as MAX_STREAM_READ_CHUNKS, C as queueDelayDeadline, D as MAX_STREAM_ERROR_BYTES, E as MAX_STREAM_CHUNK_BYTES, F as decodeStreamWriteResult, L as encodeStreamWriteBatch, M as STREAM_BATCH_CONTENT_TYPE, N as decodeStreamReadResult, O as MAX_STREAM_LONG_POLL_MS, T as MAX_STREAM_BATCH_BYTES, _ as boundedIntegerOption, a as stringify, d as MAX_QUEUE_DELIVERY_TIMEOUT_MS, f as MAX_QUEUE_DERIVED_DEADLINE_HEADROOM_MS, i as parse, j as MAX_STREAM_WRITE_CHUNKS, k as MAX_STREAM_READ_BYTES, n as rpcParse, o as createWorkflowIndex, r as rpcStringify, t as compact, u as MAX_FLEET_RPC_TIMEOUT_MS, v as checkedQueueTimestampAdd, w as strictIntegerSetting, z as normalizeStreamError } from "./util-Cu09mVzK.js";
+import { CreateEventSchema, EventSchema, HookSchema, MessageId, QueuePayloadSchema, SPEC_VERSION_CURRENT, StepSchema, WaitSchema, WorkflowRunSchema, isTerminalWorkflowRunStatus, 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 queueShards = config?.queueShards ?? 1;
-	if (!Number.isSafeInteger(queueShards) || queueShards < 1) throw new Error("world-celld: queueShards must be a positive safe integer");
-	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");
+	const queueShards = boundedIntegerOption("world-celld: queueShards", config?.queueShards, 1, 1);
+	const runRetentionMs = config?.runRetentionMs !== void 0 ? boundedIntegerOption("world-celld: runRetentionMs", config.runRetentionMs, 0, 0) : strictIntegerSetting("world-celld: runRetentionMs", process.env.CELLD_RUN_RETENTION_MS, 0, 0);
 	const rpcTimeoutMs = config?.rpcTimeoutMs ?? 3e4;
 	if (!Number.isSafeInteger(rpcTimeoutMs) || rpcTimeoutMs < 1 || rpcTimeoutMs > 3e5) throw new Error(`world-celld: rpcTimeoutMs must be between 1 and ${MAX_FLEET_RPC_TIMEOUT_MS}`);
 	const streamLongPollMs = config?.streamLongPollMs ?? Math.min(2e4, Math.max(1, rpcTimeoutMs - 1e3));
@@ -61,10 +57,15 @@ const RETRYABLE_STATUSES$1 = /* @__PURE__ */ new Set([
 	503,
 	504
 ]);
-const DEFAULT_TIMEOUT_MS$1 = 3e4;
+const DEFAULT_TIMEOUT_MS = 3e4;
 function delayMs$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function resolveFleetTimeoutMs(transport) {
+	const timeoutMs = transport.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3e5) throw new Error(`world-celld: fleet RPC timeout must be between 1 and ${MAX_FLEET_RPC_TIMEOUT_MS}`);
+	return timeoutMs;
+}
 /**
 * Invoke one DO method through the worker router.
 *
@@ -81,8 +82,7 @@ async function callFleetRoute(transport, path, args, opts) {
 	const doFetch = transport.fetchImpl ?? fetch;
 	const url = `${transport.fleetUrl.replace(/\/$/, "")}${path}`;
 	const attempts = opts?.idempotent ? 3 : 1;
-	const timeoutMs = transport.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
-	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3e5) throw new Error(`world-celld: fleet RPC timeout must be between 1 and ${MAX_FLEET_RPC_TIMEOUT_MS}`);
+	const timeoutMs = resolveFleetTimeoutMs(transport);
 	let lastError;
 	for (let attempt = 1; attempt <= attempts; attempt++) {
 		if (attempt > 1) await delayMs$1(100 * attempt + Math.random() * 200);
@@ -131,15 +131,27 @@ const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
 	504
 ]);
 const READ_ATTEMPTS = 3;
-const DEFAULT_TIMEOUT_MS = 3e4;
 const MAX_WRITE_RESPONSE_BYTES = 64;
 const MAX_READ_RESPONSE_BYTES = MAX_STREAM_READ_BYTES + 65536;
 const MAX_ERROR_RESPONSE_BYTES = 65536;
-function delayMs(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+function delayMs(ms, signal) {
+	if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+	if (signal.aborted) return Promise.reject(aborted(signal));
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			reject(aborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
 }
 function requestSignal(timeoutMs, signal) {
-	const timeout = AbortSignal.timeout(Math.max(1, timeoutMs));
+	const timeout = AbortSignal.timeout(timeoutMs);
 	return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
 function aborted(signal) {
@@ -190,6 +202,7 @@ function streamUrl(transport, name) {
 	return `${transport.fleetUrl.replace(/\/$/, "")}/v1/streams/${encodeURIComponent(name)}/chunks`;
 }
 async function writeStreamChunks(transport, name, runId, chunks) {
+	const timeoutMs = resolveFleetTimeoutMs(transport);
 	const body = encodeStreamWriteBatch(chunks);
 	if (body.byteLength > 8389632) throw new Error("world-celld: encoded stream batch exceeds configured limit");
 	const url = new URL(streamUrl(transport, name));
@@ -204,7 +217,7 @@ async function writeStreamChunks(transport, name, runId, chunks) {
 				authorization: `Bearer ${transport.secret}`
 			},
 			body,
-			signal: requestSignal(transport.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+			signal: requestSignal(timeoutMs)
 		});
 	} catch (error) {
 		throw new FleetTransportError(`world-celld: fleet unreachable at ${url.href}`, error);
@@ -218,6 +231,7 @@ async function writeStreamChunks(transport, name, runId, chunks) {
 	}
 }
 async function readStreamChunks(transport, name, request, signal) {
+	const timeoutMs = resolveFleetTimeoutMs(transport);
 	const url = new URL(streamUrl(transport, name));
 	url.searchParams.set("runId", request.runId);
 	url.searchParams.set("startIndex", String(request.startIndex));
@@ -228,27 +242,38 @@ async function readStreamChunks(transport, name, request, signal) {
 	let lastError;
 	for (let attempt = 1; attempt <= READ_ATTEMPTS; attempt++) {
 		if (signal?.aborted) throw aborted(signal);
-		if (attempt > 1) await delayMs(100 * attempt + Math.random() * 200);
+		if (attempt > 1) await delayMs(100 * attempt + Math.random() * 200, signal);
 		let response;
 		try {
 			response = await doFetch(url, {
 				method: "GET",
 				headers: { authorization: `Bearer ${transport.secret}` },
-				signal: requestSignal(transport.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal)
+				signal: requestSignal(timeoutMs, signal)
 			});
 		} catch (error) {
 			if (signal?.aborted) throw aborted(signal);
 			lastError = new FleetTransportError(`world-celld: fleet unreachable at ${url.href}`, error);
 			continue;
 		}
+		if (signal?.aborted) {
+			await response.body?.cancel(aborted(signal)).catch(() => void 0);
+			throw aborted(signal);
+		}
 		if (response.ok) try {
 			return decodeStreamReadResult(await readBoundedResponse(response, MAX_READ_RESPONSE_BYTES));
 		} catch (error) {
-			lastError = new FleetTransportError(`world-celld: malformed stream response from ${url.href}`, error);
+			if (signal?.aborted) throw aborted(signal);
+			lastError = error instanceof FleetTransportError ? error : new FleetTransportError(`world-celld: malformed stream response from ${url.href}`, error);
 			if (attempt < READ_ATTEMPTS) continue;
 			throw lastError;
 		}
-		const error = await errorFromResponse(response);
+		let error;
+		try {
+			error = await errorFromResponse(response);
+		} catch (cause) {
+			if (signal?.aborted) throw aborted(signal);
+			error = cause instanceof FleetTransportError ? cause : new FleetTransportError(`world-celld: malformed stream error response from ${url.href}`, cause);
+		}
 		if (RETRYABLE_STATUSES.has(response.status) && attempt < READ_ATTEMPTS) {
 			lastError = error;
 			continue;
@@ -279,7 +304,8 @@ const RUNS = {
 		"applyEvent",
 		"scheduleCleanup",
 		"cleanupNow",
-		"rearmCleanup"
+		"rearmCleanup",
+		"resolveHookTokenClaim"
 	])
 };
 const STREAMS = {
@@ -466,6 +492,19 @@ const debug = createDebugLogger("celld-world");
 *   HTTP statuses. QueueDO deliveries and the in-process test pump hit the
 *   exact same handler path.
 */
+const MAX_TIMER_DELAY_MS = 2147483647;
+const MAX_TEST_PUMP_BACKOFF_MS = 6e4;
+function delay(milliseconds) {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function delayFor(milliseconds) {
+	let remaining = milliseconds;
+	while (remaining > MAX_TIMER_DELAY_MS) {
+		await delay(MAX_TIMER_DELAY_MS);
+		remaining -= MAX_TIMER_DELAY_MS;
+	}
+	await delay(remaining);
+}
 /**
 * HTTP status codes that indicate permanent (non-retryable) failures.
 * Deliveries with these statuses are dropped immediately instead of retried.
@@ -504,6 +543,7 @@ function resolveBaseUrl(config) {
 * land on the same cell so dedup stays strictly consistent.
 */
 function shardFor(key, shards) {
+	if (!Number.isSafeInteger(shards) || shards < 1) throw new Error("world-celld queueShards must be a positive safe integer");
 	if (shards <= 1) return 0;
 	let hash = 2166136261;
 	for (let i = 0; i < key.length; i++) {
@@ -525,9 +565,9 @@ function shardFor(key, shards) {
 * matching QueueDO's production semantics.
 */
 function createTestPump(config) {
-	const httpTimeoutMs = config.httpTimeoutMs ?? 3e5;
-	const maxAttempts = config.maxAttempts ?? 5;
-	const baseBackoffMs = config.backoffDelayMs ?? 1e3;
+	const httpTimeoutMs = boundedIntegerOption("world-celld test pump httpTimeoutMs", config.httpTimeoutMs, 3e5, 1, MAX_QUEUE_DELIVERY_TIMEOUT_MS);
+	const maxAttempts = boundedIntegerOption("world-celld test pump maxAttempts", config.maxAttempts, 5, 1);
+	const baseBackoffMs = boundedIntegerOption("world-celld test pump backoffDelayMs", config.backoffDelayMs, 1e3, 0, MAX_TEST_PUMP_BACKOFF_MS);
 	const queues = { flow: [] };
 	const wakers = { flow: [] };
 	/** Inflight messageIds by idempotencyKey (world-local queue.js semantics). */
@@ -576,8 +616,10 @@ function createTestPump(config) {
 				parsed = null;
 			}
 			const timeoutSeconds = parsed?.timeoutSeconds;
-			if (typeof timeoutSeconds === "number") {
-				setTimeout$1(timeoutSeconds * 1e3).then(() => enqueue(pathname, envelope));
+			const now = Date.now();
+			const redeliveryAt = queueDelayDeadline(now, timeoutSeconds, 1, MAX_QUEUE_DERIVED_DEADLINE_HEADROOM_MS);
+			if (redeliveryAt !== null) {
+				delayFor(redeliveryAt - now).then(() => enqueue(pathname, envelope));
 				return;
 			}
 		}
@@ -591,8 +633,13 @@ function createTestPump(config) {
 				...envelope,
 				attempt: envelope.attempt + 1
 			};
-			const backoff = baseBackoffMs * 2 ** (next.attempt - 1);
-			setTimeout$1(backoff).then(() => enqueue(pathname, next));
+			const backoff = Math.min(MAX_TEST_PUMP_BACKOFF_MS, baseBackoffMs * 2 ** Math.min(next.attempt - 1, 30));
+			if (checkedQueueTimestampAdd(Date.now(), backoff, 330001) === null) {
+				release(envelope);
+				console.error(`[world-celld test pump] dropping ${envelope.messageId}: retry deadline exceeds the queue timestamp horizon`);
+				return;
+			}
+			delayFor(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}`);
@@ -617,8 +664,9 @@ function createTestPump(config) {
 			return idempotencyKey ? inflightMessages.get(idempotencyKey) : void 0;
 		},
 		push(pathname, envelope, delaySeconds) {
+			if (queueDelayDeadline(Date.now(), delaySeconds ?? 0, 0, 330001) === null) throw new Error("world-celld queue delaySeconds lacks required delivery headroom");
 			if (envelope.idempotencyKey) inflightMessages.set(envelope.idempotencyKey, MessageId.parse(envelope.messageId));
-			if (delaySeconds && delaySeconds > 0) setTimeout$1(delaySeconds * 1e3).then(() => enqueue(pathname, envelope));
+			if (delaySeconds && delaySeconds > 0) delayFor(delaySeconds * 1e3).then(() => enqueue(pathname, envelope));
 			else enqueue(pathname, envelope);
 		},
 		async start() {
@@ -634,7 +682,8 @@ function createTestPump(config) {
 }
 function createQueue(config) {
 	const { env, deploymentId } = config;
-	const queueShards = config.queueShards ?? 1;
+	if (!env?.WORKFLOW_QUEUE) throw new Error("world-celld queue missing WORKFLOW_QUEUE binding");
+	const queueShards = boundedIntegerOption("world-celld queueShards", config.queueShards, 1, 1);
 	const generateMessageId = monotonicFactory();
 	const testPump = createTestPump(config);
 	const getQueueStub = (shard) => {
@@ -644,7 +693,10 @@ function createQueue(config) {
 	return {
 		async queue(queueName, message, opts) {
 			parseQueueName(queueName);
-			const runId = "runId" in message && typeof message.runId === "string" ? message.runId : void 0;
+			const parsedMessage = QueuePayloadSchema.safeParse(message);
+			if (!parsedMessage.success) throw new WorkflowWorldError("world-celld queue payload is invalid", { status: 422 });
+			if (queueDelayDeadline(Date.now(), opts?.delaySeconds ?? 0, 0, 330001) === null) throw new Error("world-celld queue delaySeconds lacks required delivery headroom");
+			const runId = "runId" in parsedMessage.data && typeof parsedMessage.data.runId === "string" ? parsedMessage.data.runId : void 0;
 			if (isTestMode()) {
 				const existing = testPump.inflight(opts?.idempotencyKey);
 				if (existing) return { messageId: existing };
@@ -653,7 +705,7 @@ function createQueue(config) {
 					messageId,
 					queueName,
 					attempt: 1,
-					message,
+					message: parsedMessage.data,
 					idempotencyKey: opts?.idempotencyKey
 				}, opts?.delaySeconds);
 				return { messageId };
@@ -664,7 +716,7 @@ function createQueue(config) {
 				messageId,
 				queueName,
 				pathname: QUEUE_PATHNAME,
-				body: stringify(message),
+				body: stringify(parsedMessage.data),
 				runId,
 				idempotencyKey: opts?.idempotencyKey,
 				delaySeconds: opts?.delaySeconds,
@@ -681,22 +733,40 @@ function createQueue(config) {
 		},
 		createQueueHandler(queueNamePrefix, handler) {
 			return async (req) => {
+				if (req.method !== "POST") return Response.json({ error: "Expected POST" }, { status: 405 });
+				if (req.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase() !== "application/json") return Response.json({ error: "Expected application/json" }, { status: 415 });
 				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);
+				let attempt;
 				try {
-					const result = await handler(parse(await req.text()), {
+					attempt = strictIntegerSetting("x-vqs-message-attempt", attemptStr, 1, 1);
+				} catch {
+					return Response.json({ error: "Invalid x-vqs-message-attempt header" }, { status: 400 });
+				}
+				try {
+					let body;
+					try {
+						body = parse(await req.text());
+					} catch {
+						return Response.json({ error: "Malformed tagged JSON body" }, { status: 422 });
+					}
+					const parsedBody = QueuePayloadSchema.safeParse(body);
+					if (!parsedBody.success) return Response.json({ error: "Invalid queue payload" }, { status: 422 });
+					const result = await handler(parsedBody.data, {
 						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) }
-					});
+					if (result && typeof result.timeoutSeconds === "number") {
+						if (queueDelayDeadline(Date.now(), result.timeoutSeconds, 1, 330001) === null) throw new Error("Queue handler timeoutSeconds is out of range");
+						return Response.json({ timeoutSeconds: result.timeoutSeconds }, {
+							status: 503,
+							headers: { "Retry-After": String(result.timeoutSeconds) }
+						});
+					}
 					return new Response(null, { status: 204 });
 				} catch (error) {
 					if (isPermanentError(error)) {
@@ -740,6 +810,114 @@ function hookOwner(hook) {
 		hookId: hook.hookId
 	};
 }
+const APPLY_EVENT_ERROR_CODES = /* @__PURE__ */ new Set([
+	"RUN_NOT_FOUND",
+	"STEP_NOT_FOUND",
+	"HOOK_NOT_FOUND",
+	"WAIT_NOT_FOUND",
+	"ENTITY_CONFLICT",
+	"HOOK_CLAIM_CANCELLED",
+	"RUN_EXPIRED",
+	"TOO_EARLY",
+	"RUN_NOT_SUPPORTED"
+]);
+function malformedApplyEventOutcome(reason) {
+	throw new FleetTransportError(`world-celld: malformed applyEvent outcome: ${reason}`);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateOptionalNumber(outcome, key, integer) {
+	const value = outcome[key];
+	if (value !== void 0 && (typeof value !== "number" || !Number.isFinite(value) || integer && !Number.isSafeInteger(value))) malformedApplyEventOutcome(`${key} must be ${integer ? "a safe integer" : "a finite number"}`);
+}
+function validateOptionalRetryAfterMs(outcome) {
+	const value = outcome.retryAfterMs;
+	if (value !== void 0 && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) malformedApplyEventOutcome("retryAfterMs must be a non-negative safe integer");
+}
+function parseSuccessEntity(outcome, key, schema) {
+	const value = outcome[key];
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) malformedApplyEventOutcome(`${key} is invalid`);
+	const result = schema.safeParse(compact(value));
+	if (!result.success) malformedApplyEventOutcome(`${key} is invalid`);
+	return result.data;
+}
+/**
+* Validate the untrusted value decoded from the remote applyEvent RPC.
+* Unknown failure codes are intentionally valid and classified separately so
+* an older client can reconstruct their wire metadata without treating them
+* as success. All fields consumed by the success path are checked before any
+* derivative index operation can run.
+*/
+function parseApplyEventOutcome(value) {
+	if (!isRecord(value)) malformedApplyEventOutcome("response must be an object");
+	if (value.ok === false) {
+		if (typeof value.code !== "string" || value.code.length === 0) malformedApplyEventOutcome("failure code must be a non-empty string");
+		if (typeof value.message !== "string") malformedApplyEventOutcome("failure message must be a string");
+		validateOptionalNumber(value, "status", true);
+		validateOptionalNumber(value, "retryAfter", false);
+		validateOptionalRetryAfterMs(value);
+		validateOptionalNumber(value, "retryAfterSeconds", false);
+		validateOptionalNumber(value, "runSpecVersion", true);
+		validateOptionalNumber(value, "worldSpecVersion", true);
+		const outcome = value;
+		return APPLY_EVENT_ERROR_CODES.has(outcome.code) ? {
+			kind: "known-failure",
+			outcome
+		} : {
+			kind: "unknown-failure",
+			outcome
+		};
+	}
+	if (value.ok !== true) malformedApplyEventOutcome("ok must be true or false");
+	if (!Array.isArray(value.releasedHooks)) malformedApplyEventOutcome("releasedHooks must be an array");
+	for (const releasedHook of value.releasedHooks) if (!isRecord(releasedHook) || typeof releasedHook.hookId !== "string" || releasedHook.hookId.length === 0 || typeof releasedHook.token !== "string" || releasedHook.token.length === 0) malformedApplyEventOutcome("releasedHooks entries must contain hookId and token strings");
+	const event = parseSuccessEntity(value, "event", EventSchema);
+	const run = parseSuccessEntity(value, "run", WorkflowRunSchema);
+	const step = parseSuccessEntity(value, "step", StepSchema);
+	const hook = parseSuccessEntity(value, "hook", HookSchema);
+	const wait = parseSuccessEntity(value, "wait", WaitSchema);
+	const hookToIndex = parseSuccessEntity(value, "hookToIndex", HookSchema);
+	if (value.stepCreated !== void 0 && value.stepCreated !== true) malformedApplyEventOutcome("stepCreated must be true when present");
+	if (value.runCreated !== void 0) {
+		if (!isRecord(value.runCreated) || typeof value.runCreated.workflowName !== "string" || !(value.runCreated.createdAt instanceof Date) || Number.isNaN(value.runCreated.createdAt.getTime())) malformedApplyEventOutcome("runCreated is invalid");
+	}
+	let events;
+	if (value.events !== void 0) {
+		if (!Array.isArray(value.events)) malformedApplyEventOutcome("events must be an array");
+		events = value.events.map((candidate) => {
+			if (!isRecord(candidate)) malformedApplyEventOutcome("events contains an invalid event");
+			const result = EventSchema.safeParse(compact(candidate));
+			if (!result.success) malformedApplyEventOutcome("events contains an invalid event");
+			return result.data;
+		});
+		if (value.cursor !== null && typeof value.cursor !== "string") malformedApplyEventOutcome("cursor is required when events are present");
+		if (typeof value.hasMore !== "boolean") malformedApplyEventOutcome("hasMore is required when events are present");
+	}
+	if (value.cursor !== void 0 && value.cursor !== null && typeof value.cursor !== "string") malformedApplyEventOutcome("cursor must be a string or null");
+	if (value.hasMore !== void 0 && typeof value.hasMore !== "boolean") malformedApplyEventOutcome("hasMore must be a boolean");
+	if (value.maxEvents !== void 0 && (typeof value.maxEvents !== "number" || !Number.isSafeInteger(value.maxEvents) || value.maxEvents < 0)) malformedApplyEventOutcome("maxEvents must be a non-negative safe integer");
+	if (run !== void 0 && value.indexPublicationExpiresAt === void 0) malformedApplyEventOutcome("indexPublicationExpiresAt is required when run is present");
+	if (value.indexPublicationExpiresAt !== void 0 && (typeof value.indexPublicationExpiresAt !== "number" || !Number.isFinite(value.indexPublicationExpiresAt))) malformedApplyEventOutcome("indexPublicationExpiresAt must be a finite number");
+	return {
+		kind: "success",
+		outcome: {
+			...value,
+			event,
+			run,
+			step,
+			hook,
+			wait,
+			hookToIndex,
+			events,
+			releasedHooks: value.releasedHooks.map((releasedHook) => ({
+				hookId: releasedHook.hookId,
+				token: releasedHook.token
+			}))
+		}
+	};
+}
 /**
 * Filter data based on ResolveData parameter.
 * When resolveData is 'none', strips specified keys to reduce data transfer.
@@ -772,16 +950,44 @@ function filterHookData(hook, resolveData) {
 * outcome objects instead of throwing.
 */
 function throwOutcomeError(outcome, runId, data) {
+	const withCode = (error) => {
+		Object.assign(error, { code: outcome.code });
+		return error;
+	};
 	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 "WAIT_NOT_FOUND": throw new WorkflowWorldError(outcome.message, { status: 404 });
-		case "ENTITY_CONFLICT": throw new EntityConflictError(outcome.message);
-		case "HOOK_CLAIM_CANCELLED": throw new WorkflowWorldError(outcome.message, { status: 503 });
-		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 "RUN_NOT_FOUND": throw withCode(new WorkflowRunNotFoundError(runId));
+		case "STEP_NOT_FOUND": throw new WorkflowWorldError(outcome.message, {
+			status: 404,
+			code: outcome.code
+		});
+		case "HOOK_NOT_FOUND": throw withCode(new HookNotFoundError(data.correlationId ?? runId));
+		case "WAIT_NOT_FOUND": throw new WorkflowWorldError(outcome.message, {
+			status: 404,
+			code: outcome.code
+		});
+		case "ENTITY_CONFLICT": throw withCode(new EntityConflictError(outcome.message));
+		case "HOOK_CLAIM_CANCELLED": throw new WorkflowWorldError(outcome.message, {
+			status: 503,
+			code: outcome.code
+		});
+		case "RUN_EXPIRED": throw withCode(new RunExpiredError(outcome.message));
+		case "TOO_EARLY": throw withCode(new TooEarlyError(outcome.message, { retryAfter: outcome.retryAfterSeconds }));
+		case "RUN_NOT_SUPPORTED": throw withCode(new RunNotSupportedError(outcome.runSpecVersion ?? 0, SPEC_VERSION_CURRENT));
+		default: {
+			const error = new WorkflowWorldError(outcome.message, {
+				status: outcome.status,
+				code: outcome.code,
+				retryAfter: outcome.retryAfter
+			});
+			for (const key of [
+				"retryAfterMs",
+				"retryAfterSeconds",
+				"runSpecVersion",
+				"worldSpecVersion",
+				"details"
+			]) if (Object.hasOwn(outcome, key)) Object.assign(error, { [key]: outcome[key] });
+			throw error;
+		}
 	}
 }
 const parseRun = (run) => WorkflowRunSchema.parse(compact(run));
@@ -883,6 +1089,8 @@ function createStorage(config) {
 		},
 		events: {
 			async create(runId, data, params) {
+				data = CreateEventSchema.parse(compact(data));
+				if (runId !== null && typeof runId !== "string") throw new WorkflowWorldError("runId must be a string or null", { status: 400 });
 				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 });
@@ -905,16 +1113,16 @@ function createStorage(config) {
 						};
 					} else tokenHolder = admission.holder;
 				}
-				let outcome;
+				let parsedOutcome;
 				try {
-					outcome = await stub.applyEvent({
+					parsedOutcome = parseApplyEventOutcome(await stub.applyEvent({
 						runId: effectiveRunId,
 						data,
 						params,
 						tokenHolder,
 						hookClaimId: hookAdmission?.reservation.claimId,
 						cleanup
-					});
+					}));
 				} catch (error) {
 					if (hookAdmission) {
 						let resolution;
@@ -931,10 +1139,11 @@ function createStorage(config) {
 					}
 					throw error;
 				}
-				if (!outcome.ok) {
+				if (parsedOutcome.kind !== "success") {
 					if (hookAdmission) await env.WORKFLOW_INDEX.releaseHookReservation(hookAdmission.token, hookAdmission.owner, hookAdmission.reservation);
-					throwOutcomeError(outcome, effectiveRunId, data);
+					throwOutcomeError(parsedOutcome.outcome, effectiveRunId, data);
 				}
+				const outcome = parsedOutcome.outcome;
 				if (outcome.run) {
 					const meta = JSON.stringify({
 						runId: effectiveRunId,
@@ -1262,6 +1471,12 @@ function createStreamer(config) {
 * DevKit. Modeled on vinnymac/worlds packages/world-cloudflare/src/index.ts
 * (Apache-2.0, see NOTICE).
 */
+const REQUIRED_ENV_BINDINGS = [
+	"WORKFLOW_DB",
+	"WORKFLOW_INDEX",
+	"WORKFLOW_QUEUE",
+	"WORKFLOW_STREAMS"
+];
 function createCelldWorld(config) {
 	const resolved = resolveConfig(config);
 	let env = resolved.env;
@@ -1280,6 +1495,7 @@ function createCelldWorld(config) {
 		}
 	}
 	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");
+	for (const binding of REQUIRED_ENV_BINDINGS) if (!env[binding]) throw new Error(`world-celld: config.env is missing required binding ${binding}`);
 	const storage = createStorage({
 		env: {
 			WORKFLOW_DB: env.WORKFLOW_DB,