experimental-a2 0.19.0 → 0.21.1

package/src/server.ts

@@ -2,7 +2,7 @@ import { decodeState, encodeState } from './reducer-runtime.ts'
 // oxlint-disable no-await-in-loop -- scheduler advances after durable outcomes
 /**
  * experimental-a2/server — where a contract is implemented. `createServer({
- * contract, store, handlers, ... })` binds the vocabulary to storage and
+ * contract, store, consumers, ... })` binds the vocabulary to storage and
  * reactions; sessions, drains, claims, and scheduler all live here.
  * Server-only by construction: this entry point is the only one that
  * can reach a store backend, and its exports map fails loudly in browser
@@ -31,6 +31,8 @@ import {
   markSchedulerSendFailure,
   stateTailReaders,
   nullProtoRecord,
+  runtimeConsumerFactory,
+  runtimeConsumers,
   serverInternals,
   type DrainOutcome,
   type DrainResult,
@@ -50,9 +52,14 @@ import {
 } from './stream-buffer.ts'
 import type {
   A2Store,
+  CompleteAttemptResult,
   AppendEvent,
   Event,
   EventCause,
+  EventTarget,
+  HeadEvent,
+  HeadRef,
+  StoreConsumer,
   StoreClaimAvailableResult,
   StoreClearResult,
   StoreReclaimResult,
@@ -104,8 +111,8 @@ import {
   type A2Telemetry,
 } from './telemetry.ts'
 
-/** What every handler receives. */
-export type HandlerContext<
+/** What every consumer's `run` receives. */
+export type ConsumerContext<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
   P extends PresenceDefs = Record<never, never>,
@@ -115,21 +122,12 @@ export type HandlerContext<
   event: ContractEvent<D, K>
   /** Durable, 1-based dispatch ordinal for this event. */
   attempt: number
-  /** This session, with handler-scoped idempotent append. */
-  session: Session<D, HandlerAppend<D>, P, S>
+  /** This session, with consumer-scoped idempotent append. */
+  session: Session<D, ConsumerAppend<D>, P, S>
   /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
   signal: AbortSignal
 }
 
-export type Handler<
-  D extends EventDefs,
-  K extends keyof D & string = keyof D & string,
-  P extends PresenceDefs = Record<never, never>,
-  S = never,
-> = (
-  ctx: HandlerContext<D, K, P, S>,
-) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>
-
 export type LaneContext<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
@@ -138,10 +136,15 @@ export type LaneContext<
   event: Pick<ContractEvent<D, K>, 'type' | 'payload'> & { id?: string }
 }
 
-export type Lane<
+/**
+ * A consumer's lane: a string runs every event it takes in log order on one
+ * cursor; a function returns each event's lane, or null to run it
+ * concurrently.
+ */
+export type ConsumerLane<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
-> = string | ((context: LaneContext<D, K>) => string)
+> = string | ((context: LaneContext<D, K>) => string | null)
 
 export type SessionDispatch<D extends EventDefs> = (
   ...events: AppendInput<D>[]
@@ -152,7 +155,7 @@ export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   dispatch: SessionDispatch<D>
 }
 
