experimental-a2 0.20.0 → 0.22.0

package/docs/reference/02-server.mdx

@@ -5,61 +5,51 @@ description: "`experimental-a2/server`: `createServer`, its route, the store and
 
 ## `experimental-a2/server`
 
-### `handler(entry)`
-
-Normalizes a handler entry so you can compose an existing handler without
-branching on its shape. For ordinary use, define handlers inline in
-`createServer({ handlers })`.
-
-- Accepts a function or `{ handler, lane?, abortOn? }` and returns the object
-  shape: a function becomes `{ handler: entry }`, an object is returned
-  unchanged, and both keep their original types.
-- Does not bind a contract; `createServer({ handlers })` checks the match.
-  Annotate a new handler's context, as below, or pass an already typed
-  function.
-- Spreading the result keeps `lane` and `abortOn`; set either after the spread
-  to override it. Changing a built-in AI handler's lane can separate it from
-  the handlers it coordinates with.
-- A composition runs in one handler attempt. Work after the original resolves
-  still runs before its returned events commit, a throw fails the composed
-  attempt, and a retry can run both again.
-
-```ts server/composed-orders.ts
-import * as a2 from 'experimental-a2'
-import { createServer, handler, type HandlerContext } from 'experimental-a2/server'
-import { z } from 'zod'
-
-const orders = a2.contract({
-  name: 'composed-orders',
-  events: {
-    created: z.object({ shopId: z.string() }),
-    notified: z.object({ shopId: z.string() }),
-  },
-})
+### `consumer(options)`
 
-const created = handler({
-  lane: 'orders',
-  handler: async (ctx: HandlerContext<typeof orders.events, 'created'>) => {
-    return orders.batch({ type: 'notified', payload: ctx.event.payload })
-  },
-})
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: {
-      ...created,
-      handler: async (ctx) => {
-        const result = await created.handler(ctx)
-        // Your additional work goes here:
-        // await notifyShop(ctx.event.payload, { idempotencyKey: ctx.event.id })
-        return result
-      },
-    },
-  },
-})
+```ts
+consumer(options: {
+  contract: Contract // the contract whose events it reads
+  name: string // its identity, unique per server
+  types?: readonly EventType[] // default: every type
+  lane?: string | ((ctx: LaneContext) => string | null) // default: concurrent
+  backfill?: boolean // default false; needs a string lane, and no abortOn
+  abortOn?: AbortSpec
+}): { run(fn: (ctx: Context) => Promise<void | AppendInput | readonly AppendInput[]>): Consumer }
+```
+
+Defines a named reader of every session's log. `.run()` takes the function and
+returns the `Consumer` you pass to `createServer({ consumers })` or
+`session.consume()`. In `consumers`, the same options without `contract`, and
+`run`, define one inline on the server's contract. See
+[Consumers](/server/consumers).
+
+| Option | Behavior |
+| --- | --- |
+| `name` | 1-128 letters, digits, and `. _ : -`, starting with a letter or digit. Cursors, failures, dead letters, and child event ids key on it, so a new name is a new consumer. Names starting with `a2.` are reserved. |
+| `types` | The event types it runs on, at least one; `ctx.event` narrows to them. Other events start no work for it. Leave it out to take every type. |
+| `lane` | Omitted: every event runs concurrently on its own cursor. A string: one cursor runs every event in log order. A function of `{ sessionId, event }`: the event's lane, or `null` to run it concurrently. Resolved and stored at append. |
+| `backfill` | `true` starts a new consumer at the beginning of the log instead of at the first event appended after it exists. Needs a string `lane` and no `abortOn`; anything else throws a `TypeError`. |
+| `abortOn` | Events that fire `ctx.signal` while `run` works: an array matches by type; an object maps types to predicates `(event, trigger, { attempt })`, whose `attempt` is the trigger's durable attempt, so a cancellation can fence one recovered run. See [Cancellation](/server/cancellation). Not with `backfill`: cancellation is for work in progress, and checking it while replaying history would read the rest of the log for every event. |
+
+```ts
+// consumer options: a cancel that names one recovered run
+abortOn: {
+  cancelled: (event, trigger, { attempt }) =>
+    event.payload.of === `${trigger.id}:${attempt}`,
+},
 ```
 
+- `run` receives the context below, with `ctx.attempt` counting claims of this
+  event for this consumer. Returned events commit with the cursor's advance;
+  `ctx.session.append` commits immediately. Both derive ids of events without
+  an `id` from the trigger and the consumer's name.
+- An invalid name, an empty or unknown type list, or `backfill` with a non-string lane or with `abortOn` throws
+  a `TypeError` before any I/O. `createServer` throws on two consumers with
+  one name or a consumer of another contract.
+- `Consumer`, `ConsumerOptions`, `ConsumerLane`, `ConsumerResult`, and
+  `AbortSpec` are exported from `experimental-a2/server`.
+
 ### `createServer(options)`
 
 ```ts
@@ -69,65 +59,42 @@ createServer(options: {
   scheduler?: A2Scheduler
   telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
   presence?: { ttlMs?: number } // presence expiry policy; default 60s
-  handlers?: {
-    [type]:
-      | Handler
-      | {
-          abortOn?: AbortSpec
-          lane?: string | ((ctx: LaneContext) => string)
-          handler: Handler
-        }
-  }
+  consumers?: readonly (Consumer | InlineConsumer)[] // see consumer(options)
 }): A2Server
