experimental-a2 0.3.0 → 0.5.0

package/dist/http.js

@@ -1,66 +1,48 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { i as STREAM_TIMINGS } from "./internal-gCd5qMry.js";
-import { a as eventToWire, n as errorStatus, r as errorToWire, t as errorFromWire } from "./wire-BVsgR8o9.js";
-//#region src/http.ts
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { _ as schedulerForServer, c as STREAM_TIMINGS, d as assertServerSchedulerBindings, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, u as assertSchedulerTargets } from "./internal-DstsI6Re.js";
+import { t as invocationDeadlineMs } from "./platform-B4TnJtWu.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, r as errorFromWire, s as eventToWire, t as SOCKET_PING_FRAME, v as socketFrameFor, y as socketSubscribedFor } from "./wire-BFQmSJ-9.js";
+//#region src/sse.ts
 /**
-* experimental-a2/http — route-side transport helpers (specs/a2-api.md §9–10).
-*
-* `sseResponse` pipes a `session.stream()` iterable into a server-sent
-* events Response; `parsePushBody` validates the push envelope;
-* `errorResponse`/`deserializeError` are the A2Error wire pair the push
-* route and the client's `push` share.
+* The SSE response protocol — framing, heartbeat, deadline, and
+* teardown for the live stream lane. Internal module: `handle`'s
+* stream branch is the one sanctioned caller; the framing rules stay
+* documented on `sseResponse` because the client's parser (and the
+* stall watchdog) depend on them.
 */
