experimental-a2 0.2.0 → 0.4.0

package/dist/server-CcNnFnoW.js

@@ -0,0 +1,1405 @@
+import { n as validateSync } from "./validate-XKT4FSNn.js";
+import { n as asStoreUnavailable, t as A2Error } from "./errors-BQuJpe82.js";
+import { g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, o as RESERVED_PARTICIPANT_IDS, t as DRAIN_TIMINGS, v as serverInternals, y as serverSchedulerBindings } from "./internal-aEotMzu_.js";
+import { n as InspectionUnsupportedError, r as serverInspection } from "./inspection-DaxB5jM2.js";
+import { t as defaultSleep } from "./store-polling-DgrrAE3d.js";
+import { r as platformWaitUntil, t as invocationDeadlineMs } from "./platform-B4TnJtWu.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 store'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";
+const SCHEDULE_NAMESPACE = "a2:schedule:v1";
+const SCHEDULED_EVENT_NAMESPACE = "a2:scheduled-event: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);
+	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 deterministicId(parts) {
+	return deterministicIdFromInput(parts.join("\0"));
+}
+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
+	]);
+}
+async function deterministicScheduleId(contract, sessionId, triggerEventId, name) {
+	return deterministicIdFromInput(JSON.stringify([
+		SCHEDULE_NAMESPACE,
+		contract,
+		sessionId,
+		triggerEventId,
+		name
+	]));
+}
+async function deterministicScheduledEventId(scheduleId, itemOrdinal) {
+	return deterministicId([
+		SCHEDULED_EVENT_NAMESPACE,
+		scheduleId,
+		itemOrdinal
+	]);
+}
+//#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
+/**
+* Deliver one authenticated scheduler append through an A2 server's ordinary
+* top-level append path. Custom scheduler adapters call this after validating
+* their transport envelope; application code normally uses `session.schedule`.
+*/
+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 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);
+}
+const MAX_FAILURES = 10;
+/** Default: how long a presence value survives without a refreshing set. */
+const PRESENCE_TTL_MS = 6e4;
+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,
+		watchdogAtMs: expiresAtMs + DRAIN_TIMINGS.watchdogGraceMs,
+		deadlineCapped
+	};
+}
+function schedulerSlot(dueAt) {
+	return Math.ceil(dueAt / 1e3) * 1e3;
+}
+function currentSchedulerSlot(now) {
+	return Math.floor(now / 1e3) * 1e3;
+}
+/**
+* The namespace separator between machine name and session id in
+* storage. Machines sharing one store 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 devDefaultStore = retryableLazy(() => import("./store-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);
+}
+/**
+* Comparison key for a presence value in the degraded-tier diff — an
+* LWW tie can replace a value without moving its `seen`/`at` stamp.
+*/
+function fingerprint(value) {
+	return JSON.stringify(value) ?? "";
+}
+function foldPresenceRows(rows) {
+	const map = nullProtoRecord();
+	for (const row of rows) (map[row.participant] ??= nullProtoRecord())[row.field] = {
+		value: row.value,
+		seen: row.seen,
+		at: row.at
+	};
+	return map;
+}
+/** 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;
+	const presenceDefs = serverContract.presence;
+	const declaresPresence = Object.keys(presenceDefs).length > 0;
+	const presenceNotSupported = () => new A2Error("PRESENCE_NOT_SUPPORTED", `the contract '${name}' declares presence but the store backend for its server has no presence capability (A2Store.presence)`);
+	if (options.presence !== void 0) {
+		if (!declaresPresence) throw new TypeError(`the presence option requires a contract that declares presence fields — '${name}' has none`);
+		const { ttlMs } = options.presence;
+		if (ttlMs !== void 0 && (!Number.isInteger(ttlMs) || ttlMs <= 0)) throw new TypeError("presence.ttlMs must be a positive integer of milliseconds");
+	}
+	const presenceTtlMs = options.presence?.ttlMs ?? PRESENCE_TTL_MS;
+	let makeStore;
+	if (options.store) {
+		const explicit = options.store;
+		if (declaresPresence && !explicit.presence) throw presenceNotSupported();
+		makeStore = () => Promise.resolve(explicit);
+	} else {
+		const env = environment();
+		if (env === "production") {
+			const error = () => new A2Error("STORE_NOT_CONFIGURED", `the server for '${name}' has no store configured and NODE_ENV is 'production' — pass an explicit store backend (e.g. postgres from 'experimental-a2/store-postgres')`);
+			if (process.env["NEXT_PHASE"] !== "phase-production-build") throw error();
+			makeStore = () => Promise.reject(error());
+		} else makeStore = env === "test" ? () => import("./store-memory.js").then((m) => m.memory()) : devDefaultStore.get;
+	}
+	if (declaresPresence && !options.store) {
+		const inner = makeStore;
+		makeStore = async () => {
+			const store = await inner();
+			if (!store.presence) throw presenceNotSupported();
+			return store;
+		};
+	}
+	const resolveStore = retryableLazy(makeStore).get;
+	const telemetry = options.telemetry ?? NOOP_TELEMETRY;
+	const scheduler = options.scheduler;
+	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 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 schedulerArmSlots = /* @__PURE__ */ new Map();
+	/**
+	* Start an optional scheduler 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 startSchedulerArm = (sessionId, dueAt) => {
+		if (!scheduler) return null;
+		const slottedDueAt = schedulerSlot(dueAt);
+		const slotKey = JSON.stringify([sessionId, slottedDueAt]);
+		const existing = schedulerArmSlots.get(slotKey);
+		if (existing) return existing.promise;
+		const raw = Promise.resolve().then(() => scheduler.schedule({
+			version: 1,
+			kind: "drain",
+			contract: name,
+			sessionId,
+			dueAt: slottedDueAt
+		}));
+		const forget = setTimeout(() => {
+			if (schedulerArmSlots.get(slotKey)?.promise === raw) schedulerArmSlots.delete(slotKey);
+		}, Math.max(0, slottedDueAt - Date.now()) + 1e3);
+		forget.unref?.();
+		schedulerArmSlots.set(slotKey, {
+			promise: raw,
+			forget
+		});
+		raw.then(void 0, () => {
+			const current = schedulerArmSlots.get(slotKey);
+			if (current?.promise !== raw) return;
+			clearTimeout(current.forget);
+			schedulerArmSlots.delete(slotKey);
+		});
+		const safe = raw.catch(() => {});
+		track(safe);
+		platformWaitUntil(safe);
+		return raw;
+	};
+	const scheduledDrains = /* @__PURE__ */ new Map();
+	const scheduleDrain = (sessionId, watchdogDueAt) => {
+		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, watchdogDueAt, 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, resolveDispatchMetadata = true) => {
+		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;
+			if (!resolveDispatchMetadata) return validated;
+			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, requireDurableInitialArm = false) => 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" && !scheduler) throw new TypeError("append.dispatch requires a configured scheduler 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 store = await resolveStore();
+		let rows;
+		let shouldHealSession;
+		try {
+			const result = await store.append(nsId(sessionId), validated);
+			rows = result.events;
+			shouldHealSession = result.hasPending;
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		const appended = rows.map(toPublic);
+		const initialWatchdogAt = shouldHealSession && scheduler && source === "external" && mode === "inline" ? schedulerSlot(nextClaimWindow().watchdogAtMs) : void 0;
+		const initialArm = initialWatchdogAt !== void 0 ? startSchedulerArm(sessionId, initialWatchdogAt) : null;
+		const dispatchArm = shouldHealSession && mode === "dispatch" ? startSchedulerArm(sessionId, currentSchedulerSlot(Date.now())) : null;
+		if (shouldHealSession && mode === "inline") onAppended(appended, initialWatchdogAt);
+		if (dispatchArm) await dispatchArm;
+		if (initialArm) {
+			let timeout = null;
+			try {
+				await Promise.race([initialArm, new Promise((_, reject) => {
+					timeout = setTimeout(() => {
+						reject(/* @__PURE__ */ new Error(`a2 scheduler arm timed out after ${DRAIN_TIMINGS.schedulerArmTimeoutMs}ms`));
+					}, DRAIN_TIMINGS.schedulerArmTimeoutMs);
+				})]);
+			} catch (err) {
+				span.setAttribute("a2.append.armed", false);
+				span.recordError(err);
+				if (requireDurableInitialArm) throw err;
+			} finally {
+				if (timeout) clearTimeout(timeout);
+			}
+		}
+		return appended;
+	});
+	const readHistory = async (sessionId, bounds) => {
+		const gte = bounds?.gte;
+		const lte = bounds?.lte;
+		assertHistoryIndex("gte", gte);
+		assertHistoryIndex("lte", lte);
+		if (gte !== void 0 && lte !== void 0 && gte > lte) throw new RangeError("history.gte must be less than or equal to history.lte");
+		if (lte === 0) return [];
+		const store = await resolveStore();
+		try {
+			const readOptions = gte === void 0 && lte === void 0 ? void 0 : {
+				...gte === void 0 ? {} : { afterIndex: Math.max(0, gte - 1) },
+				...lte === void 0 ? {} : { throughIndex: lte }
+			};
+			return (await store.read(nsId(sessionId), readOptions)).filter((row) => (gte === void 0 || row.index >= gte) && (lte === void 0 || row.index <= lte));
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+	};
+	const readState = async (sessionId, reducer) => {
+		const store = await resolveStore();
+		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 store.readState(nsId(sessionId), reducer.name);
+			} catch {
+				try {
+					stateRead = {
+						snapshot: null,
+						events: await store.read(nsId(sessionId))
+					};
+				} catch (err) {
+					throw asStoreUnavailable(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 store.read(nsId(sessionId));
+			} catch (err) {
+				throw asStoreUnavailable(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(() => store.putSnapshot(nsId(sessionId), reducer.name, index, snapshotState)).catch(() => {});
+				track(write);
+				platformWaitUntil(write);
+			}
+			return {
+				state,
+				index
+			};
+		});
+	};
+	const makeSchedule = (sessionId, trigger) => {
+		const triggerEventId = trigger?.id ?? null;
+		const triggerCreatedAt = trigger?.createdAt.getTime();
+		return 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");
+			const dueAt = scheduleDueAt(timing, triggerCreatedAt ?? Date.now());
+			const payloads = events.map((event) => cloneScheduledPayload(event.payload));
+			const snapshottedEvents = events.map((event, index) => ({
+				type: event.type,
+				payload: payloads[index],
+				...event.id === void 0 ? {} : { id: event.id }
+			}));
+			const validated = validateEvents(sessionId, structuredClone(snapshottedEvents), false);
+			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName);
+			const scheduledEvents = await Promise.all(validated.map(async (event, item) => ({
+				id: event.id ?? await deterministicScheduledEventId(scheduleId, item),
+				type: event.type,
+				payload: payloads[item]
+			})));
+			if (new Set(scheduledEvents.map((event) => event.id)).size !== scheduledEvents.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "scheduled batch contains the same event id more than once");
+			try {
+				await scheduler.schedule({
+					version: 1,
+					kind: "append",
+					id: scheduleId,
+					contract: name,
+					sessionId,
+					dueAt,
+					events: scheduledEvents
+				});
+			} catch (error) {
+				throw markSchedulerSendFailure(error);
+			}
+		};
+	};
+	const toSessionEvent = (id, event) => ({
+		id: event.id,
+		type: event.type,
+		payload: event.payload,
+		index: event.index,
+		sessionId: id,
+		createdAt: event.createdAt
+	});
+	const streamEvents = (id, startAfter) => {
+		const store = resolveStore();
+		const outer = async function* () {
+			const inner = (await store).stream(nsId(id), { startAfter });
+			for await (const event of inner) yield toSessionEvent(id, event);
+		};
+		return outer();
+	};
+	const requirePresence = (store) => {
+		if (!store.presence) throw presenceNotSupported();
+		return store.presence;
+	};
+	const setPresence = async (sessionId, patch, fallbackSeen) => {
+		if (Reflect.get(patch, "~a2.pushed") === true) {
+			Object.freeze(patch.values);
+			await options.validatePush?.({
+				sessionId,
+				events: [],
+				presence: Object.freeze(patch)
+			});
+		}
+		if (typeof patch.participant !== "string" || patch.participant.length === 0) throw new TypeError("presence participant must be a non-empty string");
+		if (RESERVED_PARTICIPANT_IDS.has(patch.participant)) throw new TypeError(`presence participant must not be '${patch.participant}'`);
+		if (patch.at !== void 0 && (typeof patch.at !== "number" || !Number.isFinite(patch.at) || patch.at < 0 || patch.at > 864e13)) throw new TypeError("presence at must be non-negative epoch milliseconds within the Date range");
+		const validated = nullProtoRecord();
+		for (const [field, value] of Object.entries(patch.values)) {
+			if (value === void 0) continue;
+			const schema = Object.hasOwn(presenceDefs, field) ? presenceDefs[field] : void 0;
+			if (!schema) throw new A2Error("UNKNOWN_PRESENCE_FIELD", `contract '${name}' has no presence field '${field}'`);
+			if (value === null) {
+				validated[field] = null;
+				continue;
+			}
+			const result = validateSync(schema, value, `presence field '${field}'`);
+			if (result.issues) throw new A2Error("INVALID_PAYLOAD", `invalid value for presence field '${field}' on machine '${name}'`, { details: result.issues });
+			validated[field] = result.value;
+		}
+		const store = await resolveStore();
+		try {
+			await requirePresence(store).set(nsId(sessionId), patch.participant, validated, {
+				seen: patch.seen ?? fallbackSeen,
+				at: new Date(patch.at ?? Date.now()),
+				ttlMs: presenceTtlMs
+			});
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+	};
+	const readPresenceMap = async (sessionId) => {
+		const store = await resolveStore();
+		let rows;
+		try {
+			rows = await requirePresence(store).read(nsId(sessionId));
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		return foldPresenceRows(rows);
+	};
+	/**
+	* The two-plane feed. Patches ride `subscribe` when the adapter has
+	* the push tier; without it the map is re-read and diffed whenever
+	* the event feed wakes, and at the poll idle ceiling while it is
+	* silent — degraded means later, not lost while watched.
+	*/
+	const streamWithPresence = (id, startAfter) => {
+		const ns = nsId(id);
+		const outer = async function* () {
+			const store = await resolveStore();
+			const api = requirePresence(store);
+			const readRows = async () => {
+				try {
+					return await api.read(ns);
+				} catch (err) {
+					throw asStoreUnavailable(err);
+				}
+			};
+			const painted = /* @__PURE__ */ new Map();
+			const diffRows = (rows) => {
+				const patches = [];
+				const live = /* @__PURE__ */ new Map();
+				for (const row of rows) {
+					let liveFields = live.get(row.participant);
+					if (!liveFields) {
+						liveFields = /* @__PURE__ */ new Set();
+						live.set(row.participant, liveFields);
+					}
+					liveFields.add(row.field);
+					const stamp = {
+						seen: row.seen,
+						atMs: row.at.getTime(),
+						value: fingerprint(row.value)
+					};
+					const prior = painted.get(row.participant)?.get(row.field);
+					if (prior && prior.seen === stamp.seen && prior.atMs === stamp.atMs && prior.value === stamp.value) continue;
+					let paintedFields = painted.get(row.participant);
+					if (!paintedFields) {
+						paintedFields = /* @__PURE__ */ new Map();
+						painted.set(row.participant, paintedFields);
+					}
+					paintedFields.set(row.field, stamp);
+					patches.push({
+						participant: row.participant,
+						values: { [row.field]: row.value },
+						seen: row.seen,
+						at: row.at
+					});
+				}
+				for (const [participant, fields] of painted) {
+					for (const [field, prior] of fields) {
+						if (live.get(participant)?.has(field)) continue;
+						fields.delete(field);
+						patches.push({
+							participant,
+							values: { [field]: null },
+							seen: prior.seen,
+							at: /* @__PURE__ */ new Date()
+						});
+					}
+					if (fields.size === 0) painted.delete(participant);
+				}
+				return patches;
+			};
+			const paint = (patch) => {
+				let fields = painted.get(patch.participant);
+				for (const [field, value] of Object.entries(patch.values)) {
+					if (value === null || value === void 0) {
+						fields?.delete(field);
+						continue;
+					}
+					if (!fields) {
+						fields = /* @__PURE__ */ new Map();
+						painted.set(patch.participant, fields);
+					}
+					fields.set(field, {
+						seen: patch.seen,
+						atMs: patch.at.getTime(),
+						value: fingerprint(value)
+					});
+				}
+				if (fields?.size === 0) painted.delete(patch.participant);
+			};
+			const queue = /* @__PURE__ */ new Map();
+			let wakeQueue = null;
+			const enqueue = (patch) => {
+				for (const [field, value] of Object.entries(patch.values)) {
+					if (value === void 0) continue;
+					let fields = queue.get(patch.participant);
+					if (!fields) {
+						fields = /* @__PURE__ */ new Map();
+						queue.set(patch.participant, fields);
+					}
+					const queued = fields.get(field);
+					if (queued && queued.at.getTime() > patch.at.getTime()) continue;
+					fields.set(field, {
+						value,
+						seen: patch.seen,
+						at: patch.at
+					});
+				}
+				wakeQueue?.();
+			};
+			const dequeue = () => {
+				for (const [participant, fields] of queue) {
+					for (const [field, stamp] of fields) {
+						fields.delete(field);
+						if (fields.size === 0) queue.delete(participant);
+						return {
+							participant,
+							values: { [field]: stamp.value },
+							seen: stamp.seen,
+							at: stamp.at
+						};
+					}
+					queue.delete(participant);
+				}
+				return null;
+			};
+			const unsubscribe = api.subscribe?.(ns, enqueue);
+			const events = store.stream(ns, { startAfter })[Symbol.asyncIterator]();
+			let pendingEvent = null;
+			try {
+				const snapshotRows = await readRows();
+				for (const row of snapshotRows) {
+					let fields = painted.get(row.participant);
+					if (!fields) {
+						fields = /* @__PURE__ */ new Map();
+						painted.set(row.participant, fields);
+					}
+					fields.set(row.field, {
+						seen: row.seen,
+						atMs: row.at.getTime(),
+						value: fingerprint(row.value)
+					});
+				}
+				yield { snapshot: foldPresenceRows(snapshotRows) };
+				for (;;) {
+					for (;;) {
+						const patch = dequeue();
+						if (!patch) break;
+						paint(patch);
+						yield patch;
+					}
+					pendingEvent ??= events.next();
+					let woke;
+					if (unsubscribe) {
+						const arrival = new Promise((resolve) => {
+							wakeQueue = resolve;
+						});
+						woke = await Promise.race([pendingEvent.then(() => "event"), arrival.then(() => "patch")]);
+						wakeQueue = null;
+						if (woke === "patch") continue;
+					} else {
+						const sleeper = defaultSleep(POLL_TIMINGS.idleCeilingMs);
+						woke = await Promise.race([pendingEvent.then(() => "event"), sleeper.promise.then(() => "tick")]);
+						sleeper.cancel();
+					}
+					if (woke === "event") {
+						const result = await pendingEvent;
+						pendingEvent = null;
+						if (result.done) return;
+						yield toSessionEvent(id, result.value);
+					}
+					if (!unsubscribe) for (const patch of diffRows(await readRows())) yield patch;
+				}
+			} finally {
+				wakeQueue = null;
+				unsubscribe?.();
+				pendingEvent?.catch(() => {});
+				await events.return?.();
+			}
+		};
+		return outer();
+	};
+	const makeSession = (id, append, trigger) => ({
+		id,
+		append,
+		schedule: makeSchedule(id, trigger),
+		history: async (bounds) => (await readHistory(id, bounds)).map(toPublic),
+		state: (reducer) => readState(id, reducer),
+		stream: (opts) => {
+			const startAfter = opts?.startAfter ?? 0;
+			assertStreamIndex(startAfter);
+			return opts?.presence === true ? streamWithPresence(id, startAfter) : streamEvents(id, startAfter);
+		},
+		...declaresPresence ? {
+			setPresence: (patch) => setPresence(id, patch, trigger?.index ?? 0),
+			presence: () => readPresenceMap(id)
+		} : {}
+	});
+	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, watchdogDueAt) => scheduleDrain(publicSessionId, watchdogDueAt), {
+				index: trigger.index,
+				attempt
+			}, generatedIds);
+		};
+		return {
+			event: toPublic(trigger),
+			attempt,
+			session: makeSession(publicSessionId, append, trigger),
+			signal
+		};
+	};
+	const abortHubs = /* @__PURE__ */ new Map();
+	const createAbortHub = (store, ns, startAfter) => {
+		const hub = {
+			subscriptions: /* @__PURE__ */ new Set(),
+			seen: /* @__PURE__ */ new Map(),
+			startAfter,
+			ready: Promise.resolve(),
+			watch: null,
+			error: null,
+			iterator: null,
+			stopped: false
+		};
+		hub.ready = (async () => {
+			const existing = await store.read(ns, { afterIndex: startAfter });
+			for (const event of existing) dispatchAbortEvent(hub, event);
+			const tail = existing.at(-1)?.index ?? startAfter;
+			const iterator = store.stream(ns, { startAfter: 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 (store, ns, trigger, abortOn, attempt) => {
+		let hub = abortHubs.get(ns);
+		if (!hub) hub = createAbortHub(store, 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.startAfter || [...subscription.types].some((type) => !activeTypes.has(type))) {
+			const earlier = await store.read(ns, { afterIndex: trigger.index });
+			hub.startAfter = Math.min(hub.startAfter, 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) => {
+			const withId = { ...event };
+			withId.id = event.id ?? await deterministicReturnedEventId(trigger.id, item);
+			return withId;
+		}));
+		return validateEvents(sessionId, withIds).map((event) => Object.assign(event, {
+			id: event.id,
+			cause: {
+				index: trigger.index,
+				attempt: trigger.attemptCount
+			}
+		}));
+	};
+	const drainSession = (sessionId, watchdogDueAt, signal) => telemetry.span("a2.drain", {
+		"a2.contract": name,
+		"a2.session_id": sessionId
+	}, async (span) => {
+		const store = await resolveStore();
+		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 schedulerArm;
+		let heartbeat = null;
+		let lapseTimer = null;
+		let retryTimer = null;
+		let renewal = null;
+		let stopRenewing = false;
+		const lapseDue = () => {
+			lapseTimer = null;
+			const nowMs = Date.now();
+			for (const [index, entry] of active) {
+				if (entry.lapsed || entry.expiresAtMs > nowMs) continue;
+				entry.lapsed = true;
+				entry.supersede.abort(new A2Error("CLAIM_EXPIRED", `the claim on event ${index} in session '${sessionId}' lapsed without renewal`));
+			}
+			scheduleLapse();
+		};
+		const scheduleLapse = () => {
+			if (lapseTimer) {
+				clearTimeout(lapseTimer);
+				lapseTimer = null;
+			}
+			let next = Number.POSITIVE_INFINITY;
+			for (const entry of active.values()) if (!entry.lapsed) next = Math.min(next, entry.expiresAtMs);
+			if (next === Number.POSITIVE_INFINITY) return;
+			lapseTimer = setTimeout(lapseDue, Math.max(0, next - Date.now()));
+			lapseTimer.unref?.();
+		};
+		const scheduleRenewRetry = () => {
+			if (stopRenewing || retryTimer) return;
+			const nowMs = Date.now();
+			if (![...active.values()].some((entry) => !entry.lapsed && entry.expiresAtMs > nowMs)) return;
+			const delay = DRAIN_TIMINGS.renewRetryMs * (.5 + Math.random() * .5);
+			retryTimer = setTimeout(() => {
+				retryTimer = null;
+				renew();
+			}, delay);
+			retryTimer.unref?.();
+		};
+		const alignWatchdogAt = (minimumDueAt) => {
+			if (watchdogDueAt === void 0) return minimumDueAt;
+			return watchdogDueAt + Math.max(0, Math.ceil((minimumDueAt - watchdogDueAt) / DRAIN_TIMINGS.claimHeartbeatMs)) * DRAIN_TIMINGS.claimHeartbeatMs;
+		};
+		const requestWatchdog = (dueAt) => {
+			const arm = startSchedulerArm(sessionId, alignWatchdogAt(dueAt));
+			if (arm) schedulerArm = arm;
+		};
+		const renew = () => {
+			if (stopRenewing || renewal || active.size === 0) return renewal ?? Promise.resolve();
+			const window = nextClaimWindow();
+			requestWatchdog(window.watchdogAtMs);
+			const claims = [...active.entries()].map(([index, entry]) => ({
+				index,
+				attempt: entry.attempt
+			}));
+			const operation = store.renewClaims({
+				sessionId: ns,
+				holder,
+				claims,
+				ttlMs: window.ttlMs,
+				...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {}
+			}).then((result) => {
+				for (const index of result.renewed) {
+					const entry = active.get(index);
+					if (entry && !entry.lapsed) entry.expiresAtMs = window.expiresAtMs;
+				}
+				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
+					});
+				}
+				if (window.deadlineCapped) stopRenewing = true;
+				scheduleLapse();
+			}, () => {
+				scheduleRenewRetry();
+			});
+			let tracked;
+			tracked = operation.finally(() => {
+				if (renewal === tracked) renewal = null;
+			});
+			renewal = tracked;
+			return tracked;
+		};
+		const runEvent = async (event, supersedeSignal) => {
+			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 = supersedeSignal;
+				let returned;
+				try {
+					if (registration?.abortOn) {
+						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 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) {
+					if (supersedeSignal.aborted && err === supersedeSignal.reason) {
+						eventSpan.setAttribute("a2.event.outcome", "surrendered");
+						return {
+							status: "surrendered",
+							opensLane: false,
+							appendsEvents: false
+						};
+					}
+					eventSpan.recordError(err);
+					const failure = await store.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 store.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, 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
+				});
+			}
+			const supersede = new AbortController();
+			let fence;
+			const fenced = new Promise((resolve) => {
+				fence = resolve;
+			});
+			let entry;
+			const execution = Promise.race([runEvent(event, supersede.signal), fenced]).then((eventOutcome) => {
+				if (active.get(event.index) === entry) 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;
+			});
+			entry = {
+				attempt: event.attemptCount,
+				execution,
+				supersede,
+				fence,
+				expiresAtMs,
+				lapsed: false
+			};
+			active.set(event.index, entry);
+			scheduleLapse();
+			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 store.claimAvailable({
+						sessionId: ns,
+						holder,
+						ttlMs: window.ttlMs,
+						...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
+						...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
+					});
+					if (claim.outcome === "claimed") {
+						requestWatchdog(window.watchdogAtMs);
+						if (window.deadlineCapped) stopRenewing = true;
+						for (const event of claim.events) start(event, window.expiresAtMs);
+						shouldClaim = false;
+					}
+				}
+				if (active.size > 0) {
+					const wake = signal?.wait(signalVersion);
+					await Promise.race([...[...active.values()].map((entry) => entry.execution), ...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") {
+					requestWatchdog(claim.retryAt.getTime() + DRAIN_TIMINGS.watchdogGraceMs);
+					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);
+			if (retryTimer) clearTimeout(retryTimer);
+			await renewal;
+			await Promise.allSettled([...active.values()].map((entry) => entry.execution));
+			if (lapseTimer) clearTimeout(lapseTimer);
+		}
+		span.setAttribute("a2.drain.processed", processed);
+		span.setAttribute("a2.drain.outcome", outcome);
+		return {
+			settled: outcome === "settled",
+			outcome,
+			processed,
+			...schedulerArm ? { schedulerArm } : {}
+		};
+	});
+	const appendExternal = async (sessionId, mode, events, requireDurableInitialArm = false) => {
+		const pushed = events.filter((event) => Reflect.get(event, "~a2.pushed") === true);
+		if (pushed.length > 0) await options.validatePush?.({
+			sessionId,
+			events: pushed
+		});
+		return appendCore(sessionId, events, "external", mode, (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt), void 0, void 0, requireDurableInitialArm);
+	};
+	const self = {
+		contract: serverContract,
+		session(id) {
+			assertSessionId(id);
+			const appendInline = async (...events) => appendExternal(id, "inline", events);
+			const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
+			const append = Object.assign(appendInline, { dispatch: appendDispatch });
+			return makeSession(id, append, null);
+		},
+		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);
+		},
+		schedulerDrain: (sessionId, opts) => {
+			assertSessionId(sessionId);
+			return drainSession(sessionId, opts?.watchdogDueAt);
+		},
+		schedulerAppend: async (sessionId, events) => {
+			if (!scheduler) throw new TypeError("scheduled append delivery requires a configured scheduler adapter");
+			assertSessionId(sessionId);
+			await appendExternal(sessionId, "inline", [...events], true);
+		}
+	});
+	serverSchedulerBindings.set(self, { scheduler });
+	serverInspection.set(self, {
+		async listSessions(inspectionOptions) {
+			const store = await resolveStore();
+			if (!store.inspect) throw new InspectionUnsupportedError("this store backend does not support inspection");
+			const page = await store.inspect.listSessions({
+				prefix: `${name}${NS}`,
+				limit: inspectionOptions.limit,
+				...inspectionOptions.cursor !== void 0 ? { cursor: inspectionOptions.cursor } : {}
+			});
+			return {
+				cursor: page.cursor,
+				sessions: page.sessions.map((session) => {
+					const publicSession = { ...session };
+					publicSession.sessionId = stripNs(session.sessionId);
+					return publicSession;
+				})
+			};
+		},
+		async readSessionPage(sessionId, inspectionOptions) {
+			assertSessionId(sessionId);
+			if (!Number.isSafeInteger(inspectionOptions.afterIndex) || inspectionOptions.afterIndex < 0 || !Number.isSafeInteger(inspectionOptions.limit) || inspectionOptions.limit < 1 || inspectionOptions.throughIndex !== void 0 && (!Number.isSafeInteger(inspectionOptions.throughIndex) || inspectionOptions.throughIndex < 0)) throw new TypeError("invalid inspection event page bounds");
+			const store = await resolveStore();
+			if (!store.inspect) throw new InspectionUnsupportedError("this store backend does not support inspection");
+			const ns = nsId(sessionId);
+			const snapshots = inspectionOptions.afterIndex === 0 ? await store.inspect.listSnapshots(ns) : [];
+			const { events, throughIndex } = store.inspect.readEvents ? await store.inspect.readEvents(ns, inspectionOptions) : await (async () => {
+				const all = await store.read(ns);
+				const currentFrontier = all.at(-1)?.index ?? 0;
+				const throughIndex = Math.min(inspectionOptions.throughIndex ?? currentFrontier, currentFrontier);
+				return {
+					events: all.filter((event) => event.index > inspectionOptions.afterIndex && event.index <= throughIndex).slice(0, inspectionOptions.limit),
+					throughIndex
+				};
+			})();
+			if (!Number.isSafeInteger(throughIndex) || throughIndex < 0 || events.length > inspectionOptions.limit || inspectionOptions.throughIndex !== void 0 && inspectionOptions.afterIndex > 0 && throughIndex !== inspectionOptions.throughIndex) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' has invalid bounds`);
+			for (let position = 0; position < events.length; position += 1) if (events[position].index !== inspectionOptions.afterIndex + position + 1 || events[position].index > throughIndex) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' is not contiguous`);
+			if (inspectionOptions.afterIndex < throughIndex && events.length === 0) throw new A2Error("STORE_UNAVAILABLE", `inspection event page for session '${sessionId}' ended before index ${throughIndex}`);
+			const lastIndex = events.at(-1)?.index ?? inspectionOptions.afterIndex;
+			return {
+				events: events.map((event) => {
+					const publicEvent = { ...event };
+					publicEvent.sessionId = sessionId;
+					return publicEvent;
+				}),
+				snapshots: snapshots.filter((snapshot) => snapshot.index <= throughIndex),
+				throughIndex,
+				nextIndex: lastIndex < throughIndex ? lastIndex : null
+			};
+		}
+	});
+	return self;
+}
+function assertSessionId(id) {
+	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 assertHistoryIndex(name, value) {
+	if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) throw new TypeError(`history.${name} must be a non-negative safe integer`);
+}
+function assertStreamIndex(value) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("stream.startAfter 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");
+}
+function assertScheduleName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("schedule name must be a non-empty string");
+}
+const SCHEDULE_DELAY = /^(?:0|[1-9]\d*)(?:\.\d+)?(ms|s|m|h|d)$/;
+const SCHEDULE_DELAY_MULTIPLIER = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+function scheduleDueAt(timing, baseTime) {
+	if (timing === null || typeof timing !== "object" || Array.isArray(timing)) throw new TypeError("schedule timing must contain exactly one of 'delay' or 'at'");
+	const record = timing;
+	const hasDelay = Object.hasOwn(record, "delay");
+	const hasAt = Object.hasOwn(record, "at");
+	if (hasDelay === hasAt) throw new TypeError("schedule timing must contain exactly one of 'delay' or 'at'");
+	let dueAt;
+	if (hasAt) {
+		const at = record["at"];
+		if (!(at instanceof Date) || !Number.isFinite(at.getTime())) throw new TypeError("schedule at must be a valid Date");
+		dueAt = at.getTime();
+	} else {
+		const delay = record["delay"];
+		if (typeof delay !== "string") throw new TypeError("schedule delay must use ms, s, m, h, or d (for example '30s')");
+		const match = SCHEDULE_DELAY.exec(delay);
+		const amount = match ? Number(delay.slice(0, -match[1].length)) : NaN;
+		if (!match || !Number.isFinite(amount) || amount <= 0) throw new TypeError("schedule delay must be positive and use ms, s, m, h, or d (for example '30s')");
+		dueAt = baseTime + amount * SCHEDULE_DELAY_MULTIPLIER[match[1]];
+	}
+	if (!Number.isFinite(dueAt)) throw new TypeError("schedule due time must be a finite epoch time");
+	return dueAt;
+}
+function assertScheduledPayload(payload) {
+	try {
+		if (isJsonValue(payload, /* @__PURE__ */ new WeakSet())) return;
+	} catch {}
+	throw new TypeError("session.schedule event payload must be JSON-serializable");
+}
+function cloneScheduledPayload(payload) {
+	assertScheduledPayload(payload);
+	try {
+		const cloned = structuredClone(payload);
+		const encoded = JSON.stringify(cloned);
+		if (encoded === void 0) throw new TypeError();
+		return JSON.parse(encoded);
+	} catch {
+		throw new TypeError("session.schedule event payload must be JSON-serializable");
+	}
+}
+function isJsonValue(value, ancestors) {
+	if (value === null) return true;
+	if (typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0);
+	if (typeof value !== "object") return false;
+	if (ancestors.has(value)) return false;
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			const keys = Reflect.ownKeys(value);
+			if (keys.length !== value.length + 1 || !keys.includes("length")) return false;
+			for (let index = 0; index < value.length; index += 1) {
+				const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+				if (!descriptor || !descriptor.enumerable || !("value" in descriptor) || !isJsonValue(descriptor.value, ancestors)) return false;
+			}
+			return true;
+		}
+		if (Object.getPrototypeOf(value) !== Object.prototype) return false;
+		for (const key of Reflect.ownKeys(value)) {
+			if (typeof key !== "string") return false;
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			if (!descriptor || !descriptor.enumerable || !("value" in descriptor) || !isJsonValue(descriptor.value, ancestors)) return false;
+		}
+		return true;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+function cloneInitial(initial) {
+	try {
+		return structuredClone(initial);
+	} catch {
+		return initial;
+	}
+}
+//#endregion
+export { deliverSchedulerAppend as n, createServer as t };