experimental-a2 0.16.0 → 0.17.0

package/dist/{server-BD5ckxZb.js → server-Rj64fNvX.js}

@@ -1,10 +1,50 @@
-import { n as validateSync } from "./validate-XKT4FSNn.js";
-import { n as NonRetriableError, r as asStoreUnavailable, t as A2Error } from "./errors-DCk6ch5n.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-Dq2qYxou.js";
-import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-CmxUbV93.js";
+import { a as NonRetriableError, i as A2Error, n as isSessionCleared, o as asStoreUnavailable, r as sessionClearedError } from "./session-clear-DGI4jTQ5.js";
+import { n as foldEvent, s as validateSync, t as cloneInitial } from "./reducer-BAXc8JyF.js";
+import { n as encodeState, t as decodeState } from "./reducer-runtime-DQwz_J59.js";
+import { _ as serverInternals, c as STATE_CACHE, g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, l as STREAM_TIMINGS, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS, v as stateTailReaders } from "./internal-CbVvEwad.js";
+import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-4_y8lETm.js";
+import { i as takeBuffered, n as isSerializedEvent, r as parseSerializedEvent, t as bufferedEvents } from "./stream-buffer-Cx7AAPGq.js";
 import { r as platformWaitUntil, 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, s as eventToWire, t as SOCKET_PING_FRAME, v as socketFrameFor, y as socketSubscribedFor } from "./wire-BO5wWCb1.js";
+import { A as stateSnapshotToWire, C as serializedEventToWireJson, D as socketFrameFor, E as socketEventsFor, O as socketSubscribedFor, S as presenceSnapshotToWire, T as socketErrorAckFor, b as presencePatchToWire, d as heldEventBatch, i as compactEventJson, j as wireVersion, k as socketUnsubscribedFor, m as isStreamEvent, n as SOCKET_PING_FRAME, o as errorStatus, r as asA2Error, s as errorToWire, t as EVENT_WRITE_CHARS, u as eventToWire, w as socketAckFor } from "./wire-DjfHOvdW.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+//#region src/bounded-cache.ts
+function boundedCache({ maxEntries, maxBytes }) {
+	const entries = /* @__PURE__ */ new Map();
+	let total = 0;
+	const remove = (key) => {
+		const entry = entries.get(key);
+		if (!entry) return;
+		entries.delete(key);
+		total -= entry.bytes;
+	};
+	return {
+		get(key) {
+			const entry = entries.get(key);
+			if (!entry) return void 0;
+			entries.delete(key);
+			entries.set(key, entry);
+			return entry.value;
+		},
+		set(key, value, bytes) {
+			remove(key);
+			if (bytes > maxBytes / 4) return;
+			entries.set(key, {
+				value,
+				bytes
+			});
+			total += bytes;
+			for (const oldest of entries.keys()) {
+				if (entries.size <= maxEntries && total <= maxBytes) break;
+				remove(oldest);
+			}
+		},
+		delete: remove,
+		deleteWhere(match) {
+			for (const key of entries.keys()) if (match(key)) remove(key);
+		}
+	};
+}
+//#endregion
 //#region src/push-envelope.ts
 /**
 * The push envelope's trust boundary for `{ sessionId, events, presence? }`,
@@ -191,25 +231,43 @@ function socketShell(socket, release, onFrame, deadlineAt) {
 		track
 	};
 }
-const socketSubscription = (target, startAfter, presence) => ({
-	target,
-	iterator: (presence ? target.stream({
-		startAfter,
-		presence: true
-	}) : target.stream({ startAfter }))[Symbol.asyncIterator](),
-	stopped: false
-});
+const socketSubscription = (options) => {
+	const { target, startAfter, presence, attempt } = options;
+	return {
+		target,
+		iterator: (presence ? target.stream({
+			startAfter,
+			presence: true
+		}) : target.stream({ startAfter }))[Symbol.asyncIterator](),
+		stopped: false,
+		...attempt === void 0 ? {} : { attempt }
+	};
+};
 const stopSubscription = (subscription) => {
 	subscription.stopped = true;
 	subscription.iterator.return?.()?.catch(() => {});
 };
-const pumpSubscription = async (shell, subscription, frameFor) => {
+/**
+* Sends a subscription's items until it ends. With `batch`, an event and
+* the events its iterator already holds go out as one frame.
+*/
+const pumpSubscription = async (options) => {
+	const { shell, subscription, frameFor, batch } = options;
 	for (;;) {
 		while (!shell.torn() && !subscription.stopped && shell.buffered() > SOCKET_TIMINGS.highWaterMarkBytes) 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 || done) return;
-		shell.send(frameFor(value));
+		if (!batch || !isStreamEvent(value)) {
+			shell.send(frameFor(value));
+			continue;
+		}
+		const { events } = heldEventBatch({
+			first: value,
+			iterator: subscription.iterator,
+			encode: compactEventJson
+		});
+		shell.send(batch(events));
 	}
 };
 const handleSocketPush = async (shell, target, sessionId, frame, req, ackSessionId, gatePush, activate) => {
@@ -255,7 +313,11 @@ const applySocketPresence = async (shell, target, sessionId, frame, gatePush) =>
 };
 function sessionSocket(sessionId, session, socket, options) {
 	const target = session;
-	const subscription = socketSubscription(target, options?.startAfter ?? 0, options?.presence === true);
+	const subscription = socketSubscription({
+		target,
+		startAfter: options?.startAfter ?? 0,
+		presence: options?.presence === true
+	});
 	const handleFrame = (frame) => {
 		switch (frame["kind"]) {
 			case "push": {
@@ -286,20 +348,41 @@ function sessionSocket(sessionId, session, socket, options) {
 		}
 	};
 	const shell = socketShell(socket, () => stopSubscription(subscription), handleFrame, options?.deadline);
-	pumpSubscription(shell, subscription, socketFrameFor).then(() => shell.shutdown(1e3), () => shell.shutdown(1011, "stream failed"));
+	pumpSubscription({
+		shell,
+		subscription,
+		frameFor: socketFrameFor,
+		...options?.wire === 2 ? { batch: (events) => socketEventsFor(events) } : {}
+	}).then(() => shell.shutdown(1e3), () => shell.shutdown(1011, "stream failed"));
 }
 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;
+		const { id, attempt, index, bootstrap, reducer } = entry;
 		if (typeof id !== "string" || id.length === 0) return null;
-		if (typeof index !== "number" || !Number.isInteger(index) || index < 0) return null;
-		entries.push({
+		if (attempt !== void 0 && (typeof attempt !== "number" || !Number.isSafeInteger(attempt) || attempt < 0)) return null;
+		if (reducer !== void 0 && (typeof reducer !== "string" || reducer.length === 0)) return null;
+		const lane = {
 			id,
-			index
-		});
+			...attempt === void 0 ? {} : { attempt }
+		};
+		if (bootstrap === true) {
+			if (index !== void 0 || typeof reducer !== "string") return null;
+			entries.push({
+				...lane,
+				bootstrap: true,
+				reducer
+			});
+		} else {
+			if (bootstrap !== void 0 || typeof index !== "number" || !Number.isSafeInteger(index) || index < 0) return null;
+			entries.push({
+				...lane,
+				index,
+				...reducer === void 0 ? {} : { reducer }
+			});
+		}
 	}
 	return entries;
 };