-const invalid = (message) => new A2Error("INVALID_PAYLOAD", `malformed push body: ${message}`);
-/**
-* Validate the push envelope — `{ sessionId, events }` — throwing
-* `INVALID_PAYLOAD` on a malformed body. Payload validation against the
-* machine's schemas happens in `append`, not here.
-*/
-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 } = body;
-	if (typeof sessionId !== "string" || sessionId.length === 0) throw invalid("sessionId must be a non-empty string");
-	if (!Array.isArray(events) || events.length === 0) throw invalid("events must be a non-empty array");
-	return {
-		sessionId,
-		events: 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;
-			Object.defineProperty(out, "~a2.pushed", { value: true });
-			return out;
-		})
-	};
-}
 /**
 * Pipe a live event iterable into an SSE `Response`. Each event is one
-* frame — `id:` carries the log index, `data:` the JSON event. A
+* 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.
+* 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;
-	const stopHeartbeat = () => {
+	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) {
@@ -69,23 +51,49 @@ function sseResponse(iterable) {
 				try {
 					controller.enqueue(encoder.encode(": ping\n\n"));
 				} catch {
-					stopHeartbeat();
+					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) {
-			const { value, done } = await iterator.next();
-			if (done) {
-				stopHeartbeat();
-				controller.close();
-				return;
+			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;
 			}
-			controller.enqueue(encoder.encode(`id: ${value.index}\ndata: ${JSON.stringify(eventToWire(value))}\n\n`));
 		},
 		async cancel() {
-			stopHeartbeat();
-			await iterator.return?.();
+			if (closed) return;
+			closed = true;
+			stopTimers();
+			await returnIterator();
 		}
 	});
 	return new Response(stream, {
@@ -97,15 +105,433 @@ function sseResponse(iterable) {
 		}
 	});
 }
+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/push-envelope.ts
+/**
+* The push envelope's trust boundary — parsing and provenance-branding
+* 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 — `handle` (and the
+* socket handler) compose it; it is not part of the public surface.
+*/
+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;
+	Object.defineProperty(out, "~a2.pushed", { value: true });
+	return out;
+}
+/** The events half of the envelope — shared verbatim by the POST body
+* and the socket's `push` frames, so the provenance brand and the
+* INVALID_PAYLOAD shapes are 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;
+		Object.defineProperty(out, "~a2.pushed", { value: true });
+		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 {
+			session = null;
+		}
+		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) ?? 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;
+		}
+		try {
+			const patch = parsePresenceSibling(frame);
+			if (patch) await subscription.target.setPresence(patch);
+		} catch {
+			shell.malformedFrame("invalid presence frame");
+		}
+	};
+	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/http.ts
+/**
+* experimental-a2/http — the wire's server half (specs/a2-api.md §9–10, §13).
+*
+* A thin public assembly. The surface: `handle` — GET, POST, and the
+* socket's frames parsed into intents (stream, history, push,
+* ws-upgrade) with `before`/`after` hooks around them for policy —
+* plus `A2Intent`/`A2Outcome`/`UpgradeFn`/`A2Socket` (its argument
+* types), `errorResponse`/`deserializeError` (the A2Error wire pair
+* both sides branch on), and `schedulerHandler` (the scheduler
+* callback mount). The machinery lives in internal modules — the SSE
+* framing in sse.ts, the push-envelope trust boundary in
+* push-envelope.ts, the socket shell and multiplexed handler in
+* session-socket.ts — because nothing outside `handle` is sanctioned
+* to compose them. Policy — auth, caching, quotas — never enters this
+* module: the hooks own it.
+*/
+/**
+* Create one scheduler callback route for servers sharing the same configured
+* scheduler. Configuration mistakes throw immediately while the route module
+* is evaluated, before a delivery can be acknowledged by the wrong adapter.
+*/
+function schedulerHandler(firstServer, ...servers) {
+	if (firstServer === void 0) throw new TypeError("schedulerHandler() requires at least one A2 server");
+	const scheduler = schedulerForServer(firstServer);
+	const targets = [firstServer, ...servers];
+	assertSchedulerTargets(targets, { allowStructural: false });
+	assertServerSchedulerBindings(scheduler, targets);
+	return scheduler.handler(...targets);
+}
 /**
 * Serialize an error into the documented wire shape,
 * `{ error: { code, message, details } }`, with the mapped status
-* (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
-* 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
-* failure is retryable-once, not a protocol contract.
+* (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a
+* 503 STORE_UNAVAILABLE — from the client's perspective an unknown server
+* failure is retryable-once, not a protocol contract. The natural
+* return value of a `before` hook that wants the wire's own error
+* shapes.
 */
 function errorResponse(error) {
-	const a2error = error instanceof A2Error ? error : new A2Error("LOG_UNAVAILABLE", "internal error", { cause: error });
+	const a2error = asA2Error(error);
 	return Response.json(errorToWire(a2error), { status: errorStatus(a2error.code) });
 }
 /**
@@ -116,5 +542,165 @@ function errorResponse(error) {
 function deserializeError(body) {
 	return errorFromWire(body);
 }
+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;
+};
+/**
+* The session route pair as one call: `export const { GET, POST } =
+* handle(server, options?)` serves the live stream (SSE GET, resumed
+* at `index`), the history slice (GET with `gte`/`lte`), the push
+* envelope (POST), and — with `options.upgrade` — the multiplexed
+* WebSocket, all through one pair of policy hooks.
+*
+* Parsing is protocol, hooks are policy: a request that fails to parse
+* (missing sessionId, malformed bounds, bad push envelope) answers
+* INVALID_PAYLOAD on the wire before any hook runs. `before` sees
+* every parsed intent — HTTP requests and socket frames alike, with
+* `request` always the original (for socket frames: upgrade) Request —
+* and short-circuits by returning a Response: over HTTP it is the
+* response verbatim; over the socket it is translated to the wire's
+* own vocabulary (subscribe → `unsubscribed { reason: 'subscribe
+* rejected' }`, push → an INVALID_PAYLOAD error ack), because a
+* Response body cannot cross a socket. `after` runs only where the
+* library produced an HTTP response — never after a short-circuit,
+* never for socket frames — and may mutate `response.headers` in place
+* or return a replacement (history caching policy lives here, on
+* `outcome.covered`). `options.deadline` (epoch ms) closes sockets
+* cleanly ahead of a known platform deadline, so clients reconnect on
+* our schedule.
+*/
+function handle(server, options) {
+	const presence = options?.presence === true;
+	const before = async (request, intent) => {
+		const result = await options?.before?.({
+			request,
+			intent
+		});
+		return result instanceof Response ? result : null;
+	};
+	const decorate = async (request, intent, outcome, response) => {
+		const replaced = await options?.after?.({
+			request,
+			intent,
+			outcome,
+			response
+		});
+		return replaced instanceof Response ? replaced : response;
+	};
+	const attach = (request) => (socket) => {
+		sessionsSocket(async (sessionId, startAfter) => {
+			return await before(request, {
+				type: "stream",
+				sessionId,
+				startAfter,
+				transport: "ws"
+			}) === null ? server.session(sessionId) : null;
+		}, socket, {
+			presence,
+			...options?.deadline === void 0 ? {} : { deadline: options.deadline },
+			gatePush: async (sessionId, events) => {
+				return await before(request, {
+					type: "push",
+					sessionId,
+					events,
+					transport: "ws"
+				}) === null ? null : new A2Error("INVALID_PAYLOAD", "push rejected");
+			}
+		});
+	};
+	return {
+		async GET(req) {
+			try {
+				if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+					const short = await before(req, { type: "ws-upgrade" });
+					if (short !== null) return short;
+					if (options?.upgrade === void 0) return new Response("WebSocket upgrade requested, but handle() has no upgrade implementation — pass options.upgrade, e.g. { upgrade: (attach) => experimental_upgradeWebSocket(attach) } from '@vercel/functions'", { status: 426 });
+					return await options.upgrade(attach(req));
+				}
+				const { searchParams } = new URL(req.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);
+					const intent = {
+						type: "history",
+						sessionId,
+						...bounds
+					};
+					const short = await before(req, intent);
+					if (short !== null) return short;
+					const events = await server.session(sessionId).history(bounds);
+					const covered = events.length === bounds.lte - bounds.gte + 1;
+					return await decorate(req, intent, {
+						type: "history",
+						covered,
+						events
+					}, Response.json(events.map(eventToWire)));
+				}
+				const startAfter = parseResumeIndex(searchParams.get("index"));
+				const intent = {
+					type: "stream",
+					sessionId,
+					startAfter,
+					transport: "sse"
+				};
+				const short = await before(req, intent);
+				if (short !== null) return short;
+				const target = server.session(sessionId);
+				const response = sseResponse(presence ? target.stream({
+					startAfter,
+					presence: true
+				}) : target.stream({ startAfter }));
+				return await decorate(req, intent, { type: "stream" }, response);
+			} catch (err) {
+				return errorResponse(err);
+			}
+		},
+		async POST(req) {
+			try {
+				const body = await parsePushBody(req);
+				const intent = {
+					type: "push",
+					sessionId: body.sessionId,
+					events: body.events,
+					...body.presence === void 0 ? {} : { presence: body.presence },
+					transport: "http"
+				};
+				const short = await before(req, intent);
+				if (short !== null) return short;
+				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 await decorate(req, intent, {
+					type: "push",
+					appended
+				}, Response.json(appended));
+			} catch (err) {
+				return errorResponse(err);
+			}
+		}
+	};
+}
 //#endregion
-export { deserializeError, errorResponse, parsePushBody, sseResponse };
+export { deserializeError, errorResponse, handle, schedulerHandler };
+
+//# sourceMappingURL=http.js.map