-
-type Handler = (
-  ctx: Context,
-) => Promise<void | AppendInput | readonly AppendInput[]>
 ```
 
 Implements a contract: binds its vocabulary to storage and reactions.
 `experimental-a2/server` is the only entry point that can reach a store
 backend; under the browser condition its exports resolve to a loud error. See
-[Handlers](/server/handlers).
+[Consumers](/server/consumers). The options type is `ServerOptions`, exported
+from `experimental-a2/server`.
 
 | Option | Behavior |
 | --- | --- |
-| `handlers` | One table, complete at construction. Compose files by spreading objects in; a duplicate key silently last-wins. |
-| `lane` | Within one session, same-lane events run one at a time in log order; all others run concurrently. A resolver receives `{ sessionId, event }`. The value is resolved and stored at append, so a later deployment can't reinterpret pending work. See [Lanes](/server/handlers#lanes). |
-| `abortOn` | Events that fire `ctx.signal` while the handler runs: an array matches by type; an object maps types to predicates `(event, trigger, { attempt })`, whose `attempt` is the trigger's durable attempt, so a cancellation can fence one recovered run. See [Cancellation](/server/cancellation). |
+| `consumers` | The consumers this server runs, each with its own cursors in every session: a `Consumer` from `consumer()`, or `{ name, types?, lane?, backfill?, abortOn?, run }` inline, whose `run` narrows to its `types`. Names must be unique, and every consumer must read this server's contract; otherwise construction throws a `TypeError`. Omit it for a history-only server. |
 | `presence.ttlMs` | How long a presence value survives without a refreshing set: a positive integer of milliseconds, default 60 seconds, counted on the storage's clock, never the sender's stamp. Only for contracts that declare `presence`; elsewhere construction throws a `TypeError`. |
 
-```ts
-generate: {
-  abortOn: {
-    cancelled: (event, trigger, { attempt }) =>
-      event.payload.of === `${trigger.id}:${attempt}`,
-  },
-  handler: async (ctx) => { /* ... */ },
-}
-```
-
-- Handlers are concurrent by default. A2 starts every eligible event once its
-  append commits.
-- A handler returns nothing, one event, or an array. A2 marks the trigger
-  processed and appends the returned batch in one atomic store operation; when
-  the handler throws, the returned events never exist.
-- Handlers are optional per event type. An event type without one settles in
-  its append transaction with no dispatch attempt, and starts no drain or
-  scheduler arm when the session has no older pending handler work. See
-  [Events without handlers](/server/handlers#events-without-handlers).
+- A2 starts every eligible event once its append commits. A consumer without
+  a lane runs its events concurrently.
+- `run` returns nothing, one event, or an array. A2 moves the consumer's
+  cursor past the trigger and appends the returned batch in one atomic store
+  operation; when `run` throws, the returned events never exist.
+- An event no consumer takes starts no work: no dispatch attempt, and no drain
+  or scheduler arm when the session has no older pending work. See
+  [Which events it takes](/server/consumers#which-events-it-takes).
 
-The context every handler receives:
+The context every consumer's `run` receives, `ConsumerContext`:
 
 | Property | Meaning |
 | --- | --- |
 | `ctx.event` | `Event`: the triggering event |
-| `ctx.attempt` | durable 1-based dispatch claim ordinal; increments on every durable claim and may skip when a process dies before handler entry |
-| `ctx.session` | this session: `id` (equal to `ctx.event.sessionId`), `append`, `schedule`, `clear`, `history`, `state`, `stream`, `setPresence` |
+| `ctx.attempt` | durable 1-based claim ordinal of this event for this consumer; increments on every durable claim and may skip when a process dies before `run` |
+| `ctx.session` | this session: `id` (equal to `ctx.event.sessionId`), `append`, `schedule`, `clear`, `history`, `state`, `stream`, `consume`, `setPresence` |
 | `ctx.signal` | `AbortSignal`: fires on lease lapse (`CLAIM_EXPIRED`), proven supersession (`SUPERSEDED_ATTEMPT`), and matching `abortOn` events |
 
-`ctx.session` shares the `server.session(id)` surface; handler-specific
-behavior is noted under each method. Its `state(reducer)` folds through the
+`ConsumerContext`, `ConsumerAppend`, and `LaneContext` are exported from
+`experimental-a2/server`. `ctx.session` shares the `server.session(id)`
+surface; consumer-specific behavior is noted under each method. Its `state(reducer)` folds through the
 trigger's index by default (see
 [`session.state`](#sessionstatereducer-options)), and its `append` takes a
 name:
@@ -136,12 +103,12 @@ name:
 ctx.session.append(name: string, ...events: AppendInput[]): Promise<Event[]>
 ```
 
