@ewhauser/world-celld 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { S as normalizeStreamError, a as stringify, b as encodeStreamWriteBatch, c as MAX_STREAM_BATCH_BYTES, d as MAX_STREAM_LONG_POLL_MS, f as MAX_STREAM_READ_BYTES, g as decodeStreamReadResult, h as STREAM_BATCH_CONTENT_TYPE, i as parse, l as MAX_STREAM_CHUNK_BYTES, m as MAX_STREAM_WRITE_CHUNKS, n as rpcParse, o as createWorkflowIndex, p as MAX_STREAM_READ_CHUNKS, r as rpcStringify, t as compact, u as MAX_STREAM_ERROR_BYTES, v as decodeStreamWriteResult } from "./util-DmO0XkFw.js";
+import { EventSchema, HookSchema, MessageId, SPEC_VERSION_CURRENT, StepSchema, 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";
@@ -8,6 +8,13 @@ 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");
+	const rpcTimeoutMs = config?.rpcTimeoutMs ?? 3e4;
+	if (!Number.isSafeInteger(rpcTimeoutMs) || rpcTimeoutMs < 1) throw new Error("world-celld: rpcTimeoutMs must be a positive safe integer");
+	const streamLongPollMs = config?.streamLongPollMs ?? Math.min(2e4, Math.max(1, rpcTimeoutMs - 1e3));
+	if (!Number.isSafeInteger(streamLongPollMs) || streamLongPollMs < 1 || streamLongPollMs > 2e4) throw new Error(`world-celld: streamLongPollMs must be between 1 and ${MAX_STREAM_LONG_POLL_MS}`);
+	if (streamLongPollMs >= rpcTimeoutMs) throw new Error("world-celld: streamLongPollMs must be less than rpcTimeoutMs");
+	const streamFlushIntervalMs = config?.streamFlushIntervalMs ?? 0;
+	if (!Number.isSafeInteger(streamFlushIntervalMs) || streamFlushIntervalMs < 0) throw new Error("world-celld: streamFlushIntervalMs must be a non-negative safe integer");
 	return {
 		fleetUrl: config?.fleetUrl ?? process.env.CELLD_FLEET_URL,
 		secret: config?.secret ?? process.env.CELLD_WORLD_SECRET,
@@ -16,8 +23,9 @@ function resolveConfig(config) {
 		baseUrl: config?.baseUrl,
 		queueShards: config?.queueShards ?? 1,
 		runRetentionMs,
-		readPollMs: config?.readPollMs ?? 250,
-		rpcTimeoutMs: config?.rpcTimeoutMs ?? 3e4
+		streamLongPollMs,
+		streamFlushIntervalMs,
+		rpcTimeoutMs
 	};
 }
 //#endregion
@@ -46,13 +54,13 @@ var FleetTransportError = class extends Error {
 //#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([
+const RETRYABLE_STATUSES$1 = /* @__PURE__ */ new Set([
 	502,
 	503,
 	504
 ]);
-const DEFAULT_TIMEOUT_MS = 3e4;
-function delayMs(ms) {
+const DEFAULT_TIMEOUT_MS$1 = 3e4;
+function delayMs$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
@@ -64,12 +72,16 @@ function delayMs(ms) {
 * via queue redelivery. Read-only calls retry on transport failures.
 */
 async function callDO(transport, binding, name, method, args, opts) {
+	return await callFleetRoute(transport, `/v1/rpc/${binding}/${encodeURIComponent(name)}/${method}`, args, opts);
+}
+/** Invoke a fixed authenticated worker route using the generic RPC codec. */
+async function callFleetRoute(transport, path, args, opts) {
 	const doFetch = transport.fetchImpl ?? fetch;
-	const url = `${transport.fleetUrl.replace(/\/$/, "")}/v1/rpc/${binding}/${encodeURIComponent(name)}/${method}`;
+	const url = `${transport.fleetUrl.replace(/\/$/, "")}${path}`;
 	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);
+		if (attempt > 1) await delayMs$1(100 * attempt + Math.random() * 200);
 		let response;
 		try {
 			response = await doFetch(url, {
@@ -79,7 +91,7 @@ async function callDO(transport, binding, name, method, args, opts) {
 					authorization: `Bearer ${transport.secret}`
 				},
 				body: rpcStringify(args),
-				signal: AbortSignal.timeout(Math.max(1, transport.timeoutMs ?? DEFAULT_TIMEOUT_MS))
+				signal: AbortSignal.timeout(Math.max(1, transport.timeoutMs ?? DEFAULT_TIMEOUT_MS$1))
 			});
 		} catch (error) {
 			lastError = new FleetTransportError(`world-celld: fleet unreachable at ${url}`, error);
@@ -99,7 +111,7 @@ async function callDO(transport, binding, name, method, args, opts) {
 		} catch {
 			wire = { message: text || `HTTP ${response.status}` };
 		}
-		if (RETRYABLE_STATUSES.has(response.status) && attempt < attempts) {
+		if (RETRYABLE_STATUSES$1.has(response.status) && attempt < attempts) {
 			lastError = reconstructError(wire, response.status);
 			continue;
 		}
@@ -108,6 +120,140 @@ async function callDO(transport, binding, name, method, args, opts) {
 	throw lastError instanceof Error ? lastError : new FleetTransportError("world-celld: rpc failed", lastError);
 }
 //#endregion
+//#region src/remote/stream-client.ts
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	502,
+	503,
+	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 requestSignal(timeoutMs, signal) {
+	const timeout = AbortSignal.timeout(Math.max(1, timeoutMs));
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function aborted(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+async function readBoundedResponse(response, maxBytes) {
+	if (Number(response.headers.get("content-length") ?? "0") > maxBytes) {
+		await response.body?.cancel("stream response exceeds configured limit").catch(() => void 0);
+		throw new FleetTransportError(`world-celld: stream response exceeds ${maxBytes} bytes`);
+	}
+	if (!response.body) return /* @__PURE__ */ new Uint8Array();
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel("stream response exceeds configured limit").catch(() => void 0);
+				throw new FleetTransportError(`world-celld: stream response exceeds ${maxBytes} bytes`);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return body;
+}
+async function errorFromResponse(response) {
+	const text = new TextDecoder().decode(await readBoundedResponse(response, MAX_ERROR_RESPONSE_BYTES));
+	let wire;
+	try {
+		wire = JSON.parse(text).error;
+	} catch {
+		wire = { message: text || `HTTP ${response.status}` };
+	}
+	return reconstructError(wire, response.status);
+}
+function streamUrl(transport, name) {
+	return `${transport.fleetUrl.replace(/\/$/, "")}/v1/streams/${encodeURIComponent(name)}/chunks`;
+}
+async function writeStreamChunks(transport, name, runId, chunks) {
+	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));
+	url.searchParams.set("runId", runId);
+	const doFetch = transport.fetchImpl ?? fetch;
+	let response;
+	try {
+		response = await doFetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": STREAM_BATCH_CONTENT_TYPE,
+				authorization: `Bearer ${transport.secret}`
+			},
+			body,
+			signal: requestSignal(transport.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new FleetTransportError(`world-celld: fleet unreachable at ${url.href}`, error);
+	}
+	if (!response.ok) throw await errorFromResponse(response);
+	try {
+		return decodeStreamWriteResult(await readBoundedResponse(response, MAX_WRITE_RESPONSE_BYTES));
+	} catch (error) {
+		if (error instanceof FleetTransportError) throw error;
+		throw new FleetTransportError(`world-celld: malformed stream response from ${url.href}`, error);
+	}
+}
+async function readStreamChunks(transport, name, request, signal) {
+	const url = new URL(streamUrl(transport, name));
+	url.searchParams.set("runId", request.runId);
+	url.searchParams.set("startIndex", String(request.startIndex));
+	url.searchParams.set("maxChunks", String(request.maxChunks));
+	url.searchParams.set("maxBytes", String(request.maxBytes));
+	url.searchParams.set("waitMs", String(request.waitMs));
+	const doFetch = transport.fetchImpl ?? fetch;
+	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);
+		let response;
+		try {
+			response = await doFetch(url, {
+				method: "GET",
+				headers: { authorization: `Bearer ${transport.secret}` },
+				signal: requestSignal(transport.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal)
+			});
+		} catch (error) {
+			if (signal?.aborted) throw aborted(signal);
+			lastError = new FleetTransportError(`world-celld: fleet unreachable at ${url.href}`, error);
+			continue;
+		}
+		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 (attempt < READ_ATTEMPTS) continue;
+			throw lastError;
+		}
+		const error = await errorFromResponse(response);
+		if (RETRYABLE_STATUSES.has(response.status) && attempt < READ_ATTEMPTS) {
+			lastError = error;
+			continue;
+		}
+		throw error;
+	}
+	throw lastError instanceof Error ? lastError : new FleetTransportError("world-celld: stream read failed", lastError);
+}
+//#endregion
 //#region src/remote/namespaces.ts
 const RUNS = {
 	methods: [
@@ -121,7 +267,8 @@ const RUNS = {
 		"getCleanupStatus",
 		"scheduleCleanup",
 		"cleanupNow",
-		"rearmCleanup"
+		"rearmCleanup",
+		"resolveHookTokenClaim"
 	],
 	mutating: /* @__PURE__ */ new Set([
 		"applyEvent",
@@ -132,10 +279,8 @@ const RUNS = {
 };
 const STREAMS = {
 	methods: [
-		"writeChunk",
 		"closeStream",
-		"getChunks",
-		"getInfo",
+		"failStream",
 		"registerStream",
 		"listStreams",
 		"expireRegistry",
@@ -143,14 +288,28 @@ const STREAMS = {
 		"expireStream"
 	],
 	mutating: /* @__PURE__ */ new Set([
-		"writeChunk",
 		"closeStream",
+		"failStream",
 		"registerStream",
 		"expireRegistry",
 		"finalizeRegistry",
 		"expireStream"
 	])
 };
+function makeStreamNamespace(transport) {
+	return {
+		idFromName(name) {
+			return { toString: () => name };
+		},
+		get(id) {
+			const name = id.toString();
+			const control = makeStub(transport, "streams", name, STREAMS);
+			control.writeChunks = (runId, chunks) => writeStreamChunks(transport, name, runId, chunks);
+			control.readChunks = (request, signal) => readStreamChunks(transport, name, request, signal);
+			return control;
+		}
+	};
+}
 const QUEUE = {
 	methods: [
 		"enqueue",
@@ -184,41 +343,76 @@ function makeNamespace(transport, binding, 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),
-		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", [
-			token,
-			hookId,
-			serializedHook,
-			owner
-		], false),
-		releaseHookToken: (token, owner) => call("releaseHookToken", [token, owner], false),
-		deleteHookIndexes: (token, hookId, owner) => call("deleteHookIndexes", [
-			token,
-			hookId,
-			owner
-		], false)
-	};
-}
+const RUN_CATALOG = {
+	methods: [
+		"upsertRun",
+		"list",
+		"expireRun"
+	],
+	mutating: /* @__PURE__ */ new Set()
+};
+const RUN_FENCES = {
+	methods: [
+		"getStatus",
+		"fenceTerminal",
+		"fenceExpired"
+	],
+	mutating: /* @__PURE__ */ new Set()
+};
+const HOOK_TOKENS = {
+	methods: [
+		"get",
+		"reserve",
+		"finalize",
+		"releaseClaim",
+		"releaseBatch"
+	],
+	mutating: /* @__PURE__ */ new Set()
+};
+const HOOK_IDS = {
+	methods: [
+		"get",
+		"reserve",
+		"publish",
+		"releaseClaim",
+		"releaseBatch"
+	],
+	mutating: /* @__PURE__ */ new Set()
+};
 function createRemoteEnv(transport) {
+	const runCatalog = makeNamespace(transport, "run-catalog", RUN_CATALOG);
+	const runFences = makeNamespace(transport, "run-fences", RUN_FENCES);
+	const hookTokens = makeNamespace(transport, "hook-tokens", HOOK_TOKENS);
+	const hookIds = makeNamespace(transport, "hook-ids", HOOK_IDS);
+	const workflowIndex = createWorkflowIndex({
+		runCatalog,
+		runFences,
+		hookTokens,
+		hookIds
+	});
 	return {
 		WORKFLOW_DB: makeNamespace(transport, "runs", RUNS),
-		WORKFLOW_STREAMS: makeNamespace(transport, "streams", STREAMS),
-		WORKFLOW_INDEX: makeIndexNamespace(transport),
+		WORKFLOW_STREAMS: makeStreamNamespace(transport),
+		WORKFLOW_INDEX: {
+			...workflowIndex,
+			commitRun: (run, serializedMetadata) => callFleetRoute(transport, "/v1/index/runs/commit", [run, serializedMetadata], { idempotent: true }),
+			listRuns: (options) => callFleetRoute(transport, "/v1/index/runs/list", [options], { idempotent: true }),
+			expireRun: (request) => callFleetRoute(transport, "/v1/index/runs/expire", [request], { idempotent: true }),
+			reserveHook: (token, owner) => callFleetRoute(transport, "/v1/index/hooks/reserve", [token, owner], { idempotent: true }),
+			finalizeHookIndexes: (token, hookId, serializedHook, owner, reservation) => callFleetRoute(transport, "/v1/index/hooks/finalize", [
+				token,
+				hookId,
+				serializedHook,
+				owner,
+				reservation
+			], { idempotent: true }),
+			releaseHookReservation: (token, owner, reservation) => callFleetRoute(transport, "/v1/index/hooks/release-reservation", [
+				token,
+				owner,
+				reservation
+			], { idempotent: true }),
+			releaseHookIndexes: (request) => callFleetRoute(transport, "/v1/index/hooks/release", [request], { idempotent: true })
+		},
 		WORKFLOW_QUEUE: makeNamespace(transport, "queue", QUEUE)
 	};
 }
@@ -294,10 +488,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";
@@ -321,9 +512,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
@@ -337,14 +527,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;
@@ -376,6 +560,9 @@ function createTestPump(config) {
 			signal: AbortSignal.timeout(httpTimeoutMs)
 		});
 		if (response.ok) {
+			try {
+				await response.body?.cancel();
+			} catch {}
 			release(envelope);
 			return;
 		}
@@ -437,7 +624,6 @@ function createTestPump(config) {
 			if (running) return;
 			running = true;
 			loop("flow");
-			loop("step");
 		},
 		stop() {
 			running = false;
@@ -456,13 +642,13 @@ function createQueue(config) {
 	};
 	return {
 		async queue(queueName, message, opts) {
-			const { kind } = parseQueueName(queueName);
-			const runId = "runId" in message ? message.runId : "workflowRunId" in message ? message.workflowRunId : void 0;
+			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,
@@ -476,7 +662,7 @@ 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,
@@ -510,7 +696,7 @@ function createQueue(config) {
 						status: 503,
 						headers: { "Retry-After": String(result.timeoutSeconds) }
 					});
-					return Response.json({ ok: true });
+					return new Response(null, { status: 204 });
 				} catch (error) {
 					if (isPermanentError(error)) {
 						debug("[world-celld queue handler] permanent error:", {
@@ -589,11 +775,12 @@ 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 "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 "LEGACY_RUN_NOT_SUPPORTED": throw new WorkflowWorldError(outcome.message, { status: 422 });
 	}
 }
 const parseRun = (run) => WorkflowRunSchema.parse(compact(run));
@@ -604,6 +791,19 @@ function unwrapRead(outcome) {
 	if (!outcome.ok) throw new RunExpiredError(outcome.message);
 	return outcome.value;
 }
+/** Bound cross-run fanout so large list pages cannot create an RPC burst. */
+const RUN_LIST_CONCURRENCY = 8;
+/**
+* Run statuses only move pending -> running -> terminal, and terminal statuses
+* are immutable. An older index value may therefore safely exclude a filter
+* only when it is already terminal, or when the caller asks for pending and
+* the index has advanced beyond pending. Earlier non-terminal metadata cannot
+* exclude a later status because a post-commit index write may need replay.
+*/
+function indexStatusExcludes(indexed, requested) {
+	if (requested === void 0 || indexed === requested) return false;
+	return isTerminalWorkflowRunStatus(indexed) || requested === "pending";
+}
 function createStorage(config) {
 	const { env } = config;
 	const cleanup = {
@@ -631,7 +831,7 @@ function createStorage(config) {
 				let scanCursor = params?.pagination?.cursor;
 				let exhausted = false;
 				while (matches.length <= limit && !exhausted) {
-					const kvList = await env.WORKFLOW_INDEX.list({
+					const kvList = await env.WORKFLOW_INDEX.listRuns({
 						prefix,
 						limit: Math.min(1e3, Math.max(50, limit)),
 						cursor: scanCursor,
@@ -641,22 +841,32 @@ function createStorage(config) {
 						exhausted = true;
 						break;
 					}
+					const candidates = [];
 					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,
+						const metadata = JSON.parse(key.value);
+						if (indexStatusExcludes(metadata.status, params?.status)) continue;
+						candidates.push({
+							key: key.name,
+							metadata
+						});
+					}
+					for (let offset = 0; offset < candidates.length && matches.length <= limit;) {
+						const needed = limit + 1 - matches.length;
+						const batch = candidates.slice(offset, offset + Math.min(RUN_LIST_CONCURRENCY, needed));
+						const resolved = await Promise.all(batch.map(async ({ key, metadata }) => {
+							try {
+								const run = await runsGet(metadata.runId, { resolveData: params?.resolveData });
+								return !params?.status || run.status === params.status ? {
+									key,
 									run
-								});
-								if (matches.length > limit) break;
+								} : null;
+							} catch (error) {
+								if (!WorkflowRunNotFoundError.is(error) && !RunExpiredError.is(error)) throw error;
+								return null;
 							}
-						} catch (error) {
-							if (!WorkflowRunNotFoundError.is(error) && !RunExpiredError.is(error)) throw error;
-						}
+						}));
+						for (const match of resolved) if (match) matches.push(match);
+						offset += batch.length;
 					}
 					exhausted = kvList.list_complete;
 					scanCursor = kvList.cursor ?? kvList.keys.at(-1)?.name;
@@ -671,36 +881,57 @@ 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 });
 				else effectiveRunId = runId;
 				const stub = getRunDO(effectiveRunId);
 				let tokenHolder;
-				let hookReservation;
+				let hookAdmission;
 				if (data.eventType === "hook_created") {
-					hookReservation = {
+					const owner = {
 						runId: effectiveRunId,
 						hookId: data.correlationId
 					};
-					const reservation = await env.WORKFLOW_INDEX.reserveHookToken(data.eventData.token, hookReservation);
-					tokenHolder = reservation.claimed ? null : reservation.holder;
+					const admission = await env.WORKFLOW_INDEX.reserveHook(data.eventData.token, owner);
+					if (admission.admitted) {
+						tokenHolder = null;
+						hookAdmission = {
+							owner,
+							reservation: admission.reservation,
+							token: data.eventData.token
+						};
+					} else tokenHolder = admission.holder;
 				}
 				let outcome;
 				try {
 					outcome = await stub.applyEvent({
 						runId: effectiveRunId,
 						data,
+						params,
 						tokenHolder,
+						hookClaimId: hookAdmission?.reservation.claimId,
 						cleanup
 					});
 				} catch (error) {
-					if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
+					if (hookAdmission) {
+						let resolution;
+						try {
+							resolution = await stub.resolveHookTokenClaim({
+								hookId: hookAdmission.owner.hookId,
+								token: hookAdmission.token,
+								claimId: hookAdmission.reservation.claimId
+							});
+						} catch {
+							throw error;
+						}
+						if (!resolution.committed) await env.WORKFLOW_INDEX.releaseHookReservation(hookAdmission.token, hookAdmission.owner, hookAdmission.reservation);
+					}
 					throw error;
 				}
 				if (!outcome.ok) {
-					if (hookReservation && data.eventType === "hook_created") await env.WORKFLOW_INDEX.releaseHookToken(data.eventData.token, hookReservation);
+					if (hookAdmission) await env.WORKFLOW_INDEX.releaseHookReservation(hookAdmission.token, hookAdmission.owner, hookAdmission.reservation);
 					throwOutcomeError(outcome, effectiveRunId, data);
 				}
 				if (outcome.run) {
@@ -709,30 +940,32 @@ function createStorage(config) {
 						createdAt: outcome.run.createdAt.toISOString(),
 						status: outcome.run.status
 					});
-					await env.WORKFLOW_INDEX.putOwned(effectiveRunId, workflowRunIndexKey(outcome.run), meta);
-					await env.WORKFLOW_INDEX.putOwned(effectiveRunId, globalRunIndexKey(outcome.run), meta);
+					await env.WORKFLOW_INDEX.commitRun(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, {
+					await env.WORKFLOW_INDEX.finalizeHookIndexes(outcome.hookToIndex.token, outcome.hookToIndex.hookId, serialized, hookOwner(outcome.hookToIndex), hookAdmission?.reservation);
+				} else if (hookAdmission) await env.WORKFLOW_INDEX.releaseHookReservation(hookAdmission.token, hookAdmission.owner, hookAdmission.reservation);
+				const terminal = Boolean(outcome.run && isTerminalWorkflowRunStatus(outcome.run.status));
+				if (outcome.releasedHooks.length > 0) await env.WORKFLOW_INDEX.releaseHookIndexes({
 					runId: effectiveRunId,
-					hookId: released.hookId
+					hooks: outcome.releasedHooks,
+					terminal
 				});
-				if (outcome.event?.correlationId) {
-					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) {
@@ -756,23 +989,30 @@ 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);
-						const outcome = await getRunDO(runId).getEvent(eventId);
-						return outcome.ok ? outcome.value : null;
-					}))).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
 				};
 			}
 		},
@@ -800,12 +1040,12 @@ function createStorage(config) {
 		},
 		hooks: {
 			async get(hookId, params) {
-				const raw = await env.WORKFLOW_INDEX.get(`hookid:${hookId}`);
+				const raw = await env.WORKFLOW_INDEX.getHookById(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}`);
+				const raw = await env.WORKFLOW_INDEX.getHookByToken(token);
 				if (!raw) throw new HookNotFoundError(token);
 				return filterHookData(parseHook(parse(raw)), params?.resolveData ?? "all");
 			},
@@ -829,19 +1069,27 @@ function createStorage(config) {
 }
 //#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_LONG_POLL_MS = MAX_STREAM_LONG_POLL_MS;
 const DEFAULT_CHUNK_PAGE_SIZE = 32;
 const MAX_CHUNK_PAGE_SIZE = 32;
+const REGISTERED_STREAM_CACHE_SIZE = 4096;
 function toBytes(chunk) {
 	return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
 }
+function throwTerminal(result) {
+	if (result.state === "expired") throw new Error("Stream has expired");
+	if (result.state === "errored") {
+		const error = new Error(result.error?.message ?? "Stream failed");
+		error.name = result.error?.name ?? "Error";
+		throw error;
+	}
+}
 function createStreamer(config) {
 	const { env } = config;
-	const readPollMs = config.readPollMs ?? READ_POLL_MS;
+	const streamLongPollMs = config.streamLongPollMs ?? DEFAULT_LONG_POLL_MS;
+	if (!Number.isSafeInteger(streamLongPollMs) || streamLongPollMs < 1 || streamLongPollMs > 2e4) throw new Error(`streamLongPollMs must be between 1 and ${MAX_STREAM_LONG_POLL_MS}`);
+	const streamFlushIntervalMs = config.streamFlushIntervalMs ?? 0;
+	if (!Number.isSafeInteger(streamFlushIntervalMs) || streamFlushIntervalMs < 0) throw new Error("streamFlushIntervalMs must be a non-negative safe integer");
 	const getStreamDO = (streamName) => {
 		const id = env.WORKFLOW_STREAMS.idFromName(`stream:${streamName}`);
 		return env.WORKFLOW_STREAMS.get(id);
@@ -850,83 +1098,161 @@ function createStreamer(config) {
 		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. */
+	/** Bounded per-isolate cache; eviction only repeats idempotent registration. */
 	const registeredStreams = /* @__PURE__ */ new Set();
 	async function registerStreamForRun(name, runId) {
 		const cacheKey = `${runId}\0${name}`;
 		if (registeredStreams.has(cacheKey)) return;
 		await getRunRegistryDO(runId).registerStream(runId, name);
+		if (registeredStreams.size >= REGISTERED_STREAM_CACHE_SIZE) {
+			const oldest = registeredStreams.values().next().value;
+			if (oldest !== void 0) registeredStreams.delete(oldest);
+		}
 		registeredStreams.add(cacheKey);
 	}
-	return {
-		async writeToStream(name, runId, chunk) {
-			const resolvedRunId = await runId;
-			await registerStreamForRun(name, resolvedRunId);
-			await getStreamDO(name).writeChunk(resolvedRunId, toBytes(chunk));
-		},
-		async closeStream(name, runId) {
-			const resolvedRunId = await runId;
-			await registerStreamForRun(name, resolvedRunId);
-			await getStreamDO(name).closeStream(resolvedRunId);
-		},
-		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({
+	const writeChunksToStream = async (name, runId, input) => {
+		if (input.length === 0) return;
+		const resolvedRunId = await runId;
+		const chunks = input.map(toBytes);
+		for (const chunk of chunks) if (chunk.byteLength > 1048576) throw new Error(`Stream chunk exceeds ${MAX_STREAM_CHUNK_BYTES} bytes`);
+		await registerStreamForRun(name, resolvedRunId);
+		let batch = [];
+		let batchBytes = 0;
+		for (const chunk of chunks) {
+			if (batch.length > 0 && (batch.length === 32 || batchBytes + chunk.byteLength > 8388608)) {
+				await getStreamDO(name).writeChunks(resolvedRunId, batch);
+				batch = [];
+				batchBytes = 0;
+			}
+			batch.push(chunk);
+			batchBytes += chunk.byteLength;
+		}
+		if (batch.length > 0) await getStreamDO(name).writeChunks(resolvedRunId, batch);
+	};
+	const writeToStream = (name, runId, chunk) => writeChunksToStream(name, runId, [chunk]);
+	const closeStream = async (name, runId) => {
+		const resolvedRunId = await runId;
+		await registerStreamForRun(name, resolvedRunId);
+		await getStreamDO(name).closeStream(resolvedRunId);
+	};
+	const errorStream = async (name, runId, error) => {
+		const resolvedRunId = await runId;
+		await registerStreamForRun(name, resolvedRunId);
+		await getStreamDO(name).failStream(resolvedRunId, normalizeStreamError(error));
+	};
+	const readFromStream = async (name, runId, startIndex = 0) => {
+		const stub = getStreamDO(name);
+		let nextIndex;
+		if (startIndex < 0) {
+			const info = await stub.readChunks({
+				runId,
+				startIndex: 0,
+				maxChunks: 0,
+				maxBytes: MAX_STREAM_READ_BYTES,
+				waitMs: 0
+			});
+			throwTerminal(info);
+			nextIndex = Math.max(0, info.tailIndex + 1 + startIndex);
+		} else nextIndex = startIndex;
+		let cancelled = false;
+		const abortController = new AbortController();
+		return new ReadableStream({
+			async pull(controller) {
+				for (;;) {
+					if (cancelled) return;
+					let result;
+					try {
+						result = await stub.readChunks({
+							runId,
 							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));
+							maxChunks: 32,
+							maxBytes: MAX_STREAM_READ_BYTES,
+							waitMs: streamLongPollMs
+						}, abortController.signal);
+					} catch (error) {
+						if (cancelled || abortController.signal.aborted) return;
+						throw error;
+					}
+					if (result.chunks.length > 0) {
+						for (const chunk of result.chunks) controller.enqueue(chunk);
+						nextIndex += result.chunks.length;
+						return;
+					}
+					throwTerminal(result);
+					if (result.state === "closed") {
+						controller.close();
+						return;
 					}
-				},
-				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
-			};
+			},
+			cancel() {
+				cancelled = true;
+				abortController.abort(new DOMException("Stream reader cancelled", "AbortError"));
+			}
+		});
+	};
+	const listStreamsByRunId = (runId) => getRunRegistryDO(runId).listStreams();
+	const getStreamChunks = async (name, runId, options) => {
+		const requestedLimit = options?.limit ?? DEFAULT_CHUNK_PAGE_SIZE;
+		if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1) throw new Error("Stream chunk limit must be a positive safe integer");
+		const limit = Math.min(requestedLimit, 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).readChunks({
+			runId,
+			startIndex,
+			maxChunks: limit,
+			maxBytes: MAX_STREAM_READ_BYTES,
+			waitMs: 0
+		});
+		throwTerminal(result);
+		const data = result.chunks.map((chunk, offset) => ({
+			index: startIndex + offset,
+			data: chunk
+		}));
+		const nextIndex = startIndex + data.length;
+		const hasMore = nextIndex <= result.tailIndex;
+		return {
+			data,
+			cursor: hasMore ? String(nextIndex) : null,
+			hasMore,
+			done: result.state === "closed"
+		};
+	};
+	const getStreamInfo = async (name, runId) => {
+		const result = await getStreamDO(name).readChunks({
+			runId,
+			startIndex: 0,
+			maxChunks: 0,
+			maxBytes: MAX_STREAM_READ_BYTES,
+			waitMs: 0
+		});
+		throwTerminal(result);
+		return {
+			tailIndex: result.tailIndex,
+			done: result.state === "closed"
+		};
+	};
+	return {
+		streamFlushIntervalMs,
+		streams: {
+			write: (runId, name, chunk) => writeToStream(name, runId, chunk),
+			writeMulti: (runId, name, chunks) => writeChunksToStream(name, runId, chunks),
+			close: (runId, name) => closeStream(name, runId),
+			fail: (runId, name, error) => errorStream(name, runId, error),
+			get: (runId, name, startIndex) => readFromStream(name, runId, 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,
+		writeChunksToStream,
+		closeStream,
+		errorStream,
+		readFromStream,
+		listStreamsByRunId,
+		getStreamChunks,
+		getStreamInfo
 	};
 }
 //#endregion
@@ -971,7 +1297,8 @@ function createCelldWorld(config) {
 	});
 	const streamer = createStreamer({
 		env: { WORKFLOW_STREAMS: env.WORKFLOW_STREAMS },
-		readPollMs: resolved.readPollMs
+		streamLongPollMs: resolved.streamLongPollMs,
+		streamFlushIntervalMs: resolved.streamFlushIntervalMs
 	});
 	const runStub = (runId) => env.WORKFLOW_DB.get(env.WORKFLOW_DB.idFromName(runId));
 	const retention = {
@@ -998,6 +1325,6 @@ function createCelldWorld(config) {
 	};
 }
 //#endregion
-export { createCelldWorld, createCelldWorld as createWorld };
+export { MAX_STREAM_BATCH_BYTES, MAX_STREAM_CHUNK_BYTES, MAX_STREAM_ERROR_BYTES, MAX_STREAM_LONG_POLL_MS, MAX_STREAM_READ_BYTES, MAX_STREAM_READ_CHUNKS, MAX_STREAM_WRITE_CHUNKS, createCelldWorld, createCelldWorld as createWorld };
 
 //# sourceMappingURL=index.js.map