experimental-a2 0.6.0 → 0.8.0

package/dist/{server-Duw6MVlB.js → server-B2XNevQA.js}

@@ -1,10 +1,687 @@
 import { n as validateSync } from "./validate-XKT4FSNn.js";
 import { n as asStoreUnavailable, t as A2Error } from "./errors-BQuJpe82.js";
-import { g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, o as RESERVED_PARTICIPANT_IDS, t as DRAIN_TIMINGS, v as serverInternals, y as serverSchedulerBindings } from "./internal-DstsI6Re.js";
-import { n as InspectionUnsupportedError, r as serverInspection } from "./inspection-DaxB5jM2.js";
-import { t as defaultSleep } from "./store-polling-dSeLxzfb.js";
-import { r as platformWaitUntil, t as invocationDeadlineMs } from "./platform-B4TnJtWu.js";
+import { c as STREAM_TIMINGS, g as serverInternals, h as nullProtoRecord, i as POLL_TIMINGS, m as markSchedulerSendFailure, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS } from "./internal-DRXJ56EI.js";
+import { t as defaultSleep } from "./store-polling-6DW7F1DT.js";
+import { _ as socketErrorAckFor, a as errorToWire, b as socketUnsubscribedFor, g as socketAckFor, h as presenceSnapshotToWire, i as errorStatus, n as asA2Error, p as presencePatchToWire, s as eventToWire, t as SOCKET_PING_FRAME, v as socketFrameFor, y as socketSubscribedFor } from "./wire-B6te_wns.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+//#region src/platform.ts
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+function requestContext() {
+	try {
+		return Reflect.get(globalThis, SYMBOL_FOR_REQ_CONTEXT)?.get?.() ?? {};
+	} catch {
+		return {};
+	}
+}
+/** The current invocation's Vercel deployment identity, when available. */
+function platformVercelOidcToken() {
+	try {
+		const token = requestContext().headers?.["x-vercel-oidc-token"];
+		return typeof token === "string" && token.length > 0 ? token : null;
+	} catch {
+		return null;
+	}
+}
+function platformWaitUntil(promise) {
+	try {
+		requestContext().waitUntil?.(promise);
+	} catch {}
+}
+/** The invocation's termination time in epoch ms, or null if unknowable. */
+function invocationDeadlineMs() {
+	const deadline = requestContext().deadline;
+	if (deadline === void 0 || deadline === null) return null;
+	const ms = new Date(deadline).getTime();
+	return Number.isNaN(ms) ? null : ms;
+}
+//#endregion
+//#region src/push-envelope.ts
+/**
+* The push envelope's trust boundary for `{ sessionId, events, presence? }`,
+* shared verbatim by the HTTP
+* POST lane and the socket's push/presence frames so INVALID_PAYLOAD
+* shapes are one implementation. Internal module, not public API.
+*/
+const invalidPushBody = (message) => new A2Error("INVALID_PAYLOAD", `malformed push body: ${message}`);
+const invalid = invalidPushBody;
+function parsePresenceSibling(value) {
+	if (value === void 0) return void 0;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalid("presence must be an object when present");
+	const { participant, values, seen, at } = value;
+	if (typeof participant !== "string" || participant.length === 0) throw invalid("presence.participant must be a non-empty string");
+	if (RESERVED_PARTICIPANT_IDS.has(participant)) throw invalid(`presence.participant must not be '${participant}'`);
+	if (values === null || typeof values !== "object" || Array.isArray(values)) throw invalid("presence.values must be an object");
+	if (seen !== void 0 && (typeof seen !== "number" || !Number.isFinite(seen) || seen < 0)) throw invalid("presence.seen must be a non-negative number when present");
+	if (at !== void 0 && (typeof at !== "number" || !Number.isFinite(at) || at < 0 || at > 864e13)) throw invalid("presence.at must be a non-negative epoch-milliseconds timestamp within the Date range when present");
+	const out = {
+		participant,
+		values
+	};
+	if (seen !== void 0) out.seen = seen;
+	if (at !== void 0) out.at = at;
+	return out;
+}
+/** The events half of the envelope, shared by the POST body and socket
+* `push` frames so INVALID_PAYLOAD shapes have one implementation. */
+function parsePushEvents(events) {
+	if (!Array.isArray(events) || events.length === 0) throw invalid("events must be a non-empty array");
+	return events.map((event, i) => {
+		if (event === null || typeof event !== "object") throw invalid(`events[${i}] must be an object`);
+		const { type, payload, id } = event;
+		if (typeof type !== "string" || type.length === 0) throw invalid(`events[${i}].type must be a non-empty string`);
+		if (id !== void 0 && typeof id !== "string") throw invalid(`events[${i}].id must be a string when present`);
+		const out = {
+			type,
+			payload
+		};
+		if (id !== void 0) out.id = id;
+		return out;
+	});
+}
+/**
+* Validate the push envelope — `{ sessionId, events, presence? }` —
+* throwing `INVALID_PAYLOAD` on a malformed body. Payload validation
+* against the machine's schemas happens in `append` and `setPresence`,
+* not here. Either plane may appear alone: a presence-only push has no
+* (or empty) `events`.
+*/
+async function parsePushBody(req) {
+	let body;
+	try {
+		body = await req.json();
+	} catch (cause) {
+		throw new A2Error("INVALID_PAYLOAD", "push body is not valid JSON", { cause });
+	}
+	if (body === null || typeof body !== "object") throw invalid("expected an object");
+	const { sessionId, events, presence } = body;
+	if (typeof sessionId !== "string" || sessionId.length === 0) throw invalid("sessionId must be a non-empty string");
+	const parsedPresence = parsePresenceSibling(presence);
+	if (parsedPresence !== void 0 && (events === void 0 || Array.isArray(events) && events.length === 0)) return {
+		sessionId,
+		events: [],
+		presence: parsedPresence
+	};
+	const parsed = parsePushEvents(events);
+	return parsedPresence !== void 0 ? {
+		sessionId,
+		events: parsed,
+		presence: parsedPresence
+	} : {
+		sessionId,
+		events: parsed
+	};
+}
+//#endregion
+//#region src/session-socket.ts
+/**
+* The A2 socket protocol's server half (specs/a2-api.md §13): the
+* per-socket shell — teardown, backpressure, heartbeat, the malformed
+* budget, the in-flight bound — and `sessionsSocket`, the multiplexed
+* frame handler riding it. Internal module: `handle`'s upgrade lane is
+* the sanctioned mount; only `A2Socket` (the structural socket the
+* platform hands over) is re-exported as public surface.
+*/
+const messageText = (data) => {
+	if (typeof data === "string") return data;
+	if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+	if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data);
+	if (Array.isArray(data) && data.every(ArrayBuffer.isView)) {
+		const decoder = new TextDecoder();
+		let text = "";
+		for (const part of data) text += decoder.decode(part, { stream: true });
+		return text + decoder.decode();
+	}
+	return null;
+};
+/**
+* How many unparseable or invalid frames a socket may send before it
+* is closed (1008): the budget absorbs isolated client bugs without
+* letting a broken peer spin the validation path forever. Push frames
+* with a usable `req` never count — their failures are answered with
+* error acks, exactly like the POST path's 4xx bodies.
+*/
+const MAX_MALFORMED_FRAMES = 5;
+function socketShell(socket, release, onFrame, deadlineAt) {
+	let torn = false;
+	let malformed = 0;
+	let heartbeat;
+	let deadline;
+	const teardown = () => {
+		if (torn) return;
+		torn = true;
+		if (heartbeat !== void 0) clearInterval(heartbeat);
+		if (deadline !== void 0) clearTimeout(deadline);
+		release();
+	};
+	const shutdown = (code, reason) => {
+		if (torn) return;
+		teardown();
+		try {
+			socket.close(code, reason);
+		} catch {}
+	};
+	const send = (data) => {
+		if (torn) return;
+		if (typeof socket.bufferedAmount === "number" && socket.bufferedAmount > SOCKET_TIMINGS.disconnectWaterMarkBytes) {
+			shutdown(1008, "backpressure: peer not reading");
+			return;
+		}
+		try {
+			socket.send(data);
+		} catch {
+			teardown();
+		}
+	};
+	const malformedFrame = (reason) => {
+		malformed += 1;
+		if (malformed >= MAX_MALFORMED_FRAMES) shutdown(1008, `too many malformed frames (last: ${reason})`);
+	};
+	let inFlight = 0;
+	const track = (work) => {
+		inFlight += 1;
+		work.finally(() => {
+			inFlight -= 1;
+		});
+	};
+	const handleMessage = (data) => {
+		if (torn) return;
+		const text = messageText(data);
+		if (text === null) {
+			malformedFrame("non-text frame");
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			malformedFrame("frame is not valid JSON");
+			return;
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			malformedFrame("frame is not an object");
+			return;
+		}
+		onFrame(parsed);
+	};
+	socket.on("message", handleMessage);
+	socket.on("close", teardown);
+	socket.on("error", teardown);
+	heartbeat = setInterval(() => send(SOCKET_PING_FRAME), STREAM_TIMINGS.sseHeartbeatMs);
+	heartbeat.unref?.();
+	if (deadlineAt !== void 0) {
+		deadline = setTimeout(() => shutdown(1e3, "deadline"), Math.max(0, deadlineAt - Date.now()));
+		deadline.unref?.();
+	}
+	return {
+		torn: () => torn,
+		send,
+		shutdown,
+		malformedFrame,
+		buffered: () => typeof socket.bufferedAmount === "number" ? socket.bufferedAmount : 0,
+		overCap: () => inFlight >= SOCKET_TIMINGS.maxInFlightMessages,
+		track
+	};
+}
+const stopSubscription = (subscription) => {
+	subscription.stopped = true;
+	subscription.iterator.return?.()?.catch(() => {});
+};
+const parseSubscribeEntries = (value) => {
+	if (!Array.isArray(value) || value.length === 0) return null;
+	const entries = [];
+	for (const entry of value) {
+		if (entry === null || typeof entry !== "object") return null;
+		const { id, index } = entry;
+		if (typeof id !== "string" || id.length === 0) return null;
+		if (typeof index !== "number" || !Number.isInteger(index) || index < 0) return null;
+		entries.push({
+			id,
+			index
+		});
+	}
+	return entries;
+};
+/**
+* Speak the multiplexed A2 socket protocol (specs/a2-api.md §13)
+* against many sessions on one socket. `subscribe` frames open a
+* per-session pump at that session's own resume frontier; push and
+* presence frames route by `sessionId` through the same validation
+* seams as the POST lane; every down frame carries the `sessionId` it
+* belongs to. One heartbeat, one
+* malformed budget, one in-flight bound, one backpressure gauge — per
+* socket, shared by all sessions. A session's stream ending or failing
+* answers `unsubscribed` for that session; only the peer, the
+* deadline, the malformed budget, or backpressure closes the socket.
+*/
+function sessionsSocket(resolve, socket, options) {
+	const presence = options?.presence === true;
+	const subscriptions = /* @__PURE__ */ new Map();
+	const retire = (id, subscription) => {
+		if (subscriptions.get(id) === subscription) subscriptions.delete(id);
+	};
+	const pump = async (id, subscription) => {
+		for (;;) {
+			for (;;) {
+				if (shell.torn() || subscription.stopped || shell.buffered() <= SOCKET_TIMINGS.highWaterMarkBytes) break;
+				await new Promise((wake) => setTimeout(wake, SOCKET_TIMINGS.resumePollMs));
+			}
+			if (shell.torn() || subscription.stopped) return;
+			const { value, done } = await subscription.iterator.next();
+			if (shell.torn() || subscription.stopped) return;
+			if (done) return;
+			shell.send(socketFrameFor(value, id));
+		}
+	};
+	const runSubscription = async (id, subscription) => {
+		try {
+			await pump(id, subscription);
+			if (shell.torn() || subscription.stopped) return;
+			retire(id, subscription);
+			shell.send(socketUnsubscribedFor(id));
+		} catch {
+			if (shell.torn() || subscription.stopped) return;
+			retire(id, subscription);
+			shell.send(socketUnsubscribedFor(id, "stream failed"));
+		}
+	};
+	const startSubscription = async (id, index) => {
+		let session;
+		try {
+			session = await resolve(id, index);
+		} catch {
+			if (!shell.torn()) shell.send(socketUnsubscribedFor(id, "stream failed"));
+			return;
+		}
+		if (shell.torn()) return;
+		if (session === null) {
+			shell.send(socketUnsubscribedFor(id, "subscribe rejected"));
+			return;
+		}
+		const target = session;
+		const existing = subscriptions.get(id);
+		if (existing) stopSubscription(existing);
+		const subscription = {
+			target,
+			iterator: (presence ? target.stream({
+				startAfter: index,
+				presence: true
+			}) : target.stream({ startAfter: index }))[Symbol.asyncIterator](),
+			stopped: false
+		};
+		subscriptions.set(id, subscription);
+		shell.send(socketSubscribedFor(id));
+		runSubscription(id, subscription);
+	};
+	let controlTail = Promise.resolve();
+	const control = (work) => {
+		controlTail = controlTail.then(work).catch(() => {});
+	};
+	const handlePush = async (frame, req, sessionId) => {
+		const subscription = subscriptions.get(sessionId);
+		if (subscription === void 0) {
+			shell.send(socketErrorAckFor(req, new A2Error("STORE_UNAVAILABLE", "session is not subscribed on this socket"), sessionId));
+			return;
+		}
+		try {
+			const events = parsePushEvents(frame["events"]);
+			const denial = await options?.gatePush?.(sessionId, events, void 0) ?? null;
+			if (denial !== null) {
+				shell.send(socketErrorAckFor(req, denial, sessionId));
+				return;
+			}
+			const appended = await subscription.target.append(...events);
+			shell.send(socketAckFor(req, appended, sessionId));
+		} catch (err) {
+			shell.send(socketErrorAckFor(req, asA2Error(err), sessionId));
+		}
+	};
+	const handlePresence = async (frame, sessionId) => {
+		const subscription = subscriptions.get(sessionId);
+		if (subscription === void 0) return;
+		if (typeof subscription.target.setPresence !== "function") {
+			shell.malformedFrame("presence frame on a presence-less session");
+			return;
+		}
+		let patch;
+		try {
+			patch = parsePresenceSibling(frame);
+		} catch {
+			shell.malformedFrame("invalid presence frame");
+			return;
+		}
+		if (!patch) return;
+		try {
+			if ((await options?.gatePush?.(sessionId, [], patch) ?? null) !== null) return;
+			await subscription.target.setPresence(patch);
+		} catch (error) {
+			const failure = asA2Error(error);
+			if (failure.code === "INVALID_PAYLOAD" || failure.code === "UNKNOWN_PRESENCE_FIELD") {
+				shell.malformedFrame("invalid presence frame");
+				return;
+			}
+			shell.shutdown(1011, "internal error");
+		}
+	};
+	const handleFrame = (frame) => {
+		switch (frame["kind"]) {
+			case "subscribe": {
+				const entries = parseSubscribeEntries(frame["sessions"]);
+				if (entries === null) {
+					shell.malformedFrame("malformed subscribe frame");
+					return;
+				}
+				for (const entry of entries) control(() => startSubscription(entry.id, entry.index));
+				return;
+			}
+			case "unsubscribe": {
+				const ids = frame["sessions"];
+				if (!Array.isArray(ids) || ids.length === 0 || !ids.every((id) => typeof id === "string")) {
+					shell.malformedFrame("malformed unsubscribe frame");
+					return;
+				}
+				for (const id of ids) control(() => {
+					const subscription = subscriptions.get(id);
+					if (subscription === void 0) return;
+					stopSubscription(subscription);
+					subscriptions.delete(id);
+				});
+				return;
+			}
+			case "push": {
+				const req = frame["req"];
+				const sessionId = frame["sessionId"];
+				if (shell.overCap()) {
+					if (typeof req === "number") shell.send(socketErrorAckFor(req, new A2Error("STORE_UNAVAILABLE", "push shed: too many in flight on this socket"), typeof sessionId === "string" ? sessionId : void 0));
+					else shell.malformedFrame("push frame without a numeric req");
+					return;
+				}
+				if (typeof req !== "number") {
+					shell.malformedFrame("push frame without a numeric req");
+					return;
+				}
+				if (typeof sessionId !== "string" || sessionId.length === 0) {
+					shell.send(socketErrorAckFor(req, new A2Error("INVALID_PAYLOAD", "push frame without a sessionId")));
+					return;
+				}
+				shell.track(handlePush(frame, req, sessionId));
+				return;
+			}
+			case "presence": {
+				if (shell.overCap()) return;
+				const sessionId = frame["sessionId"];
+				if (typeof sessionId !== "string" || sessionId.length === 0) {
+					shell.malformedFrame("presence frame without a sessionId");
+					return;
+				}
+				shell.track(handlePresence(frame, sessionId));
+				return;
+			}
+			default: return;
+		}
+	};
+	const shell = socketShell(socket, () => {
+		for (const subscription of subscriptions.values()) stopSubscription(subscription);
+		subscriptions.clear();
+	}, (frame) => handleFrame(frame), options?.deadline);
+}
+//#endregion
+//#region src/sse.ts
+/**
+* The SSE response protocol — framing, heartbeat, deadline, and
+* teardown for the live stream lane. Internal module: `server.fetch` is
+* the sanctioned caller; the framing rules stay
+* documented on `sseResponse` because the client's parser (and the
+* stall watchdog) depend on them.
+*/
+/**
+* Pipe a live event iterable into an SSE `Response`. Each event is one
+* frame — `id:` carries the event-log index, `data:` the JSON event. A
+* `stream({ presence: true })` iterable also yields presence items,
+* which ride as named frames old clients skip: `event:
+* presence-snapshot` first (the map, ISO dates), then `event: presence`
+* per patch — no `id:`, presence never advances the resume frontier. A
+* disconnecting client cancels the stream, which closes the underlying
+* subscription. Two kinds of comment frames ride along: a `: connected`
+* prelude that flushes headers immediately, and a `: ping` heartbeat
+* every 15 seconds so clients (and proxies) can tell a quiet stream
+* from a dead connection — the session client's stall watchdog counts
+* on it. When the platform exposes an invocation deadline, the response
+* closes cleanly one second before it so the client reconnects without
+* a platform-timeout failure.
+*/
+function sseResponse(iterable) {
+	const iterator = iterable[Symbol.asyncIterator]();
+	const encoder = new TextEncoder();
+	let heartbeat;
+	let deadlineTimer;
+	let closed = false;
+	let iteratorReturned = false;
+	const stopTimers = () => {
+		if (heartbeat !== void 0) clearInterval(heartbeat);
+		if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
+		heartbeat = void 0;
+		deadlineTimer = void 0;
+	};
+	const returnIterator = async () => {
+		if (iteratorReturned) return;
+		iteratorReturned = true;
+		await iterator.return?.();
+	};
+	const stream = new ReadableStream({
+		start(controller) {
+			controller.enqueue(encoder.encode(": connected\n\n"));
+			heartbeat = setInterval(() => {
+				try {
+					controller.enqueue(encoder.encode(": ping\n\n"));
+				} catch {
+					stopTimers();
+				}
+			}, STREAM_TIMINGS.sseHeartbeatMs);
+			heartbeat.unref?.();
+			const invocationDeadline = invocationDeadlineMs();
+			if (invocationDeadline !== null) {
+				const delay = Math.max(0, invocationDeadline - Date.now() - STREAM_TIMINGS.sseDeadlineGraceMs);
+				deadlineTimer = setTimeout(() => {
+					if (closed) return;
+					closed = true;
+					stopTimers();
+					returnIterator().catch(() => {});
+					try {
+						controller.close();
+					} catch {}
+				}, delay);
+				deadlineTimer.unref?.();
+			}
+		},
+		async pull(controller) {
+			try {
+				const { value, done } = await iterator.next();
+				if (closed) return;
+				if (done) {
+					closed = true;
+					stopTimers();
+					controller.close();
+					return;
+				}
+				controller.enqueue(encoder.encode(frameFor(value)));
+			} catch (error) {
+				if (closed) return;
+				closed = true;
+				stopTimers();
+				returnIterator().catch(() => {});
+				throw error;
+			}
+		},
+		async cancel() {
+			if (closed) return;
+			closed = true;
+			stopTimers();
+			await returnIterator();
+		}
+	});
+	return new Response(stream, {
+		status: 200,
+		headers: {
+			"content-type": "text/event-stream",
+			"cache-control": "no-cache, no-transform",
+			connection: "keep-alive"
+		}
+	});
+}
+function frameFor(item) {
+	if ("snapshot" in item) return `event: presence-snapshot\ndata: ${JSON.stringify(presenceSnapshotToWire(item))}\n\n`;
+	if ("participant" in item) return `event: presence\ndata: ${JSON.stringify(presencePatchToWire(item))}\n\n`;
+	return `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(item))}\n\n`;
+}
+//#endregion
+//#region src/server-fetch.ts
+const serverFetchHooks = /* @__PURE__ */ new WeakMap();
+function setServerFetchHooks(server, hooks) {
+	serverFetchHooks.set(server.fetch, hooks);
+}
+const parseHistoryBounds = (gte, lte) => {
+	if (gte === null || lte === null) throw new A2Error("INVALID_PAYLOAD", "a history read takes both gte and lte");
+	const bounds = {
+		gte: Number(gte),
+		lte: Number(lte)
+	};
+	for (const [name, value] of Object.entries(bounds)) if (!Number.isSafeInteger(value) || value < 0) throw new A2Error("INVALID_PAYLOAD", `history ${name} must be a non-negative safe integer`);
+	if (bounds.gte > bounds.lte) throw new A2Error("INVALID_PAYLOAD", "history gte must be less than or equal to lte");
+	return bounds;
+};
+const parseResumeIndex = (raw) => {
+	if (raw === null) return 0;
+	const index = Number(raw);
+	if (!Number.isSafeInteger(index) || index < 0) throw new A2Error("INVALID_PAYLOAD", "stream index must be a non-negative safe integer");
+	return index;
+};
+const errorResponse = (error) => {
+	const a2error = asA2Error(error);
+	return Response.json(errorToWire(a2error), { status: errorStatus(a2error.code) });
+};
+const forbidden = () => new A2Error("FORBIDDEN", "the operation is not authorized");
+const freezePush = (sessionId, events, presence, transport) => {
+	for (const event of events) Object.freeze(event);
+	Object.freeze(events);
+	if (presence !== void 0) {
+		Object.freeze(presence.values);
+		Object.freeze(presence);
+	}
+	return {
+		type: "push",
+		sessionId,
+		events,
+		...presence === void 0 ? {} : { presence },
+		transport
+	};
+};
+function createServerFetch(server) {
+	const presence = Object.keys(server.contract.presence).length > 0;
+	const fetch = async (request, options) => {
+		const authorized = async (operation) => {
+			try {
+				return await options?.authorize?.(Object.freeze(operation)) !== false;
+			} catch (cause) {
+				throw new A2Error("STORE_UNAVAILABLE", "authorization failed", { cause });
+			}
+		};
+		const authorize = async (operation) => {
+			if (!await authorized(operation)) throw forbidden();
+		};
+		const validateIngress = async (context) => {
+			await serverFetchHooks.get(fetch)?.validateIngress?.(context);
+		};
+		const attach = (socket) => {
+			const deadline = invocationDeadlineMs();
+			sessionsSocket(async (sessionId, startAfter) => {
+				return await authorized({
+					type: "stream",
+					sessionId,
+					startAfter,
+					transport: "websocket"
+				}) ? server.session(sessionId) : null;
+			}, socket, {
+				presence,
+				...deadline === null ? {} : { deadline },
+				gatePush: async (sessionId, events, pushedPresence) => {
+					try {
+						await authorize(freezePush(sessionId, events, pushedPresence, "websocket"));
+						await validateIngress({
+							sessionId,
+							events,
+							...pushedPresence === void 0 ? {} : { presence: pushedPresence }
+						});
+						return null;
+					} catch (error) {
+						return asA2Error(error);
+					}
+				}
+			});
+		};
+		try {
+			if (request.method === "GET") {
+				if (request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+					if (options?.upgradeWebSocket === void 0) return new Response("WebSocket upgrade requested, but server.fetch() has no upgrade implementation", { status: 426 });
+					return await options.upgradeWebSocket(attach);
+				}
+				const { searchParams } = new URL(request.url);
+				const sessionId = searchParams.get("sessionId");
+				if (sessionId === null || sessionId.length === 0) throw new A2Error("INVALID_PAYLOAD", "missing sessionId");
+				const gteRaw = searchParams.get("gte");
+				const lteRaw = searchParams.get("lte");
+				if (gteRaw !== null || lteRaw !== null) {
+					const bounds = parseHistoryBounds(gteRaw, lteRaw);
+					await authorize({
+						type: "history",
+						sessionId,
+						...bounds,
+						transport: "http"
+					});
+					const events = await server.session(sessionId).history(bounds);
+					const covered = events.length === bounds.lte - bounds.gte + 1;
+					return Response.json(events.map(eventToWire), { headers: { "a2-history-covered": String(covered) } });
+				}
+				const startAfter = parseResumeIndex(searchParams.get("index"));
+				await authorize({
+					type: "stream",
+					sessionId,
+					startAfter,
+					transport: "http"
+				});
+				const target = server.session(sessionId);
+				return sseResponse(presence ? target.stream({
+					startAfter,
+					presence: true
+				}) : target.stream({ startAfter }));
+			}
+			if (request.method === "POST") {
+				const body = await parsePushBody(request);
+				await authorize(freezePush(body.sessionId, body.events, body.presence, "http"));
+				await validateIngress({
+					sessionId: body.sessionId,
+					events: body.events,
+					...body.presence === void 0 ? {} : { presence: body.presence }
+				});
+				const session = server.session(body.sessionId);
+				if (body.presence !== void 0) {
+					const target = session;
+					if (typeof target.setPresence !== "function") throw invalidPushBody("presence is not declared by this contract");
+					await target.setPresence(body.presence);
+				}
+				const appended = body.events.length === 0 ? [] : await session.append(...body.events);
+				return Response.json(appended.map(eventToWire));
+			}
+			return new Response("Method Not Allowed", {
+				status: 405,
+				headers: { allow: "GET, POST" }
+			});
+		} catch (error) {
+			return errorResponse(error);
+		}
+	};
+	return fetch;
+}
+//#endregion
 //#region src/deterministic-id.ts
 /**
 * Deterministic default ids for handler `session.append` calls. A handler
@@ -446,21 +1123,45 @@ function createServer(options) {
 			throw asStoreUnavailable(err);
 		}
 	};
-	const readCachedState = async (store, sessionId, reducerName) => {
+	const readCachedState = async (store, sessionId, reducerName, throughIndex, snapshotThroughIndex) => {
 		try {
-			return await store.readState(nsId(sessionId), reducerName);
+			return await store.readState(nsId(sessionId), reducerName, throughIndex === void 0 && snapshotThroughIndex === void 0 ? void 0 : {
+				...throughIndex === void 0 ? {} : { throughIndex },
+				...snapshotThroughIndex === void 0 ? {} : { snapshotThroughIndex }
+			});
 		} catch {
 			try {
 				return {
+					headIndex: null,
 					snapshot: null,
-					events: await store.read(nsId(sessionId))
+					events: await store.read(nsId(sessionId), throughIndex === void 0 ? void 0 : { throughIndex })
 				};
 			} catch (err) {
 				throw asStoreUnavailable(err);
 			}
 		}
 	};
-	const foldStateRead = async (store, sessionId, reducer, stateRead, span) => {
+	const planStateReads = (batch) => {
+		const bySession = /* @__PURE__ */ new Map();
+		for (const entry of batch) {
+			const entries = bySession.get(entry.sessionId);
+			if (entries) entries.push(entry);
+			else bySession.set(entry.sessionId, [entry]);
+		}
+		const plans = [];
+		for (const [sessionId, entries] of bySession) {
+			const boundaries = entries.flatMap((entry) => entry.throughIndex === void 0 ? [] : [entry.throughIndex]);
+			const plan = {
+				sessionId,
+				entries
+			};
+			if (boundaries.length === entries.length) plan.throughIndex = Math.max(...boundaries);
+			if (boundaries.length > 0) plan.snapshotThroughIndex = Math.min(...boundaries);
+			plans.push(plan);
+		}
+		return plans;
+	};
+	const foldStatePlan = async (store, reducer, plan, stateRead) => {
 		let state = cloneInitial(reducer.initialState);
 		let index = 0;
 		let snapshotOutcome = "miss";
@@ -481,84 +1182,120 @@ function createServer(options) {
 				snapshotOutcome = "hit";
 			}
 		}