-export type HandlerAppend<D extends EventDefs> = (
+export type ConsumerAppend<D extends EventDefs> = (
   name: string,
   ...events: AppendInput<D>[]
 ) => Promise<ContractEvent<D>[]>
@@ -191,7 +194,7 @@ export type SessionClearOptions = {
 export type SessionClearResult = { cleared: boolean; index: number }
 
 export type SessionRedriveOptions = {
-  /** `retry` runs the handler again with a fresh failure budget; `skip` settles the event without running it. */
+  /** `retry` runs the consumer again with a fresh failure budget; `skip` settles the event without running it. */
   action: 'retry' | 'skip'
 }
 
@@ -200,18 +203,36 @@ export type SessionRedriveResult = {
   redriven: boolean
 }
 
+export type SessionConsumeOptions = {
+  /**
+   * Run until the consumer has handled every event it takes through this
+   * index. Default: the session's head when the call starts. An index past
+   * the head counts as the head.
+   */
+  through?: number
+  /** Stops waiting: the call throws the signal's reason. */
+  signal?: AbortSignal
+}
+
+export type SessionConsumeResult = {
+  /** The consumer has handled every event it takes through this index. */
+  index: number
+}
+
 /** A dead-lettered event, with what an operator needs to resolve it. */
 export type DeadLetter<D extends EventDefs> = ContractEvent<D> & {
+  /** The consumer this event is dead for; it may be done for others. */
+  consumer: string
   lane: string | null
   /** Durable dispatch claims, including claims abandoned by hard kills. */
   attemptCount: number
   /**
    * Failed attempts since the event was appended or last retried: caught
-   * handler failures, and attempts that ended before they finished.
+   * consumer failures, and attempts that ended before they finished.
    */
   failureCount: number
   /**
-   * The last error a handler threw, stringified; null when every failed
+   * The last error the consumer threw, stringified; null when every failed
    * attempt ended before it finished.
    */
   lastError: string | null
@@ -227,7 +248,7 @@ export type SessionDeadLetters<D extends EventDefs> = {
    * an append. Any other event is left alone and reports `redriven: false`.
    */
   redrive(
-    index: number,
+    target: { consumer: string; index: number },
     options: SessionRedriveOptions,
   ): Promise<SessionRedriveResult>
 }
@@ -283,6 +304,17 @@ export type Session<
    */
   clear(options?: SessionClearOptions): Promise<SessionClearResult>
   history(options?: { gte?: number; lte?: number }): Promise<ContractEvent<D>[]>
+  /**
+   * Run a consumer with a string lane on this session, here, until it has
+   * handled every event it takes through `through`. The server's own
+   * consumer shares its cursor with background work, so this waits for
+   * whichever invocation holds it. A consumer the server doesn't run is
+   * pulled only by `consume`, and keeps its place between calls.
+   */
+  consume(
+    consumer: Consumer<D>,
+    options?: SessionConsumeOptions,
+  ): Promise<SessionConsumeResult>
   state: {
     <T>(
       reducer: Reducer<D, T, Record<never, never>>,
@@ -302,7 +334,7 @@ export type Session<
 }
 
 /**
- * The public server shape scheduler handlers accept. It stays structural so
+ * The public server shape scheduler consumers accept. It stays structural so
  * servers of any contract mix in one route; A2's private server internals add
  * delayed-append delivery without exposing an untyped append method here.
  */
@@ -425,11 +457,11 @@ export async function deliverSchedulerClear(
 }
 
 /**
- * Which events fire `ctx.signal` while a handler runs — the preemption
+ * Which events fire `ctx.signal` while a consumer runs — the preemption
  * channel for user cancellation. The array form matches by type; the
  * object form takes per-type predicates for targeted cancellation
- * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
- * without `abortOn` pay nothing. An aborted handler should catch and
+ * (`(event, trigger) => event.payload.of === trigger.id`). Consumers
+ * without `abortOn` pay nothing. An aborted consumer should catch and
  * return normally; throwing means "retry me".
  */
 export type AbortSpec<D extends EventDefs, K extends keyof D & string> =
@@ -444,36 +476,209 @@ export type AbortSpec<D extends EventDefs, K extends keyof D & string> =
           ) => boolean)
     }
 
-export type HandlerEntry<
+/** What a consumer's `run` returns: nothing, one event, or a batch. */
+export type ConsumerResult<D extends EventDefs> = Promise<
+  void | AppendInput<D> | readonly AppendInput<D>[]
+>
+
+/** How `createServer` runs a consumer. Built by `consumer().run()`. */
+export type ConsumerSpec<D extends EventDefs> = {
+  readonly types: readonly (keyof D & string)[] | null
+  readonly lane: ConsumerLane<D> | null
+  readonly backfill: boolean
+  readonly abortOn: AbortSpec<D, keyof D & string> | null
+  readonly run: (ctx: ConsumerContext<D>) => ConsumerResult<D>
+}
+
+/** A named reader of a session's log with its own durable cursors. */
+export type Consumer<D extends EventDefs> = {
+  readonly name: string
+  readonly contract: { readonly name: string }
+  readonly spec: ConsumerSpec<D>
+}
+
+export type ConsumerOptions<
   D extends EventDefs,
-  K extends keyof D & string = keyof D & string,
-  P extends PresenceDefs = Record<never, never>,
-  S = never,
-> =
-  | Handler<D, K, P, S>
-  | {
-      abortOn?: AbortSpec<D, K>
-      /** Session-scoped FIFO key, resolved and persisted when the event lands. */
-      lane?: Lane<D, K>
-      handler: Handler<D, K, P, S>
-    }
+  P extends PresenceDefs,
+  R extends RegisteredReducer<D, P> | undefined,
+  K extends keyof D & string,
+> = {
+  /** The contract whose events it reads. */
+  contract: Contract<D, P, R>
+  /** Its identity, unique per server. A new name is a new consumer. */
+  name: string
+  /** The event types it runs on; default every type. */
+  types?: readonly K[]
+  /** Omitted: concurrent. A string: one ordered lane. A function: per event. */
+  lane?: ConsumerLane<D, K>
+  /** A new consumer starts at the beginning of the log. Needs a string lane. */
+  backfill?: boolean
+  abortOn?: AbortSpec<D, K>
+}
+
+/**
+ * A consumer written in `createServer({ consumers })`: `consumer()`'s
+ * options without the contract, which is the server's, and its `run`.
+ */
+export type InlineConsumer<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  R extends RegisteredReducer<D, P> | undefined,
+  K extends keyof D & string,
+> = Omit<ConsumerOptions<D, P, R, K>, 'contract'> & {
+  run: (ctx: ConsumerContext<D, K, P, PublicState<R>>) => ConsumerResult<D>
+}
+
+/** The types an inline consumer takes: the ones it lists, or every type. */
+type InlineTypes<D extends EventDefs, X> = unknown extends X
+  ? keyof D & string
+  : Extract<X, keyof D & string>
+
+/**
+ * `createServer`'s consumers: each a `consumer()` or written inline. `C` is
+ * inferred per entry, so an inline `run` sees only the types it lists.
+ */
+export type ServerConsumers<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  R extends RegisteredReducer<D, P> | undefined,
+  C extends readonly unknown[],
+> = {
+  readonly [I in keyof C]:
+    InlineConsumer<D, P, R, InlineTypes<D, C[I]>> | Extract<C[I], Consumer<D>>
+}
 
-type HandlerFunction = (ctx: never) => Promise<unknown>
+const CONSUMER_NAME = /^[a-z0-9][a-z0-9._:-]{0,127}$/i
 
-export function handler<
-  H extends HandlerFunction | { handler: HandlerFunction },
->(entry: H): H extends HandlerFunction ? { handler: H } : H
-export function handler(
-  entry: HandlerFunction | { handler: HandlerFunction },
-): { handler: HandlerFunction } {
-  return typeof entry === 'function' ? { handler: entry } : entry
+/** Define a consumer: a named reader of each session's log. */
+export function consumer<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  R extends RegisteredReducer<D, P> | undefined,
+  const K extends keyof D & string = keyof D & string,
+>(
+  options: ConsumerOptions<D, P, R, K>,
+): {
+  run(
+    fn: (ctx: ConsumerContext<D, K, P, PublicState<R>>) => ConsumerResult<D>,
+  ): Consumer<D>
+} {
+  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<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  R extends RegisteredReducer<D, P> | undefined,
+  const K extends keyof D & string = keyof D & string,
+>(
+  options: ConsumerOptions<D, P, R, K>,
+  runtime: boolean,
+): {
+  run(
+    fn: (ctx: ConsumerContext<D, K, P, PublicState<R>>) => ConsumerResult<D>,
+  ): Consumer<D>
+} {
+  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 === undefined ? 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`,
+    )
+  }
+  // Cancellation is for work in progress. Checking it while replaying
+  // history would read the rest of the log for every event replayed.
+  if (backfill && options.abortOn !== undefined) {
+    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: Consumer<D> = {
+        name: consumerName,
+        contract: { name: contract.name },
+        spec: {
+          types,
+          lane: lane as ConsumerLane<D> | null,
+          backfill,
+          abortOn: (options.abortOn ?? null) as AbortSpec<
+            D,
+            keyof D & string
+          > | null,
+          run: fn as unknown as (ctx: ConsumerContext<D>) => ConsumerResult<D>,
+        },
+      }
+      if (runtime) runtimeConsumers.add(defined)
+      return defined
+    },
+  }
 }
+runtimeConsumerFactory.define = (options) =>
+  defineConsumer(options as Parameters<typeof consumer>[0], true)
+
+/** A registered consumer as the store needs to know it. */
+const storeConsumerOf = (registered: {
+  name: string
+  log: StoreConsumer['log']
+}): StoreConsumer =>
+  registered.log
+    ? { name: registered.name, log: registered.log }
+    : { name: registered.name }
 
 export type ServerOptions<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
   R extends RegisteredReducer<D, P> | undefined =
     RegisteredReducer<D, P> | undefined,
+  C extends readonly unknown[] = readonly Consumer<D>[],
 > = {
   /** The contract this server implements (see `a2.contract`). */
   contract: Contract<D, P, R>
@@ -495,16 +700,39 @@ export type ServerOptions<
    */
   presence?: { ttlMs?: number }
   /**
-   * The reactions, keyed by event type — all present at construction,
-   * so a handler can never be silently missing because its module
-   * wasn't imported. Compose across files by spreading objects (note:
-   * a duplicate key under spread silently last-wins).
+   * The consumers, each a named reader of every session's log with its own
+   * cursors: a `consumer()`, or its options and `run` written inline, on this
+   * contract. Names are unique; a duplicate throws.
    */
-  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P, PublicState<R>> }
+  consumers?: ServerConsumers<D, P, R, C> | readonly Consumer<D>[]
 }
 
 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 = 1_000
+
+/**
+ * `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 = <T>(
+  task: Promise<T>,
+  signal: AbortSignal | undefined,
+): Promise<T> => {
+  if (!signal) return task
+  task.catch(() => {})
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const abort = (): void => 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: number): number =>
   Math.min(
@@ -512,7 +740,7 @@ const failureRetryDelayMs = (failureCount: number): number =>
     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: {
     supersede: AbortController
@@ -724,30 +952,47 @@ function foldPresenceRows(
 
 type SnapshotWrites = Map<
   number,
-  { state: unknown; pinEventIndexes: Set<number> }
+  { state: unknown; pins: Map<string, HeadRef> }
 >
 
+/** One cursor head, as a map key. */
+const headKey = (ref: HeadRef): string =>
+  JSON.stringify([ref.consumer, ref.lane, ref.index])
+
+const headRefOf = (head: HeadEvent): HeadRef => ({
+  consumer: head.consumer,
+  lane: head.lane,
+  index: head.index,
+})
+
 const addSnapshotWrite = (
   writes: SnapshotWrites,
   index: number,
   state: unknown,
-  pinEventIndex?: number,
+  pin?: HeadRef,
 ): void => {
   let write = writes.get(index)
   if (!write) {
-    write = { state: cloneInitial(state), pinEventIndexes: new Set() }
+    write = { state: cloneInitial(state), pins: new Map() }
     writes.set(index, write)
   }
-  if (pinEventIndex !== undefined) write.pinEventIndexes.add(pinEventIndex)
+  if (pin !== undefined) write.pins.set(headKey(pin), pin)
 }
 
+/** Whether a registered consumer runs events of this type. */
+const takes = (
+  registered: { readonly types: ReadonlySet<string> | null },
+  type: string,
+): boolean => registered.types === null || registered.types.has(type)
+
 /** Implement a contract: bind its vocabulary to storage and reactions. */
 export function createServer<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
   R extends RegisteredReducer<D, P> | undefined =
     RegisteredReducer<D, P> | undefined,
->(options: ServerOptions<D, P, R>): A2Server<D, P, R> {
+  const C extends readonly unknown[] = readonly Consumer<D>[],
+>(options: ServerOptions<D, P, R, C>): A2Server<D, P, R> {
   const serverContract = options?.contract
   if (
     serverContract === null ||
@@ -759,6 +1004,12 @@ export function createServer<
       'createServer expects options with a contract (see a2.contract)',
     )
   }
+  // Ignored, a handler table would run nothing and say nothing.
+  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: Readonly<PresenceDefs> = serverContract.presence
@@ -847,24 +1098,11 @@ export function createServer<
         context: { attempt: number },
       ) => boolean)
   >
-  const handlers = new Map<
-    string,
-    { handler: Handler<D>; abortOn: AbortMatcher | null; lane: Lane<D> | null }
-  >()
-  for (const [type, entry] of Object.entries(options.handlers ?? {})) {
-    if (entry === undefined) 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: AbortSpec<D, keyof D & string> | null | undefined,
+  ): AbortMatcher | null => {
     let abortOn: AbortMatcher | null = null
-    const spec = typeof entry === 'function' ? undefined : entry.abortOn
-    if (spec !== undefined) {
+    if (spec !== undefined && spec !== null) {
       abortOn = new Map()
       const pairs = Array.isArray(spec)
         ? spec.map((abortType) => [abortType, true as const] as const)
@@ -892,22 +1130,117 @@ export function createServer<
       }
       if (abortOn.size === 0) abortOn = null
     }
-    const lane = typeof entry === 'function' ? null : (entry.lane ?? null)
+    return abortOn
+  }
+
+  /** A consumer as this server runs it. */
+  type RegisteredConsumer = {
+    name: string
+    types: ReadonlySet<string> | null
+    /** Lane-function and concurrent consumers; log consumers resolve none. */
+    laneOf: ((sessionId: string, event: AppendEvent) => string | null) | null
+    log: StoreConsumer['log']
+    abortOn: (type: string) => AbortMatcher | null
+    run: (ctx: ConsumerContext<D>) => Promise<unknown>
+    /** A2's own consumers: child and timer ids leave out the name. */
+    anonymousIds: boolean
+  }
+  const laneContext = (sessionId: string, event: AppendEvent): LaneContext<D> =>
+    ({
+      sessionId,
+      event: {
+        type: event.type,
+        payload: structuredClone(event.payload),
+        ...(event.id === undefined ? {} : { id: event.id }),
+      },
+    }) as LaneContext<D>
+  const registeredConsumers = new Map<string, RegisteredConsumer>()
+  /** A consumer definition as the server runs it. */
+  const registrationOf = (defined: Consumer<D>): RegisteredConsumer => {
+    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 }
+          : undefined,
+      abortOn: () => matcher,
+      run: run as (ctx: ConsumerContext<D>) => Promise<unknown>,
+      anonymousIds: runtimeConsumers.has(defined),
+    }
+  }
+  /** The definitions the server runs, so `consume` can tell its own from another. */
+  const definitions = new Map<string, Consumer<D>>()
+  /** A consumer written inline is `consumer()`'s options and `run`, on this contract. */
+  const definitionOf = (entry: unknown): Consumer<D> => {
     if (
-      lane !== null &&
-      typeof lane !== 'function' &&
-      (typeof lane !== 'string' || lane.length === 0)
+      entry === null ||
+      typeof entry !== 'object' ||
+      'spec' in entry ||
+      !('run' in entry)
     ) {
+      return entry as Consumer<D>
+    }
+    const { run, ...rest } = entry as InlineConsumer<D, P, R, keyof D & string>
+    return consumer({ ...rest, contract: serverContract }).run(run)
+  }
+  for (const entry of (options.consumers ?? []) as readonly unknown[]) {
+    const defined = definitionOf(entry)
+    if (defined?.contract?.name !== name || !defined.spec) {
       throw new TypeError(
-        `lane for '${type}' must be a non-empty string or a function`,
+        `createServer for '${name}' got a consumer of another contract`,
       )
     }
-    handlers.set(type, {
-      handler: callback as Handler<D>,
-      abortOn,
-      lane: lane as Lane<D> | null,
-    })
+    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)
+  }
+  // Runtime consumers leave their name out of child ids, so no event may
+  // start two of them: their first returned events would share an id.
+  const anonymousTypes = new Map<string, string>()
+  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 !== undefined) {
+        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: StoreConsumer[] = [...registeredConsumers.values()].map(
+    storeConsumerOf,
+  )
+  /** Whether an event starts cursor work for any consumer. */
+  const startsWork = (event: AppendEvent): boolean =>
+    (event.targets?.length ?? 0) > 0 ||
+    [...registeredConsumers.values()].some(
+      (registered) => registered.log && takes(registered, event.type),
+    )
 
   const prefix = `${name}${NS}`
   const nsId = (sessionId: string): string => `${prefix}${sessionId}`
@@ -1004,7 +1337,7 @@ export function createServer<
     const signal = createDrainSignal()
     const p = new Promise<void>((resolve) => {
       queueMicrotask(() => {
-        void drainSession(sessionId, watchdogDueAt, signal)
+        void drainSession(sessionId, { watchdogDueAt, signal })
           .then(() => resolve())
           .catch(() => resolve())
       })
@@ -1047,28 +1380,15 @@ export function createServer<
       const validated: AppendEvent = { type: e.type, payload: result.value }
       if (e.id !== undefined) 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 === undefined ? {} : { id: e.id }),
-                } as never,
-              })
-            : 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: EventTarget[] = []
+      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
     })
   }
