experimental-a2 0.20.0 → 0.21.1

package/dist/{server-qyb5aJJG.js → server-DvIB8kj5.js}

@@ -1,12 +1,12 @@
-import { a as NonRetriableError, i as A2Error, n as isSessionCleared, o as asStoreUnavailable, r as sessionClearedError } from "./session-clear-DGI4jTQ5.js";
-import { n as foldEvent, s as validateSync, t as cloneInitial } from "./reducer-BAXc8JyF.js";
+import { a as NonRetriableError, i as A2Error, n as isSessionCleared, o as asStoreUnavailable, r as sessionClearedError } from "./session-clear-wHd5GCpZ.js";
+import { n as foldEvent, s as validateSync, t as cloneInitial } from "./reducer-CjmvZSAb.js";
 import { n as encodeState, t as decodeState } from "./reducer-runtime-DQwz_J59.js";
-import { _ as nullProtoRecord, c as STATE_CACHE, g as markSchedulerSendFailure, i as POLL_TIMINGS, l as STREAM_TIMINGS, m as failedPreviousAttempt, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS, v as serverInternals, y as stateTailReaders } from "./internal-CscSY7K_.js";
+import { _ as nullProtoRecord, b as serverInternals, c as STATE_CACHE, g as markSchedulerSendFailure, i as POLL_TIMINGS, l as STREAM_TIMINGS, m as failedPreviousAttempt, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS, v as runtimeConsumerFactory, x as stateTailReaders, y as runtimeConsumers } from "./internal-Bc4PvfHk.js";
 import { t as boundedCache } from "./bounded-cache-CPHWF-8h.js";
-import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-7WJV0YWP.js";
+import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-DYNyxCev.js";
 import { i as takeBuffered, n as isSerializedEvent, r as parseSerializedEvent, t as bufferedEvents } from "./stream-buffer-Cx7AAPGq.js";
 import { r as platformWaitUntil, t as invocationDeadlineMs } from "./platform-B4TnJtWu.js";
-import { A as stateSnapshotToWire, C as serializedEventToWireJson, D as socketFrameFor, E as socketEventsFor, O as socketSubscribedFor, S as presenceSnapshotToWire, T as socketErrorAckFor, b as presencePatchToWire, d as heldEventBatch, i as compactEventJson, j as wireVersion, k as socketUnsubscribedFor, m as isStreamEvent, n as SOCKET_PING_FRAME, o as errorStatus, r as asA2Error, s as errorToWire, t as EVENT_WRITE_CHARS, u as eventToWire, w as socketAckFor } from "./wire-BKxH1vbP.js";
+import { A as stateSnapshotToWire, C as serializedEventToWireJson, D as socketFrameFor, E as socketEventsFor, O as socketSubscribedFor, S as presenceSnapshotToWire, T as socketErrorAckFor, b as presencePatchToWire, d as heldEventBatch, i as compactEventJson, j as wireVersion, k as socketUnsubscribedFor, m as isStreamEvent, n as SOCKET_PING_FRAME, o as errorStatus, r as asA2Error, s as errorToWire, t as EVENT_WRITE_CHARS, u as eventToWire, w as socketAckFor } from "./wire-CZGqNZRx.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 //#region src/push-envelope.ts
 /**
@@ -34,6 +34,10 @@ function parsePresenceSibling(value) {
 	if (at !== void 0) out.at = at;
 	return out;
 }
+/** The longest event id a push may carry: ids are indexed, and Postgres's index rows have a limit. */
+const MAX_PUSHED_ID = 256;
+/** A UUIDv5, the shape of the ids A2 derives (deterministic-id.ts). */
+const DERIVED_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 /** The events half of the envelope, shared by the POST body and socket
 * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
 function parsePushEvents(events) {
@@ -43,6 +47,8 @@ function parsePushEvents(events) {
 		const { type, payload, id } = event;
 		if (typeof type !== "string" || type.length === 0) throw invalid(`events[${i}].type must be a non-empty string`);
 		if (id !== void 0 && typeof id !== "string") throw invalid(`events[${i}].id must be a string when present`);
+		if (id !== void 0 && (id.length === 0 || id.length > MAX_PUSHED_ID)) throw invalid(`events[${i}].id must be 1-${MAX_PUSHED_ID} characters when present`);
+		if (id !== void 0 && DERIVED_ID.test(id)) throw invalid(`events[${i}].id is shaped like the ids A2 derives for consumers (a UUIDv5); use crypto.randomUUID() or idempotentId()`);
 		const out = {
 			type,
 			payload
@@ -982,7 +988,7 @@ function createServerFetch(server) {
 //#endregion
 //#region src/deterministic-id.ts
 /**
-* Deterministic default ids for handler `session.append` calls. A handler
+* Deterministic default ids for consumer `session.append` calls. A consumer
 * 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
@@ -1008,20 +1014,27 @@ async function deterministicIdFromInput(input) {
 async function deterministicId(parts) {
 	return deterministicIdFromInput(parts.join("\0"));
 }
-async function deterministicEventId(triggerEventId, name, itemOrdinal) {
+/**
+* `consumer` keys the id on the consumer that appends, so two consumers of
+* one event never collide. A2's own consumers pass none: their types are
+* disjoint, so the event alone keys them.
+*/
+async function deterministicEventId(triggerEventId, name, itemOrdinal, consumer) {
 	if (name.length === 0) throw new TypeError("append name must not be empty");
 	return deterministicId([
 		APPEND_NAMESPACE,
 		triggerEventId,
 		name,
-		itemOrdinal
+		itemOrdinal,
+		...consumer === void 0 ? [] : [consumer]
 	]);
 }