-		span.setAttribute("a2.state.snapshot", snapshotOutcome);
 		if (snapshotOutcome === "rejected") try {
-			rows = await store.read(nsId(sessionId));
+			rows = await store.read(nsId(plan.sessionId), plan.throughIndex === void 0 ? void 0 : { throughIndex: plan.throughIndex });
 		} catch (err) {
 			throw asStoreUnavailable(err);
 		}
-		for (const row of rows) {
-			state = reducer.fold(state, toPublic(row));
-			index = row.index;
+		const ordered = plan.entries.toSorted((a, b) => (a.throughIndex ?? Number.POSITIVE_INFINITY) - (b.throughIndex ?? Number.POSITIVE_INFINITY));
+		const writes = /* @__PURE__ */ new Map();
+		let rowPosition = 0;
+		for (const entry of ordered) {
+			const target = entry.throughIndex ?? Number.POSITIVE_INFINITY;
+			while (rowPosition < rows.length && rows[rowPosition].index <= target) {
+				const row = rows[rowPosition];
+				state = reducer.fold(state, toPublic(row));
+				index = row.index;
+				rowPosition += 1;
+			}
+			const resultState = cloneInitial(state);
+			const folded = rowPosition;
+			entry.span.setAttribute("a2.state.snapshot", snapshotOutcome);
+			entry.span.setAttribute("a2.state.folded", folded);
+			entry.span.setAttribute("a2.state.index", index);
+			if (index > 0 && (folded > 0 || entry.pinEventIndex !== void 0)) {
+				const advancesHead = stateRead.headIndex === null || index > stateRead.headIndex;
+				const repairsHead = snapshotOutcome === "rejected" && index === stateRead.headIndex;
+				if (!advancesHead && !repairsHead && entry.pinEventIndex === void 0) {
+					entry.resolve({
+						state: resultState,
+						index
+					});
+					continue;
+				}
+				let write = writes.get(index);
+				if (!write) {
+					write = {
+						state: cloneInitial(resultState),
+						pinEventIndexes: /* @__PURE__ */ new Set()
+					};
+					writes.set(index, write);
+				}
+				if (entry.pinEventIndex !== void 0) write.pinEventIndexes.add(entry.pinEventIndex);
+			}
+			entry.resolve({
+				state: resultState,
+				index
+			});
+		}
+		if (writes.size > 0) {
+			const snapshots = [];
+			for (const [snapshotIndex, write] of writes) {
+				const snapshot = {
+					index: snapshotIndex,
+					state: write.state
+				};
+				if (write.pinEventIndexes.size > 0) snapshot.pinEventIndexes = [...write.pinEventIndexes];
+				snapshots.push(snapshot);
+			}
+			const persistence = Promise.resolve().then(() => store.putSnapshots(nsId(plan.sessionId), reducer.name, snapshots)).catch(() => {});
+			track(persistence);
+			platformWaitUntil(persistence);
 		}
-		span.setAttribute("a2.state.folded", rows.length);
-		span.setAttribute("a2.state.index", index);
-		return {
-			state,
-			index,
-			folded: rows.length
-		};
 	};
 	const pendingStateReads = /* @__PURE__ */ new Map();