@@ -322,18 +405,34 @@ function sessionsSocket(resolve, socket, options) {
 		if (subscriptions.get(id) === subscription) subscriptions.delete(id);
 	};
 	const runSubscription = async (id, subscription) => {
+		const { attempt } = subscription;
 		try {
-			await pumpSubscription(shell, subscription, (item) => socketFrameFor(item, id));
+			await pumpSubscription({
+				shell,
+				subscription,
+				frameFor: (item) => socketFrameFor(item, id),
+				...options?.wire === 2 ? { batch: (events) => socketEventsFor(events, id) } : {}
+			});
 			if (shell.torn() || subscription.stopped) return;
 			retire(id, subscription);
-			shell.send(socketUnsubscribedFor(id));
+			shell.send(socketUnsubscribedFor({
+				sessionId: id,
+				attempt
+			}));
 		} catch (error) {
 			if (shell.torn() || subscription.stopped) return;
 			retire(id, subscription);
-			shell.send(socketUnsubscribedFor(id, "stream failed", asA2Error(error)));
+			shell.send(socketUnsubscribedFor({
+				sessionId: id,
+				attempt,
+				reason: "stream failed",
+				error: asA2Error(error)
+			}));
 		}
 	};
-	const startSubscription = async (id, index) => {
+	const startSubscription = async (entry) => {
+		const { id, attempt } = entry;
+		const index = entry.index ?? 0;
 		const existing = subscriptions.get(id);
 		if (existing) {
 			stopSubscription(existing);
@@ -341,19 +440,37 @@ function sessionsSocket(resolve, socket, options) {
 		}
 		let session;
 		try {
-			session = await resolve(id, index);
+			session = await resolve(id, index, entry);
 		} catch (error) {
-			if (!shell.torn()) shell.send(socketUnsubscribedFor(id, "stream failed", asA2Error(error)));
+			if (!shell.torn()) shell.send(socketUnsubscribedFor({
+				sessionId: id,
+				attempt,
+				reason: "stream failed",
+				error: asA2Error(error)
+			}));
 			return;
 		}
 		if (shell.torn()) return;
 		if (session === null) {
-			shell.send(socketUnsubscribedFor(id, "subscribe rejected", new A2Error("FORBIDDEN", "the subscription is not authorized")));
+			shell.send(socketUnsubscribedFor({
+				sessionId: id,
+				attempt,
+				reason: "subscribe rejected",
+				error: new A2Error("FORBIDDEN", "the subscription is not authorized")
+			}));
 			return;
 		}
-		const subscription = socketSubscription(session, index, presence);
+		const subscription = socketSubscription({
+			target: session,
+			startAfter: index,
+			presence,
+			attempt
+		});
 		subscriptions.set(id, subscription);
-		shell.send(socketSubscribedFor(id));
+		shell.send(socketSubscribedFor({
+			sessionId: id,
+			attempt
+		}));
 		runSubscription(id, subscription);
 	};
 	let controlTail = Promise.resolve();
@@ -384,7 +501,7 @@ function sessionsSocket(resolve, socket, options) {
 					shell.malformedFrame("malformed subscribe frame");
 					return;
 				}
-				for (const entry of entries) control(() => startSubscription(entry.id, entry.index));
+				for (const entry of entries) control(() => startSubscription(entry));
 				return;
 			}
 			case "unsubscribe": {
@@ -449,7 +566,10 @@ function sessionsSocket(resolve, socket, options) {
 */
 /**
 * 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
+* frame — `id:` carries the event-log index, `data:` the JSON event.
+* Frames for events the iterable already holds are written together. With
+* `wire: 2` those events share one frame instead: `data:` is a JSON array of
+* `CompactWireEvent`s and `id:` the last one's index. 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`
@@ -463,7 +583,8 @@ function sessionsSocket(resolve, socket, options) {
 * closes cleanly one second before it so the client reconnects without
 * a platform-timeout failure.
 */
-function sseResponse(iterable) {
+function sseResponse(iterable, options = {}) {
+	const write = options.wire === 2 ? batchedFrames : eventFrames;
 	const iterator = iterable[Symbol.asyncIterator]();
 	const encoder = new TextEncoder();
 	let heartbeat;
@@ -529,7 +650,7 @@ function sseResponse(iterable) {
 					controller.close();
 					return;
 				}
-				controller.enqueue(encoder.encode(frameFor(value)));
+				controller.enqueue(encoder.encode(write(value, iterator)));
 			} catch (error) {
 				if (closed) return;
 				closed = true;
@@ -554,12 +675,114 @@ function sseResponse(iterable) {
 		}
 	});
 }
+/** Version 1: one frame per event, then each event the iterator holds. */
+function eventFrames(first, iterator) {
+	let frames = frameFor(first);
+	while (frames.length < EVENT_WRITE_CHARS) {
+		const event = takeBuffered(iterator);
+		if (!event) break;
+		frames += frameFor(event);
+	}
+	return frames;
+}
+/**
+* Version 2: events this write carries share one frame, a JSON array whose
+* `id:` is its last index. Held events are always events, so only `first`
+* can be a snapshot or presence frame.
+*/
+function batchedFrames(first, iterator) {
+	const lead = isStreamEvent(first) ? "" : frameFor(first);
+	const head = isStreamEvent(first) ? first : takeBuffered(iterator);
+	if (!head) return lead;
+	const { events, last } = heldEventBatch({
+		first: head,
+		iterator,
+		encode: compactJsonLine
+	});
+	return `${lead}id: ${last.index}\ndata: [${events.join(",")}]\n\n`;
+}
+const compactJsonLine = (event) => isSerializedEvent(event) && /[\r\n]/.test(event.payloadJson) ? compactEventJson(parseSerializedEvent(event)) : compactEventJson(event);
 function frameFor(item) {
+	if ("kind" in item) return `event: a2-snapshot\ndata: ${JSON.stringify(stateSnapshotToWire(item))}\n\n`;
 	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`;
+	if (isSerializedEvent(item)) return /[\r\n]/.test(item.payloadJson) ? `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(parseSerializedEvent(item)))}\n\n` : `id: ${item.index}\ndata: ${serializedEventToWireJson(item)}\n\n`;
 	return `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(item))}\n\n`;
 }
 //#endregion
+//#region src/bootstrap-stream.ts
+function bootstrapStream(options) {
+	return { [Symbol.asyncIterator]() {
+		let closed = false;
+		let index;
+		let source;
+		let stopActivity;
+		const abort = new AbortController();
+		const activity = createStreamActivity(() => {
+			if (source) streamActivities.get(source)?.activate();
+		});
+		const iterator = {
+			async next() {
+				if (closed) return {
+					done: true,
+					value: void 0
+				};
+				if (index === void 0) {
+					let cancel;
+					const cancelled = new Promise((resolve) => {
+						cancel = () => resolve(void 0);
+						abort.signal.addEventListener("abort", cancel, { once: true });
+					});
+					try {
+						const snapshot = await Promise.race([options.snapshot(), cancelled]);
+						if (closed || snapshot === void 0) return {
+							done: true,
+							value: void 0
+						};
+						index = snapshot.index;
+						return {
+							done: false,
+							value: snapshot
+						};
+					} finally {
+						if (cancel) abort.signal.removeEventListener("abort", cancel);
+					}
+				}
+				if (!source) {
+					source = options.stream(index)[Symbol.asyncIterator]();
+					const sourceActivity = streamActivities.get(source);
+					if (sourceActivity) {
+						activity.setIdle(sourceActivity.idle);
+						stopActivity = sourceActivity.subscribe(activity.setIdle);
+					}
+				}
+				const result = await source.next();
+				return closed ? {
+					done: true,
+					value: void 0
+				} : result;
+			},
+			async return() {
+				if (closed) return {
+					done: true,
+					value: void 0
+				};
+				closed = true;
+				abort.abort();
+				stopActivity?.();
+				await source?.return?.();
+				return {
+					done: true,
+					value: void 0
+				};
+			}
+		};
+		streamActivities.set(iterator, activity);
+		bufferedEvents.set(iterator, () => closed || !source ? void 0 : takeBuffered(source));
+		return iterator;
+	} };
+}
+//#endregion
 //#region src/server-fetch.ts
 const serverFetchHooks = /* @__PURE__ */ new WeakMap();
 function setServerFetchHooks(server, hooks) {
@@ -581,6 +804,23 @@ const parseResumeIndex = (raw) => {
 	if (!Number.isSafeInteger(index) || index < 0) throw new A2Error("INVALID_PAYLOAD", "stream index must be a non-negative safe integer");
 	return index;
 };
+const parseSubscription = (params) => {
+	const reducer = params.get("reducer");
+	const bootstrap = params.get("bootstrap");
+	const index = params.get("index");
+	if (reducer === "") throw new A2Error("INVALID_PAYLOAD", "empty reducer name");
+	if (bootstrap !== null) {
+		if (bootstrap !== "1" || index !== null || reducer === null) throw new A2Error("INVALID_PAYLOAD", "bootstrap requires a reducer and no index");
+		return {
+			bootstrap: true,
+			reducer
+		};
+	}
+	return {
+		index: parseResumeIndex(index),
+		...reducer === null ? {} : { reducer }
+	};
+};
 const errorResponse = (error) => {
 	const a2error = asA2Error(error);
 	return Response.json(errorToWire(a2error), { status: errorStatus(a2error.code) });
@@ -630,17 +870,54 @@ function createServerFetch(server) {
 				return asA2Error(error);
 			}
 		};
-		const attachMultiplexed = (socket) => {
+		const selectedSession = (sessionId, selection) => {
+			const reducer = server.contract.reducer;
+			if (selection.reducer !== void 0 && reducer !== void 0 && reducer.name !== selection.reducer) throw new A2Error("INVALID_PAYLOAD", "client reducer does not match the public contract reducer");
+			const target = server.session(sessionId);
+			const streamTarget = target;
+			if (!selection.bootstrap) return streamTarget;
+			if (!reducer) throw new A2Error("INVALID_PAYLOAD", "contract has no public reducer");
+			return {
+				...streamTarget,
+				stream: (streamOptions) => bootstrapStream({
+					snapshot: async () => {
+						const initial = await target.state(reducer);
+						return {
+							kind: "snapshot",
+							sessionId,
+							name: reducer.name,
+							index: initial.index,
+							state: encodeState({
+								reducer,
+								state: initial.state
+							}),
+							...initial.clearIndex === void 0 ? {} : { clearIndex: initial.clearIndex }
+						};
+					},
+					stream: (index) => {
+						const bounds = {
+							startAfter: index,
+							presence: streamOptions.presence === true
+						};
+						return target.stream(bounds);
+					}
+				})
+			};
+		};
+		const attachMultiplexed = (wire) => (socket) => {
 			const deadline = invocationDeadlineMs();
-			sessionsSocket(async (sessionId, startAfter) => {
-				return await authorized({
+			sessionsSocket(async (sessionId, startAfter, selection = { index: startAfter }) => {
+				const operation = {
 					type: "stream",
 					sessionId,
 					startAfter,
+					...selection.bootstrap ? { bootstrap: true } : {},
 					transport: "websocket"
-				}) ? server.session(sessionId) : null;
+				};
+				return await authorized(operation) ? selectedSession(sessionId, selection) : null;
 			}, socket, {
 				presence,
+				wire,
 				...deadline === null ? {} : { deadline },
 				gatePush: gateSocketPush
 			});
@@ -649,23 +926,27 @@ function createServerFetch(server) {
 			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 });
-					if (options.multiplexWebSocket === true) return await options.upgradeWebSocket(attachMultiplexed);
 					const { searchParams } = new URL(request.url);
+					const wire = wireVersion(searchParams.get("wire"));
+					if (options.multiplexWebSocket === true) return await options.upgradeWebSocket(attachMultiplexed(wire));
 					const sessionId = searchParams.get("sessionId");
 					if (sessionId === null || sessionId.length === 0) throw new A2Error("INVALID_PAYLOAD", "missing sessionId");
-					const startAfter = parseResumeIndex(searchParams.get("index"));
+					const selection = parseSubscription(searchParams);
+					const startAfter = selection.index ?? 0;
 					await authorize({
 						type: "stream",
 						sessionId,
 						startAfter,
+						...selection.bootstrap ? { bootstrap: true } : {},
 						transport: "websocket"
 					});
-					const target = server.session(sessionId);
+					const target = selectedSession(sessionId, selection);
 					const attach = (socket) => {
 						const deadline = invocationDeadlineMs();
 						sessionSocket(sessionId, target, socket, {
 							startAfter,
 							presence,
+							wire,
 							...deadline === null ? {} : { deadline },
 							gatePush: gateSocketPush
 						});
@@ -685,22 +966,28 @@ function createServerFetch(server) {
 						...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 { events, clearIndex } = await server.historyPage(sessionId, bounds);
+					const first = Math.max(bounds.gte, (clearIndex ?? 0) + 1);
+					const covered = events.length === Math.max(0, bounds.lte - first + 1);
+					return Response.json(events.map(eventToWire), { headers: {
+						"a2-history-covered": String(covered),
+						...clearIndex === void 0 ? {} : { "a2-clear-index": String(clearIndex) }
+					} });
 				}
-				const startAfter = parseResumeIndex(searchParams.get("index"));
+				const selection = parseSubscription(searchParams);
+				const startAfter = selection.index ?? 0;
 				await authorize({
 					type: "stream",
 					sessionId,
 					startAfter,
+					...selection.bootstrap ? { bootstrap: true } : {},
 					transport: "http"
 				});
-				const target = server.session(sessionId);
+				const target = selectedSession(sessionId, selection);
 				return sseResponse(presence ? target.stream({
 					startAfter,
 					presence: true
-				}) : target.stream({ startAfter }));
+				}) : target.stream({ startAfter }), { wire: wireVersion(searchParams.get("wire")) });
 			}
 			if (request.method === "POST") {
 				const body = await parsePushBody(request);
@@ -746,6 +1033,7 @@ const APPEND_NAMESPACE = "a2:handler-append:v2";
 const RETURN_NAMESPACE = "a2:handler-return:v1";
 const SCHEDULE_NAMESPACE = "a2:schedule:v1";
 const SCHEDULED_EVENT_NAMESPACE = "a2:scheduled-event:v1";
+const SCHEDULE_CLEAR_NAMESPACE = "a2:schedule-clear:v1";
 async function deterministicIdFromInput(input) {
 	const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(input));
 	const bytes = new Uint8Array(digest).slice(0, 16);
@@ -773,13 +1061,31 @@ async function deterministicReturnedEventId(triggerEventId, itemOrdinal) {
 		itemOrdinal
 	]);
 }
-async function deterministicScheduleId(contract, sessionId, triggerEventId, name) {
+/**
+* The id of a scheduled append. `clearIndex` is the lifetime the trigger was
+* claimed in; it joins the input only when positive, so a trigger id reused
+* after a clear schedules a distinct task while sessions never cleared keep
+* the ids they always had.
+*/
+async function deterministicScheduleId(contract, sessionId, triggerEventId, name, clearIndex = 0) {
 	return deterministicIdFromInput(JSON.stringify([
 		SCHEDULE_NAMESPACE,
 		contract,
 		sessionId,
 		triggerEventId,
-		name
+		name,
+		...clearIndex > 0 ? [clearIndex] : []
+	]));
+}
+async function deterministicScheduleClearId({ contract, sessionId, triggerEventId, clearIndex, name, ifLastIndex }) {
+	return deterministicIdFromInput(JSON.stringify([
+		SCHEDULE_CLEAR_NAMESPACE,
+		contract,
+		sessionId,
+		triggerEventId,
+		clearIndex,
+		name,
+		ifLastIndex
 	]));
 }
 async function deterministicScheduledEventId(scheduleId, itemOrdinal) {
@@ -812,14 +1118,42 @@ const CONSOLE_TELEMETRY = { span: (name, attributes, fn) => fn({
 */
 async function deliverSchedulerAppend(server, task) {
 	if (server.contract.name !== task.contract) throw new TypeError(`a2 scheduler: append task for contract '${task.contract}' cannot be delivered to '${server.contract.name}'`);
+	const { originIndex } = task;
+	if (originIndex !== void 0 && (!Number.isSafeInteger(originIndex) || originIndex < 1)) throw new TypeError("a2 scheduler: append task originIndex must be a positive safe integer");
 	const internals = serverInternals.get(server);
 	if (!internals) throw new TypeError(`a2 scheduler: server for contract '${task.contract}' cannot receive scheduled appends`);
-	await internals.schedulerAppend(task.sessionId, task.events);
+	await internals.schedulerAppend(task.sessionId, task.events, originIndex);
+}
+/**
+* Deliver one authenticated scheduler clear: a conditional
+* `clear({ ifLastIndex })` that resolves after its deletion finishes, so a
+* provider retry resumes an interrupted deletion. Custom scheduler adapters
+* call this after validating their transport envelope; application code uses
+* `session.schedule.clear`.
+*/
+async function deliverSchedulerClear(server, task) {
+	if (server.contract.name !== task.contract) throw new TypeError(`a2 scheduler: clear task for contract '${task.contract}' cannot be delivered to '${server.contract.name}'`);
+	if (task.kind !== "clear" || !Number.isSafeInteger(task.ifLastIndex) || task.ifLastIndex < 0) throw new TypeError("a2 scheduler: a clear task needs kind \"clear\" and a non-negative safe integer ifLastIndex");
+	const internals = serverInternals.get(server);
+	if (!internals) throw new TypeError(`a2 scheduler: server for contract '${task.contract}' cannot receive scheduled clears`);
+	await internals.schedulerClear(task.sessionId, task.ifLastIndex);
 }
 function handler(entry) {
 	return typeof entry === "function" ? { handler: entry } : entry;
 }
 const MAX_FAILURES = 10;
+/** Abort a lost attempt's handler and release its drain slot. */
+function endSuperseded(entry, message) {
+	entry.supersede.abort(new A2Error("SUPERSEDED_ATTEMPT", message));
+	entry.fence({
+		status: "superseded",
+		opensLane: false,
+		appendsEvents: false
+	});
+}
+/** Pause between clear-deletion batches that found only locked rows. */
+const RECLAIM_STALL_MS = 20;
+const RECLAIM_STALL_LIMIT = 50;
 /** Default: how long a presence value survives without a refreshing set. */
 const PRESENCE_TTL_MS = 6e4;
 function createDrainSignal() {
@@ -927,6 +1261,17 @@ function foldPresenceRows(rows) {
 	};
 	return map;
 }
+const addSnapshotWrite = (writes, index, state, pinEventIndex) => {
+	let write = writes.get(index);
+	if (!write) {
+		write = {
+			state: cloneInitial(state),
+			pinEventIndexes: /* @__PURE__ */ new Set()
+		};
+		writes.set(index, write);
+	}
+	if (pinEventIndex !== void 0) write.pinEventIndexes.add(pinEventIndex);
+};
 /** Implement a contract: bind its vocabulary to storage and reactions. */
 function createServer(options) {
 	const serverContract = options?.contract;
@@ -1107,7 +1452,7 @@ function createServer(options) {
 	* the drain it schedules is created in the append's active context —
 	* with a real tracer, causal work remains connected.
 	*/
-	const appendCore = (sessionId, events, source, mode, onAppended, cause, generatedIds, requireDurableInitialArm = false) => telemetry.span("a2.append", {
+	const appendCore = (sessionId, events, source, mode, onAppended, cause, generatedIds, requireDurableInitialArm = false, originIndex) => telemetry.span("a2.append", {
 		"a2.contract": name,
 		"a2.session_id": sessionId,
 		"a2.append.source": source,
@@ -1126,9 +1471,9 @@ function createServer(options) {
 		let rows;
 		let shouldHealSession;
 		try {
-			const result = await store.append(nsId(sessionId), validated);
+			const result = await store.append(nsId(sessionId), validated, originIndex === void 0 ? void 0 : { originIndex });
 			rows = result.events;
-			shouldHealSession = result.hasPending;
+			shouldHealSession = result.hasPending && !(source === "handler" && validated.every((event) => event.settled === true));
 		} catch (err) {
 			throw asStoreUnavailable(err);
 		}
@@ -1204,113 +1549,263 @@ function createServer(options) {
 		}
 		return plans;
 	};
+	const persistSnapshots = ({ store, reducer, sessionId, snapshots }) => {
+		const persistence = Promise.resolve().then(() => telemetry.span("a2.snapshot", {
+			"a2.contract": name,
+			"a2.session_id": sessionId,
+			"a2.snapshot.reducer": reducer.name,
+			"a2.snapshot.index": snapshots.at(-1).index,
+			"a2.snapshot.count": snapshots.length
+		}, async (span) => {
+			try {
+				await store.putSnapshots(nsId(sessionId), reducer.name, snapshots);
+			} catch (error) {
+				try {
+					span.recordError(error);
+				} catch (telemetryError) {
+					throw new AggregateError([error, telemetryError], "Snapshot write and error reporting failed", { cause: telemetryError });
+				}
+			}
+		})).catch((error) => {
+			console.error("[a2] error in a2.snapshot telemetry", {
+				sessionId,
+				reducer: reducer.name,
+				index: snapshots.at(-1).index
+			}, error);
+		});
+		track(persistence);
+		platformWaitUntil(persistence);
+	};
+	const stateCache = boundedCache(STATE_CACHE);
+	const cacheState = (key, next) => {
+		const current = stateCache.get(key);
+		if (current?.reducer === next.reducer && (current.index > next.index || current.index === next.index && current.persistedIndex >= next.persistedIndex)) return;
+		stateCache.set(key, next, next.bytes);
+	};
+	const writeSnapshots = ({ store, reducer, sessionId, writes }) => {
+		const snapshots = [...writes].toSorted(([a], [b]) => a - b).map(([index, write]) => {
+			const snapshot = {
+				index,
+				state: encodeState({
+					reducer,
+					state: write.state
+				})
+			};
+			if (write.pinEventIndexes.size > 0) snapshot.pinEventIndexes = [...write.pinEventIndexes];
+			return snapshot;
+		});
+		if (snapshots.length > 0) persistSnapshots({
+			store,
+			reducer,
+			sessionId,
+			snapshots
+		});
+		return snapshots;
+	};
+	/**
+	* Folds `rows` from `position` in bound order, resolving each entry with a
+	* clone once the rows through its bound are folded. `visit` sees each
+	* entry's state before later rows are folded into it.
+	*/
+	const foldEntries = ({ reducer, entries, rows, position, state, index, clearIndex, snapshot, visit }) => {
+		const start = position;
+		const ordered = entries.toSorted((a, b) => (a.throughIndex ?? Number.POSITIVE_INFINITY) - (b.throughIndex ?? Number.POSITIVE_INFINITY));
+		for (const entry of ordered) {
+			const target = entry.throughIndex ?? Number.POSITIVE_INFINITY;
+			while (position < rows.length && rows[position].index <= target) {
+				const row = rows[position];
+				state = foldEvent(reducer, state, toPublic(row));
+				index = row.index;
+				position += 1;
+			}
+			if (entry.triggerIndex !== void 0 && entry.triggerIndex <= clearIndex || entry.throughIndex !== void 0 && entry.throughIndex > 0 && entry.throughIndex < clearIndex) {
+				entry.reject(sessionClearedError(`session '${entry.sessionId}' was cleared at index ${clearIndex}`));
+				continue;
+			}
+			entry.span.setAttribute("a2.state.snapshot", snapshot);
+			entry.span.setAttribute("a2.state.folded", position - start);
+			entry.span.setAttribute("a2.state.index", index);
+			visit(entry, state, index, position - start);
+			entry.resolve({
+				state: cloneInitial(state),
+				index,
+				...clearIndex > 0 && index >= clearIndex ? { clearIndex } : {}
+			});
+		}
+		return {
+			state,
+			index,
+			position
+		};
+	};
+	/**
+	* Events from `fromIndex` (inclusive) through `throughIndex` or the newest
+	* event, or null when the tail is too long to be worth folding in memory.
+	*/
+	const readCachedTail = async (store, sessionId, fromIndex, throughIndex) => {
+		const readTail = stateTailReaders.get(store);
+		if (readTail) try {
+			return await readTail(nsId(sessionId), fromIndex, throughIndex);
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		const limit = fromIndex + STATE_CACHE.maxTail;
+		const capped = throughIndex === void 0 || throughIndex > limit;
+		const rows = await readHistory(sessionId, {
+			gte: fromIndex,
+			lte: capped ? limit : throughIndex
+		});
+		return capped && rows.at(-1)?.index === limit ? null : rows;
+	};
+	/**
+	* Serves a plan from the cached state when every read is at or past the
+	* cached index. A read bounded at the cached index by an event whose id
+	* matches the cached one (a handler's own trigger) needs no store request;
+	* any other read fetches the tail from the cached event onward and checks
+	* that event's id. Returns false when the store must answer instead.
+	*/
+	const foldCachedPlan = async (store, reducer, plan) => {
+		const key = stateCacheKey(plan.sessionId, reducer.name);
+		const cached = stateCache.get(key);
+		if (cached?.reducer !== reducer) return false;
+		if (plan.entries.some((entry) => entry.throughIndex !== void 0 && entry.throughIndex < cached.index)) return false;
+		let rows = [];
+		if (plan.entries.some((entry) => entry.throughIndex !== cached.index || entry.throughEventId !== cached.lastId)) {
+			const tail = await readCachedTail(store, plan.sessionId, cached.index, plan.throughIndex);
+			if (!tail) return false;
+			if (tail[0]?.index !== cached.index || tail[0].id !== cached.lastId || tail.some((row, position) => position > 0 && isSessionCleared(row))) {
+				stateCache.delete(key);
+				return false;
+			}
+			rows = tail;
+		}
+		const writes = /* @__PURE__ */ new Map();
+		const folded = foldEntries({
+			reducer,
+			entries: plan.entries,
+			rows,
+			position: 1,
+			state: rows.length > 1 ? cloneInitial(cached.state) : cached.state,
+			index: cached.index,
+			clearIndex: cached.clearIndex,
+			snapshot: "memory",
+			visit: (entry, state, index) => {
+				if (entry.pinEventIndex !== void 0) addSnapshotWrite(writes, index, state, entry.pinEventIndex);
+			}
+		});
+		const added = Math.max(0, folded.position - 1);
+		const rewritesHead = folded.index - cached.persistedIndex >= STATE_CACHE.snapshotEvery;
+		if (rewritesHead && !writes.has(folded.index)) writes.set(folded.index, {
+			state: folded.state,
+			pinEventIndexes: /* @__PURE__ */ new Set()
+		});
+		const snapshots = writeSnapshots({
+			store,
+			reducer,
+			sessionId: plan.sessionId,
+			writes
+		});
+		const measure = rewritesHead || cached.unmeasured + added >= STATE_CACHE.measureEvery;
+		let grown = 0;
+		if (!measure) for (let position = 1; position < folded.position; position += 1) grown += JSON.stringify(rows[position].payload)?.length ?? 0;
+		cacheState(key, {
+			reducer,
+			index: folded.index,
+			lastId: added > 0 ? rows[folded.position - 1].id : cached.lastId,
+			state: folded.state,
+			bytes: measure ? measuredBytes(reducer, folded.state, folded.index, snapshots) : cached.bytes + grown,
+			unmeasured: measure ? 0 : cached.unmeasured + added,
+			persistedIndex: Math.max(cached.persistedIndex, snapshots.at(-1)?.index ?? 0),
+			clearIndex: cached.clearIndex
+		});
+		return true;
+	};
 	const foldStatePlan = async (store, reducer, plan, stateRead) => {
 		let state = cloneInitial(reducer.initialState);
 		let index = 0;
 		let snapshotOutcome = "miss";
 		const snap = stateRead.snapshot;
 		let rows = stateRead.events;
+		let clearIndex = stateRead.clearIndex ?? 0;
 		if (snap) {
-			if (reducer.stateSchema) {
-				const result = validateSync(reducer.stateSchema, snap.state, "the stateSchema");
+			let decoded;
+			try {
+				decoded = decodeState({
+					reducer,
+					state: snap.state
+				});
+			} catch {
+				snapshotOutcome = "rejected";
+			}
+			if (snapshotOutcome !== "rejected" && reducer.stateSchema) {
+				const result = validateSync(reducer.stateSchema, decoded, "the stateSchema");
 				if (result.issues) snapshotOutcome = "rejected";
 				else {
 					state = result.value;
 					index = snap.index;
 					snapshotOutcome = "hit";
 				}
-			} else {
-				state = snap.state;
+			} else if (snapshotOutcome !== "rejected") {
+				state = decoded;
 				index = snap.index;
 				snapshotOutcome = "hit";
 			}
 		}
-		if (snapshotOutcome === "rejected") try {
-			rows = await store.read(nsId(plan.sessionId), plan.throughIndex === void 0 ? void 0 : { throughIndex: plan.throughIndex });
-		} catch (err) {
-			throw asStoreUnavailable(err);
-		}
-		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);
+		if (snapshotOutcome === "rejected") {
+			try {
+				rows = await store.read(nsId(plan.sessionId), plan.throughIndex === void 0 ? void 0 : { throughIndex: plan.throughIndex });
+			} catch (err) {
+				throw asStoreUnavailable(err);
 			}
-			entry.resolve({
-				state: resultState,
-				index
-			});
+			if (rows[0] && isSessionCleared(rows[0])) clearIndex = Math.max(clearIndex, rows[0].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 writes = /* @__PURE__ */ new Map();
+		const folded = foldEntries({
+			reducer,
+			entries: plan.entries,
+			rows,
+			position: 0,
+			state,
+			index,
+			clearIndex,
+			snapshot: snapshotOutcome,
+			visit: (entry, entryState, entryIndex, count) => {
+				if (entryIndex === 0) return;
+				if (count === 0 && entry.pinEventIndex === void 0) return;
+				const advancesHead = stateRead.headIndex === null || entryIndex > stateRead.headIndex;
+				const repairsHead = snapshotOutcome === "rejected" && entryIndex === stateRead.headIndex;
+				if (!advancesHead && !repairsHead && entry.pinEventIndex === void 0) return;
+				addSnapshotWrite(writes, entryIndex, entryState, entry.pinEventIndex);
 			}
-			const persistence = Promise.resolve().then(() => telemetry.span("a2.snapshot", {
-				"a2.contract": name,
-				"a2.session_id": plan.sessionId,
-				"a2.snapshot.reducer": reducer.name,
-				"a2.snapshot.index": snapshots.at(-1).index,
-				"a2.snapshot.count": snapshots.length
-			}, async (span) => {
-				try {
-					await store.putSnapshots(nsId(plan.sessionId), reducer.name, snapshots);
-				} catch (error) {
-					try {
-						span.recordError(error);
-					} catch (telemetryError) {
-						throw new AggregateError([error, telemetryError], "Snapshot write and error reporting failed", { cause: telemetryError });
-					}
-				}
-			})).catch((error) => {
-				console.error("[a2] error in a2.snapshot telemetry", {
-					sessionId: plan.sessionId,
-					reducer: reducer.name,
-					index: snapshots.at(-1).index
-				}, error);
-			});
-			track(persistence);
-			platformWaitUntil(persistence);
-		}
+		});
+		const snapshots = writeSnapshots({
+			store,
+			reducer,
+			sessionId: plan.sessionId,
+			writes
+		});
+		if (folded.position > 0 && STATE_CACHE.maxEntries > 0) cacheState(stateCacheKey(plan.sessionId, reducer.name), {
+			reducer,
+			index: folded.index,
+			lastId: rows[folded.position - 1].id,
+			state: folded.state,
+			bytes: measuredBytes(reducer, folded.state, folded.index, snapshots),
+			unmeasured: 0,
+			persistedIndex: Math.min(Math.max(stateRead.headIndex ?? 0, ...writes.keys()), folded.index),
+			clearIndex
+		});
 	};
 	const pendingStateReads = /* @__PURE__ */ new Map();
 	const flushStateReads = async (store, reducer, batch) => {
-		const plans = planStateReads(batch);
+		const plans = [];
+		await Promise.all(planStateReads(batch).map(async (plan) => {
+			try {
+				if (!await foldCachedPlan(store, reducer, plan)) plans.push(plan);
+			} catch (error) {
+				for (const entry of plan.entries) entry.reject(error);
+			}
+		}));
+		if (plans.length === 0) return;
 		let reads;
 		try {
 			reads = store.readStates ? await store.readStates(plans.map((plan) => ({
@@ -1321,7 +1816,7 @@ function createServer(options) {
 			if (reads.length !== plans.length) throw new TypeError("store.readStates must return one result per request");
 		} catch (error) {
 			const failure = asStoreUnavailable(error);
-			for (const entry of batch) entry.reject(failure);
+			for (const plan of plans) for (const entry of plan.entries) entry.reject(failure);
 			return;
 		}
 		await Promise.all(plans.map(async (plan, position) => {
@@ -1332,7 +1827,7 @@ function createServer(options) {
 			}
 		}));
 	};
-	const enqueueStateRead = (store, sessionId, reducer, throughIndex, pinEventIndex, span) => new Promise((resolve, reject) => {
+	const enqueueStateRead = (store, sessionId, reducer, bounds, span) => new Promise((resolve, reject) => {
 		const reducerName = reducer.name;
 		let batch = pendingStateReads.get(reducerName);
 		if (!batch) {
@@ -1346,25 +1841,25 @@ function createServer(options) {
 		}
 		batch.push({
 			sessionId,
-			...throughIndex === void 0 ? {} : { throughIndex },
-			...pinEventIndex === void 0 ? {} : { pinEventIndex },
+			...bounds,
 			span,
 			resolve,
 			reject
 		});
 	});
-	const readState = async (sessionId, reducer, throughIndex, pinEventIndex) => {
+	const readState = async (sessionId, reducer, bounds) => {
 		const store = await resolveStore();
 		return telemetry.span("a2.state", {
 			"a2.contract": name,
 			"a2.session_id": sessionId,
 			"a2.state.reducer": reducer.name
-		}, (span) => enqueueStateRead(store, sessionId, reducer, throughIndex, pinEventIndex, span));
+		}, (span) => enqueueStateRead(store, sessionId, reducer, bounds, span));
 	};
 	const makeSchedule = (sessionId, trigger) => {
 		const triggerEventId = trigger?.id ?? null;
 		const triggerCreatedAt = trigger?.createdAt.getTime();
-		return async (scheduleName, timing, ...events) => {
+		const clearIndex = trigger?.clearIndex ?? 0;
+		const schedule = async (scheduleName, timing, ...events) => {
 			if (!scheduler) throw new TypeError("session.schedule requires a configured scheduler adapter");
 			assertScheduleName(scheduleName);
 			if (events.length === 0) throw new TypeError("schedule requires at least one event");
@@ -1379,7 +1874,7 @@ function createServer(options) {
 				id: event.id
 			});
 			const validated = validateEvents(sessionId, structuredClone(snapshottedEvents), false);
-			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName);
+			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName, clearIndex);
 			const scheduledEvents = await Promise.all(validated.map(async (event, item) => ({
 				id: event.id ?? await deterministicScheduledEventId(scheduleId, item),
 				type: event.type,
@@ -1394,12 +1889,45 @@ function createServer(options) {
 					contract: name,
 					sessionId,
 					dueAt,
-					events: scheduledEvents
+					events: scheduledEvents,
+					...trigger ? { originIndex: trigger.index } : {}
 				});
 			} catch (error) {
 				throw markSchedulerSendFailure(error);
 			}
 		};
+		const clear = async (scheduleName, clearOptions) => {
+			if (!scheduler) throw new TypeError("session.schedule.clear requires a configured scheduler adapter");
+			assertScheduleName(scheduleName);
+			if (clearOptions === null || typeof clearOptions !== "object") throw new TypeError("schedule.clear requires an ifLastIndex");
+			const { ifLastIndex, ...timing } = clearOptions;
+			assertClearIndex(ifLastIndex);
+			const dueAt = scheduleDueAt(timing, triggerCreatedAt ?? Date.now());
+			const store = await resolveStore();
+			if (!store.clear || !store.reclaim) throw new TypeError("session.schedule.clear requires a store that supports clearing");
+			const id = await deterministicScheduleClearId({
+				contract: name,
+				sessionId,
+				triggerEventId,
+				clearIndex,
+				name: scheduleName,
+				ifLastIndex
+			});
+			try {
+				await scheduler.schedule({
+					version: 1,
+					kind: "clear",
+					id,
+					contract: name,
+					sessionId,
+					dueAt,
+					ifLastIndex
+				});
+			} catch (error) {
+				throw markSchedulerSendFailure(error);
+			}
+		};
+		return Object.assign(schedule, { clear });
 	};
 	const toSessionEvent = (id, event) => ({
 		id: event.id,
@@ -1459,6 +1987,13 @@ function createServer(options) {
 				}
 			};
 			streamActivities.set(stream, activity);
+			bufferedEvents.set(stream, () => {
+				const event = closed || !inner ? void 0 : takeBuffered(inner);
+				if (!event) return void 0;
+				if (!isSerializedEvent(event)) return toSessionEvent(id, event);
+				event.sessionId = id;
+				return event;
+			});
 			return stream;
 		} };
 	};
@@ -1514,6 +2049,7 @@ function createServer(options) {
 		const ns = nsId(id);
 		let closed = false;
 		let events;
+		let pendingEvent = null;
 		let unsubscribe;
 		let sleeper = null;
 		let wakeQueue = null;
@@ -1655,7 +2191,6 @@ function createServer(options) {
 				}
 				return null;
 			};
-			let pendingEvent = null;
 			try {
 				unsubscribe = api.subscribe?.(ns, enqueue);
 				events = store.stream(ns, { startAfter })[Symbol.asyncIterator]();
@@ -1745,18 +2280,86 @@ function createServer(options) {
 				}
 			};
 			streamActivities.set(stream, activity);
+			bufferedEvents.set(stream, () => {
+				if (closed || !events || pendingEvent) return void 0;
+				const event = takeBuffered(events);
+				if (!event) return void 0;
+				if (!isSerializedEvent(event)) return toSessionEvent(id, event);
+				event.sessionId = id;
+				return event;
+			});
 			return stream;
 		} };
 	};
-	const makeSession = (id, append, trigger) => ({
+	const reclaimAll = async (store, ns) => {
+		for (let stalls = 0;;) {
+			let batch;
+			try {
+				batch = await store.reclaim(ns);
+			} catch (err) {
+				throw asStoreUnavailable(err);
+			}
+			if (batch.done) return;
+			if (batch.deleted > 0) {
+				stalls = 0;
+				continue;
+			}
+			stalls += 1;
+			if (stalls === RECLAIM_STALL_LIMIT) throw new A2Error("STORE_UNAVAILABLE", `deleting the cleared history of session '${stripNs(ns)}' made no progress`);
+			await defaultSleep(RECLAIM_STALL_MS).promise;
+		}
+	};
+	const clearSession = async (sessionId, clearOptions, attempt) => {
+		const ifLastIndex = clearOptions?.ifLastIndex;
+		if (ifLastIndex !== void 0) assertClearIndex(ifLastIndex);
+		const store = await resolveStore();
+		if (!store.clear || !store.reclaim) throw new TypeError("session.clear requires a store that supports clearing");
+		const ns = nsId(sessionId);
+		let result;
+		try {
+			result = await store.clear({
+				sessionId: ns,
+				...ifLastIndex === void 0 ? {} : { ifLastIndex },
+				...attempt ? { cause: attempt.cause } : {}
+			});
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		if (result.cleared) {
+			const cachePrefix = stateCacheKey(sessionId, "");
+			stateCache.deleteWhere((key) => key.startsWith(cachePrefix));
+		}
+		const deletion = reclaimAll(store, ns);
+		if (attempt) {
+			if (attempt.cause.index <= result.clearIndex) attempt.end();
+			const kept = deletion.catch(() => void 0);
+			track(kept);
+			platformWaitUntil(kept);
+		}
+		await deletion;
+		return {
+			cleared: result.cleared,
+			index: result.index
+		};
+	};
+	const makeSession = (id, append, trigger, attempt) => ({
 		id,
 		append,
 		schedule: makeSchedule(id, trigger),
-		history: async (bounds) => (await readHistory(id, bounds)).map(toPublic),
-		state: (reducer, stateOptions) => {
+		clear: (clearOptions) => clearSession(id, clearOptions, attempt),
+		history: async (bounds) => (await readHistory(id, bounds)).filter((row) => !isSessionCleared(row)).map(toPublic),
+		state: (reducer = serverContract.reducer, stateOptions) => {
+			if (!reducer) throw new A2Error("INVALID_PAYLOAD", "contract has no public reducer");
 			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);
+			const bounds = {};
+			if (through !== void 0 && through !== "latest") {
+				bounds.throughIndex = through;
+				if (trigger) bounds.pinEventIndex = trigger.index;
+				if (through === trigger?.index && !attempt?.signal.aborted) bounds.throughEventId = trigger.id;
+			}
+			if (trigger) bounds.triggerIndex = trigger.index;
+			return readState(id, reducer, bounds);
 		},
 		stream: (opts) => {
 			const startAfter = opts?.startAfter ?? 0;
@@ -1768,7 +2371,7 @@ function createServer(options) {
 			presence: () => readPresenceMap(id)
 		} : {}
 	});
-	const makeCtx = (trigger, attempt, signal) => {
+	const makeCtx = (trigger, attempt, signal, endAttempt) => {
 		const publicSessionId = stripNs(trigger.sessionId);
 		const append = async (appendName, ...events) => {
 			assertAppendName(appendName);
@@ -1789,7 +2392,14 @@ function createServer(options) {
 		return {
 			event: toPublic(trigger),
 			attempt,
-			session: makeSession(publicSessionId, append, trigger),
+			session: makeSession(publicSessionId, append, trigger, {
+				cause: {
+					index: trigger.index,
+					attempt
+				},
+				end: endAttempt,
+				signal
+			}),
 			signal
 		};
 	};
@@ -1988,12 +2598,7 @@ function createServer(options) {
 				for (const index of result.superseded) {
 					const entry = active.get(index);
 					if (!entry) continue;
-					entry.supersede.abort(new A2Error("SUPERSEDED_ATTEMPT", `a newer attempt owns event ${index} in session '${sessionId}'`));
-					entry.fence({
-						status: "superseded",
-						opensLane: false,
-						appendsEvents: false
-					});
+					endSuperseded(entry, `a newer attempt owns event ${index} in session '${sessionId}'`);
 				}
 				if (window.deadlineCapped) stopRenewing = true;
 				scheduleLapse();
@@ -2007,7 +2612,7 @@ function createServer(options) {
 			renewal = tracked;
 			return tracked;
 		};
-		const runEvent = async (event, supersedeSignal) => {
+		const runEvent = async (event, supersedeSignal, endAttempt) => {
 			const registration = handlers.get(event.type);
 			return telemetry.span("a2.event", {
 				"a2.contract": name,
@@ -2027,7 +2632,7 @@ function createServer(options) {
 						subscription = await subscribeAbort(store, ns, event, registration.abortOn, event.attemptCount);
 						handlerSignal = AbortSignal.any([supersedeSignal, subscription.signal]);
 					}
-					const operation = registration?.handler(makeCtx(event, event.attemptCount, handlerSignal));
+					const operation = registration?.handler(makeCtx(event, event.attemptCount, handlerSignal, endAttempt));
 					const result = operation ? await (subscription ? subscription.monitor(operation) : operation) : void 0;
 					if (subscription) {
 						await subscription.close();
@@ -2044,12 +2649,22 @@ function createServer(options) {
 						};
 					}
 					eventSpan.recordError(err);
-					const failure = await store.failAttempt({
-						sessionId: ns,
-						index: event.index,
-						attempt: event.attemptCount,
-						error: describeError(err),
-						maxFailures: err instanceof NonRetriableError ? 1 : MAX_FAILURES
+					const failure = await telemetry.span("a2.commit", {
+						"a2.contract": name,
+						"a2.session_id": sessionId,
+						"a2.commit.operation": "fail",
+						"a2.commit.index": event.index,
+						"a2.commit.attempt": event.attemptCount
+					}, async (commitSpan) => {
+						const result = await store.failAttempt({
+							sessionId: ns,
+							index: event.index,
+							attempt: event.attemptCount,
+							error: describeError(err),
+							maxFailures: err instanceof NonRetriableError ? 1 : MAX_FAILURES
+						});
+						commitSpan.setAttribute("a2.commit.outcome", result.outcome);
+						return result;
 					});
 					eventSpan.setAttribute("a2.event.outcome", failure.outcome);
 					return {
@@ -2061,11 +2676,21 @@ function createServer(options) {
 					await subscription?.close();
 				}
 				await renewal;
-				const completion = await store.completeAttempt({
-					sessionId: ns,
-					index: event.index,
-					attempt: event.attemptCount,
-					events: returned
+				const completion = await telemetry.span("a2.commit", {
+					"a2.contract": name,
+					"a2.session_id": sessionId,
+					"a2.commit.operation": "complete",
+					"a2.commit.index": event.index,
+					"a2.commit.attempt": event.attemptCount
+				}, async (commitSpan) => {
+					const result = await store.completeAttempt({
+						sessionId: ns,
+						index: event.index,
+						attempt: event.attemptCount,
+						events: returned
+					});
+					commitSpan.setAttribute("a2.commit.outcome", result.outcome);
+					return result;
 				});
 				eventSpan.setAttribute("a2.event.outcome", completion.outcome === "completed" ? "processed" : completion.outcome);
 				if (completion.outcome === "superseded") return {
@@ -2084,21 +2709,18 @@ function createServer(options) {
 		let claimAgain = false;
 		const start = (event, expiresAtMs) => {
 			const previous = active.get(event.index);
-			if (previous) {
-				previous.supersede.abort(new A2Error("SUPERSEDED_ATTEMPT", `a newer attempt owns event ${event.index} in session '${sessionId}'`));
-				previous.fence({
-					status: "superseded",
-					opensLane: false,
-					appendsEvents: false
-				});
-			}
+			if (previous) endSuperseded(previous, `a newer attempt owns event ${event.index} in session '${sessionId}'`);
 			const supersede = new AbortController();
 			let fence;
 			const fenced = new Promise((resolve) => {
 				fence = resolve;
 			});
+			const endAttempt = () => endSuperseded({
+				supersede,
+				fence
+			}, `event ${event.index} in session '${sessionId}' was cleared`);
 			let entry;
-			const execution = Promise.race([runEvent(event, supersede.signal), fenced]).then((eventOutcome) => {
+			const execution = Promise.race([runEvent(event, supersede.signal, endAttempt), fenced]).then((eventOutcome) => {
 				if (active.get(event.index) === entry) active.delete(event.index);
 				if (eventOutcome.status === "processed") processed += 1;
 				if (eventOutcome.status === "failed") {
@@ -2131,12 +2753,20 @@ function createServer(options) {
 				let claim;
 				if (shouldClaim) {
 					const window = nextClaimWindow();
-					claim = await store.claimAvailable({
-						sessionId: ns,
-						holder,
-						ttlMs: window.ttlMs,
-						...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
-						...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
+					claim = await telemetry.span("a2.claim", {
+						"a2.contract": name,
+						"a2.session_id": sessionId
+					}, async (claimSpan) => {
+						const result = await store.claimAvailable({
+							sessionId: ns,
+							holder,
+							ttlMs: window.ttlMs,
+							...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
+							...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
+						});
+						claimSpan.setAttribute("a2.claim.outcome", result.outcome);
+						claimSpan.setAttribute("a2.claim.count", result.outcome === "claimed" ? result.events.length : 0);
+						return result;
 					});
 					if (claim.outcome === "claimed") {
 						requestWatchdog(window.watchdogAtMs);
@@ -2195,8 +2825,8 @@ function createServer(options) {
 			...schedulerArm ? { schedulerArm } : {}
 		};
 	});
-	const appendExternal = async (sessionId, mode, events, requireDurableInitialArm = false) => {
-		return appendCore(sessionId, events, "external", mode, (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt), void 0, void 0, requireDurableInitialArm);
+	const appendExternal = async (sessionId, mode, events, requireDurableInitialArm = false, originIndex) => {
+		return appendCore(sessionId, events, "external", mode, (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt), void 0, void 0, requireDurableInitialArm, originIndex);
 	};
 	const session = (id) => {
 		assertSessionId(id);
@@ -2205,11 +2835,21 @@ function createServer(options) {
 		const append = Object.assign(appendInline, { dispatch: appendDispatch });
 		return makeSession(id, append, null);
 	};
+	const historyPage = async (sessionId, bounds) => {
+		assertSessionId(sessionId);
+		const rows = await readHistory(sessionId, bounds);
+		const marker = rows[0] && isSessionCleared(rows[0]) ? rows[0] : void 0;
+		return {
+			events: (marker ? rows.slice(1) : rows).map(toPublic),
+			...marker ? { clearIndex: marker.index } : {}
+		};
+	};
 	const self = {
 		contract: serverContract,
 		fetch: createServerFetch({
 			contract: serverContract,
-			session
+			session,
+			historyPage
 		}),
 		session,
 		async drain(sessionId) {
@@ -2226,10 +2866,21 @@ function createServer(options) {
 			assertSessionId(sessionId);
 			return drainSession(sessionId, opts?.watchdogDueAt);
 		},
-		schedulerAppend: async (sessionId, events) => {
+		schedulerAppend: async (sessionId, events, originIndex) => {
 			if (!scheduler) throw new TypeError("scheduled append delivery requires a configured scheduler adapter");
 			assertSessionId(sessionId);
-			await appendExternal(sessionId, "inline", [...events], true);
+			try {
+				await appendExternal(sessionId, "inline", [...events], true, originIndex);
+			} catch (error) {
+				if (originIndex !== void 0 && error instanceof A2Error && error.code === "SESSION_CLEARED") return;
+				throw error;
+			}
+		},
+		historyWithMarkers: async (sessionId, gte) => (await readHistory(sessionId, { gte })).map(toPublic),
+		schedulerClear: async (sessionId, ifLastIndex) => {
+			assertSessionId(sessionId);
+			assertClearIndex(ifLastIndex);
+			await clearSession(sessionId, { ifLastIndex }, void 0);
 		}
 	});
 	return self;
@@ -2247,6 +2898,9 @@ function assertStreamIndex(value) {
 function assertStateIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("state.through must be a non-negative safe integer");
 }
+function assertClearIndex(value) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("ifLastIndex 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");
 }
@@ -2328,14 +2982,12 @@ function isJsonValue(value, ancestors) {
 		ancestors.delete(value);
 	}
 }
-function cloneInitial(initial) {
-	try {
-		return structuredClone(initial);
-	} catch {
-		return initial;
-	}
-}
+const measuredBytes = (reducer, state, index, snapshots) => JSON.stringify(snapshots.find((snapshot) => snapshot.index === index)?.state ?? encodeState({
+	reducer,
+	state
+}))?.length ?? 0;
+const stateCacheKey = (sessionId, reducerName) => `${sessionId}\u0000${reducerName}`;
 //#endregion
-export { sseResponse as a, setServerFetchHooks as i, deliverSchedulerAppend as n, parsePresenceSibling as o, handler as r, createServer as t };
+export { CONSOLE_TELEMETRY as a, parsePresenceSibling as c, handler as i, boundedCache as l, deliverSchedulerAppend as n, setServerFetchHooks as o, deliverSchedulerClear as r, sseResponse as s, createServer as t };
 
-//# sourceMappingURL=server-BD5ckxZb.js.map
+//# sourceMappingURL=server-Rj64fNvX.js.map