experimental-a2 0.2.0 → 0.4.0

package/dist/server-DJgD2YWP.js

@@ -1,877 +0,0 @@
-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-D6wNxTck.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 handler `session.append` calls. A handler
-* re-run after a crash calls `session.append` again; giving
-* each call a deterministic id — derived from the triggering event's id
-* and the caller's stable name — 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, name, itemOrdinal)`, computed with
-* WebCrypto so it runs on any platform a2 core targets.
-*/
-const APPEND_NAMESPACE = "a2:handler-append:v2";
-const RETURN_NAMESPACE = "a2:handler-return:v1";
-async function deterministicId(parts) {
-	const input = parts.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)}`;
-}
-async function deterministicEventId(triggerEventId, name, itemOrdinal) {
-	if (name.length === 0) throw new TypeError("append name must not be empty");
-	return deterministicId([
-		APPEND_NAMESPACE,
-		triggerEventId,
-		name,
-		itemOrdinal
-	]);
-}
-async function deterministicReturnedEventId(triggerEventId, itemOrdinal) {
-	return deterministicId([
-		RETURN_NAMESPACE,
-		triggerEventId,
-		itemOrdinal
-	]);
-}
-//#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;
-function createDrainSignal() {
-	const listeners = /* @__PURE__ */ new Set();
-	return {
-		version: 0,
-		closed: false,
-		notify() {
-			this.version += 1;
-			for (const listener of listeners) listener();
-			listeners.clear();
-		},
-		wait(version) {
-			if (this.version !== version) return {
-				promise: Promise.resolve(),
-				cancel: () => {}
-			};
-			let resolve;
-			const promise = new Promise((done) => {
-				resolve = done;
-			});
-			listeners.add(resolve);
-			return {
-				promise,
-				cancel: () => listeners.delete(resolve)
-			};
-		}
-	};
-}
-function dispatchAbortEvent(hub, event) {
-	let relevant = false;
-	for (const subscription of hub.subscriptions) {
-		if (!subscription.types.has(event.type)) continue;
-		relevant = true;
-		if (subscription.matches(event)) subscription.controller.abort();
-	}
-	if (relevant) hub.seen.set(event.index, event);
-}
-function pruneAbortHub(hub) {
-	let minimum = Infinity;
-	const types = /* @__PURE__ */ new Set();
-	for (const subscription of hub.subscriptions) {
-		minimum = Math.min(minimum, subscription.triggerIndex);
-		for (const type of subscription.types) types.add(type);
-	}
-	for (const [index, event] of hub.seen) if (index <= minimum || !types.has(event.type)) hub.seen.delete(index);
-}
-/**
-* Deadlines tighten the claim/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 nextClaimWindow() {
-	const nowMs = Date.now();
-	const deadlineMs = invocationDeadlineMs();
-	const deadlineTtlMs = deadlineMs === null ? DRAIN_TIMINGS.claimTtlMs : deadlineMs - nowMs;
-	const deadlineCapped = deadlineMs !== null && deadlineTtlMs <= DRAIN_TIMINGS.claimTtlMs;
-	const ttlMs = Math.max(1, Math.min(DRAIN_TIMINGS.claimTtlMs, deadlineTtlMs));
-	const expiresAtMs = nowMs + ttlMs;
-	return {
-		ttlMs,
-		expiresAtMs,
-		recoveryAtMs: expiresAtMs + DRAIN_TIMINGS.recoveryGraceMs,
-		deadlineCapped
-	};
-}
-function recoverySlot(dueAt) {
-	return Math.ceil(dueAt / 1e3) * 1e3;
-}
-function currentRecoverySlot(now) {
-	return Math.floor(now / 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 'experimental-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;
-		}
-		const lane = typeof entry === "function" ? null : entry.lane ?? null;
-		if (lane !== null && typeof lane !== "function" && (typeof lane !== "string" || lane.length === 0)) throw new TypeError(`lane for '${type}' must be a non-empty string or a function`);
-		handlers.set(type, {
-			handler,
-			abortOn,
-			lane
-		});
-	}
-	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;
-	};
-	const scheduledDrains = /* @__PURE__ */ new Map();
-	const scheduleDrain = (sessionId, recoveryDueAt) => {
-		const existing = scheduledDrains.get(sessionId);
-		if (existing && !existing.signal.closed) {
-			existing.signal.notify();
-			return;
-		}
-		if (existing) scheduledDrains.delete(sessionId);
-		const signal = createDrainSignal();
-		const p = new Promise((resolve) => {
-			queueMicrotask(() => {
-				drainSession(sessionId, recoveryDueAt, signal).then(() => resolve()).catch(() => resolve());
-			});
-		}).finally(() => {
-			if (scheduledDrains.get(sessionId)?.promise === p) scheduledDrains.delete(sessionId);
-		});
-		scheduledDrains.set(sessionId, {
-			signal,
-			promise: p
-		});
-		track(p);
-		platformWaitUntil(p);
-	};
-	const validateEvents = (sessionId, 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;
-			const registration = handlers.get(e.type);
-			if (!registration) validated.settled = true;
-			else if (registration.lane !== null) {
-				const lane = typeof registration.lane === "function" ? registration.lane({
-					sessionId,
-					event: {
-						type: e.type,
-						payload: structuredClone(result.value),
-						...e.id === void 0 ? {} : { id: e.id }
-					}
-				}) : registration.lane;
-				if (typeof lane !== "string" || lane.length === 0) throw new TypeError(`lane for '${e.type}' must resolve to a non-empty string`);
-				validated.lane = lane;
-			}
-			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, causal work remains connected.
-	*/
-	const appendCore = (sessionId, events, source, mode, onAppended, cause, generatedIds) => telemetry.span("a2.append", {
-		"a2.contract": name,
-		"a2.session_id": sessionId,
-		"a2.append.source": source,
-		"a2.append.mode": mode,
-		"a2.append.types": events.map((e) => String(e.type)).join(","),
-		"a2.append.count": events.length
-	}, async (span) => {
-		if (mode === "dispatch" && !recovery) throw new TypeError("append.dispatch requires a configured recovery adapter");
-		assertSessionId(sessionId);
-		const validated = validateEvents(sessionId, events);
-		if (cause) for (const [index, event] of validated.entries()) event.cause = generatedIds?.[index] ? {
-			...cause,
-			batchSize: events.length
-		} : cause;
-		const log = await resolveLog();
-		let rows;
-		let shouldHealSession;
-		try {
-			const result = await log.append(nsId(sessionId), validated);
-			rows = result.events;
-			shouldHealSession = result.hasPending;
-		} catch (err) {
-			throw asLogUnavailable(err);
-		}
-		const appended = rows.map(toPublic);
-		const initialRecoveryAt = shouldHealSession && recovery && source === "external" && mode === "inline" ? recoverySlot(nextClaimWindow().recoveryAtMs) : void 0;
-		const initialArm = initialRecoveryAt !== void 0 ? startRecoveryArm(sessionId, initialRecoveryAt) : null;
-		const dispatchArm = shouldHealSession && mode === "dispatch" ? startRecoveryArm(sessionId, currentRecoverySlot(Date.now())) : null;
-		if (shouldHealSession && mode === "inline") onAppended(appended, initialRecoveryAt);
-		if (dispatchArm) await dispatchArm;
-		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 readState = async (sessionId, reducer) => {
-		const log = await resolveLog();
-		return telemetry.span("a2.state", {
-			"a2.contract": name,
-			"a2.session_id": sessionId,
-			"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(sessionId), reducer.name);
-			} catch {
-				try {
-					stateRead = {
-						snapshot: null,
-						events: await log.read(nsId(sessionId))
-					};
-				} 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(sessionId));
-			} 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(sessionId), reducer.name, index, snapshotState)).catch(() => {});
-				track(write);
-				platformWaitUntil(write);
-			}
-			return {
-				state,
-				index
-			};
-		});
-	};
-	const makeSession = (id, append) => ({
-		id,
-		append,
-		history: async () => (await readAll(id)).map(toPublic),
-		state: (reducer) => readState(id, reducer),
-		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();
-		}
-	});
-	const makeCtx = (trigger, attempt, signal) => {
-		const publicSessionId = stripNs(trigger.sessionId);
-		const append = async (appendName, ...events) => {
-			assertAppendName(appendName);
-			const generatedIds = events.map((event) => event.id === void 0);
-			const withIds = await Promise.all(events.map(async (event, item) => {
-				if (event.id !== void 0) return event;
-				const id = await deterministicEventId(trigger.id, appendName, item);
-				return {
-					...event,
-					id
-				};
-			}));
-			return appendCore(publicSessionId, withIds, "handler", "inline", (_rows, recoveryDueAt) => scheduleDrain(publicSessionId, recoveryDueAt), {
-				index: trigger.index,
-				attempt
-			}, generatedIds);
-		};
-		return {
-			event: toPublic(trigger),
-			attempt,
-			session: makeSession(publicSessionId, append),
-			signal
-		};
-	};
-	const abortHubs = /* @__PURE__ */ new Map();
-	const createAbortHub = (log, ns, startAt) => {
-		const hub = {
-			subscriptions: /* @__PURE__ */ new Set(),
-			seen: /* @__PURE__ */ new Map(),
-			startAt,
-			ready: Promise.resolve(),
-			watch: null,
-			error: null,
-			iterator: null,
-			stopped: false
-		};
-		hub.ready = (async () => {
-			const existing = await log.read(ns, { afterIndex: startAt });
-			for (const event of existing) dispatchAbortEvent(hub, event);
-			const tail = existing.at(-1)?.index ?? startAt;
-			const iterator = log.stream(ns, { startAt: tail })[Symbol.asyncIterator]();
-			hub.iterator = iterator;
-			hub.watch = (async () => {
-				for (;;) {
-					const { value, done } = await iterator.next();
-					if (done || value === void 0 || hub.stopped) return;
-					dispatchAbortEvent(hub, value);
-				}
-			})().catch((error) => {
-				hub.error = error;
-			});
-		})().catch((error) => {
-			hub.error = error;
-			if (abortHubs.get(ns) === hub) abortHubs.delete(ns);
-			throw error;
-		});
-		abortHubs.set(ns, hub);
-		return hub;
-	};
-	const subscribeAbort = async (log, ns, trigger, abortOn, attempt) => {
-		let hub = abortHubs.get(ns);
-		if (!hub) hub = createAbortHub(log, ns, trigger.index);
-		const activeTypes = /* @__PURE__ */ new Set();
-		for (const active of hub.subscriptions) for (const type of active.types) activeTypes.add(type);
-		const publicTrigger = toPublic(trigger);
-		const subscription = {
-			controller: new AbortController(),
-			triggerIndex: trigger.index,
-			types: new Set(abortOn.keys()),
-			matches: (event) => {
-				if (event.index <= trigger.index) return false;
-				const matcher = abortOn.get(event.type);
-				if (matcher === void 0) return false;
-				return matcher === true ? true : matcher(toPublic(event), publicTrigger, { attempt });
-			}
-		};
-		hub.subscriptions.add(subscription);
-		if (trigger.index < hub.startAt || [...subscription.types].some((type) => !activeTypes.has(type))) {
-			const earlier = await log.read(ns, { afterIndex: trigger.index });
-			hub.startAt = Math.min(hub.startAt, trigger.index);
-			for (const event of earlier) dispatchAbortEvent(hub, event);
-		}
-		for (const event of hub.seen.values()) if (subscription.matches(event)) subscription.controller.abort();
-		await hub.ready;
-		if (hub.error !== null) throw hub.error;
-		return {
-			signal: subscription.controller.signal,
-			monitor: async (operation) => {
-				const outcome = await Promise.race([operation.then((value) => ({
-					type: "completed",
-					value
-				}), (error) => ({
-					type: "handler-failed",
-					error
-				})), hub.watch.then(() => hub.error === null ? { type: "monitor-closed" } : {
-					type: "monitor-failed",
-					error: hub.error
-				})]);
-				if (outcome.type === "completed") return outcome.value;
-				if (outcome.type === "handler-failed") throw outcome.error;
-				if (outcome.type === "monitor-failed") {
-					for (const active of hub.subscriptions) active.controller.abort(outcome.error);
-					await operation.catch(() => {});
-					throw outcome.error;
-				}
-				await operation.catch(() => {});
-				throw new Error("abort monitor closed while handlers were active");
-			},
-			close: async () => {
-				hub.subscriptions.delete(subscription);
-				if (hub.subscriptions.size > 0) {
-					pruneAbortHub(hub);
-					return;
-				}
-				hub.stopped = true;
-				abortHubs.delete(ns);
-				await hub.ready;
-				await hub.iterator?.return?.();
-				await hub.watch;
-			}
-		};
-	};
-	const returnedEvents = async (sessionId, trigger, result) => {
-		if (result === void 0) return [];
-		const events = Array.isArray(result) ? [...result] : [result];
-		if (events.length === 0) return [];
-		const withIds = await Promise.all(events.map(async (event, item) => ({
-			...event,
-			id: event.id ?? await deterministicReturnedEventId(trigger.id, item)
-		})));
-		return validateEvents(sessionId, withIds).map((event) => ({
-			...event,
-			id: event.id,
-			cause: {
-				index: trigger.index,
-				attempt: trigger.attemptCount
-			}
-		}));
-	};
-	const drainSession = (sessionId, recoveryDueAt, signal) => telemetry.span("a2.drain", {
-		"a2.contract": name,
-		"a2.session_id": sessionId
-	}, async (span) => {
-		const log = await resolveLog();
-		const ns = nsId(sessionId);
-		const holder = crypto.randomUUID();
-		const active = /* @__PURE__ */ new Map();
-		const excluded = /* @__PURE__ */ new Set();
-		let processed = 0;
-		let sawFailure = false;
-		let recoveryArm;
-		let heartbeat = null;
-		let renewal = null;
-		let stopRenewing = false;
-		const alignRecoveryAt = (minimumDueAt) => {
-			if (recoveryDueAt === void 0) return minimumDueAt;
-			return recoveryDueAt + Math.max(0, Math.ceil((minimumDueAt - recoveryDueAt) / DRAIN_TIMINGS.claimHeartbeatMs)) * DRAIN_TIMINGS.claimHeartbeatMs;
-		};
-		const requestRecovery = (dueAt) => {
-			const arm = startRecoveryArm(sessionId, alignRecoveryAt(dueAt));
-			if (arm) recoveryArm = arm;
-		};
-		const renew = () => {
-			if (stopRenewing || renewal || active.size === 0) return renewal ?? Promise.resolve();
-			const window = nextClaimWindow();
-			requestRecovery(window.recoveryAtMs);
-			const indexes = [...active.keys()];
-			const operation = log.renewClaims({
-				sessionId: ns,
-				holder,
-				indexes,
-				ttlMs: window.ttlMs,
-				...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {}
-			}).then(() => {
-				if (window.deadlineCapped) stopRenewing = true;
-			}, () => void 0);
-			let tracked;
-			tracked = operation.finally(() => {
-				if (renewal === tracked) renewal = null;
-			});
-			renewal = tracked;
-			return tracked;
-		};
-		const runEvent = async (event) => {
-			const registration = handlers.get(event.type);
-			return telemetry.span("a2.event", {
-				"a2.contract": name,
-				"a2.session_id": sessionId,
-				"a2.event.type": event.type,
-				"a2.event.index": event.index,
-				"a2.event.id": event.id,
-				"a2.event.attempt": event.attemptCount,
-				"a2.event.handled": registration !== void 0,
-				...event.lane === null ? {} : { "a2.event.lane": event.lane }
-			}, async (eventSpan) => {
-				let subscription;
-				let handlerSignal = dormantSignal;
-				let returned;
-				try {
-					if (registration?.abortOn) {
-						subscription = await subscribeAbort(log, ns, event, registration.abortOn, event.attemptCount);
-						handlerSignal = subscription.signal;
-					}
-					const operation = registration?.handler(makeCtx(event, event.attemptCount, handlerSignal));
-					const result = operation ? await (subscription ? subscription.monitor(operation) : operation) : void 0;
-					if (subscription) {
-						await subscription.close();
-						subscription = void 0;
-					}
-					returned = await returnedEvents(sessionId, event, result);
-				} catch (err) {
-					eventSpan.recordError(err);
-					const failure = await log.failAttempt({
-						sessionId: ns,
-						index: event.index,
-						attempt: event.attemptCount,
-						error: describeError(err),
-						maxFailures: MAX_FAILURES
-					});
-					eventSpan.setAttribute("a2.event.outcome", failure.outcome);
-					return {
-						status: failure.outcome,
-						opensLane: false,
-						appendsEvents: false
-					};
-				} finally {
-					await subscription?.close();
-				}
-				await renewal;
-				const completion = await log.completeAttempt({
-					sessionId: ns,
-					index: event.index,
-					attempt: event.attemptCount,
-					events: returned
-				});
-				eventSpan.setAttribute("a2.event.outcome", completion.outcome === "completed" ? "processed" : completion.outcome);
-				if (completion.outcome === "superseded") return {
-					status: "superseded",
-					opensLane: false,
-					appendsEvents: false
-				};
-				if (handlerSignal.aborted) eventSpan.setAttribute("a2.event.aborted", true);
-				return {
-					status: "processed",
-					opensLane: event.lane !== null,
-					appendsEvents: returned.length > 0
-				};
-			});
-		};
-		let claimAgain = false;
-		const start = (event) => {
-			const execution = runEvent(event).then((eventOutcome) => {
-				active.delete(event.index);
-				if (eventOutcome.status === "processed") processed += 1;
-				if (eventOutcome.status === "failed") {
-					excluded.add(event.index);
-					sawFailure = true;
-				}
-				claimAgain ||= eventOutcome.opensLane || eventOutcome.appendsEvents;
-				return eventOutcome;
-			});
-			active.set(event.index, execution);
-			if (!heartbeat && !stopRenewing) {
-				heartbeat = setInterval(() => void renew(), DRAIN_TIMINGS.claimHeartbeatMs);
-				heartbeat.unref?.();
-			}
-		};
-		let outcome = "settled";
-		let shouldClaim = true;
-		try {
-			for (;;) {
-				const signalVersion = signal?.version ?? 0;
-				let claim;
-				if (shouldClaim) {
-					const window = nextClaimWindow();
-					claim = await log.claimAvailable({
-						sessionId: ns,
-						holder,
-						ttlMs: window.ttlMs,
-						...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
-						...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
-					});
-					if (claim.outcome === "claimed") {
-						requestRecovery(window.recoveryAtMs);
-						if (window.deadlineCapped) stopRenewing = true;
-						for (const event of claim.events) start(event);
-						shouldClaim = false;
-					}
-				}
-				if (active.size > 0) {
-					const wake = signal?.wait(signalVersion);
-					await Promise.race([...active.values(), ...wake ? [wake.promise] : []]);
-					wake?.cancel();
-					shouldClaim = claimAgain || active.size === 0 || signal !== void 0 && signal.version !== signalVersion;
-					claimAgain = false;
-					continue;
-				}
-				if (!shouldClaim) {
-					shouldClaim = true;
-					continue;
-				}
-				if (claim === void 0) continue;
-				if (signal && signal.version !== signalVersion) continue;
-				if (claim.outcome === "busy") {
-					requestRecovery(claim.retryAt.getTime() + DRAIN_TIMINGS.recoveryGraceMs);
-					outcome = "busy";
-				} else if (sawFailure) outcome = "stalled";
-				if (signal) signal.closed = true;
-				break;
-			}
-		} finally {
-			if (signal) signal.closed = true;
-			stopRenewing = true;
-			if (heartbeat) clearInterval(heartbeat);
-			await renewal;
-			await Promise.allSettled(active.values());
-		}
-		span.setAttribute("a2.drain.processed", processed);
-		span.setAttribute("a2.drain.outcome", outcome);
-		return {
-			settled: outcome === "settled",
-			outcome,
-			processed,
-			...recoveryArm ? { recoveryArm } : {}
-		};
-	});
-	const appendExternal = async (sessionId, mode, events) => {
-		const pushed = events.filter((event) => Reflect.get(event, "~a2.pushed") === true);
-		if (pushed.length > 0) await options.validatePush?.({
-			sessionId,
-			events: pushed
-		});
-		return appendCore(sessionId, events, "external", mode, (_rows, recoveryDueAt) => scheduleDrain(sessionId, recoveryDueAt));
-	};
-	const self = {
-		contract: serverContract,
-		session(id) {
-			assertSessionId(id);
-			const appendInline = async (...events) => appendExternal(id, "inline", events);
-			const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
-			const append = Object.assign(appendInline, { dispatch: appendDispatch });
-			return makeSession(id, append);
-		},
-		async drain(sessionId) {
-			assertSessionId(sessionId);
-			const { settled } = await drainSession(sessionId);
-			return { settled };
-		}
-	};
-	serverInternals.set(self, {
-		settle: async () => {
-			while (inFlight.size > 0) await Promise.allSettled(inFlight);
-		},
-		recoveryDrain: (sessionId, opts) => {
-			assertSessionId(sessionId);
-			return drainSession(sessionId, 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 assertAppendName(name) {
-	if (typeof name !== "string" || name.length === 0) throw new TypeError("handler append name must be a non-empty string");
-}
-function cloneInitial(initial) {
-	try {
-		return structuredClone(initial);
-	} catch {
-		return initial;
-	}
-}
-//#endregion
-export { createServer as t };