-async function deterministicReturnedEventId(triggerEventId, itemOrdinal) {
+async function deterministicReturnedEventId(triggerEventId, itemOrdinal, consumer) {
 	return deterministicId([
 		RETURN_NAMESPACE,
 		triggerEventId,
-		itemOrdinal
+		itemOrdinal,
+		...consumer === void 0 ? [] : [consumer]
 	]);
 }
 /**
@@ -1030,17 +1043,18 @@ async function deterministicReturnedEventId(triggerEventId, itemOrdinal) {
 * after a clear schedules a distinct task while sessions never cleared keep
 * the ids they always had.
 */
-async function deterministicScheduleId(contract, sessionId, triggerEventId, name, clearIndex = 0) {
+async function deterministicScheduleId(contract, sessionId, triggerEventId, name, clearIndex = 0, consumer) {
 	return deterministicIdFromInput(JSON.stringify([
 		SCHEDULE_NAMESPACE,
 		contract,
 		sessionId,
 		triggerEventId,
 		name,
-		...clearIndex > 0 ? [clearIndex] : []
+		...clearIndex > 0 ? [clearIndex] : [],
+		...consumer === void 0 ? [] : [{ consumer }]
 	]));
 }
-async function deterministicScheduleClearId({ contract, sessionId, triggerEventId, clearIndex, name, ifLastIndex }) {
+async function deterministicScheduleClearId({ contract, sessionId, triggerEventId, clearIndex, name, ifLastIndex, consumer }) {
 	return deterministicIdFromInput(JSON.stringify([
 		SCHEDULE_CLEAR_NAMESPACE,
 		contract,
@@ -1048,7 +1062,8 @@ async function deterministicScheduleClearId({ contract, sessionId, triggerEventI
 		triggerEventId,
 		clearIndex,
 		name,
-		ifLastIndex
+		ifLastIndex,
+		...consumer === void 0 ? [] : [{ consumer }]
 	]));
 }
 async function deterministicScheduledEventId(scheduleId, itemOrdinal) {
@@ -1101,13 +1116,76 @@ async function deliverSchedulerClear(server, task) {
 	if (!internals) throw new TypeError(`a2 scheduler: server for contract '${task.contract}' cannot receive scheduled clears`);
 	await internals.schedulerClear(task.sessionId, task.ifLastIndex);
 }
-function handler(entry) {
-	return typeof entry === "function" ? { handler: entry } : entry;
+const CONSUMER_NAME = /^[a-z0-9][a-z0-9._:-]{0,127}$/i;
+/** Define a consumer: a named reader of each session's log. */
+function consumer(options) {
+	return defineConsumer(options, false);
+}
+/**
+* `consumer()`, and for A2's own runtimes (`runtime`) a name under `a2.` and
+* child ids without the name: their types are disjoint, so the event alone
+* keys them, and regrouping A2's consumers never changes an id.
+*/
+function defineConsumer(options, runtime) {
+	const contract = options?.contract;
+	if (!contract || typeof contract.name !== "string") throw new TypeError("consumer expects options with a contract");
+	const consumerName = options.name;
+	if (typeof consumerName !== "string" || !CONSUMER_NAME.test(consumerName)) throw new TypeError("consumer name must be 1-128 letters, digits, and . _ : - characters");
+	if (consumerName.startsWith("a2.") !== runtime) throw new TypeError(runtime ? `A2's own consumers are named under 'a2.'` : `consumer names starting with 'a2.' are reserved`);
+	const types = options.types === void 0 ? null : [...options.types];
+	if (types?.length === 0) throw new TypeError(`consumer '${consumerName}' lists no types; leave types out to take every type`);
+	for (const type of types ?? []) if (!Object.hasOwn(contract.events, type)) throw new TypeError(`contract '${contract.name}' has no event type '${String(type)}'`);
+	const lane = options.lane ?? null;
+	if (lane !== null && typeof lane !== "function" && (typeof lane !== "string" || lane.length === 0)) throw new TypeError(`lane for consumer '${consumerName}' must be a non-empty string or a function`);
+	const backfill = options.backfill ?? false;
+	if (backfill && typeof lane !== "string") throw new TypeError(`consumer '${consumerName}' backfills, so its lane must be a string`);
+	if (backfill && options.abortOn !== void 0) throw new TypeError(`consumer '${consumerName}' backfills, so it can't use abortOn`);
+	return { run(fn) {
+		if (typeof fn !== "function") throw new TypeError(`consumer '${consumerName}' needs a run function`);
+		const defined = {
+			name: consumerName,
+			contract: { name: contract.name },
+			spec: {
+				types,
+				lane,
+				backfill,
+				abortOn: options.abortOn ?? null,
+				run: fn
+			}
+		};
+		if (runtime) runtimeConsumers.add(defined);
+		return defined;
+	} };
 }
+runtimeConsumerFactory.define = (options) => defineConsumer(options, true);
+/** A registered consumer as the store needs to know it. */
+const storeConsumerOf = (registered) => registered.log ? {
+	name: registered.name,
+	log: registered.log
+} : { name: registered.name };
 const MAX_FAILURES = 10;
+/** How long `consume` waits before looking again at a head it can't run. */
+const CONSUME_WAIT_MIN_MS = 25;
+const CONSUME_WAIT_MAX_MS = 1e3;
+/**
+* `task`, or a rejection with `signal`'s reason once it aborts. The task runs
+* on either way, and its own failure is caught, so nothing goes unhandled.
+*/
+const untilAborted = (task, signal) => {
+	if (!signal) return task;
+	task.catch(() => {});
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(signal.reason);
+		signal.addEventListener("abort", abort, { once: true });
+		task.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", abort);
+		});
+	});
+};
 /** How long an event waits after its `failureCount`th failed attempt. */
 const failureRetryDelayMs = (failureCount) => Math.min(DRAIN_TIMINGS.failureRetryBaseMs * 2 ** Math.max(failureCount - 1, 0), DRAIN_TIMINGS.failureRetryMaxMs);
-/** Abort a lost attempt's handler and release its drain slot. */
+/** Abort a lost attempt's consumer and release its drain slot. */
 function endSuperseded(entry, message) {
 	entry.supersede.abort(new A2Error("SUPERSEDED_ATTEMPT", message));
 	entry.fence({
@@ -1242,21 +1320,35 @@ function foldPresenceRows(rows) {
 	};
 	return map;
 }
-const addSnapshotWrite = (writes, index, state, pinEventIndex) => {
+/** One cursor head, as a map key. */
+const headKey = (ref) => JSON.stringify([
+	ref.consumer,
+	ref.lane,
+	ref.index
+]);
+const headRefOf = (head) => ({
+	consumer: head.consumer,
+	lane: head.lane,
+	index: head.index
+});
+const addSnapshotWrite = (writes, index, state, pin) => {
 	let write = writes.get(index);
 	if (!write) {
 		write = {
 			state: cloneInitial(state),
-			pinEventIndexes: /* @__PURE__ */ new Set()
+			pins: /* @__PURE__ */ new Map()
 		};
 		writes.set(index, write);
 	}
-	if (pinEventIndex !== void 0) write.pinEventIndexes.add(pinEventIndex);
+	if (pin !== void 0) write.pins.set(headKey(pin), pin);
 };
+/** Whether a registered consumer runs events of this type. */
+const takes = (registered, type) => registered.types === null || registered.types.has(type);
 /** 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)");
+	if (Object.hasOwn(options, "handlers")) throw new TypeError("createServer no longer takes handlers: write each as a consumer in `consumers` (see https://www.a2.dev/upgrades/0-21)");
 	const name = serverContract.name;
 	const defs = serverContract.events;
 	const presenceDefs = serverContract.presence;
@@ -1292,15 +1384,9 @@ function createServer(options) {
 	const resolveStore = retryableLazy(makeStore).get;
 	const telemetry = options.telemetry ?? CONSOLE_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 callback = typeof entry === "function" ? entry : entry?.handler;
-		if (typeof callback !== "function") throw new TypeError(`handler for '${type}' must be a function`);
+	const abortMatcherOf = (spec) => {
 		let abortOn = null;
-		const spec = typeof entry === "function" ? void 0 : entry.abortOn;
-		if (spec !== void 0) {
+		if (spec !== void 0 && spec !== null) {
 			abortOn = /* @__PURE__ */ new Map();
 			const pairs = Array.isArray(spec) ? spec.map((abortType) => [abortType, true]) : Object.entries(spec);
 			for (const [abortType, matcher] of pairs) {
@@ -1310,14 +1396,70 @@ function createServer(options) {
 			}
 			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: callback,
-			abortOn,
-			lane
-		});
+		return abortOn;
+	};
+	const laneContext = (sessionId, event) => ({
+		sessionId,
+		event: {
+			type: event.type,
+			payload: structuredClone(event.payload),
+			...event.id === void 0 ? {} : { id: event.id }
+		}
+	});
+	const registeredConsumers = /* @__PURE__ */ new Map();
+	/** A consumer definition as the server runs it. */
+	const registrationOf = (defined) => {
+		const { types, lane, backfill, abortOn, run } = defined.spec;
+		const matcher = abortMatcherOf(abortOn);
+		return {
+			name: defined.name,
+			types: types === null ? null : new Set(types),
+			laneOf: typeof lane === "string" ? null : lane === null ? () => null : (sessionId, event) => {
+				const resolved = lane(laneContext(sessionId, event));
+				if (resolved !== null && (typeof resolved !== "string" || resolved.length === 0)) throw new TypeError(`lane for consumer '${defined.name}' must resolve to a non-empty string or null`);
+				return resolved;
+			},
+			log: typeof lane === "string" ? {
+				lane,
+				types: types === null ? null : [...types],
+				backfill
+			} : void 0,
+			abortOn: () => matcher,
+			run,
+			anonymousIds: runtimeConsumers.has(defined)
+		};
+	};
+	/** The definitions the server runs, so `consume` can tell its own from another. */
+	const definitions = /* @__PURE__ */ new Map();
+	/** A consumer written inline is `consumer()`'s options and `run`, on this contract. */
+	const definitionOf = (entry) => {
+		if (entry === null || typeof entry !== "object" || "spec" in entry || !("run" in entry)) return entry;
+		const { run, ...rest } = entry;
+		return consumer({
+			...rest,
+			contract: serverContract
+		}).run(run);
+	};
+	for (const entry of options.consumers ?? []) {
+		const defined = definitionOf(entry);
+		if (defined?.contract?.name !== name || !defined.spec) throw new TypeError(`createServer for '${name}' got a consumer of another contract`);
+		if (registeredConsumers.has(defined.name)) throw new TypeError(`two consumers are named '${defined.name}'`);
+		registeredConsumers.set(defined.name, registrationOf(defined));
+		definitions.set(defined.name, defined);
+	}
+	const anonymousTypes = /* @__PURE__ */ new Map();
+	for (const registered of registeredConsumers.values()) {
+		if (!registered.anonymousIds) continue;
+		for (const type of registered.types ?? Object.keys(defs)) {
+			const other = anonymousTypes.get(type);
+			if (other !== void 0) throw new TypeError(`A2's consumers '${other}' and '${registered.name}' both take '${type}'`);
+			anonymousTypes.set(type, registered.name);
+		}
 	}
+	/** The consumers this server serves, as the store needs to know them. */
+	const storeConsumers = [...registeredConsumers.values()].map(storeConsumerOf);
+	/** Whether an event starts cursor work for any consumer. */
+	const startsWork = (event) => (event.targets?.length ?? 0) > 0 || [...registeredConsumers.values()].some((registered) => registered.log && takes(registered, event.type));
 	const prefix = `${name}${NS}`;
 	const nsId = (sessionId) => `${prefix}${sessionId}`;
 	const stripNs = (stored) => stored.slice(prefix.length);
@@ -1414,20 +1556,15 @@ function createServer(options) {
 			};
 			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;
+			const targets = [];
+			for (const registered of registeredConsumers.values()) {
+				if (!registered.laneOf || !takes(registered, e.type)) continue;
+				targets.push({
+					consumer: registered.name,
+					lane: registered.laneOf(sessionId, validated)
+				});
 			}
+			if (targets.length > 0) validated.targets = targets;
 			return validated;
 		});
 	};
@@ -1455,9 +1592,12 @@ function createServer(options) {
 		let rows;
 		let shouldHealSession;
 		try {
-			const result = await store.append(nsId(sessionId), validated, originIndex === void 0 ? void 0 : { originIndex });
+			const result = await store.append(nsId(sessionId), validated, {
+				consumers: storeConsumers,
+				...originIndex === void 0 ? {} : { originIndex }
+			});
 			rows = result.events;
-			shouldHealSession = result.hasPending && !(source === "handler" && validated.every((event) => event.settled === true));
+			shouldHealSession = result.hasPending && !(source === "consumer" && !validated.some(startsWork));
 		} catch (err) {
 			throw asStoreUnavailable(err);
 		}
@@ -1566,7 +1706,7 @@ function createServer(options) {
 					state: write.state
 				})
 			};