-- It commits immediately, so its events may run while the handler is still
-  active unless a lane orders them. See
-  [Append what should happen now](/server/handlers#append-what-should-happen-now).
+- It commits immediately, so its events may run while `run` is still active
+  unless a lane orders them. See
+  [Append what should happen now](/server/consumers#append-what-should-happen-now).
 - The name is the idempotency key, scoped to the trigger, for events whose
-  `id` is omitted: each such id derives from the trigger id, the name, and the
-  event's position. The same name and generated-id batch returns the existing
+  `id` is omitted: each such id derives from the trigger id, the consumer's
+  name, the append's name, and the event's position. The same name and generated-id batch returns the existing
   rows on retry; a changed batch conflicts with them.
 - An explicit `id` wins, so different triggering events can converge on one
   fact. Root `server.session(id).append(...events)` takes no name.
@@ -214,7 +181,7 @@ automatically.
 - Authentication stays in the route, where headers, cookies, and framework
   context are available. Capture the authenticated principal in `authorize`.
 - `authorize` is an ingress policy for this `fetch` call, not a global server
-  policy: direct `session.append`, handler appends, scheduled appends, and
+  policy: direct `session.append`, consumer appends, scheduled appends, and
   server-side `setPresence` bypass it.
 - By default the `sessionId` and `index` query parameters bind one session to
   the socket. A2 authorizes the stream before upgrading, and frames can't
@@ -243,7 +210,7 @@ you append, read, or stream. `session.id` is the `id` passed in. See
 
 It has every [session method](#session), plus
 [`deadLetters()`](#sessiondeadletters) and
-[`redrive()`](#sessionredriveindex-options), which `ctx.session` doesn't.
+[`redrive()`](#sessionredrivetarget-options), which `ctx.session` doesn't.
 
 ### `server.drain(sessionId)`
 
@@ -251,43 +218,48 @@ It has every [session method](#session), plus
 server.drain(sessionId: string): Promise<{ settled: boolean }>
 ```
 
-Claims every eligible event and runs their handlers concurrently.
+Claims every eligible event for each consumer and runs them concurrently.
 `settled` means no actionable or live-claimed work remains. Past the
 invocation's deadline it claims nothing and returns `settled: false`. A dead-lettered
 event can block later work in its lane while other lanes continue, until
-[`session.redrive()`](#sessionredriveindex-options) resolves it. Scheduler
+[`session.redrive()`](#sessionredrivetarget-options) resolves it. Scheduler
 callbacks use it; you'll rarely call it yourself. The public result stays this
 simple boolean.
 
 ### `A2Store`
 
-Custom store adapters implement these atomic drain methods:
+Custom store adapters keep the log and one cursor per (session, consumer,
+lane). These are the dispatch methods:
 
 ```ts
 // Custom server store adapter:
 type EventCause = {
+  consumer: string
+  lane: string | null // null: a concurrent consumer's cursor of one event
   index: number
   attempt: number
-  batchSize?: number // present on named handler appends
+  batchSize?: number // present on named consumer appends
 }
 
+type EventTarget = { consumer: string; lane: string | null }
+
 type AppendEvent = {
   type: string
   payload: unknown
   id?: string
   cause?: EventCause
-  lane?: string
-  settled?: true // internal: no handler is registered for this event type
+  targets?: readonly EventTarget[] // lane-function and concurrent consumers
 }
 
 type ReturnedEvent = AppendEvent & { id: string }
 
-type StoredEvent = Event & {
-  cause: EventCause | null
+type StoredEvent = Event & { cause: EventCause | null }
+
+type HeadRef = { consumer: string; lane: string | null; index: number }
+
+type HeadDispatch = {
+  consumer: string
   lane: string | null
-  processedAt: Date | null
-  processedByAttempt: number | null
-  returnedEventIds: string[] | null
   firstClaimedAt: Date | null
   lastClaimedAt: Date | null
   attemptCount: number
@@ -298,16 +270,25 @@ type StoredEvent = Event & {
   lastFailedAttempt: number | null
   lastError: string | null
   failedAt: Date | null
-  clearIndex?: number // on claimed events, once the session has been cleared
 }
 
-type StoreAppendResult = {
-  events: StoredEvent[]
-  hasPending: boolean
+type HeadEvent = StoredEvent &
+  HeadDispatch & {
+    clearIndex?: number // on claimed heads, once the session has been cleared
+  }
+
+type StoredCursor = HeadDispatch & { position: number; head: number | null }
+
+type StoreConsumer = {
+  name: string
+  // a consumer with one string lane: its cursor reads the log by type
+  log?: { lane: string; types: readonly string[] | null; backfill: boolean }
 }
 
+type StoreAppendResult = { events: StoredEvent[]; hasPending: boolean }
+
 type StoreClaimAvailableResult =
-  | { outcome: 'claimed'; events: StoredEvent[] }
+  | { outcome: 'claimed'; events: HeadEvent[]; head?: number } // head: the session's head when the claim was made
   | { outcome: 'busy'; retryAt: Date }
   | { outcome: 'settled' }
 
@@ -319,9 +300,19 @@ interface A2Store {
   append(
     sessionId: string,
     events: AppendEvent[],
-    options?: { originIndex?: number },
+    options?: { originIndex?: number; consumers?: readonly StoreConsumer[] },
   ): Promise<StoreAppendResult>
 
+  cursors(sessionId: string): Promise<StoredCursor[]>
+
+  // for session.consume(): create a missing log cursor (at the clear marker
+  // with backfill, else at the head), give an idle one its next event,
+  // leave one with a head alone; returns it and the session's head
+  wakeLog(options: {
+    sessionId: string
+    consumer: StoreConsumer & { log: NonNullable<StoreConsumer['log']> }
+  }): Promise<{ cursor: StoredCursor; head: number }>
+
   // optional together; required for session.clear()
   clear?(options: {
     sessionId: string
@@ -331,11 +322,13 @@ interface A2Store {
   reclaim?(sessionId: string): Promise<{ deleted: number; done: boolean }>
 
   // optional together; required for session.deadLetters() and redrive()
-  deadLetters?(sessionId: string): Promise<StoredEvent[]>
+  deadLetters?(sessionId: string): Promise<HeadEvent[]>
   redrive?(options: {
     sessionId: string
+    consumer: string
     index: number
     action: 'retry' | 'skip'
+    consumers?: readonly StoreConsumer[]
   }): Promise<{ redriven: boolean; hasPending: boolean }>
 
   claimAvailable(options: {
@@ -343,27 +336,33 @@ interface A2Store {
     holder: string
     ttlMs: number
     expiresAtMs?: number
-    excludeIndexes?: readonly number[]
+    exclude?: readonly HeadRef[]
+    consumers?: readonly StoreConsumer[]
     maxFailures?: number
   }): Promise<StoreClaimAvailableResult>
 
   renewClaims(options: {
     sessionId: string
     holder: string
-    claims: readonly { index: number; attempt: number }[]
+    claims: readonly (HeadRef & { attempt: number })[]
     ttlMs: number
     expiresAtMs?: number
-  }): Promise<{ renewed: number[]; superseded: number[] }>
+  }): Promise<{ renewed: HeadRef[]; superseded: HeadRef[] }>
 
   completeAttempt(options: {
     sessionId: string
+    consumer: string
+    lane: string | null
     index: number
     attempt: number
     events: ReturnedEvent[]
+    consumers?: readonly StoreConsumer[]
   }): Promise<CompleteAttemptResult>
 
   failAttempt(options: {
     sessionId: string
+    consumer: string
+    lane: string | null
     index: number
     attempt: number
     error: string
@@ -376,17 +375,27 @@ interface A2Store {
 }
 ```
 
+A cursor's **head** is the next event it runs: the lowest unfinished event of
+its lane, the event itself for a concurrent cursor, or for a log cursor the
+next event after its position whose type it takes. The clear marker is never a
+head. A head is eligible when no live claim or retry hold owns it, it is not
+dead-lettered, and it lies above the latest clear marker. Moving a cursor past
+its head resets the head's attempt and failure fields and releases its
+snapshot pins. `consumers` names the consumers the caller serves: work for any
+other consumer is neither pending nor claimed. Omitted, every cursor counts.
+
 | Method | Atomic effect |
 | --- | --- |
-| `append` | Write a consecutive batch and report session-wide pending handler work as `hasPending`. Events with the internal `settled` flag get `processedAt` in the same transaction, with no dispatch attempt. An event with a `cause` commits only while `cause.attempt` is the parent's latest attempt and the parent isn't dead-lettered; otherwise throw `SUPERSEDED_ATTEMPT`. The check serializes against a concurrent claim, after the idempotent-replay path. |
-| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. Taking over a lapsed claim, one its holder never completed or failed, adds one to `failureCount`; when that reaches `maxFailures`, dead-letter the event instead of claiming it: advance `attemptCount` to fence the lapsed attempt, leave `lastFailedAttempt` unchanged, and return it with `failedAt` set. A failure's retry hold has no holder, so it is no lapsed claim. |
-| `renewClaims` | Extend the listed live claims the holder still owns. `renewed` lists those; `superseded` lists claims whose event's `attemptCount` passed the listed attempt. An expired claim no successor took is in neither and may still complete; renewal never revives it. |
-| `completeAttempt` | In one transaction: fence on the current attempt, mark the parent processed, store its exact ordered `returnedEventIds`, and append the returned batch. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
-| `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. Short of that, with `retryAfterMs` the event stays unclaimable for that long: set its claim expiry with no holder, so `claimAvailable` reports it `busy` until then. A repeated acknowledgment is idempotent; a stale attempt returns `superseded`. |
-| `clear` | Serialized with `append`. Check `ifLastIndex` against the head and the latest marker, then append a settled clear marker at the next index, touching no existing rows. A `cause` is fenced like a handler append. |
-| `reclaim` | Delete one bounded batch of rows below the latest clear marker, with their bookkeeping, event-id records, lane pointers, and cached state. Report how many rows went, and `done` when none are left. Never wait on a lock other methods hold. |
-| `deadLetters` | Return the unprocessed events with `failedAt` set above the latest clear marker, oldest first. |
-| `redrive` | Only for an unprocessed event with `failedAt` set above the latest clear marker. `retry` clears `failedAt` and `failureCount`, leaving claims and the last failure. `skip` sets `processedAt` with no `processedByAttempt` or `returnedEventIds` and exposes the next event in its lane. Anything else reports `redriven: false` and writes nothing. Both serialize with claims and handler appends, `skip` also with lane promotion; report `hasPending` like `append`. |
+| `append` | Write a consecutive batch. Each event's `targets` start work: a lane target queues the event in that consumer's lane cursor, a null lane creates a cursor for that event alone. Each log consumer in `consumers` whose types the batch carries gets its cursor created (at the start of the log with `backfill`, otherwise just before the batch) or, when idle, a head. Report pending work for the served consumers as `hasPending`. An event with a `cause` commits only while that cursor's head is `cause.index`, `cause.attempt` is its latest attempt, and it isn't dead-lettered; otherwise throw `SUPERSEDED_ATTEMPT`. The check serializes against a concurrent claim, after the idempotent-replay path. |
+| `cursors` | List every log and lane cursor, and every concurrent cursor that still has a head, by consumer, then lane, with concurrent cursors last by head. Lane and concurrent cursors whose work lies at or below the latest clear marker are not listed. |
+| `claimAvailable` | Claim every eligible head of the served consumers, in event order, then by consumer. A claim records its holder, expiry, timestamps, and next `attemptCount`. Taking over a lapsed claim, one its holder never completed or failed, adds one to `failureCount`; when that reaches `maxFailures`, dead-letter the head instead of claiming it: advance `attemptCount` to fence the lapsed attempt, leave `lastFailedAttempt` unchanged, and return it with `failedAt` set. Excluded heads stay unclaimed and keep blocking their lane. A claim may report `head`, the session's head when the claim was made. |
+| `renewClaims` | Extend the listed live claims the holder still owns. `renewed` lists those; `superseded` lists claims whose head a newer attempt took, or whose cursor moved past it. An expired claim no successor took is in neither and may still complete; renewal never revives it. |
+| `completeAttempt` | In one transaction: fence on the current attempt, append the returned batch with its own targets, record the completion with its exact ordered child ids, and move the cursor past its head. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
+| `failAttempt` | Record one current caught failure on the cursor, clear its claim, and dead-letter at `maxFailures`. Short of that, with `retryAfterMs` the head stays unclaimable for that long: set its claim expiry with no holder, so `claimAvailable` reports it `busy` until then. A repeated acknowledgment is idempotent; a stale attempt returns `superseded`. |
+| `clear` | Serialized with `append`. Check `ifLastIndex` against the head and the latest marker, then append a clear marker at the next index. Log cursors count from the marker; lane and concurrent cursors at or below it are superseded. A `cause` is fenced like a consumer append. |
+| `reclaim` | Delete one bounded batch of rows below the latest clear marker, with their cursor records, event-id records, and cached state. Report how many rows went, and `done` when none are left. Never wait on a lock other methods hold. |
+| `deadLetters` | Return the dead-lettered heads above the latest clear marker, in event order, then by consumer. |
+| `redrive` | Only for the consumer's dead-lettered head at `index` above the latest clear marker. `retry` clears `failedAt` and `failureCount`, leaving claims and the last failure. `skip` moves the cursor past it with no completion. Anything else reports `redriven: false` and writes nothing. Both serialize with claims and consumer appends; report `hasPending` like `append`. |
 
 `readHistory(sessionId, options)` is an optional capability with the same
 exclusive `afterIndex` and inclusive `throughIndex` bounds as `read()`. Without
@@ -396,14 +405,14 @@ A store that supports clearing treats every event at or below the latest
 marker as superseded, whether or not its row still exists. Each check belongs
 inside the operation's existing atomic step:
 
-- `claimAvailable` never claims it; lane readiness at append and completion
-  ignores it, so a dead-lettered lane head stops blocking.
+- `claimAvailable` never claims it, so a dead-lettered lane head stops
+  blocking; a new event in that lane becomes its head.
 - `renewClaims` reports it in `superseded`; `completeAttempt` and
   `failAttempt` return `superseded`.
 - An `append` whose `cause` names it throws `SUPERSEDED_ATTEMPT`; one whose
   `originIndex` is at or below the marker throws `SESSION_CLEARED`.
 - Reads start at the marker; `readState` returns its index as `clearIndex`,
-  and claimed events carry it as `clearIndex`.
+  and claimed heads carry it as `clearIndex`.
 - In `append` and `completeAttempt`, an event id whose row is below this
   session's marker is free to reuse.
 
@@ -414,15 +423,18 @@ stores support both.
 
 Stored fields:
 
-- `attemptCount` counts claims, including abandoned ones. `failureCount`
-  counts failed attempts: caught failures, and lapsed claims a later claim
-  took over. Ten dead-letter the event. See
+- `attemptCount` counts claims of the current head, including abandoned ones.
+  `failureCount` counts its failed attempts: caught failures, and lapsed
+  claims a later claim took over. Ten dead-letter the head. Both start over
+  when the cursor moves on. See
   [Guarantees](/server/guarantees#one-event-many-attempts).
-- `cause` names the event and handler attempt whose `ctx.session.append` or
-  return value first persisted the child; `null` means a top-level event.
-- `lane` is the session-scoped serialized group, resolved before append.
-- `returnedEventIds` makes a lost completion acknowledgment recoverable without
-  accepting a partial child batch.
+- `cause` names the consumer, lane, event, and attempt whose
+  `ctx.session.append` or return value first persisted the child; `null`
+  means a top-level event.
+- `lane` is the cursor's lane, resolved before append; `null` is a concurrent
+  cursor of one event.
+- A completion's recorded child ids make a lost acknowledgment recoverable
+  without accepting a partial child batch.
 - Lifecycle timestamps are adapter clock values for their atomic operations,
   not exact database commit times. Built-in adapters persist all these fields
   inside their existing atomic operations, with no extra round trip.
@@ -453,7 +465,7 @@ from `experimental-a2/server`.
 
 Drain tasks wake pending work and carry no application payload. Append tasks
 carry the events for `session.schedule`; `originIndex` is the scheduling
-handler's event, absent for root schedules. Clear tasks carry the condition for
+consumer's trigger, absent for root schedules. Clear tasks carry the condition for
 `session.schedule.clear`.
 
 Deliver an authenticated, normalized append or clear task through the server
@@ -482,7 +494,7 @@ verifies that the task and server contract match.
 
 - `deliverSchedulerAppend` revalidates the carried event inputs and uses the
   ordinary top-level append. The target server must have a scheduler. When
-  the append leaves pending handler work, it resolves only after a recovery
+  the append leaves pending consumer work, it resolves only after a recovery
   watchdog is durable, so a send failure keeps the delivery retryable. A task
   whose `originIndex` was cleared resolves without appending.
 - `deliverSchedulerClear` runs `clear({ ifLastIndex })` and resolves after its
@@ -505,11 +517,12 @@ The only way to move a session forward. See [Guarantees](/server/guarantees).
 - A multi-event append is atomic: all-or-nothing, consecutive positions, one
   transaction.
 - An explicit `id` makes it idempotent across retries; re-sending an identical
-  batch returns the original rows.
+  batch returns the original rows. Ids are unique per session: the same `id`
+  in another session is another event.
 - Events pushed through `server.fetch` arrive through this same append.
-- Only event types with registered handlers are dispatched; the append itself
-  settles the rest. An unhandled append still starts session healing when
-  older handled work is pending. The store reports that pending state in the
+- Only events some consumer takes are dispatched; the append itself settles
+  the rest. An append no consumer takes still starts session healing when
+  older work is pending. The store reports that pending state in the
   atomic append, so the decision needs no follow-up read.
 
 ### `session.append.dispatch(...events)`
@@ -525,7 +538,7 @@ scheduler instead of starting an inline drain. See
 [Dispatch in a fresh invocation](/schedulers/overview#dispatch-in-a-fresh-invocation).
 
 - Awaits acceptance of an immediate scheduler message. A batch that leaves no
-  pending handler work sends none.
+  pending consumer work sends none.
 - Throws before writing when the server has no scheduler.
 - If the send fails, the events are already durable: give them explicit IDs
   and retry the same dispatch.
@@ -546,7 +559,7 @@ session.schedule(
 ```
 
 Appends the events later through the configured scheduler, from root and
-handler sessions. Resolves after provider acceptance, not after append. `name`
+consumer sessions. Resolves after provider acceptance, not after append. `name`
 must be non-empty, with at least one event. `ScheduleDelay`, `ScheduleTiming`,
 and `SessionSchedule` are exported from `experimental-a2/server`. See
 [Timers](/server/timers) for stale-timer guards, provider limits, and
@@ -554,7 +567,7 @@ deployment compatibility.
 
 | Timing | Meaning |
 | --- | --- |
-| `{ delay: '30s' }` | relative delay with unit `ms`, `s`, `m`, `h`, or `d`; from the call's wall clock on a root session, from the trigger's durable `createdAt` in a handler, so handler retries keep the delivery time |
+| `{ delay: '30s' }` | relative delay with unit `ms`, `s`, `m`, `h`, or `d`; from the call's wall clock on a root session, from the trigger's durable `createdAt` in a consumer, so retries keep the delivery time |
 | `{ at: Date }` | absolute delivery time; use it when a retried root call needs one target |
 
 - The template type checks the unit. At runtime the number must be an
@@ -563,9 +576,10 @@ deployment compatibility.
   once are rejected.
 - The target is the earliest useful delivery time. Adapters encode it in
   whole-second slots; an already-due target is sent immediately.
-- The task id derives from the contract, session, and name. Handler tasks add
-  the trigger id and, once the session has been cleared, the clear, so a
-  trigger id reused in a new lifetime schedules a new task. Omitted event ids
+- The task id derives from the contract, session, and name. A consumer's
+  tasks add the trigger id, the consumer's name, and, once the session has
+  been cleared, the clear, so a trigger id reused in a new lifetime schedules
+  a new task. Omitted event ids
   derive from the task id and position; explicit ids win.
 - Reuse a name only for identical timing and events. Provider deduplication is
   an optimization; stable event ids make later duplicate deliveries converge in
@@ -575,11 +589,11 @@ deployment compatibility.
   functions, symbols, cycles, accessors, and non-plain prototypes are rejected;
   shared references become independent values.
 - Delivery validates the snapshotted schema input through an ordinary
-  top-level append, outside any handler's completion transaction, so a schema
-  transform produces the stored payload from the original input. The events
-  have `cause: null` and run through handlers, lanes, state, and streams
-  normally.
-- A handler task belongs to its trigger's lifetime: if the session is cleared
+  top-level append, outside any consumer's completion transaction, so a
+  schema transform produces the stored payload from the original input. The
+  events have `cause: null` and run through consumers, lanes, state, and
+  streams normally.
+- A consumer's task belongs to its trigger's lifetime: if the session is cleared
   before delivery, it is acknowledged without appending. A root task joins
   whichever lifetime exists at delivery, and its name identifies one task
   across lifetimes, so put something from the new lifetime in the name when
@@ -611,10 +625,10 @@ and `index` is always the head after the call:
 | otherwise | `{ cleared: true, index }`, the new marker |
 
 - Every event at or below the marker is superseded: never dispatched again,
-  never blocking its lane. Its running handler's appends throw
+  never blocking its lane. A run still working on one has its appends throw
   `SUPERSEDED_ATTEMPT` and its state reads throw `SESSION_CLEARED` rather than
   fold the new lifetime. Exception: after a clear from another instance, a
-  read bounded at the handler's own event may return that event's state from
+  read bounded at the run's own event may return that event's state from
   memory until its `ctx.signal` aborts.
 - Pushes and appends after the marker start the new lifetime.
 - `clear()` then deletes the old events, their bookkeeping and event-id
@@ -624,8 +638,8 @@ and `index` is always the head after the call:
 - If deletion fails, the call rejects with the session already cleared; any
   later clear of the session, including a retry, finishes the deletion.
 - Old event ids can be used again. Presence is not cleared.
-- On `ctx.session`, the clear is fenced like the handler's appends and ends the
-  handler's own attempt: `ctx.signal` aborts with `SUPERSEDED_ATTEMPT` and
+- On `ctx.session`, the clear is fenced like the run's appends and ends the
+  run's own attempt: `ctx.signal` aborts with `SUPERSEDED_ATTEMPT` and
   returned events are discarded. Its deletion keeps running under the
   platform's `waitUntil`.
 - All built-in stores support clearing.
@@ -647,19 +661,19 @@ works as in `session.schedule`, with the same provider limits. See
 [Scheduling a clear](/contract/sessions#scheduling-a-clear).
 
 - The task id derives from the contract, session, name, and condition, plus
-  the trigger id and any earlier clear inside a handler. Reuse a name only for
-  the same timing.
+  the trigger id, the consumer's name, and any earlier clear inside a
+  consumer. Reuse a name only for the same timing.
 - Delivery runs `clear({ ifLastIndex })` and acknowledges after the deletion
   finishes. No event is appended; a stale or duplicate delivery changes
   nothing. Indexes never repeat, so a condition from an older lifetime never
   matches a newer one.
 - `ifLastIndex: ctx.event.index` matches only while the trigger is still the
-  head. The handler's own appends and returned events move the head, so a
-  handler that writes should use the index of its last `ctx.session.append`.
+  head. The consumer's own appends and returned events move the head, so a
+  consumer that writes should use the index of its last `ctx.session.append`.
   Actor handlers always commit state, so they can't use the trigger's index.
-- A delay short enough to deliver while the handler still runs can match
-  before its writes land; the clear then ends the handler's attempt and
-  discards its returned events.
+- A delay short enough to deliver while `run` still works can match before its
+  writes land; the clear then ends that attempt and discards its returned
+  events.
 - Each delivery attempt resumes the deletion. Vercel Queues redelivers until
   retention ends. QStash retries up to its `retries` budget; a deletion that
   outlasts them leaves the message in QStash's dead-letter queue, the rest of
@@ -672,6 +686,7 @@ works as in `session.schedule`, with the same provider limits. See
 session.deadLetters(): Promise<DeadLetter[]>
 
 type DeadLetter = Event & {
+  consumer: string
   lane: string | null
   attemptCount: number
   failureCount: number
@@ -680,35 +695,37 @@ type DeadLetter = Event & {
 }
 ```
 
-The session's dead-lettered events, oldest first, each with why it failed. See
-[Resolve a dead letter](/server/handlers#resolve-a-dead-letter).
+The session's dead letters in event order, then by consumer, each with why it
+failed. One event can be dead for one consumer and done for another. See
+[Resolve a dead letter](/server/consumers#resolve-a-dead-letter).
 
 - `failureCount` counts the attempts that spent its budget: caught failures,
   and attempts that ended before they finished. `attemptCount` counts every
-  claim. `lastError` is the last error a handler threw, stringified, or null
+  claim. `lastError` is the last error `run` threw, stringified, or null
   when every failed attempt ended before it finished.
 - Events at or below the latest clear marker are never listed.
 - Only on `server.session(id)`. `DeadLetter` is exported from
   `experimental-a2/server`.
 
-### `session.redrive(index, options)`
+### `session.redrive(target, options)`
 
 ```ts
 session.redrive(
-  index: number,
+  target: { consumer: string; index: number },
   options: { action: 'retry' | 'skip' },
 ): Promise<{ redriven: boolean }>
 ```
 
-Resolves the dead-lettered event at `index` in one atomic store operation.
+Resolves the consumer's dead-lettered event at `index` in one atomic store
+operation. Every dead letter names its consumer, A2's own included.
 
 | Action | Effect |
 | --- | --- |
-| `retry` | The handler runs again as a new attempt, with a fresh ten-failure budget. Once it completes, its lane continues. |
-| `skip` | The event is marked processed without running its handler, and the next event in its lane runs. Its effects never happen. |
+| `retry` | The consumer runs the event again as a new attempt, with a fresh ten-failure budget. Once it completes, its lane continues. |
+| `skip` | The consumer's cursor moves past the event without running it, and the next event in its lane runs. Its effects never happen for that consumer. |
 
-- `index` is a positive safe integer and `action` is required; anything else
-  throws a `TypeError` before any I/O.
+- `consumer` is a consumer's name, `index` is a positive safe integer, and
+  `action` is required; anything else throws a `TypeError` before any I/O.
 - `redriven` is `false`, with nothing written, when the event isn't
   dead-lettered: still pending, already processed, already redriven, missing,
   or at or below the latest clear marker. Calling it again is safe.
@@ -717,12 +734,50 @@ Resolves the dead-lettered event at `index` in one atomic store operation.
   `schedulerArmTimeoutMs`. A failed send doesn't reject the call; it marks the
   `a2.redrive` span and leaves later appends, `server.drain()`, or another
   `redrive` to wake the session.
-- A retried event keeps its `attemptCount` and last failure, so the next run's
-  `ctx.attempt` keeps counting. A skipped event keeps `failedAt` and has no
-  `processedByAttempt`.
+- A retried head keeps its `attemptCount` and last failure, so the next run's
+  `ctx.attempt` keeps counting. A skip moves the consumer's cursor on, and its
+  next head starts with fresh counts.
 - Only on `server.session(id)`. `SessionRedriveOptions` and
   `SessionRedriveResult` are exported from `experimental-a2/server`.
 
+### `session.consume(consumer, options?)`
+
+```ts
+session.consume(
+  consumer: Consumer,
+  options?: { through?: number; signal?: AbortSignal },
+): Promise<{ index: number }>
+```
+
+Runs a consumer with a string `lane` on this session, here, until it has
+handled every event it takes through `through`: by default the session's head
+when the call starts, and never more than it. Returns the index it has handled
+every event through, at least `through`. See
+[Run a consumer now](/server/consumers#run-a-consumer-now-with-consume).
+
+- The consumer's cursor is created on the first call when it's missing: at the
+  start of the log with `backfill`, otherwise at the head. An idle cursor also
+  finds events appended by deployments that don't run the consumer. A session
+  with nothing after its latest clear, or never written, gets no cursor: the
+  call writes nothing.
+- The server's own consumer shares its cursor with background drains: a head
+  another invocation holds, or one waiting out a failure's backoff, is waited
+  for. Nothing past `through` runs here; it carries on in the background. A different
+  definition under one of the server's consumer names throws a `TypeError`.
+- A consumer the server doesn't run is claimed only by `consume`, and keeps
+  its place between calls.
+- A dead-lettered head throws `CONSUMER_DEAD_LETTERED`. `signal` stops the
+  wait and throws its reason, even while an event runs here; that run
+  finishes on its own.
+- `ctx.session.consume` of a consumer that is waiting on the running one
+  throws a `TypeError`, unless that consumer has handled everything through
+  `through` already.
+- A consumer without a string `lane`, one of another contract, a `through`
+  that isn't a non-negative safe integer, or `ctx.session.consume` of the
+  running consumer itself throws a `TypeError` before any I/O.
+- On `server.session(id)` and `ctx.session`. `SessionConsumeOptions` and
+  `SessionConsumeResult` are exported from `experimental-a2/server`.
+
 ### `session.history()`
 
 ```ts
@@ -747,18 +802,18 @@ session.state(
 ```
 
 The log folded through one committed prefix. `index` is its exact boundary, an
-append-order cursor rather than a handler-settlement marker; hand it to the
+append-order cursor rather than a consumer-progress marker; hand it to the
 client to resume there. See [State](/contract/state).
 
 - Omitting `through` reads the latest committed frontier on a root session,
   and through `ctx.event.index` on `ctx.session`, inclusive and stable across
-  concurrent appends and retries. In a handler, use `{ through: 'latest' }`
+  concurrent appends and retries. In a consumer, use `{ through: 'latest' }`
   only when later committed events are intentionally part of the decision.
 - A numeric `through` is an inclusive, non-negative safe integer;
   `through: 0` returns the reducer's initial state.
 - A latest read and a following append are not atomic. See
   [State](/contract/state#reducers) for joins that converge.
-- Never dispatches handlers or waits for pending work. Snapshot write-back
+- Never runs consumers or waits for pending work. Snapshot write-back
   uses platform `waitUntil`, and its failures never fail the completed read:
   they go to `a2.snapshot` telemetry or the default console sink, without
   snapshot contents.
@@ -767,11 +822,12 @@ client to resume there. See [State](/contract/state).
   positive `through` below `clearIndex` throws `SESSION_CLEARED`; `through: 0`
   returns the seed without `clearIndex`.
 - On `ctx.session`, every state read throws `SESSION_CLEARED` once the trigger
-  has been cleared, including `{ through: 'latest' }`. Handler `history()` and
+  has been cleared, including `{ through: 'latest' }`. Its `history()` and
   `stream()` are not fenced.
-- Default and numeric handler reads retain their exact folded checkpoint until
-  the trigger completes or dead-letters and no other unfinished handler uses
-  it. Handler `{ through: 'latest' }` reads and root reads retain nothing.
+- Default and numeric reads on `ctx.session` retain their exact folded
+  checkpoint until the trigger completes or dead-letters and no other
+  unfinished run uses it. Its `{ through: 'latest' }` reads and root reads
+  retain nothing.
   There are no retention options. A numeric read behind the latest snapshot
   can use the greatest eligible retained checkpoint. See
   [Snapshots are a cache](/contract/state#snapshots-are-a-cache).
@@ -791,7 +847,7 @@ session.stream(options: {
 ```
 
 A live feed of the session's events. Server-side only; `server.fetch` exposes
-it over SSE and WebSocket. Subscribing never dispatches handlers.
+it over SSE and WebSocket. Subscribing never runs consumers.
 
 - `startAfter` is a non-negative safe integer; `startAfter: 20` begins with
   event 21.
@@ -828,6 +884,9 @@ broadcasts. No log row, no dispatch, no scheduler arm; `history()` and
   epoch-ms stamp; the browser client stamps its sends automatically. Without
   `at`, receipt time stands in: a stampless caller is a single writer, so
   receipt order is its send order.
+- `null` clears a field. The store keeps the clear's `at` until the field's
+  TTL runs out, so an older value that reaches it later, such as one sent
+  through another server instance, still loses.
 - A bad payload throws `INVALID_PAYLOAD`, an unknown field throws
   `UNKNOWN_PRESENCE_FIELD`, and a non-finite or negative `at` throws a
   `TypeError`.
@@ -854,7 +913,7 @@ session.presence(): Promise<{
 ```
 
 The current presence map, expired values pruned: a point-in-time read for
-server renders. Live consumers use `stream({ presence: true })`. Each entry's
+server renders. Live views use `stream({ presence: true })`. Each entry's
 `at` is the sender's stamp for when the value was set, the last-writer-wins
 comparator; how long a value
 stays painted is view logic, decided at render time.