experimental-a2 0.0.0

package/dist/server-DYsnKTTy.js

@@ -0,0 +1,780 @@
+import { n as validateSync } from "./validate-XKT4FSNn.js";
+import { n as asLogUnavailable, t as A2Error } from "./errors-BJRMd-h6.js";
+import { i as serverInternals, t as DRAIN_TIMINGS } from "./internal-Dm8Ejnud.js";
+import { n as serverInspection } from "./inspection-E7qbD0Xj.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+//#region src/deterministic-id.ts
+/**
+* Deterministic default ids for `ctx.append` (specs/a2-implementation.md
+* §5). A handler re-run after a crash calls `ctx.append` again; giving
+* each call a deterministic id — derived from the triggering event's id
+* and the call's position — makes the re-run a no-op via the log's
+* unique index on event ids.
+*
+* The id is a UUIDv5-shaped SHA-1 over
+* `(namespace, triggerEventId, callOrdinal, itemOrdinal)`, computed with
+* WebCrypto so it runs on any platform a2 core targets.
+*/
+const NAMESPACE = "a2:ctx-append:v1";
+async function deterministicEventId(triggerEventId, callOrdinal, itemOrdinal) {
+	const input = [
+		NAMESPACE,
+		triggerEventId,
+		callOrdinal,
+		itemOrdinal
+	].join("\0");
+	const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(input));
+	const bytes = new Uint8Array(digest).slice(0, 16);
+	bytes[6] = (bytes[6] ?? 0) & 15 | 80;
+	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+//#endregion
+//#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 {};
+	}
+}
+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/telemetry.ts
+const NOOP_HANDLE = {
+	setAttribute: () => {},
+	recordError: () => {}
+};
+/** The zero-cost default when no telemetry is configured. */
+const NOOP_TELEMETRY = { span: (_name, _attributes, fn) => fn(NOOP_HANDLE) };
+//#endregion
+//#region src/server.ts
+const MAX_FAILURES = 10;
+/**
+* Deadlines tighten the lease/watchdog window; they never decide whether a
+* handler starts. A platform timeout therefore follows the same path as any
+* other process death: the in-flight event remains pending and is retried.
+*/
+function nextLeaseWindow() {
+	const nowMs = Date.now();
+	const deadlineMs = invocationDeadlineMs();
+	const deadlineTtlMs = deadlineMs === null ? DRAIN_TIMINGS.leaseTtlMs : deadlineMs - nowMs;
+	const deadlineCapped = deadlineMs !== null && deadlineTtlMs <= DRAIN_TIMINGS.leaseTtlMs;
+	const ttlMs = Math.max(1, Math.min(DRAIN_TIMINGS.leaseTtlMs, deadlineTtlMs));
+	const expiresAtMs = nowMs + ttlMs;
+	return {
+		ttlMs,
+		expiresAtMs,
+		recoveryAtMs: expiresAtMs + DRAIN_TIMINGS.recoveryGraceMs,
+		deadlineCapped
+	};
+}
+function recoverySlot(dueAt) {
+	return Math.ceil(dueAt / 1e3) * 1e3;
+}
+/**
+* The namespace separator between machine name and session id in
+* storage. Machines sharing one log backend (the dev-default sqlite
+* file, a shared Postgres) must not collide on session ids; the machine
+* name is what makes multi-machine apps unambiguous (a2-api.md §1), so
+* it prefixes every storage key.
+*/
+const NS = "";
+const devDefaultLog = retryableLazy(() => import("./log-sqlite.js").then((m) => m.sqlite()));
+function environment() {
+	const env = typeof process === "undefined" ? void 0 : process.env?.["NODE_ENV"];
+	if (env === "test") return "test";
+	if (env === "production") return "production";
+	return "development";
+}
+function describeError(err) {
+	if (err instanceof Error) return err.stack ?? `${err.name}: ${err.message}`;
+	return String(err);
+}
+/** Implement a contract: bind its vocabulary to storage and reactions. */
+function createServer(options) {
+	const serverContract = options?.contract;
+	if (serverContract === null || typeof serverContract !== "object" || typeof serverContract.name !== "string" || serverContract.events === null) throw new TypeError("createServer expects options with a contract (see a2.contract)");
+	const name = serverContract.name;
+	const defs = serverContract.events;
+	let makeLog;
+	if (options.log) {
+		const explicit = options.log;
+		makeLog = () => Promise.resolve(explicit);
+	} else {
+		const env = environment();
+		if (env === "production") {
+			const error = () => new A2Error("LOG_NOT_CONFIGURED", `the server for '${name}' has no log configured and NODE_ENV is 'production' — pass an explicit log backend (e.g. postgres from 'a2/log-postgres')`);
+			if (process.env["NEXT_PHASE"] !== "phase-production-build") throw error();
+			makeLog = () => Promise.reject(error());
+		} else makeLog = env === "test" ? () => import("./log-memory.js").then((m) => m.memory()) : devDefaultLog.get;
+	}
+	const resolveLog = retryableLazy(makeLog).get;
+	const telemetry = options.telemetry ?? NOOP_TELEMETRY;
+	const recovery = options.recovery;
+	const handlers = /* @__PURE__ */ new Map();
+	for (const [type, entry] of Object.entries(options.handlers ?? {})) {
+		if (entry === void 0) continue;
+		if (!Object.hasOwn(defs, type)) throw new TypeError(`contract '${name}' has no event type '${type}' — cannot register a handler for it`);
+		const handler = typeof entry === "function" ? entry : entry?.handler;
+		if (typeof handler !== "function") throw new TypeError(`handler for '${type}' must be a function`);
+		let abortOn = null;
+		const spec = typeof entry === "function" ? void 0 : entry.abortOn;
+		if (spec !== void 0) {
+			abortOn = /* @__PURE__ */ new Map();
+			const pairs = Array.isArray(spec) ? spec.map((abortType) => [abortType, true]) : Object.entries(spec);
+			for (const [abortType, matcher] of pairs) {
+				if (matcher === void 0) continue;
+				if (!Object.hasOwn(defs, abortType)) throw new TypeError(`contract '${name}' has no event type '${String(abortType)}' — cannot abort on it`);
+				abortOn.set(String(abortType), matcher);
+			}
+			if (abortOn.size === 0) abortOn = null;
+		}
+		handlers.set(type, {
+			handler,
+			abortOn
+		});
+	}
+	const dormantSignal = new AbortController().signal;
+	const prefix = `${name}${NS}`;
+	const nsId = (sessionId) => `${prefix}${sessionId}`;
+	const stripNs = (stored) => stored.slice(prefix.length);
+	const toPublic = (row) => ({
+		id: row.id,
+		type: row.type,
+		payload: row.payload,
+		index: row.index,
+		sessionId: stripNs(row.sessionId),
+		createdAt: row.createdAt
+	});
+	const inFlight = /* @__PURE__ */ new Set();
+	const track = (p) => {
+		inFlight.add(p);
+		const drop = () => {
+			inFlight.delete(p);
+		};
+		p.then(drop, drop);
+	};
+	const recoveryArmSlots = /* @__PURE__ */ new Map();
+	/**
+	* Start an optional recovery arm without putting it on the execution path.
+	* The returned raw promise lets the initial append report failure; the
+	* tracked copy is always rejection-safe for heartbeat callers.
+	*/
+	const startRecoveryArm = (sessionId, dueAt) => {
+		if (!recovery) return null;
+		const slottedDueAt = recoverySlot(dueAt);
+		const slotKey = JSON.stringify([sessionId, slottedDueAt]);
+		const existing = recoveryArmSlots.get(slotKey);
+		if (existing) return existing.promise;
+		const raw = Promise.resolve().then(() => recovery.arm({
+			contract: name,
+			sessionId,
+			dueAt: slottedDueAt
+		}));
+		const forget = setTimeout(() => {
+			if (recoveryArmSlots.get(slotKey)?.promise === raw) recoveryArmSlots.delete(slotKey);
+		}, Math.max(0, slottedDueAt - Date.now()) + 1e3);
+		forget.unref?.();
+		recoveryArmSlots.set(slotKey, {
+			promise: raw,
+			forget
+		});
+		raw.then(void 0, () => {
+			const current = recoveryArmSlots.get(slotKey);
+			if (current?.promise !== raw) return;
+			clearTimeout(current.forget);
+			recoveryArmSlots.delete(slotKey);
+		});
+		const safe = raw.catch(() => {});
+		track(safe);
+		platformWaitUntil(safe);
+		return raw;
+	};
+	/**
+	* Schedule the fire-and-forget inline drain for an append. The drain
+	* is tree-scoped: it owns the append's causal tree — everything up to
+	* `frontier` (which ordering forces it through anyway) plus whatever
+	* its handlers append — and stops there. Later events from other
+	* callers belong to those callers' drains.
+	*/
+	const scheduleDrain = (sessionId, frontier, recoveryDueAt) => {
+		const p = drainSession(sessionId, {
+			full: false,
+			frontier
+		}, recoveryDueAt).catch(() => {});
+		track(p);
+		platformWaitUntil(p);
+	};
+	const inProcessHolds = /* @__PURE__ */ new Map();
+	const inProcessWaiters = /* @__PURE__ */ new Map();
+	const acquireSlot = async (ns, opts) => {
+		if (!opts.wait && inProcessHolds.has(ns)) return null;
+		for (;;) {
+			const current = inProcessHolds.get(ns);
+			if (!current) break;
+			inProcessWaiters.set(ns, (inProcessWaiters.get(ns) ?? 0) + 1);
+			try {
+				await current;
+			} finally {
+				const waiting = (inProcessWaiters.get(ns) ?? 1) - 1;
+				if (waiting === 0) inProcessWaiters.delete(ns);
+				else inProcessWaiters.set(ns, waiting);
+			}
+		}
+		let release;
+		const done = new Promise((resolve) => {
+			release = resolve;
+		});
+		inProcessHolds.set(ns, done);
+		return () => {
+			if (inProcessHolds.get(ns) === done) inProcessHolds.delete(ns);
+			release();
+		};
+	};
+	const hasInProcessActivity = (ns) => inProcessHolds.has(ns) || (inProcessWaiters.get(ns) ?? 0) > 0;
+	const validateEvents = (events) => {
+		if (events.length === 0) throw new TypeError("append requires at least one event");
+		return events.map((e) => {
+			const schema = Object.hasOwn(defs, e.type) ? defs[e.type] : void 0;
+			if (!schema) throw new A2Error("UNKNOWN_EVENT_TYPE", `contract '${name}' has no event type '${String(e.type)}'`);
+			const result = validateSync(schema, e.payload, `event '${e.type}'`);
+			if (result.issues) throw new A2Error("INVALID_PAYLOAD", `invalid payload for event '${e.type}' on machine '${name}'`, { details: result.issues });
+			const validated = {
+				type: e.type,
+				payload: result.value
+			};
+			if (e.id !== void 0) validated.id = e.id;
+			return validated;
+		});
+	};
+	/**
+	* Validate + write. `onAppended` runs inside the telemetry span, so
+	* the drain it schedules is created in the append's active context —
+	* with a real tracer, the whole causal tree lands in one trace.
+	*/
+	const appendCore = (sessionId, events, source, onAppended, cause) => telemetry.span("a2.append", {
+		"a2.contract": name,
+		"a2.session_id": sessionId,
+		"a2.append.source": source,
+		"a2.append.types": events.map((e) => String(e.type)).join(","),
+		"a2.append.count": events.length
+	}, async (span) => {
+		assertSessionId(sessionId);
+		const validated = validateEvents(events);
+		if (cause) for (const event of validated) event.cause = cause;
+		const log = await resolveLog();
+		let rows;
+		try {
+			rows = await log.append(nsId(sessionId), validated);
+		} catch (err) {
+			throw asLogUnavailable(err);
+		}
+		const appended = rows.map(toPublic);
+		const initialRecoveryAt = recovery && source === "external" ? recoverySlot(nextLeaseWindow().recoveryAtMs) : void 0;
+		const initialArm = initialRecoveryAt !== void 0 ? startRecoveryArm(sessionId, initialRecoveryAt) : null;
+		onAppended(appended, initialRecoveryAt);
+		if (initialArm) {
+			let timeout = null;
+			try {
+				await Promise.race([initialArm, new Promise((_, reject) => {
+					timeout = setTimeout(() => {
+						reject(/* @__PURE__ */ new Error(`a2 recovery arm timed out after ${DRAIN_TIMINGS.recoveryArmTimeoutMs}ms`));
+					}, DRAIN_TIMINGS.recoveryArmTimeoutMs);
+				})]);
+			} catch (err) {
+				span.setAttribute("a2.append.armed", false);
+				span.recordError(err);
+			} finally {
+				if (timeout) clearTimeout(timeout);
+			}
+		}
+		return appended;
+	});
+	const readAll = async (sessionId) => {
+		const log = await resolveLog();
+		try {
+			return await log.read(nsId(sessionId));
+		} catch (err) {
+			throw asLogUnavailable(err);
+		}
+	};
+	const makeCtx = (trigger, attempt, onCtxAppend, signal) => {
+		let callOrdinal = 0;
+		const publicSessionId = stripNs(trigger.sessionId);
+		return {
+			event: toPublic(trigger),
+			attempt,
+			append: async (...events) => {
+				const call = callOrdinal++;
+				const withIds = await Promise.all(events.map(async (e, item) => {
+					if (e.id !== void 0) return e;
+					const id = await deterministicEventId(trigger.id, call, item);
+					return {
+						...e,
+						id
+					};
+				}));
+				return appendCore(publicSessionId, withIds, "handler", (rows) => {
+					const maxIndex = rows.at(-1)?.index ?? 0;
+					if (!onCtxAppend(maxIndex)) scheduleDrain(publicSessionId, maxIndex);
+				}, {
+					index: trigger.index,
+					attempt
+				});
+			},
+			history: async () => (await readAll(publicSessionId)).map(toPublic),
+			signal
+		};
+	};
+	/**
+	* Run a handler registered with `abortOn` (a2-api.md §7): before
+	* invoking, check events already appended past the trigger (the
+	* abort-landed-before-we-started case); then hold a live subscription
+	* for the handler's duration and fire the signal on a match. Closed
+	* when the handler settles. Handlers without `abortOn` never get
+	* here — no subscription, zero cost.
+	*/
+	const runAbortable = async (log, ns, trigger, attempt, registration, onCtxAppend) => {
+		const controller = new AbortController();
+		const publicTrigger = toPublic(trigger);
+		const matches = (event) => {
+			const matcher = registration.abortOn.get(event.type);
+			if (matcher === void 0) return false;
+			if (matcher === true) return true;
+			return matcher(toPublic(event), publicTrigger);
+		};
+		const already = await log.read(ns, { afterIndex: trigger.index });
+		if (already.some((e) => matches(e))) controller.abort();
+		let watcher = null;
+		let watch = null;
+		if (!controller.signal.aborted) {
+			const tail = already.at(-1)?.index ?? trigger.index;
+			watcher = log.stream(ns, { startAt: tail })[Symbol.asyncIterator]();
+			const iterator = watcher;
+			watch = (async () => {
+				for (;;) {
+					const { value, done } = await iterator.next();
+					if (done || value === void 0) return;
+					if (matches(value)) {
+						controller.abort();
+						return;
+					}
+				}
+			})().catch(() => {});
+		}
+		try {
+			await registration.handler(makeCtx(trigger, attempt, onCtxAppend, controller.signal));
+		} finally {
+			await watcher?.return?.();
+			await watch;
+		}
+		return { aborted: controller.signal.aborted };
+	};
+	const drainHoldingLease = async (log, ns, scope, recoveryDueAt) => {
+		let processed = 0;
+		const holder = crypto.randomUUID();
+		const publicSessionId = stripNs(ns);
+		const alignRecoveryAt = (minimumDueAt) => {
+			if (recoveryDueAt === void 0) return minimumDueAt;
+			return recoveryDueAt + Math.max(0, Math.ceil((minimumDueAt - recoveryDueAt) / DRAIN_TIMINGS.leaseHeartbeatMs)) * DRAIN_TIMINGS.leaseHeartbeatMs;
+		};
+		let armInFlight = null;
+		let pendingRecoveryAt = 0;
+		const pumpRecoveryArm = () => {
+			if (armInFlight || pendingRecoveryAt === 0) return armInFlight;
+			const dueAt = pendingRecoveryAt;
+			pendingRecoveryAt = 0;
+			const raw = startRecoveryArm(publicSessionId, dueAt);
+			if (!raw) return null;
+			armInFlight = raw;
+			const finished = () => {
+				if (armInFlight === raw) armInFlight = null;
+				pumpRecoveryArm();
+			};
+			raw.then(finished, finished);
+			return raw;
+		};
+		const requestRecoveryArm = (dueAt) => {
+			pendingRecoveryAt = Math.max(pendingRecoveryAt, dueAt);
+			return pumpRecoveryArm();
+		};
+		let leaseLost = false;
+		let stopRenewing = false;
+		let renewalInFlight = null;
+		let heartbeat = null;
+		const stopHeartbeat = () => {
+			if (heartbeat) clearInterval(heartbeat);
+			heartbeat = null;
+		};
+		const renewLease = () => {
+			if (stopRenewing || leaseLost) return Promise.resolve();
+			if (renewalInFlight) return renewalInFlight;
+			const window = nextLeaseWindow();
+			requestRecoveryArm(alignRecoveryAt(window.recoveryAtMs));
+			const renewal = log.lease.acquire({
+				sessionId: ns,
+				holder,
+				ttlMs: window.ttlMs,
+				...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {}
+			}).then((renewed) => {
+				if (!renewed) leaseLost = true;
+				if (window.deadlineCapped) {
+					stopRenewing = true;
+					stopHeartbeat();
+				}
+			}, () => {});
+			let tracked;
+			tracked = renewal.finally(() => {
+				if (renewalInFlight === tracked) renewalInFlight = null;
+			});
+			renewalInFlight = tracked;
+			return tracked;
+		};
+		const initialWindow = nextLeaseWindow();
+		const initialClaim = await log.claimNext({
+			sessionId: ns,
+			holder,
+			ttlMs: initialWindow.ttlMs,
+			...initialWindow.deadlineCapped ? { expiresAtMs: initialWindow.expiresAtMs } : {},
+			...scope.full ? {} : { maxIndex: scope.frontier }
+		});
+		if (initialClaim.outcome === "settled") return {
+			outcome: "settled",
+			processed
+		};
+		const initialRecoveryArm = requestRecoveryArm(alignRecoveryAt(initialWindow.recoveryAtMs));
+		if (initialClaim.outcome === "busy") return {
+			outcome: "busy",
+			processed,
+			...initialRecoveryArm ? { recoveryArm: initialRecoveryArm } : {}
+		};
+		stopRenewing = initialWindow.deadlineCapped;
+		if (!stopRenewing) {
+			heartbeat = setInterval(() => {
+				renewLease();
+			}, DRAIN_TIMINGS.leaseHeartbeatMs);
+			heartbeat.unref?.();
+		}
+		let inHold = true;
+		const onCtxAppend = (maxIndex) => {
+			if (!inHold) return false;
+			if (!scope.full && maxIndex > scope.frontier) scope.frontier = maxIndex;
+			return true;
+		};
+		let next = initialClaim.event;
+		try {
+			for (;;) {
+				const registration = handlers.get(next.type);
+				const step = await telemetry.span("a2.event", {
+					"a2.contract": name,
+					"a2.session_id": stripNs(ns),
+					"a2.event.type": next.type,
+					"a2.event.index": next.index,
+					"a2.event.id": next.id,
+					"a2.event.attempt": next.attemptCount,
+					"a2.event.handled": registration !== void 0
+				}, async (span) => {
+					try {
+						if (registration) try {
+							if (registration.abortOn) {
+								const { aborted } = await runAbortable(log, ns, next, next.attemptCount, {
+									handler: registration.handler,
+									abortOn: registration.abortOn
+								}, onCtxAppend);
+								if (aborted) span.setAttribute("a2.event.aborted", true);
+							} else await registration.handler(makeCtx(next, next.attemptCount, onCtxAppend, dormantSignal));
+						} catch (err) {
+							span.recordError(err);
+							const failure = await log.failAttempt({
+								sessionId: ns,
+								index: next.index,
+								attempt: next.attemptCount,
+								error: describeError(err),
+								maxFailures: MAX_FAILURES
+							});
+							if (failure.outcome === "superseded") leaseLost = true;
+							span.setAttribute("a2.event.outcome", failure.outcome);
+							return { outcome: failure.outcome };
+						}
+						await renewalInFlight;
+						const claimed = await log.completeAndClaimNext({
+							sessionId: ns,
+							holder,
+							completedIndex: next.index,
+							attempt: next.attemptCount,
+							...scope.full ? {} : { maxIndex: scope.frontier }
+						});
+						if (claimed.outcome === "superseded") {
+							leaseLost = true;
+							span.setAttribute("a2.event.outcome", "superseded");
+							return { outcome: "superseded" };
+						}
+						if (claimed.outcome === "claimed") leaseLost = false;
+						else if (claimed.outcome === "busy") leaseLost = true;
+						span.setAttribute("a2.event.outcome", "processed");
+						return {
+							outcome: "processed",
+							next: claimed
+						};
+					} finally {
+						if (leaseLost) span.setAttribute("a2.event.lease_lost", true);
+					}
+				});
+				if (step.outcome === "dead_lettered") return {
+					outcome: "settled",
+					processed
+				};
+				if (step.outcome === "failed") return {
+					outcome: "stalled",
+					processed
+				};
+				if (step.outcome === "superseded") return {
+					outcome: "busy",
+					processed
+				};
+				processed += 1;
+				if (step.next.outcome === "claimed") {
+					next = step.next.event;
+					continue;
+				}
+				return {
+					outcome: step.next.outcome,
+					processed
+				};
+			}
+		} finally {
+			inHold = false;
+			stopRenewing = true;
+			stopHeartbeat();
+			await renewalInFlight;
+			await log.lease.release({
+				sessionId: ns,
+				holder
+			});
+		}
+	};
+	const drainSession = (sessionId, scope, recoveryDueAt) => telemetry.span("a2.drain", {
+		"a2.contract": name,
+		"a2.session_id": sessionId,
+		"a2.drain.scope": scope.full ? "full" : "tree"
+	}, async (span) => {
+		const log = await resolveLog();
+		const ns = nsId(sessionId);
+		const releaseSlot = await acquireSlot(ns, { wait: !scope.full });
+		if (!releaseSlot) {
+			span.setAttribute("a2.drain.outcome", "busy");
+			return {
+				settled: false,
+				outcome: "busy",
+				processed: 0
+			};
+		}
+		let outcome;
+		let processed;
+		let recoveryArm;
+		try {
+			({outcome, processed, recoveryArm} = await drainHoldingLease(log, ns, scope, recoveryDueAt));
+		} finally {
+			releaseSlot();
+		}
+		span.setAttribute("a2.drain.processed", processed);
+		if (outcome === "busy" || outcome === "stalled") {
+			span.setAttribute("a2.drain.outcome", outcome);
+			return {
+				settled: false,
+				outcome,
+				processed,
+				...recoveryArm ? { recoveryArm } : {}
+			};
+		}
+		const leftover = await log.read(ns, { unprocessedOnly: true });
+		if (leftover.length === 0 || leftover[0]?.failedAt) {
+			span.setAttribute("a2.drain.outcome", "settled");
+			return {
+				settled: true,
+				outcome: "settled",
+				processed
+			};
+		}
+		if (!hasInProcessActivity(ns)) scheduleDrain(sessionId, leftover.at(-1)?.index ?? 0, recoveryDueAt);
+		span.setAttribute("a2.drain.outcome", "handed_off");
+		return {
+			settled: false,
+			outcome: "handed_off",
+			processed
+		};
+	});
+	const self = {
+		contract: serverContract,
+		session(id) {
+			assertSessionId(id);
+			return {
+				sessionId: id,
+				append: (...events) => appendCore(id, events, "external", (rows, recoveryDueAt) => {
+					scheduleDrain(id, rows.at(-1)?.index ?? 0, recoveryDueAt);
+				}),
+				history: async () => (await readAll(id)).map(toPublic),
+				state: async (reducer) => {
+					const log = await resolveLog();
+					return telemetry.span("a2.state", {
+						"a2.contract": name,
+						"a2.session_id": id,
+						"a2.state.reducer": reducer.name
+					}, async (span) => {
+						let state = cloneInitial(reducer.initialState);
+						let index = 0;
+						let snapshotOutcome = "miss";
+						let stateRead;
+						try {
+							stateRead = await log.readState(nsId(id), reducer.name);
+						} catch {
+							try {
+								stateRead = {
+									snapshot: null,
+									events: await log.read(nsId(id))
+								};
+							} catch (err) {
+								throw asLogUnavailable(err);
+							}
+						}
+						const snap = stateRead.snapshot;
+						let rows = stateRead.events;
+						if (snap) {
+							if (reducer.stateSchema) {
+								const result = validateSync(reducer.stateSchema, snap.state, "the stateSchema");
+								if (result.issues) snapshotOutcome = "rejected";
+								else {
+									state = result.value;
+									index = snap.index;
+									snapshotOutcome = "hit";
+								}
+							} else {
+								state = snap.state;
+								index = snap.index;
+								snapshotOutcome = "hit";
+							}
+						}
+						span.setAttribute("a2.state.snapshot", snapshotOutcome);
+						if (snapshotOutcome === "rejected") try {
+							rows = await log.read(nsId(id));
+						} catch (err) {
+							throw asLogUnavailable(err);
+						}
+						for (const row of rows) {
+							state = reducer.fold(state, toPublic(row));
+							index = row.index;
+						}
+						span.setAttribute("a2.state.folded", rows.length);
+						span.setAttribute("a2.state.index", index);
+						if (rows.length > 0) {
+							const snapshotState = cloneInitial(state);
+							const write = Promise.resolve().then(() => log.putSnapshot(nsId(id), reducer.name, index, snapshotState)).catch(() => {});
+							track(write);
+							platformWaitUntil(write);
+						}
+						return {
+							state,
+							index
+						};
+					});
+				},
+				stream: (opts) => {
+					const log = resolveLog();
+					const startAt = opts?.startAt ?? 0;
+					const outer = async function* () {
+						const inner = (await log).stream(nsId(id), { startAt });
+						for await (const event of inner) yield {
+							id: event.id,
+							type: event.type,
+							payload: event.payload,
+							index: event.index,
+							sessionId: id,
+							createdAt: event.createdAt
+						};
+					};
+					return outer();
+				}
+			};
+		},
+		async drain(sessionId) {
+			assertSessionId(sessionId);
+			const { settled } = await drainSession(sessionId, {
+				full: true,
+				frontier: 0
+			});
+			return { settled };
+		}
+	};
+	serverInternals.set(self, {
+		settle: async () => {
+			while (inFlight.size > 0) await Promise.allSettled(inFlight);
+		},
+		recoveryDrain: (sessionId, opts) => {
+			assertSessionId(sessionId);
+			return drainSession(sessionId, {
+				full: true,
+				frontier: 0
+			}, opts?.recoveryDueAt);
+		}
+	});
+	serverInspection.set(self, {
+		async listSessions(inspectionOptions) {
+			const log = await resolveLog();
+			if (!log.inspect) throw new TypeError("this log backend does not support inspection");
+			const page = await log.inspect.listSessions({
+				prefix: `${name}${NS}`,
+				limit: inspectionOptions.limit,
+				...inspectionOptions.cursor !== void 0 ? { cursor: inspectionOptions.cursor } : {}
+			});
+			return {
+				cursor: page.cursor,
+				sessions: page.sessions.map((session) => ({
+					...session,
+					sessionId: stripNs(session.sessionId)
+				}))
+			};
+		},
+		async readSession(sessionId) {
+			assertSessionId(sessionId);
+			const log = await resolveLog();
+			if (!log.inspect) throw new TypeError("this log backend does not support inspection");
+			const ns = nsId(sessionId);
+			const [events, snapshots] = await Promise.all([log.read(ns), log.inspect.listSnapshots(ns)]);
+			return {
+				events: events.map((event) => ({
+					...event,
+					sessionId
+				})),
+				snapshots
+			};
+		}
+	});
+	return self;
+}
+function assertSessionId(id) {
+	if (typeof id !== "string" || id.length === 0) throw new TypeError("session id must be a non-empty string");
+	if (id.includes(NS)) throw new TypeError("session id contains a reserved control character");
+}
+function cloneInitial(initial) {
+	try {
+		return structuredClone(initial);
+	} catch {
+		return initial;
+	}
+}
+//#endregion
+export { createServer as t };