-			if (write.pinEventIndexes.size > 0) snapshot.pinEventIndexes = [...write.pinEventIndexes];
+			if (write.pins.size > 0) snapshot.pins = [...write.pins.values()];
 			return snapshot;
 		});
 		if (snapshots.length > 0) persistSnapshots({
@@ -1635,7 +1775,7 @@ function createServer(options) {
 	/**
 	* Serves a plan from the cached state when every read is at or past the
 	* cached index. A read bounded at the cached index by an event whose id
-	* matches the cached one (a handler's own trigger) needs no store request;
+	* matches the cached one (a consumer's own trigger) needs no store request;
 	* any other read fetches the tail from the cached event onward and checks
 	* that event's id. Returns false when the store must answer instead.
 	*/
@@ -1665,14 +1805,14 @@ function createServer(options) {
 			clearIndex: cached.clearIndex,
 			snapshot: "memory",
 			visit: (entry, state, index) => {
-				if (entry.pinEventIndex !== void 0) addSnapshotWrite(writes, index, state, entry.pinEventIndex);
+				if (entry.pin !== void 0) addSnapshotWrite(writes, index, state, entry.pin);
 			}
 		});
 		const added = Math.max(0, folded.position - 1);
 		const rewritesHead = folded.index - cached.persistedIndex >= STATE_CACHE.snapshotEvery;
 		if (rewritesHead && !writes.has(folded.index)) writes.set(folded.index, {
 			state: folded.state,
-			pinEventIndexes: /* @__PURE__ */ new Set()
+			pins: /* @__PURE__ */ new Map()
 		});
 		const snapshots = writeSnapshots({
 			store,
@@ -1746,11 +1886,11 @@ function createServer(options) {
 			snapshot: snapshotOutcome,
 			visit: (entry, entryState, entryIndex, count) => {
 				if (entryIndex === 0) return;
-				if (count === 0 && entry.pinEventIndex === void 0) return;
+				if (count === 0 && entry.pin === void 0) return;
 				const advancesHead = stateRead.headIndex === null || entryIndex > stateRead.headIndex;
 				const repairsHead = snapshotOutcome === "rejected" && entryIndex === stateRead.headIndex;
-				if (!advancesHead && !repairsHead && entry.pinEventIndex === void 0) return;
-				addSnapshotWrite(writes, entryIndex, entryState, entry.pinEventIndex);
+				if (!advancesHead && !repairsHead && entry.pin === void 0) return;
+				addSnapshotWrite(writes, entryIndex, entryState, entry.pin);
 			}
 		});
 		const snapshots = writeSnapshots({
@@ -1832,6 +1972,8 @@ function createServer(options) {
 	};
 	const makeSchedule = (sessionId, trigger) => {
 		const triggerEventId = trigger?.id ?? null;
+		/** Timers a consumer sets key on its name, except A2's own. */
+		const triggerConsumer = trigger && !registeredConsumers.get(trigger.consumer)?.anonymousIds ? trigger.consumer : void 0;
 		const triggerCreatedAt = trigger?.createdAt.getTime();
 		const clearIndex = trigger?.clearIndex ?? 0;
 		const schedule = async (scheduleName, timing, ...events) => {
@@ -1849,7 +1991,7 @@ function createServer(options) {
 				id: event.id
 			});
 			const validated = validateEvents(sessionId, structuredClone(snapshottedEvents), false);
-			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName, clearIndex);
+			const scheduleId = await deterministicScheduleId(name, sessionId, triggerEventId, scheduleName, clearIndex, triggerConsumer);
 			const scheduledEvents = await Promise.all(validated.map(async (event, item) => ({
 				id: event.id ?? await deterministicScheduledEventId(scheduleId, item),
 				type: event.type,
@@ -1886,7 +2028,8 @@ function createServer(options) {
 				triggerEventId,
 				clearIndex,
 				name: scheduleName,
-				ifLastIndex
+				ifLastIndex,
+				...triggerConsumer === void 0 ? {} : { consumer: triggerConsumer }
 			});
 			try {
 				await scheduler.schedule({
@@ -2332,6 +2475,7 @@ function createServer(options) {
 		}
 		return rows.flatMap((row) => row.failedAt === null ? [] : [{
 			...toPublic(row),
+			consumer: row.consumer,
 			lane: row.lane,
 			attemptCount: row.attemptCount,
 			failureCount: row.failureCount,
@@ -2339,14 +2483,18 @@ function createServer(options) {
 			failedAt: row.failedAt
 		}]);
 	};
-	const redriveEvent = async (sessionId, index, redriveOptions) => {
+	const redriveEvent = async (sessionId, target, redriveOptions) => {
+		const index = target?.index;
+		const redriven = target?.consumer;
 		assertRedriveIndex(index);
+		if (typeof redriven !== "string" || redriven.length === 0) throw new TypeError("redrive requires a consumer name");
 		const action = redriveOptions?.action;
 		if (action !== "retry" && action !== "skip") throw new TypeError("redrive requires action 'retry' or 'skip'");
 		return telemetry.span("a2.redrive", {
 			"a2.contract": name,
 			"a2.session_id": sessionId,
 			"a2.redrive.index": index,
+			"a2.redrive.consumer": redriven,
 			"a2.redrive.action": action
 		}, async (span) => {
 			const store = await redrivingStore("redrive");
@@ -2354,8 +2502,10 @@ function createServer(options) {
 			try {
 				result = await store.redrive({
 					sessionId: nsId(sessionId),
+					consumer: redriven,
 					index,
-					action
+					action,
+					consumers: storeConsumers
 				});
 			} catch (err) {
 				throw asStoreUnavailable(err);
@@ -2375,9 +2525,100 @@ function createServer(options) {
 			return { redriven: result.redriven };
 		});
 	};
+	/**
+	* `session.consume`: wakes the consumer's cursor, then drains only that
+	* consumer until its head lies past `through`. A head another invocation
+	* holds, or one waiting out a failure, is waited for; a dead-lettered head
+	* throws.
+	*/
+	/** Per session, which consumer's running head is waiting in `consume` on which: a cycle never ends. */
+	const consumeWaits = /* @__PURE__ */ new Map();
+	const consumeSession = (sessionId, defined, consumeOptions = {}, trigger = null) => {
+		assertSessionId(sessionId);
+		if (defined?.contract?.name !== name || !defined.spec) throw new TypeError(`session.consume for '${name}' got a consumer of another contract`);
+		const own = definitions.get(defined.name);
+		if (own !== void 0 && own !== defined) throw new TypeError(`this server runs a different consumer named '${defined.name}'`);
+		if (defined.name === trigger?.consumer) throw new TypeError(`consumer '${defined.name}' can't consume itself: its own head is running`);
+		const registered = own ? registeredConsumers.get(defined.name) : registrationOf(defined);
+		const log = registered.log;
+		if (!log) throw new TypeError(`consumer '${defined.name}' needs a string lane to be consumed: only then does it have one position`);
+		const { through: requested, signal } = consumeOptions;
+		if (requested !== void 0) assertConsumeIndex(requested);
+		const waiter = trigger?.consumer;
+		const waits = waiter === void 0 ? void 0 : consumeWaits.get(sessionId) ?? consumeWaits.set(sessionId, /* @__PURE__ */ new Map()).get(sessionId);
+		let cycle = false;
+		if (waiter !== void 0 && waits) {
+			for (let next = defined.name; next !== void 0 && !cycle; next = waits.get(next)) cycle = next === waiter;
+			if (!cycle) waits.set(waiter, defined.name);
+		}
+		const storeConsumer = {
+			name: registered.name,
+			log
+		};
+		const consumed = telemetry.span("a2.consume", {
+			"a2.contract": name,
+			"a2.session_id": sessionId,
+			"a2.consume.consumer": registered.name
+		}, async (span) => {
+			const store = await resolveStore();
+			const ns = nsId(sessionId);
+			let woken = await store.wakeLog({
+				sessionId: ns,
+				consumer: storeConsumer
+			});
+			const through = Math.min(requested ?? woken.head, woken.head);
+			span.setAttribute("a2.consume.through", through);
+			const done = () => woken.cursor.head === null || woken.cursor.head > through;
+			if (cycle && !done()) throw new TypeError(`consumer '${waiter}' can't consume '${defined.name}' through ${through}: '${defined.name}' is waiting on it in session '${sessionId}'`);
+			let drains = 0;
+			let wait = CONSUME_WAIT_MIN_MS;
+			while (!done()) {
+				signal?.throwIfAborted();
+				const { cursor } = woken;
+				if (cursor.failedAt !== null) throw new A2Error("CONSUMER_DEAD_LETTERED", `consumer '${registered.name}' is dead-lettered at event ${cursor.head} in session '${sessionId}': ${cursor.lastError ?? "every attempt ended before it finished"}`);
+				drains += 1;
+				const drained = drainSession(sessionId, {
+					only: registered,
+					through
+				});
+				try {
+					await untilAborted(drained, signal);
+				} catch (error) {
+					if (signal?.aborted) drained.then(() => scheduleDrain(sessionId), () => {});
+					throw error;
+				}
+				const before = cursor;
+				woken = await store.wakeLog({
+					sessionId: ns,
+					consumer: storeConsumer
+				});
+				const moved = woken.cursor.head !== before.head || woken.cursor.attemptCount !== before.attemptCount;
+				if (done() || moved) {
+					wait = CONSUME_WAIT_MIN_MS;
+					continue;
+				}
+				const sleep = defaultSleep(wait);
+				const abort = () => sleep.cancel();
+				signal?.addEventListener("abort", abort, { once: true });
+				await sleep.promise;
+				signal?.removeEventListener("abort", abort);
+				wait = Math.min(wait * 2, CONSUME_WAIT_MAX_MS);
+			}
+			if (drains > 0 || own && woken.cursor.head !== null) scheduleDrain(sessionId);
+			const index = woken.cursor.head === null ? woken.head : woken.cursor.head - 1;
+			span.setAttribute("a2.consume.index", index);
+			span.setAttribute("a2.consume.drains", drains);
+			return { index };
+		});
+		return waiter === void 0 || cycle ? consumed : consumed.finally(() => {
+			waits?.delete(waiter);
+			if (waits?.size === 0) consumeWaits.delete(sessionId);
+		});
+	};
 	const makeSession = (id, append, trigger, attempt) => ({
 		id,
 		append,
+		consume: (defined, consumeOptions) => consumeSession(id, defined, consumeOptions, trigger),
 		schedule: makeSchedule(id, trigger),
 		clear: (clearOptions) => clearSession(id, clearOptions, attempt),
 		history: async (bounds) => (await readHistory(id, bounds)).filter((row) => !isSessionCleared(row)).map(toPublic),
@@ -2388,7 +2629,7 @@ function createServer(options) {
 			const bounds = {};
 			if (through !== void 0 && through !== "latest") {
 				bounds.throughIndex = through;
-				if (trigger) bounds.pinEventIndex = trigger.index;
+				if (trigger) bounds.pin = headRefOf(trigger);
 				if (through === trigger?.index && !attempt?.signal.aborted) bounds.throughEventId = trigger.id;
 			}
 			if (trigger) bounds.triggerIndex = trigger.index;
@@ -2404,32 +2645,35 @@ function createServer(options) {
 			presence: () => readPresenceMap(id)
 		} : {}
 	});
+	/** The consumer name a trigger's child ids key on, if any. */
+	const idConsumerOf = (trigger) => registeredConsumers.get(trigger.consumer)?.anonymousIds ? void 0 : trigger.consumer;
 	const makeCtx = (trigger, attempt, signal, endAttempt) => {
 		const publicSessionId = stripNs(trigger.sessionId);
+		const idConsumer = idConsumerOf(trigger);
+		const cause = {
+			consumer: trigger.consumer,
+			lane: trigger.lane,
+			index: trigger.index,
+			attempt
+		};
 		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);
+				const id = await deterministicEventId(trigger.id, appendName, item, idConsumer);
 				return {
 					...event,
 					id
 				};
 			}));
-			return appendCore(publicSessionId, withIds, "handler", "inline", (_rows, watchdogDueAt) => scheduleDrain(publicSessionId, watchdogDueAt), {
-				index: trigger.index,
-				attempt
-			}, generatedIds);
+			return appendCore(publicSessionId, withIds, "consumer", "inline", (_rows, watchdogDueAt) => scheduleDrain(publicSessionId, watchdogDueAt), cause, generatedIds);
 		};
 		const ctx = {
 			event: toPublic(trigger),
 			attempt,
 			session: makeSession(publicSessionId, append, trigger, {
-				cause: {
-					index: trigger.index,
-					attempt
-				},
+				cause,
 				end: endAttempt,
 				signal
 			}),
@@ -2507,21 +2751,21 @@ function createServer(options) {
 					type: "completed",
 					value
 				}), (error) => ({
-					type: "handler-failed",
+					type: "run-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 === "run-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");
+				throw new Error("abort monitor closed while consumers were active");
 			},
 			close: async () => {
 				hub.subscriptions.delete(subscription);
@@ -2541,28 +2785,32 @@ function createServer(options) {
 		if (result === void 0) return [];
 		const events = Array.isArray(result) ? [...result] : [result];
 		if (events.length === 0) return [];
+		const idConsumer = idConsumerOf(trigger);
 		const withIds = await Promise.all(events.map(async (event, item) => {
 			const withId = { ...event };
-			withId.id = event.id ?? await deterministicReturnedEventId(trigger.id, item);
+			withId.id = event.id ?? await deterministicReturnedEventId(trigger.id, item, idConsumer);
 			return withId;
 		}));
 		return validateEvents(sessionId, withIds).map((event) => Object.assign(event, {
 			id: event.id,
 			cause: {
+				consumer: trigger.consumer,
+				lane: trigger.lane,
 				index: trigger.index,
 				attempt: trigger.attemptCount
 			}
 		}));
 	};
-	const drainSession = (sessionId, { watchdogDueAt, signal, handOffFailure = false } = {}) => telemetry.span("a2.drain", {
+	const drainSession = (sessionId, { watchdogDueAt, signal, handOffFailure = false, only, through } = {}) => 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();
+		/** Running heads, keyed by `headKey`: one event can run for several consumers. */
 		const active = /* @__PURE__ */ new Map();
-		const excluded = /* @__PURE__ */ new Set();
+		const excluded = /* @__PURE__ */ new Map();
 		let processed = 0;
 		let sawFailure = false;
 		let schedulerArm;
@@ -2574,10 +2822,10 @@ function createServer(options) {
 		const lapseDue = () => {
 			lapseTimer = null;
 			const nowMs = Date.now();
-			for (const [index, entry] of active) {
+			for (const entry of active.values()) {
 				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`));
+				entry.supersede.abort(new A2Error("CLAIM_EXPIRED", `the claim on event ${entry.ref.index} for consumer '${entry.ref.consumer}' in session '${sessionId}' lapsed without renewal`));
 			}
 			scheduleLapse();
 		};
@@ -2615,8 +2863,8 @@ function createServer(options) {
 			if (stopRenewing || renewal || active.size === 0) return renewal ?? Promise.resolve();
 			const window = nextClaimWindow();
 			requestWatchdog(window.watchdogAtMs);
-			const claims = [...active.entries()].map(([index, entry]) => ({
-				index,
+			const claims = [...active.values()].map((entry) => ({
+				...entry.ref,
 				attempt: entry.attempt
 			}));
 			const operation = store.renewClaims({
@@ -2626,14 +2874,14 @@ function createServer(options) {
 				ttlMs: window.ttlMs,
 				...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {}
 			}).then((result) => {
-				for (const index of result.renewed) {
-					const entry = active.get(index);
+				for (const ref of result.renewed) {
+					const entry = active.get(headKey(ref));
 					if (entry && !entry.lapsed) entry.expiresAtMs = window.expiresAtMs;
 				}
-				for (const index of result.superseded) {
-					const entry = active.get(index);
-					if (!entry) continue;
-					endSuperseded(entry, `a newer attempt owns event ${index} in session '${sessionId}'`);
+				for (const ref of result.superseded) {
+					const entry = active.get(headKey(ref));
+					if (!entry || entry.completing) continue;
+					endSuperseded(entry, `a newer attempt owns event ${ref.index} for consumer '${ref.consumer}' in session '${sessionId}'`);
 				}
 				if (window.deadlineCapped) stopRenewing = true;
 				scheduleLapse();
@@ -2647,41 +2895,46 @@ function createServer(options) {
 			renewal = tracked;
 			return tracked;
 		};
-		/** Records an event the store dead-lettered on takeover; it never runs. */
+		/** Records a head the store dead-lettered on takeover; it never runs. */
 		const reportExhausted = (event) => 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.consumer": event.consumer,
 			"a2.event.attempt": event.attemptCount,
-			"a2.event.handled": handlers.has(event.type),
+			"a2.event.handled": registeredConsumers.has(event.consumer),
 			...event.lane === null ? {} : { "a2.event.lane": event.lane }
 		}, async (eventSpan) => {
 			eventSpan.setAttribute("a2.event.outcome", "dead_lettered");
 		});
-		const runEvent = async (event, supersedeSignal, endAttempt) => {
-			const registration = handlers.get(event.type);
+		const runEvent = async (event, supersedeSignal, endAttempt, beginCompleting, sessionHead) => {
+			const registration = only?.name === event.consumer ? only : registeredConsumers.get(event.consumer);
+			const abortOn = registration?.abortOn(event.type) ?? null;
 			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.consumer": event.consumer,
 				"a2.event.attempt": event.attemptCount,
 				"a2.event.handled": registration !== void 0,
+				"a2.event.age_ms": Math.max(0, Date.now() - event.createdAt.getTime()),
+				...sessionHead === void 0 ? {} : { "a2.event.lag": Math.max(0, sessionHead - event.index) },
 				...event.lane === null ? {} : { "a2.event.lane": event.lane }
 			}, async (eventSpan) => {
 				let subscription;
-				let handlerSignal = supersedeSignal;
+				let runSignal = supersedeSignal;
 				let completion;
 				let completing = false;
 				try {
-					if (registration?.abortOn) {
-						subscription = await subscribeAbort(store, ns, event, registration.abortOn, event.attemptCount);
-						handlerSignal = AbortSignal.any([supersedeSignal, subscription.signal]);
+					if (abortOn) {
+						subscription = await subscribeAbort(store, ns, event, abortOn, event.attemptCount);
+						runSignal = AbortSignal.any([supersedeSignal, subscription.signal]);
 					}
-					const operation = registration?.handler(makeCtx(event, event.attemptCount, handlerSignal, endAttempt));
+					const operation = registration?.run(makeCtx(event, event.attemptCount, runSignal, endAttempt));
 					const result = operation ? await (subscription ? subscription.monitor(operation) : operation) : void 0;
 					if (subscription) {
 						await subscription.close();
@@ -2690,6 +2943,7 @@ function createServer(options) {
 					const returned = await returnedEvents(sessionId, event, result);
 					await renewal;
 					completing = true;
+					beginCompleting();
 					completion = await telemetry.span("a2.commit", {
 						"a2.contract": name,
 						"a2.session_id": sessionId,
@@ -2699,9 +2953,12 @@ function createServer(options) {
 					}, async (commitSpan) => {
 						const committed = await store.completeAttempt({
 							sessionId: ns,
+							consumer: event.consumer,
+							lane: event.lane,
 							index: event.index,
 							attempt: event.attemptCount,
-							events: returned
+							events: returned,
+							consumers: storeConsumers
 						});
 						commitSpan.setAttribute("a2.commit.outcome", committed.outcome);
 						return committed;
@@ -2727,6 +2984,8 @@ function createServer(options) {
 					}, async (commitSpan) => {
 						const result = await store.failAttempt({
 							sessionId: ns,
+							consumer: event.consumer,
+							lane: event.lane,
 							index: event.index,
 							attempt: event.attemptCount,
 							error: describeError(err),
@@ -2751,7 +3010,7 @@ function createServer(options) {
 					opensLane: false,
 					appendsEvents: false
 				};
-				if (handlerSignal.aborted) eventSpan.setAttribute("a2.event.aborted", true);
+				if (runSignal.aborted) eventSpan.setAttribute("a2.event.aborted", true);
 				return {
 					status: "processed",
 					opensLane: event.lane !== null,
@@ -2760,9 +3019,11 @@ function createServer(options) {
 			});
 		};
 		let claimAgain = false;
-		const start = (event, expiresAtMs) => {
-			const previous = active.get(event.index);
-			if (previous) endSuperseded(previous, `a newer attempt owns event ${event.index} in session '${sessionId}'`);
+		const start = (event, expiresAtMs, sessionHead) => {
+			const ref = headRefOf(event);
+			const key = headKey(ref);
+			const previous = active.get(key);
+			if (previous) endSuperseded(previous, `a newer attempt owns event ${event.index} for consumer '${event.consumer}' in session '${sessionId}'`);
 			const supersede = new AbortController();
 			let fence;
 			const fenced = new Promise((resolve) => {
@@ -2771,27 +3032,31 @@ function createServer(options) {
 			const endAttempt = () => endSuperseded({
 				supersede,
 				fence
-			}, `event ${event.index} in session '${sessionId}' was cleared`);
+			}, `event ${event.index} for consumer '${event.consumer}' in session '${sessionId}' was cleared`);
 			let entry;
-			const execution = Promise.race([runEvent(event, supersede.signal, endAttempt), fenced]).then((eventOutcome) => {
-				if (active.get(event.index) === entry) active.delete(event.index);
+			const execution = Promise.race([runEvent(event, supersede.signal, endAttempt, () => {
+				entry.completing = true;
+			}, sessionHead), fenced]).then((eventOutcome) => {
+				if (active.get(key) === entry) active.delete(key);
 				if (eventOutcome.status === "processed") processed += 1;
 				if (eventOutcome.status === "failed") {
-					excluded.add(event.index);
+					excluded.set(key, ref);
 					sawFailure = true;
 				}
 				claimAgain ||= eventOutcome.opensLane || eventOutcome.appendsEvents;
 				return eventOutcome;
 			});
 			entry = {
+				ref,
 				attempt: event.attemptCount,
 				execution,
 				supersede,
 				fence,
 				expiresAtMs,
-				lapsed: false
+				lapsed: false,
+				completing: false
 			};
-			active.set(event.index, entry);
+			active.set(key, entry);
 			scheduleLapse();
 			if (!heartbeat && !stopRenewing) {
 				heartbeat = setInterval(() => void renew(), DRAIN_TIMINGS.claimHeartbeatMs);
@@ -2820,7 +3085,9 @@ function createServer(options) {
 							ttlMs: window.ttlMs,
 							maxFailures: MAX_FAILURES,
 							...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
-							...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
+							consumers: only ? [storeConsumerOf(only)] : storeConsumers,
+							...through === void 0 ? {} : { through },
+							...excluded.size === 0 ? {} : { exclude: [...excluded.values()] }
 						});
 						claimSpan.setAttribute("a2.claim.outcome", result.outcome);
 						claimSpan.setAttribute("a2.claim.count", result.outcome === "claimed" ? result.events.length : 0);
@@ -2831,7 +3098,7 @@ function createServer(options) {
 						for (const event of claim.events) if (event.failedAt !== null) await reportExhausted(event);
 						if (runnable.length > 0) requestWatchdog(window.watchdogAtMs);
 						if (window.deadlineCapped) stopRenewing = true;
-						for (const event of runnable) start(event, window.expiresAtMs);
+						for (const event of runnable) start(event, window.expiresAtMs, claim.head);
 						shouldClaim = false;
 					}
 				}
@@ -2860,6 +3127,10 @@ function createServer(options) {
 				}
 				if (claim === void 0) continue;
 				if (signal && signal.version !== signalVersion) continue;
+				if (claimAgain) {
+					claimAgain = false;
+					continue;
+				}
 				if (claim.outcome === "busy") {
 					requestWatchdog(claim.retryAt.getTime() + DRAIN_TIMINGS.watchdogGraceMs);
 					outcome = "busy";
@@ -2899,7 +3170,7 @@ function createServer(options) {
 		const append = Object.assign(appendInline, { dispatch: appendDispatch });
 		return Object.assign(makeSession(id, append, null), {
 			deadLetters: () => listDeadLetters(id),
-			redrive: (index, redriveOptions) => redriveEvent(id, index, redriveOptions)
+			redrive: (target, redriveOptions) => redriveEvent(id, target, redriveOptions)
 		});
 	};
 	const historyPage = async (sessionId, bounds) => {
@@ -2968,6 +3239,9 @@ function assertStreamIndex(value) {
 function assertStateIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("state.through must be a non-negative safe integer");
 }
+function assertConsumeIndex(value) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("consume through must be a non-negative safe integer");
+}
 function assertRedriveIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("redrive requires a positive safe-integer index");
 }
@@ -2975,7 +3249,7 @@ function assertClearIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("ifLastIndex must be a non-negative safe integer");
 }
 function assertAppendName(name) {
-	if (typeof name !== "string" || name.length === 0) throw new TypeError("handler append name must be a non-empty string");
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("consumer 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");
@@ -3061,6 +3335,6 @@ const measuredBytes = (reducer, state, index, snapshots) => JSON.stringify(snaps
 }))?.length ?? 0;
 const stateCacheKey = (sessionId, reducerName) => `${sessionId}\u0000${reducerName}`;
 //#endregion
-export { CONSOLE_TELEMETRY as a, parsePresenceSibling as c, handler as i, deliverSchedulerAppend as n, setServerFetchHooks as o, deliverSchedulerClear as r, sseResponse as s, createServer as t };
+export { CONSOLE_TELEMETRY as a, parsePresenceSibling as c, deliverSchedulerClear as i, createServer as n, setServerFetchHooks as o, deliverSchedulerAppend as r, sseResponse as s, consumer as t };
 
-//# sourceMappingURL=server-qyb5aJJG.js.map
+//# sourceMappingURL=server-DvIB8kj5.js.map