@@ -1081,7 +1401,7 @@ export function createServer<
   const appendCore = (
     sessionId: string,
     events: AppendInput<D>[],
-    source: 'external' | 'handler',
+    source: 'external' | 'consumer',
     mode: 'inline' | 'dispatch',
     onAppended: (rows: ContractEvent<D>[], watchdogDueAt?: number) => void,
     cause?: EventCause,
@@ -1118,20 +1438,16 @@ export function createServer<
         let rows: StoredEvent[]
         let shouldHealSession: boolean
         try {
-          const result = await store.append(
-            nsId(sessionId),
-            validated,
-            originIndex === undefined ? undefined : { originIndex },
-          )
+          const result = await store.append(nsId(sessionId), validated, {
+            consumers: storeConsumers,
+            ...(originIndex === undefined ? {} : { originIndex }),
+          })
           rows = result.events
-          // A handler appending only settled events adds no work, and the
-          // drain holding its trigger is already running.
+          // A consumer appending events no consumer takes adds no work, and
+          // the drain holding its trigger is already running.
           shouldHealSession =
             result.hasPending &&
-            !(
-              source === 'handler' &&
-              validated.every((event) => event.settled === true)
-            )
+            !(source === 'consumer' && !validated.some(startsWork))
         } catch (err) {
           throw asStoreUnavailable(err)
         }
@@ -1242,8 +1558,8 @@ export function createServer<
     throughIndex?: number
     /** The id of the event at `throughIndex`, when the reader knows it. */
     throughEventId?: string
-    pinEventIndex?: number
-    /** A handler read: rejected once this trigger index has been cleared. */
+    pin?: HeadRef
+    /** A consumer read: rejected once this trigger index has been cleared. */
     triggerIndex?: number
     span: A2SpanHandle
     resolve: (result: StateResult) => void
@@ -1388,9 +1704,7 @@ export function createServer<
           index,
           state: encodeState({ reducer, 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) {
@@ -1503,7 +1817,7 @@ export function createServer<
   /**
    * 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.
    */
@@ -1560,8 +1874,8 @@ export function createServer<
       clearIndex: cached.clearIndex,
       snapshot: 'memory',
       visit: (entry, state, index) => {
-        if (entry.pinEventIndex !== undefined) {
-          addSnapshotWrite(writes, index, state, entry.pinEventIndex)
+        if (entry.pin !== undefined) {
+          addSnapshotWrite(writes, index, state, entry.pin)
         }
       },
     })
@@ -1571,7 +1885,7 @@ export function createServer<
     if (rewritesHead && !writes.has(folded.index)) {
       writes.set(folded.index, {
         state: folded.state,
-        pinEventIndexes: new Set(),
+        pins: new Map(),
       })
     }
     const snapshots = writeSnapshots({
@@ -1672,14 +1986,13 @@ export function createServer<
       snapshot: snapshotOutcome,
       visit: (entry, entryState, entryIndex, count) => {
         if (entryIndex === 0) return
-        if (count === 0 && entry.pinEventIndex === undefined) return
+        if (count === 0 && entry.pin === undefined) return
         const advancesHead =
           stateRead.headIndex === null || entryIndex > stateRead.headIndex
         const repairsHead =
           snapshotOutcome === 'rejected' && entryIndex === stateRead.headIndex
-        if (!advancesHead && !repairsHead && entry.pinEventIndex === undefined)
-          return
-        addSnapshotWrite(writes, entryIndex, entryState, entry.pinEventIndex)
+        if (!advancesHead && !repairsHead && entry.pin === undefined) return
+        addSnapshotWrite(writes, entryIndex, entryState, entry.pin)
       },
     })
     const snapshots = writeSnapshots({
@@ -1775,7 +2088,7 @@ export function createServer<
   type StateReadBounds = {
     throughIndex?: number
     throughEventId?: string
-    pinEventIndex?: number
+    pin?: HeadRef
     triggerIndex?: number
   }
 
@@ -1794,7 +2107,7 @@ export function createServer<
         pendingStateReads.set(reducerName, opened)
         // One microtask is the whole batching window — deliberately NOT
         // DataLoader's post-promise-job nextTick, which would defer
-        // handler-internal reads past the entire microtask cascade and
+        // consumer-internal reads past the entire microtask cascade and
         // reorder drain interleaving (and has no edge-runtime primitive).
         // It still coalesces reliably: siblings of one Promise.all
         // traverse identical awaits (store resolution, span wrapper), so
@@ -1836,12 +2149,14 @@ export function createServer<
 
   const makeSchedule = (
     sessionId: string,
-    trigger: Pick<
-      StoredEvent,
-      'id' | 'createdAt' | 'index' | 'clearIndex'
-    > | null,
+    trigger: HeadEvent | null,
   ): SessionSchedule<D> => {
     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
+        : undefined
     const triggerCreatedAt = trigger?.createdAt.getTime()
     const clearIndex = trigger?.clearIndex ?? 0
     const schedule = async (
@@ -1878,6 +2193,7 @@ export function createServer<
         triggerEventId,
         scheduleName,
         clearIndex,
+        triggerConsumer,
       )
       const scheduledEvents: ScheduledEvent[] = await Promise.all(
         validated.map(async (event, item) => ({
@@ -1943,6 +2259,7 @@ export function createServer<
         clearIndex,
         name: scheduleName,
         ifLastIndex,
+        ...(triggerConsumer === undefined ? {} : { consumer: triggerConsumer }),
       })
       try {
         await scheduler.schedule({
@@ -2122,7 +2439,7 @@ export function createServer<
         {
           seen: patch.seen ?? fallbackSeen,
           // The sender's stamp is the LWW order; receipt time is the
-          // fallback for stampless callers (handlers, old wire
+          // fallback for stampless callers (consumers, old wire
           // clients), where receipt order is sender order — single
           // writer. Storage anchors expiry on its own clock either way.
           at: new Date(patch.at ?? Date.now()),
@@ -2497,7 +2814,7 @@ export function createServer<
     }
   }
 
-  /** The handler attempt a `ctx.session.clear()` belongs to. */
+  /** The consumer attempt a `ctx.session.clear()` belongs to. */
   type ClearingAttempt = {
     cause: EventCause
     end: () => void
@@ -2530,7 +2847,7 @@ export function createServer<
     }
     if (result.cleared) {
       // This instance's own reads after the clear, including the clearing
-      // handler's, go to the store and see the boundary.
+      // consumer's, go to the store and see the boundary.
       const cachePrefix = stateCacheKey(sessionId, '')
       stateCache.deleteWhere((key) => key.startsWith(cachePrefix))
     }
@@ -2565,7 +2882,7 @@ export function createServer<
     sessionId: string,
   ): Promise<DeadLetter<D>[]> => {
     const store = await redrivingStore('deadLetters')
-    let rows: StoredEvent[]
+    let rows: HeadEvent[]
     try {
       rows = await store.deadLetters(nsId(sessionId))
     } catch (err) {
@@ -2577,6 +2894,7 @@ export function createServer<
         : [
             {
               ...toPublic(row),
+              consumer: row.consumer,
               lane: row.lane,
               attemptCount: row.attemptCount,
               failureCount: row.failureCount,
@@ -2589,10 +2907,15 @@ export function createServer<
 
   const redriveEvent = async (
     sessionId: string,
-    index: number,
+    target: { consumer: string; index: number },
     redriveOptions: SessionRedriveOptions,
   ): Promise<SessionRedriveResult> => {
+    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'")
@@ -2603,6 +2926,7 @@ export function createServer<
         'a2.contract': name,
         'a2.session_id': sessionId,
         'a2.redrive.index': index,
+        'a2.redrive.consumer': redriven,
         'a2.redrive.action': action,
       },
       async (span) => {
@@ -2611,8 +2935,10 @@ export function createServer<
         try {
           result = await store.redrive({
             sessionId: nsId(sessionId),
+            consumer: redriven,
             index,
             action,
+            consumers: storeConsumers,
           })
         } catch (err) {
           throw asStoreUnavailable(err)
@@ -2643,18 +2969,169 @@ export function createServer<
     )
   }
 
+  /**
+   * `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 = new Map<string, Map<string, string>>()
+
+  const consumeSession = (
+    sessionId: string,
+    defined: Consumer<D>,
+    consumeOptions: SessionConsumeOptions = {},
+    trigger: HeadEvent | null = null,
+  ): Promise<SessionConsumeResult> => {
+    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 !== undefined && 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 !== undefined) assertConsumeIndex(requested)
+    // A run that waits on a consumer already waiting on it, here, would wait
+    // forever. Checked and recorded before any await, so two can't both pass.
+    // One that would close that cycle isn't recorded: it returns only if what
+    // it asks for is done already, since the other's cursor can't move.
+    const waiter = trigger?.consumer
+    const waits =
+      waiter === undefined
+        ? undefined
+        : (consumeWaits.get(sessionId) ??
+          consumeWaits.set(sessionId, new Map()).get(sessionId)!)
+    let cycle = false
+    if (waiter !== undefined && waits) {
+      for (
+        let next: string | undefined = defined.name;
+        next !== undefined && !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 = (): boolean =>
+          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) {
+            // An abort stops the wait at once; a run in progress carries on,
+            // and what it appends still reaches the server's consumers.
+            if (signal?.aborted)
+              void 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
+          }
+          // Another invocation holds the head, or it waits out a failure.
+          const sleep = defaultSleep(wait)
+          const abort = (): void => sleep.cancel()
+          signal?.addEventListener('abort', abort, { once: true })
+          await sleep.promise
+          signal?.removeEventListener('abort', abort)
+          wait = Math.min(wait * 2, CONSUME_WAIT_MAX_MS)
+        }
+        // Work past `through` carries on in the background, as after an append,
+        // and so do the server's consumers of what this consumer's runs appended.
+        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 === undefined || cycle
+      ? consumed
+      : consumed.finally(() => {
+          waits?.delete(waiter)
+          if (waits?.size === 0) consumeWaits.delete(sessionId)
+        })
+  }
+
   const makeSession = <Append>(
     id: string,
     append: Append,
-    trigger: Pick<
-      StoredEvent,
-      'id' | 'createdAt' | 'index' | 'clearIndex'
-    > | null,
+    trigger: HeadEvent | null,
     attempt?: ClearingAttempt,
   ): Session<D, Append, P> =>
     ({
       id,
       append,
+      consume: (defined: Consumer<D>, consumeOptions?: SessionConsumeOptions) =>
+        consumeSession(id, defined, consumeOptions, trigger),
       schedule: makeSchedule(id, trigger),
       clear: (clearOptions?: SessionClearOptions) =>
         clearSession(id, clearOptions, attempt),
@@ -2683,7 +3160,7 @@ export function createServer<
         const bounds: StateReadBounds = {}
         if (through !== undefined && through !== 'latest') {
           bounds.throughIndex = through
-          if (trigger) bounds.pinEventIndex = trigger.index
+          if (trigger) bounds.pin = headRefOf(trigger)
           // Only a live attempt may be answered from memory with no store
           // request; a superseded one (including by a clear) reads the store.
           if (through === trigger?.index && !attempt?.signal.aborted)
@@ -2716,42 +3193,60 @@ export function createServer<
 
   // ── drain ────────────────────────────────────────────────────────
 
+  /** The consumer name a trigger's child ids key on, if any. */
+  const idConsumerOf = (trigger: HeadEvent): string | undefined =>
+    registeredConsumers.get(trigger.consumer)?.anonymousIds
+      ? undefined
+      : trigger.consumer
+
   const makeCtx = (
-    trigger: StoredEvent,
+    trigger: HeadEvent,
     attempt: number,
     signal: AbortSignal,
     endAttempt: () => void,
-  ): HandlerContext<D> => {
+  ): ConsumerContext<D> => {
     const publicSessionId = stripNs(trigger.sessionId)
-    const append: HandlerAppend<D> = async (appendName, ...events) => {
+    const idConsumer = idConsumerOf(trigger)
+    const cause: EventCause = {
+      consumer: trigger.consumer,
+      lane: trigger.lane,
+      index: trigger.index,
+      attempt,
+    }
+    const append: ConsumerAppend<D> = async (appendName, ...events) => {
       assertAppendName(appendName)
       const generatedIds = events.map((event) => event.id === undefined)
       const withIds = await Promise.all(
         // oxlint-disable-next-line no-map-spread
         events.map(async (event, item) => {
           if (event.id !== undefined) 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',
+        'consumer',
         'inline',
         (_rows, watchdogDueAt) => scheduleDrain(publicSessionId, watchdogDueAt),
-        { index: trigger.index, attempt },
+        cause,
         generatedIds,
       )
     }
-    const ctx: HandlerContext<D> = {
+    const ctx: ConsumerContext<D> = {
       event: toPublic(trigger),
       attempt,
-      // The handler-scoped `setPresence` stamps `seen` with the
-      // triggering event's index by default — the frontier the handler
+      // The consumer-scoped `setPresence` stamps `seen` with the
+      // triggering event's index by default — the frontier the consumer
       // provably reflects.
       session: makeSession(publicSessionId, append, trigger, {
-        cause: { index: trigger.index, attempt },
+        cause,
         end: endAttempt,
         signal,
       }),
@@ -2857,7 +3352,7 @@ export function createServer<
         const outcome = await Promise.race([
           operation.then(
             (value) => ({ type: 'completed' as const, value }),
-            (error: unknown) => ({ type: 'handler-failed' as const, error }),
+            (error: unknown) => ({ type: 'run-failed' as const, error }),
           ),
           hub.watch!.then(() =>
             hub.error === null
@@ -2866,7 +3361,7 @@ export function createServer<
           ),
         ])
         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)
@@ -2875,7 +3370,7 @@ export function createServer<
           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)
@@ -2894,18 +3389,22 @@ export function createServer<
 
   const returnedEvents = async (
     sessionId: string,
-    trigger: StoredEvent,
-    result: void | AppendInput<D> | readonly AppendInput<D>[],
+    trigger: HeadEvent,
+    result: unknown,
   ): Promise<ReturnedEvent[]> => {
     if (result === undefined) return []
-    const events = Array.isArray(result) ? [...result] : [result]
+    const events = (
+      Array.isArray(result) ? [...result] : [result]
+    ) as AppendInput<D>[]
     if (events.length === 0) return []
+    const idConsumer = idConsumerOf(trigger)
     const withIds = await Promise.all(
-      // oxlint-disable-next-line oxc/no-map-spread -- handler results remain caller-owned
+      // oxlint-disable-next-line oxc/no-map-spread -- consumer results remain caller-owned
       events.map(async (event, item) => {
         const withId = { ...event }
         withId.id =
-          event.id ?? (await deterministicReturnedEventId(trigger.id, item))
+          event.id ??
+          (await deterministicReturnedEventId(trigger.id, item, idConsumer))
         return withId
       }),
     )
@@ -2913,6 +3412,8 @@ export function createServer<
       Object.assign(event, {
         id: event.id!,
         cause: {
+          consumer: trigger.consumer,
+          lane: trigger.lane,
           index: trigger.index,
           attempt: trigger.attemptCount,
         },
@@ -2931,8 +3432,22 @@ export function createServer<
 
   const drainSession = (
     sessionId: string,
-    watchdogDueAt?: number,
-    signal?: DrainSignal,
+    {
+      watchdogDueAt,
+      signal,
+      handOffFailure = false,
+      only,
+      through,
+    }: {
+      watchdogDueAt?: number | undefined
+      signal?: DrainSignal | undefined
+      /** Return a failure after arming as `failed` instead of throwing it. */
+      handOffFailure?: boolean
+      /** Claim and run only this consumer's heads, for `consume`. */
+      only?: RegisteredConsumer | undefined
+      /** With `only`: claim no head past it; what's past it is the background's. */
+      through?: number | undefined
+    } = {},
   ): Promise<DrainResult> =>
     telemetry.span(
       'a2.drain',
@@ -2942,6 +3457,7 @@ export function createServer<
         const ns = nsId(sessionId)
         const holder = crypto.randomUUID()
         type ActiveEvent = {
+          ref: HeadRef
           attempt: number
           execution: Promise<EventOutcome>
           supersede: AbortController
@@ -2950,9 +3466,15 @@ export function createServer<
           /** Local lease estimate: request time + ttl — at or before the store's. */
           expiresAtMs: number
           lapsed: boolean
+          /**
+           * Its completion is committing. A renewal may then find the cursor
+           * already past the head; completion is the fence, not that report.
+           */
+          completing: boolean
         }
-        const active = new Map<number, ActiveEvent>()
-        const excluded = new Set<number>()
+        /** Running heads, keyed by `headKey`: one event can run for several consumers. */
+        const active = new Map<string, ActiveEvent>()
+        const excluded = new Map<string, HeadRef>()
         let processed = 0
         let sawFailure = false
         let schedulerArm: Promise<void> | undefined
@@ -2969,13 +3491,13 @@ export function createServer<
         const lapseDue = (): void => {
           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`,
+                `the claim on event ${entry.ref.index} for consumer '${entry.ref.consumer}' in session '${sessionId}' lapsed without renewal`,
               ),
             )
           }
@@ -3036,8 +3558,8 @@ export function createServer<
           }
           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
@@ -3052,20 +3574,20 @@ export function createServer<
             })
             .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
+                for (const ref of result.superseded) {
+                  const entry = active.get(headKey(ref))
+                  if (!entry || entry.completing) continue
                   // Idempotent: the local lapse normally aborted this signal
                   // already — this is the proof, whose job is the release.
                   endSuperseded(
                     entry,
-                    `a newer attempt owns event ${index} in session '${sessionId}'`,
+                    `a newer attempt owns event ${ref.index} for consumer '${ref.consumer}' in session '${sessionId}'`,
                   )
                 }
                 if (window.deadlineCapped) stopRenewing = true
@@ -3085,8 +3607,8 @@ export function createServer<
           return tracked
         }
 
-        /** Records an event the store dead-lettered on takeover; it never runs. */
-        const reportExhausted = (event: StoredEvent): Promise<void> =>
+        /** Records a head the store dead-lettered on takeover; it never runs. */
+        const reportExhausted = (event: HeadEvent): Promise<void> =>
           telemetry.span(
             'a2.event',
             {
@@ -3095,8 +3617,9 @@ export function createServer<
               '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) => {
@@ -3105,11 +3628,17 @@ export function createServer<
           )
 
         const runEvent = async (
-          event: StoredEvent,
+          event: HeadEvent,
           supersedeSignal: AbortSignal,
           endAttempt: () => void,
+          beginCompleting: () => void,
+          sessionHead: number | undefined,
         ): Promise<EventOutcome> => {
-          const registration = handlers.get(event.type)
+          const registration =
+            only?.name === event.consumer
+              ? only
+              : registeredConsumers.get(event.consumer)
+          const abortOn = registration?.abortOn(event.type) ?? null
           return telemetry.span(
             'a2.event',
             {
@@ -3118,8 +3647,16 @@ export function createServer<
               '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 !== undefined,
+              'a2.event.age_ms': Math.max(
+                0,
+                Date.now() - event.createdAt.getTime(),
+              ),
+              ...(sessionHead === undefined
+                ? {}
+                : { 'a2.event.lag': Math.max(0, sessionHead - event.index) }),
               ...(event.lane === null ? {} : { 'a2.event.lane': event.lane }),
             },
             async (eventSpan) => {
@@ -3130,24 +3667,25 @@ export function createServer<
                     close(): Promise<void>
                   }
                 | undefined
-              let handlerSignal = supersedeSignal
-              let returned: ReturnedEvent[]
+              let runSignal = supersedeSignal
+              let completion: CompleteAttemptResult
+              let completing = false
               try {
-                if (registration?.abortOn) {
+                if (abortOn) {
                   subscription = await subscribeAbort(
                     store,
                     ns,
                     event,
-                    registration.abortOn,
+                    abortOn,
                     event.attemptCount,
                   )
-                  handlerSignal = AbortSignal.any([
+                  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
@@ -3158,12 +3696,41 @@ export function createServer<
                   await subscription.close()
                   subscription = undefined
                 }
-                returned = await returnedEvents(sessionId, event, result)
+                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,
+                    'a2.commit.operation': 'complete',
+                    'a2.commit.index': event.index,
+                    'a2.commit.attempt': event.attemptCount,
+                  },
+                  async (commitSpan) => {
+                    const committed = await store.completeAttempt({
+                      sessionId: ns,
+                      consumer: event.consumer,
+                      lane: event.lane,
+                      index: event.index,
+                      attempt: event.attemptCount,
+                      events: returned,
+                      consumers: storeConsumers,
+                    })
+                    commitSpan.setAttribute(
+                      'a2.commit.outcome',
+                      committed.outcome,
+                    )
+                    return committed
+                  },
+                )
               } catch (err) {
                 if (supersedeSignal.aborted && err === supersedeSignal.reason) {
-                  // The handler surrendered to its own abort — identity, not
+                  // The consumer surrendered to its own abort — identity, not
                   // code, so it cannot arrive from another context. A lapse
-                  // is not a handler failure: no completion; the claim simply
+                  // is not a consumer failure: no completion; the claim simply
                   // expires, and the claim that takes it over counts it.
                   eventSpan.setAttribute('a2.event.outcome', 'surrendered')
                   return {
@@ -3172,6 +3739,14 @@ export function createServer<
                     appendsEvents: false,
                   }
                 }
+                const refused =
+                  completing &&
+                  err instanceof A2Error &&
+                  err.code === 'PARTIAL_DUPLICATE_BATCH'
+                // A store that cannot record the completion is not the
+                // consumer failing: the claim lapses, and the claim that takes
+                // it over counts it. A returned batch it refuses is.
+                if (completing && !refused) throw err
                 // Everything else — including a store fence rejection — is
                 // adjudicated by failAttempt, which is itself fenced: a
                 // genuinely superseded attempt gets 'superseded' back with
@@ -3189,14 +3764,19 @@ export function createServer<
                   async (commitSpan) => {
                     const result = await store.failAttempt({
                       sessionId: ns,
+                      consumer: event.consumer,
+                      lane: event.lane,
                       index: event.index,
                       attempt: event.attemptCount,
                       error: describeError(err),
-                      // A NonRetriableError is terminal on its first throw:
-                      // deterministic failures should not burn the retry
-                      // budget before dead-lettering.
+                      // A NonRetriableError is terminal on its first throw,
+                      // and so is a refused batch, whose retry returns the
+                      // same ids: deterministic failures should not burn the
+                      // retry budget before dead-lettering.
                       maxFailures:
-                        err instanceof NonRetriableError ? 1 : MAX_FAILURES,
+                        err instanceof NonRetriableError || refused
+                          ? 1
+                          : MAX_FAILURES,
                       retryAfterMs: failureRetryDelayMs(event.failureCount + 1),
                     })
                     commitSpan.setAttribute('a2.commit.outcome', result.outcome)
@@ -3212,27 +3792,6 @@ export function createServer<
               } finally {
                 await subscription?.close()
               }
-              await renewal
-              const completion = await telemetry.span(
-                'a2.commit',
-                {
-                  'a2.contract': name,
-                  'a2.session_id': sessionId,
-                  'a2.commit.operation': 'complete',
-                  'a2.commit.index': event.index,
-                  'a2.commit.attempt': event.attemptCount,
-                },
-                async (commitSpan) => {
-                  const result = await store.completeAttempt({
-                    sessionId: ns,
-                    index: event.index,
-                    attempt: event.attemptCount,
-                    events: returned,
-                  })
-                  commitSpan.setAttribute('a2.commit.outcome', result.outcome)
-                  return result
-                },
-              )
               eventSpan.setAttribute(
                 'a2.event.outcome',
                 completion.outcome === 'completed'
@@ -3246,13 +3805,13 @@ export function createServer<
                   appendsEvents: false,
                 }
               }
-              if (handlerSignal.aborted) {
+              if (runSignal.aborted) {
                 eventSpan.setAttribute('a2.event.aborted', true)
               }
               return {
                 status: 'processed',
                 opensLane: event.lane !== null,
-                appendsEvents: returned.length > 0,
+                appendsEvents: completion.events.length > 0,
               }
             },
           )
@@ -3260,16 +3819,22 @@ export function createServer<
 
         let claimAgain = false
 
-        const start = (event: StoredEvent, expiresAtMs: number): void => {
-          // Re-claiming an index this drain still tracks is durable proof
+        const start = (
+          event: HeadEvent,
+          expiresAtMs: number,
+          sessionHead: number | undefined,
+        ): void => {
+          const ref = headRefOf(event)
+          const key = headKey(ref)
+          // Re-claiming a head this drain still tracks is durable proof
           // that the old attempt lost: our own new claim advanced the
           // ordinal. Fence the old entry before it can be confused with
           // the new one.
-          const previous = active.get(event.index)
+          const previous = active.get(key)
           if (previous) {
             endSuperseded(
               previous,
-              `a newer attempt owns event ${event.index} in session '${sessionId}'`,
+              `a newer attempt owns event ${event.index} for consumer '${event.consumer}' in session '${sessionId}'`,
             )
           }
           const supersede = new AbortController()
@@ -3277,40 +3842,50 @@ export function createServer<
           const fenced = new Promise<EventOutcome>((resolve) => {
             fence = resolve
           })
-          // A handler's own committed clear supersedes it immediately.
+          // A consumer's own committed clear supersedes it immediately.
           const endAttempt = (): void =>
             endSuperseded(
               { supersede, fence },
-              `event ${event.index} in session '${sessionId}' was cleared`,
+              `event ${event.index} for consumer '${event.consumer}' in session '${sessionId}' was cleared`,
             )
           // The race lets a durable supersession release this slot while the
-          // zombie handler keeps running — its completion and failure are
+          // zombie consumer keeps running — its completion and failure are
           // fenced by the store, so nothing it does from here is counted.
           let entry!: ActiveEvent
           const execution = Promise.race([
-            runEvent(event, supersede.signal, endAttempt),
+            runEvent(
+              event,
+              supersede.signal,
+              endAttempt,
+              () => {
+                entry.completing = true
+              },
+              sessionHead,
+            ),
             fenced,
           ]).then((eventOutcome) => {
             // Identity-guarded: a fenced predecessor's continuation must
             // not delete the entry of the attempt that replaced it.
-            if (active.get(event.index) === entry) active.delete(event.index)
+            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,
+            completing: false,
           }
-          active.set(event.index, entry)
+          active.set(key, entry)
           scheduleLapse()
           if (!heartbeat && !stopRenewing) {
             heartbeat = setInterval(
@@ -3345,9 +3920,11 @@ export function createServer<
                     ...(window.deadlineCapped
                       ? { expiresAtMs: window.expiresAtMs }
                       : {}),
+                    consumers: only ? [storeConsumerOf(only)] : storeConsumers,
+                    ...(through === undefined ? {} : { through }),
                     ...(excluded.size === 0
                       ? {}
-                      : { excludeIndexes: [...excluded] }),
+                      : { exclude: [...excluded.values()] }),
                   })
                   claimSpan.setAttribute('a2.claim.outcome', result.outcome)
                   claimSpan.setAttribute(
@@ -3367,7 +3944,8 @@ export function createServer<
                   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
               }
             }
@@ -3413,6 +3991,12 @@ export function createServer<
             }
             if (claim === undefined) continue
             if (signal && signal.version !== signalVersion) continue
+            // A run that finished while the claim was in flight may have
+            // moved its cursor to a head the claim's snapshot missed.
+            if (claimAgain) {
+              claimAgain = false
+              continue
+            }
             if (claim.outcome === 'busy') {
               requestWatchdog(
                 claim.retryAt.getTime() + DRAIN_TIMINGS.watchdogGraceMs,
@@ -3424,6 +4008,12 @@ export function createServer<
             if (signal) signal.closed = true
             break
           }
+        } catch (error) {
+          // The successor armed for this drain's claims drains the session
+          // again, so the scheduler delivery need not stay as a second retry.
+          if (!handOffFailure || schedulerArm === undefined) throw error
+          span.recordError(error)
+          outcome = 'failed'
         } finally {
           if (signal) signal.closed = true
           stopRenewing = true
@@ -3481,8 +4071,10 @@ export function createServer<
     }) as SessionAppend<D>
     return Object.assign(makeSession(id, append, null), {
       deadLetters: () => listDeadLetters(id),
-      redrive: (index: number, redriveOptions: SessionRedriveOptions) =>
-        redriveEvent(id, index, redriveOptions),
+      redrive: (
+        target: { consumer: string; index: number },
+        redriveOptions: SessionRedriveOptions,
+      ) => redriveEvent(id, target, redriveOptions),
     })
   }
 
@@ -3525,7 +4117,10 @@ export function createServer<
     },
     schedulerDrain: (sessionId, opts) => {
       assertSessionId(sessionId)
-      return drainSession(sessionId, opts?.watchdogDueAt)
+      return drainSession(sessionId, {
+        watchdogDueAt: opts?.watchdogDueAt,
+        handOffFailure: true,
+      })
     },
     schedulerAppend: async (sessionId, events, originIndex) => {
       if (!scheduler) {
@@ -3543,7 +4138,7 @@ export function createServer<
           originIndex,
         )
       } catch (error) {
-        // The scheduling handler's lifetime was cleared: an acknowledged no-op.
+        // The scheduling consumer's lifetime was cleared: an acknowledged no-op.
         if (
           originIndex !== undefined &&
           error instanceof A2Error &&
@@ -3591,6 +4186,12 @@ function assertStateIndex(value: number): void {
   }
 }
 
+function assertConsumeIndex(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError('consume through must be a non-negative safe integer')
+  }
+}
+
 function assertRedriveIndex(value: number): void {
   if (!Number.isSafeInteger(value) || value < 1) {
     throw new TypeError('redrive requires a positive safe-integer index')
@@ -3605,7 +4206,7 @@ function assertClearIndex(value: number): void {
 
 function assertAppendName(name: string): void {
   if (typeof name !== 'string' || name.length === 0) {
-    throw new TypeError('handler append name must be a non-empty string')
+    throw new TypeError('consumer append name must be a non-empty string')
   }
 }