-	const flushStateReads = async (store, reducerName, batch) => {
+	const flushStateReads = async (store, reducer, batch) => {
+		const plans = planStateReads(batch);
 		let reads;
 		try {
-			reads = store.readStates ? await store.readStates(batch.map((entry) => nsId(entry.sessionId)), reducerName) : null;
+			reads = store.readStates ? await store.readStates(plans.map((plan) => ({
+				sessionId: nsId(plan.sessionId),
+				...plan.throughIndex === void 0 ? {} : { throughIndex: plan.throughIndex },
+				...plan.snapshotThroughIndex === void 0 ? {} : { snapshotThroughIndex: plan.snapshotThroughIndex }
+			})), reducer.name) : await Promise.all(plans.map((plan) => readCachedState(store, plan.sessionId, reducer.name, plan.throughIndex, plan.snapshotThroughIndex)));
 		} catch {
 			reads = null;
 		}
-		if (!reads || reads.length !== batch.length) {
-			for (const entry of batch) entry.resolve(readCachedState(store, entry.sessionId, reducerName));
+		if (!reads || reads.length !== plans.length) try {
+			reads = await Promise.all(plans.map((plan) => readCachedState(store, plan.sessionId, reducer.name, plan.throughIndex, plan.snapshotThroughIndex)));
+		} catch (err) {
+			for (const entry of batch) entry.reject(err);
 			return;
 		}
-		const seen = /* @__PURE__ */ new Set();
-		for (const [position, entry] of batch.entries()) {
-			const shared = seen.has(entry.sessionId);
-			seen.add(entry.sessionId);
-			try {
-				const read = reads[position];
-				entry.resolve(shared ? structuredClone(read) : read);
-			} catch {
-				entry.resolve(readCachedState(store, entry.sessionId, reducerName));
-			}
+		for (const [position, plan] of plans.entries()) try {
+			await foldStatePlan(store, reducer, plan, reads[position]);
+		} catch (err) {
+			for (const entry of plan.entries) entry.reject(err);
 		}
 	};
-	const enqueueStateRead = (store, sessionId, reducerName) => new Promise((resolve) => {
+	const enqueueStateRead = (store, sessionId, reducer, throughIndex, pinEventIndex, span) => new Promise((resolve, reject) => {
+		const reducerName = reducer.name;
 		let batch = pendingStateReads.get(reducerName);
 		if (!batch) {
 			const opened = [];
 			pendingStateReads.set(reducerName, opened);
 			queueMicrotask(() => {
 				pendingStateReads.delete(reducerName);
-				flushStateReads(store, reducerName, opened);
+				flushStateReads(store, reducer, opened);
 			});
 			batch = opened;
 		}
 		batch.push({
 			sessionId,
-			resolve
+			...throughIndex === void 0 ? {} : { throughIndex },
+			...pinEventIndex === void 0 ? {} : { pinEventIndex },
+			span,
+			resolve,
+			reject
 		});
 	});
-	const readState = async (sessionId, reducer) => {
+	const readState = async (sessionId, reducer, throughIndex, pinEventIndex) => {
 		const store = await resolveStore();
 		return telemetry.span("a2.state", {
 			"a2.contract": name,
 			"a2.session_id": sessionId,
 			"a2.state.reducer": reducer.name
-		}, async (span) => {
-			const stateRead = store.readStates ? await enqueueStateRead(store, sessionId, reducer.name) : await readCachedState(store, sessionId, reducer.name);
-			const { state, index, folded } = await foldStateRead(store, sessionId, reducer, stateRead, span);
-			if (folded > 0) {
-				const snapshotState = cloneInitial(state);
-				const write = Promise.resolve().then(() => store.putSnapshot(nsId(sessionId), reducer.name, index, snapshotState)).catch(() => {});
-				track(write);
-				platformWaitUntil(write);
-			}
-			return {
-				state,
-				index
-			};
-		});
+		}, (span) => enqueueStateRead(store, sessionId, reducer, throughIndex, pinEventIndex, span));
 	};
 	const makeSchedule = (sessionId, trigger) => {
 		const triggerEventId = trigger?.id ?? null;
@@ -569,11 +1306,14 @@ function createServer(options) {
 			if (events.length === 0) throw new TypeError("schedule requires at least one event");
 			const dueAt = scheduleDueAt(timing, triggerCreatedAt ?? Date.now());
 			const payloads = events.map((event) => cloneScheduledPayload(event.payload));
-			const snapshottedEvents = events.map((event, index) => ({
+			const snapshottedEvents = events.map((event, index) => event.id === void 0 ? {
+				type: event.type,
+				payload: payloads[index]
+			} : {
 				type: event.type,
 				payload: payloads[index],
-				...event.id === void 0 ? {} : { id: event.id }
-			}));
+				id: event.id
+			});
 			const validated = validateEvents(sessionId, structuredClone(snapshottedEvents), false);
 			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName);
 			const scheduledEvents = await Promise.all(validated.map(async (event, item) => ({
@@ -618,14 +1358,6 @@ function createServer(options) {
 		return store.presence;
 	};
 	const setPresence = async (sessionId, patch, fallbackSeen) => {
-		if (Reflect.get(patch, "~a2.pushed") === true) {
-			Object.freeze(patch.values);
-			await options.validatePush?.({
-				sessionId,
-				events: [],
-				presence: Object.freeze(patch)
-			});
-		}
 		if (typeof patch.participant !== "string" || patch.participant.length === 0) throw new TypeError("presence participant must be a non-empty string");
 		if (RESERVED_PARTICIPANT_IDS.has(patch.participant)) throw new TypeError(`presence participant must not be '${patch.participant}'`);
 		if (patch.at !== void 0 && (typeof patch.at !== "number" || !Number.isFinite(patch.at) || patch.at < 0 || patch.at > 864e13)) throw new TypeError("presence at must be non-negative epoch milliseconds within the Date range");
@@ -843,7 +1575,11 @@ function createServer(options) {
 		append,
 		schedule: makeSchedule(id, trigger),
 		history: async (bounds) => (await readHistory(id, bounds)).map(toPublic),
-		state: (reducer) => readState(id, reducer),
+		state: (reducer, stateOptions) => {
+			const through = stateOptions?.through ?? trigger?.index;
+			if (through !== void 0 && through !== "latest") assertStateIndex(through);
+			return readState(id, reducer, through === "latest" ? void 0 : through, trigger && through !== "latest" ? trigger.index : void 0);
+		},
 		stream: (opts) => {
 			const startAfter = opts?.startAfter ?? 0;
 			assertStreamIndex(startAfter);
@@ -1230,11 +1966,22 @@ function createServer(options) {
 						shouldClaim = false;
 					}
 				}
+				if (claim?.outcome === "claimed" && [...active.values()].some((entry) => entry.lapsed)) {
+					shouldClaim = true;
+					continue;
+				}
 				if (active.size > 0) {
 					const wake = signal?.wait(signalVersion);
-					await Promise.race([...[...active.values()].map((entry) => entry.execution), ...wake ? [wake.promise] : []]);
+					const hasLapsed = [...active.values()].some((entry) => entry.lapsed);
+					const retry = claim?.outcome === "busy" && hasLapsed ? defaultSleep(Math.max(0, claim.retryAt.getTime() - Date.now())) : void 0;
+					const retryDue = await Promise.race([
+						...[...active.values()].map((entry) => entry.execution.then(() => false)),
+						...wake ? [wake.promise.then(() => false)] : [],
+						...retry ? [retry.promise.then(() => true)] : []
+					]);
 					wake?.cancel();
-					shouldClaim = claimAgain || active.size === 0 || signal !== void 0 && signal.version !== signalVersion;
+					retry?.cancel();
+					shouldClaim = retryDue || claimAgain || active.size === 0 || hasLapsed || signal !== void 0 && signal.version !== signalVersion;
 					claimAgain = false;
 					continue;
 				}
@@ -1270,22 +2017,22 @@ function createServer(options) {
 		};
 	});
 	const appendExternal = async (sessionId, mode, events, requireDurableInitialArm = false) => {
-		const pushed = events.filter((event) => Reflect.get(event, "~a2.pushed") === true);
-		if (pushed.length > 0) await options.validatePush?.({
-			sessionId,
-			events: pushed
-		});
 		return appendCore(sessionId, events, "external", mode, (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt), void 0, void 0, requireDurableInitialArm);
 	};
+	const session = (id) => {
+		assertSessionId(id);
+		const appendInline = async (...events) => appendExternal(id, "inline", events);
+		const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
+		const append = Object.assign(appendInline, { dispatch: appendDispatch });
+		return makeSession(id, append, null);
+	};
 	const self = {
 		contract: serverContract,
-		session(id) {
-			assertSessionId(id);
-			const appendInline = async (...events) => appendExternal(id, "inline", events);
-			const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
-			const append = Object.assign(appendInline, { dispatch: appendDispatch });
-			return makeSession(id, append, null);
-		},
+		fetch: createServerFetch({
+			contract: serverContract,
+			session
+		}),
+		session,
 		async drain(sessionId) {
 			assertSessionId(sessionId);
 			const { settled } = await drainSession(sessionId);
@@ -1306,57 +2053,6 @@ function createServer(options) {
 			await appendExternal(sessionId, "inline", [...events], true);
 		}
 	});
-	serverSchedulerBindings.set(self, { scheduler });
-	serverInspection.set(self, {
-		async listSessions(inspectionOptions) {
-			const store = await resolveStore();
-			if (!store.inspect) throw new InspectionUnsupportedError("this store backend does not support inspection");
-			const page = await store.inspect.listSessions({
-				prefix: `${name}${NS}`,
-				limit: inspectionOptions.limit,
-				...inspectionOptions.cursor !== void 0 ? { cursor: inspectionOptions.cursor } : {}
-			});
-			return {
-				cursor: page.cursor,
-				sessions: page.sessions.map((session) => {
-					const publicSession = { ...session };
-					publicSession.sessionId = stripNs(session.sessionId);
-					return publicSession;
-				})
-			};
-		},
-		async readSessionPage(sessionId, inspectionOptions) {
-			assertSessionId(sessionId);
-			if (!Number.isSafeInteger(inspectionOptions.afterIndex) || inspectionOptions.afterIndex < 0 || !Number.isSafeInteger(inspectionOptions.limit) || inspectionOptions.limit < 1 || inspectionOptions.throughIndex !== void 0 && (!Number.isSafeInteger(inspectionOptions.throughIndex) || inspectionOptions.throughIndex < 0)) throw new TypeError("invalid inspection event page bounds");
-			const store = await resolveStore();
-			if (!store.inspect) throw new InspectionUnsupportedError("this store backend does not support inspection");
-			const ns = nsId(sessionId);
-			const snapshots = inspectionOptions.afterIndex === 0 ? await store.inspect.listSnapshots(ns) : [];
-			const { events, throughIndex } = store.inspect.readEvents ? await store.inspect.readEvents(ns, inspectionOptions) : await (async () => {
-				const all = await store.read(ns);
-				const currentFrontier = all.at(-1)?.index ?? 0;
-				const throughIndex = Math.min(inspectionOptions.throughIndex ?? currentFrontier, currentFrontier);
-				return {
-					events: all.filter((event) => event.index > inspectionOptions.afterIndex && event.index <= throughIndex).slice(0, inspectionOptions.limit),
-					throughIndex
-				};
-			})();
-			if (!Number.isSafeInteger(throughIndex) || throughIndex < 0 || events.length > inspectionOptions.limit || inspectionOptions.throughIndex !== void 0 && inspectionOptions.afterIndex > 0 && throughIndex !== inspectionOptions.throughIndex) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' has invalid bounds`);
-			for (let position = 0; position < events.length; position += 1) if (events[position].index !== inspectionOptions.afterIndex + position + 1 || events[position].index > throughIndex) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' is not contiguous`);
-			if (inspectionOptions.afterIndex < throughIndex && events.length === 0) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' ended before index ${throughIndex}`);
-			const lastIndex = events.at(-1)?.index ?? inspectionOptions.afterIndex;
-			return {
-				events: events.map((event) => {
-					const publicEvent = { ...event };
-					publicEvent.sessionId = sessionId;
-					return publicEvent;
-				}),
-				snapshots: snapshots.filter((snapshot) => snapshot.index <= throughIndex),
-				throughIndex,
-				nextIndex: lastIndex < throughIndex ? lastIndex : null
-			};
-		}
-	});
 	return self;
 }
 function assertSessionId(id) {
@@ -1369,6 +2065,9 @@ function assertHistoryIndex(name, value) {
 function assertStreamIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("stream.startAfter must be a non-negative safe integer");
 }
+function assertStateIndex(value) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("state.through must be a non-negative safe integer");
+}
 function assertAppendName(name) {
 	if (typeof name !== "string" || name.length === 0) throw new TypeError("handler append name must be a non-empty string");
 }
@@ -1458,6 +2157,6 @@ function cloneInitial(initial) {
 	}
 }
 //#endregion
-export { deliverSchedulerAppend as n, createServer as t };
+export { platformVercelOidcToken as i, deliverSchedulerAppend as n, setServerFetchHooks as r, createServer as t };
 
-//# sourceMappingURL=server-Duw6MVlB.js.map
+//# sourceMappingURL=server-B2XNevQA.js.map