experimental-a2 0.17.0 → 0.18.1

package/docs/reference/02-server.mdx

@@ -0,0 +1,860 @@
+---
+title: Server
+description: "`experimental-a2/server`: `createServer`, its route, the store and scheduler adapter interfaces, and every session method."
+---
+
+## `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() }),
+  },
+})
+
+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
+      },
+    },
+  },
+})
+```
+
+### `createServer(options)`
+
+```ts
+createServer(options: {
+  contract: Contract // the vocabulary this server implements
+  store?: A2Store    // default: sqlite in dev, memory in tests, required in prod
+  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
+        }
+  }
+}): 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).
+
+| 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). |
+| `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).
+
+The context every handler receives:
+
+| 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.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
+trigger's index by default (see
+[`session.state`](#sessionstatereducer-options)), and its `append` takes a
+name:
+
+```ts
+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).
+- 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
+  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.
+
+### `server.fetch(request, options?)`
+
+```ts
+server.fetch(
+  request: Request,
+  options?: {
+    authorize?: (operation: A2Operation) => boolean | Promise<boolean>
+    upgradeWebSocket?: (
+      attach: (socket: A2Socket) => void,
+    ) => Response | Promise<Response>
+    multiplexWebSocket?: boolean
+  },
+): Promise<Response>
+
+type A2Operation =
+  | {
+      type: 'stream'
+      sessionId: string
+      startAfter: number
+      transport: 'http' | 'websocket'
+    }
+  | {
+      type: 'history'
+      sessionId: string
+      gte: number
+      lte: number
+      transport: 'http'
+    }
+  | {
+      type: 'push'
+      sessionId: string
+      events: readonly {
+        type: ContractEventType | string
+        payload: unknown
+        id?: string
+      }[]
+      presence?: {
+        participant: string
+        values: Readonly<Record<string, unknown>>
+        seen?: number
+        at?: number
+      }
+      transport: 'http' | 'websocket'
+    }
+```
+
+The bound Fetch API route for this server: an unprotected route exports it
+directly as `GET` and `POST`. See [Routes](/server/routes).
+
+| Request | Response |
+| --- | --- |
+| `GET` | streams one session over SSE, resumed after the `index` query parameter |
+| `GET` with `gte` and `lte` | the closed history range as JSON; `a2-history-covered` is `true` when every requested index was returned. If the range includes the latest clear marker, `a2-clear-index` is set and coverage counts only the requested indexes after it; a range entirely below the marker returns `[]` |
+| `GET` with `Upgrade: websocket` | calls `upgradeWebSocket`, or returns 426 without it |
+| `POST` | accepts `{ sessionId, events, presence? }` and returns the appended events |
+
+A contract that declares presence streams it and accepts presence pushes
+automatically.
+
+| Option | Behavior |
+| --- | --- |
+| `authorize` | Runs after the request or socket frame is parsed, before schema validation, presence validation, or I/O. Event and presence field names are typed from the contract; values stay `unknown`. Operation objects, push events, event arrays, and presence patches are frozen: authorize them, don't rewrite them. `false` denies with `FORBIDDEN`; a throw becomes `STORE_UNAVAILABLE`. |
+| `upgradeWebSocket` | receives an `attach` callback for the platform socket and returns the upgrade response |
+| `multiplexWebSocket` | `true` shares one socket across sessions, with `multiplex: true` in the client's `ws` API |
+
+- 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
+  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
+  select another session.
+- A multiplexed socket runs `authorize` for each session subscribe and each
+  event or presence push. Authenticate the physical WebSocket GET before
+  calling `server.fetch`, and validate `Origin` when browser cookies
+  authenticate it (handshakes skip the CORS preflight). Enable multiplexing
+  only when that request context may access every session `authorize` accepts.
+- A denied subscribe receives `unsubscribed` and leaves other sessions alone. A
+  denied event push receives a `FORBIDDEN` ack. Denied presence is silently
+  dropped, because it is fire-and-forget.
+- SSE and WebSocket lifetimes use the platform's ambient invocation deadline,
+  and background work uses its ambient `waitUntil`. Neither is an option.
+
+### `server.session(id)`
+
+```ts
+server.session(id: string): Session
+```
+
+A handle on one instance of the contract: the unit of log ordering, lane keys,
+recovery, state, and live sync. Creating it does no I/O; nothing loads until
+you append, read, or stream. `session.id` is the `id` passed in. See
+[Sessions](/contract/sessions).
+
+It has every [session method](#session), plus
+[`deadLetters()`](#sessiondeadletters) and
+[`redrive()`](#sessionredriveindex-options), which `ctx.session` doesn't.
+
+### `server.drain(sessionId)`
+
+```ts
+server.drain(sessionId: string): Promise<{ settled: boolean }>
+```
+
+Claims every eligible event and runs their handlers 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
+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:
+
+```ts
+// Custom server store adapter:
+type EventCause = {
+  index: number
+  attempt: number
+  batchSize?: number // present on named handler appends
+}
+
+type AppendEvent = {
+  type: string
+  payload: unknown
+  id?: string
+  cause?: EventCause
+  lane?: string
+  settled?: true // internal: no handler is registered for this event type
+}
+
+type ReturnedEvent = AppendEvent & { id: string }
+
+type StoredEvent = Event & {
+  cause: EventCause | null
+  lane: string | null
+  processedAt: Date | null
+  processedByAttempt: number | null
+  returnedEventIds: string[] | null
+  firstClaimedAt: Date | null
+  lastClaimedAt: Date | null
+  attemptCount: number
+  claimHolder: string | null
+  claimExpiresAt: Date | null
+  failureCount: number
+  lastFailedAt: Date | null
+  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 StoreClaimAvailableResult =
+  | { outcome: 'claimed'; events: StoredEvent[] }
+  | { outcome: 'busy'; retryAt: Date }
+  | { outcome: 'settled' }
+
+type CompleteAttemptResult =
+  | { outcome: 'completed'; events: StoredEvent[] }
+  | { outcome: 'superseded' }
+
+interface A2Store {
+  append(
+    sessionId: string,
+    events: AppendEvent[],
+    options?: { originIndex?: number },
+  ): Promise<StoreAppendResult>
+
+  // optional together; required for session.clear()
+  clear?(options: {
+    sessionId: string
+    ifLastIndex?: number
+    cause?: EventCause
+  }): Promise<{ cleared: boolean; index: number; clearIndex: number }>
+  reclaim?(sessionId: string): Promise<{ deleted: number; done: boolean }>
+
+  // optional together; required for session.deadLetters() and redrive()
+  deadLetters?(sessionId: string): Promise<StoredEvent[]>
+  redrive?(options: {
+    sessionId: string
+    index: number
+    action: 'retry' | 'skip'
+  }): Promise<{ redriven: boolean; hasPending: boolean }>
+
+  claimAvailable(options: {
+    sessionId: string
+    holder: string
+    ttlMs: number
+    expiresAtMs?: number
+    excludeIndexes?: readonly number[]
+    maxFailures?: number
+  }): Promise<StoreClaimAvailableResult>
+
+  renewClaims(options: {
+    sessionId: string
+    holder: string
+    claims: readonly { index: number; attempt: number }[]
+    ttlMs: number
+    expiresAtMs?: number
+  }): Promise<{ renewed: number[]; superseded: number[] }>
+
+  completeAttempt(options: {
+    sessionId: string
+    index: number
+    attempt: number
+    events: ReturnedEvent[]
+  }): Promise<CompleteAttemptResult>
+
+  failAttempt(options: {
+    sessionId: string
+    index: number
+    attempt: number
+    error: string
+    maxFailures: number
+    retryAfterMs?: number
+  }): Promise<{
+    outcome: 'failed' | 'dead_lettered' | 'superseded'
+    failureCount: number
+  }>
+}
+```
+
+| 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`. |
+
+`readHistory(sessionId, options)` is an optional capability with the same
+exclusive `afterIndex` and inclusive `throughIndex` bounds as `read()`. Without
+it, `session.history()` falls back to `read()`.
+
+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.
+- `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`.
+- In `append` and `completeAttempt`, an event id whose row is below this
+  session's marker is free to reuse.
+
+Without `clear` and `reclaim`, `session.clear()` and `session.schedule.clear()`
+throw a `TypeError` before writing anything. Without `deadLetters` and
+`redrive`, so do `session.deadLetters()` and `session.redrive()`. All built-in
+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
+  [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.
+- 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.
+
+### `A2Scheduler`
+
+Custom scheduler adapters implement two methods:
+
+| Method | Effect |
+| --- | --- |
+| `schedule(task: SchedulerTask): Promise<void>` | put one versioned task on durable delivery infrastructure |
+| `handler(...servers)` | return the route that receives drain, append, and clear tasks; requires at least one drainable server and rejects duplicate contract names synchronously |
+
+Application routes call `scheduler.handler(...servers)` on the configured
+adapter. See
+[Production](/server/production#2-add-a-scheduler-for-handlers-and-timers).
+
+`SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask |
+SchedulerClearTask`. These task types, plus `ScheduledEvent`, are exported
+from `experimental-a2/server`.
+
+| Task | Fields |
+| --- | --- |
+| `SchedulerDrainTask` | `version: 1`, `kind: 'drain'`, `contract`, `sessionId`, required epoch-ms `dueAt` |
+| `SchedulerAppendTask` | `version: 1`, `kind: 'append'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, readonly `events`, optional `originIndex` |
+| `SchedulerClearTask` | `version: 1`, `kind: 'clear'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, `ifLastIndex` |
+| `ScheduledEvent` | fixed `id`, `type`, and JSON `payload` |
+
+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
+`session.schedule.clear`.
+
+Deliver an authenticated, normalized append or clear task through the server
+helpers:
+
+```ts custom-scheduler.ts
+import {
+  deliverSchedulerAppend,
+  deliverSchedulerClear,
+  type DrainableServer,
+  type SchedulerAppendTask,
+  type SchedulerClearTask,
+} from 'experimental-a2/server'
+
+export async function deliver(
+  server: DrainableServer,
+  task: SchedulerAppendTask | SchedulerClearTask,
+) {
+  if (task.kind === 'clear') await deliverSchedulerClear(server, task)
+  else await deliverSchedulerAppend(server, task)
+}
+```
+
+Authenticate the transport and validate the task envelope first. Each helper
+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
+  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
+  deletion finishes. A store failure rejects, so the provider redelivers and
+  the retry finishes deleting.
+
+## Session
+
+### `session.append(...events)`
+
+```ts
+session.append(
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+The only way to move a session forward. See [Guarantees](/server/guarantees).
+
+- Validates payloads against the contract's schemas before writing anything.
+- 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.
+- 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
+  atomic append, so the decision needs no follow-up read.
+
+### `session.append.dispatch(...events)`
+
+```ts
+session.append.dispatch(
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+Commits the same atomic batch, then sends pending work to the configured
+scheduler instead of starting an inline drain. See
+[Dispatch in a fresh invocation](/server/production#dispatch-in-a-fresh-invocation).
+
+- Awaits acceptance of an immediate scheduler message. A batch that leaves no
+  pending handler 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.
+- It picks how the session wakes, not which worker runs: an already active
+  drain may claim the new work first.
+- Exists only on a server session's top-level append. `ctx.session.append`
+  runs inside an active drain, where its immediate and returned children
+  become eligible, so it has no `dispatch`.
+
+### `session.schedule(name, timing, ...events)`
+
+```ts
+session.schedule(
+  name: string,
+  timing: ScheduleTiming, // { delay: ScheduleDelay } | { at: Date }
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<void>
+```
+
+Appends the events later through the configured scheduler, from root and
+handler 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
+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 |
+| `{ 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
+  unsigned base-10 decimal without leading zeros, finite, and above zero; `0s`,
+  signs, exponents, malformed durations, invalid dates, and both fields at
+  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
+  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
+  the store.
+- Payloads are snapshotted into plain JSON, then validated before sending.
+  Encode dates as ISO strings and classes as plain data. `undefined`, bigint,
+  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
+  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
+  scheduling again after a clear.
+- There is no cancellation, reschedule, cron, or timer-listing API.
+
+### `session.clear(options?)`
+
+```ts
+session.clear(options?: { ifLastIndex?: number }): Promise<{
+  cleared: boolean
+  index: number
+}>
+```
+
+Ends the session's current lifetime: one atomic step checks the condition and
+appends a reserved clear marker at the next index. The session id stays usable
+and indexes never restart. See
+[Clearing a session](/contract/sessions#clearing-a-session).
+
+`ifLastIndex` is a non-negative safe integer. The first matching rule decides,
+and `index` is always the head after the call:
+
+| When | Result |
+| --- | --- |
+| the latest marker is at `ifLastIndex + 1` | `{ cleared: true, index }`, a retry of that clear |
+| `ifLastIndex` is given and is not the head | `{ cleared: false, index }`, nothing changes |
+| the head is `0` or already a clear marker | `{ cleared: true, index }`, nothing changes |
+| 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
+  `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
+  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
+  records, and cached state below the marker in short batches, resolving when
+  they're gone. Other work on the session runs between batches. There is no
+  background sweep.
+- 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
+  returned events are discarded. Its deletion keeps running under the
+  platform's `waitUntil`.
+- All built-in stores support clearing.
+
+### `session.schedule.clear(name, options)`
+
+```ts
+session.schedule.clear(
+  name: string,
+  options: ({ delay: ScheduleDelay } | { at: Date }) & {
+    ifLastIndex: number
+  },
+): Promise<void>
+```
+
+Publishes a conditional clear to the configured scheduler and resolves after
+provider acceptance. `name` is non-empty and `ifLastIndex` is required; timing
+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.
+- 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`.
+  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.
+- 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
+  the old history still invisible, and any later clear of the session finishes
+  it.
+
+### `session.deadLetters()`
+
+```ts
+session.deadLetters(): Promise<DeadLetter[]>
+
+type DeadLetter = Event & {
+  lane: string | null
+  attemptCount: number
+  failureCount: number
+  lastError: string | null
+  failedAt: Date
+}
+```
+
+The session's dead-lettered events, oldest first, each with why it failed. See
+[When an event dead-letters](/server/production#3-when-an-event-dead-letters).
+
+- `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
+  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)`
+
+```ts
+session.redrive(
+  index: number,
+  options: { action: 'retry' | 'skip' },
+): Promise<{ redriven: boolean }>
+```
+
+Resolves the dead-lettered event at `index` in one atomic store operation.
+
+| 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. |
+
+- `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.
+- Afterwards, unfinished work wakes the session as an append does: an inline
+  drain, plus a scheduler watchdog when one is configured, joined for up to
+  `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`.
+- Only on `server.session(id)`. `SessionRedriveOptions` and
+  `SessionRedriveResult` are exported from `experimental-a2/server`.
+
+### `session.history()`
+
+```ts
+session.history(options?: { gte?: number; lte?: number }): Promise<Event[]>
+```
+
+Raw events, oldest first, without dispatch metadata. See
+[History](/contract/state#history).
+
+- `gte` and `lte` are inclusive, non-negative safe-integer indexes; omit one to
+  leave that end open. `lte: 0` returns `[]`; `gte > lte` throws.
+- After a clear, history starts after the marker; the marker itself is not
+  returned.
+
+### `session.state(reducer, options?)`
+
+```ts
+session.state(
+  reducer: Reducer<S>,
+  options?: { through?: number | 'latest' },
+): Promise<{ state: S; index: number; clearIndex?: number }>
+```
+
+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
+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' }`
+  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
+  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.
+- After a clear, the result includes `clearIndex`, the latest marker, and
+  state folds from there; forward the whole result when hydrating a client. A
+  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
+  `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.
+  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).
+- Operational snapshot-read failures keep existing A2 errors and turn others
+  into `STORE_UNAVAILABLE` with the original error as `cause`, without falling
+  back to individual reads or raw history. Cache misses and `stateSchema`
+  rejections rebuild from the log.
+
+### `session.stream(options?)`
+
+```ts
+session.stream(options?: { startAfter?: number }): AsyncIterable<Event | SessionCleared>
+session.stream(options: {
+  startAfter?: number
+  presence: true
+}): AsyncIterable<Event | SessionCleared | PresencePatch | PresenceSnapshot>
+```
+
+A live feed of the session's events. Server-side only; `server.fetch` exposes
+it over SSE and WebSocket. Subscribing never dispatches handlers.
+
+- `startAfter` is a non-negative safe integer; `startAfter: 20` begins with
+  event 21.
+- A clear arrives in order as a `SessionCleared` marker (`type: 'a2.cleared'`).
+  A stream that opens below the latest marker begins with it. A running stream
+  delivers the log in order, so events from before the clear can arrive ahead
+  of the marker. Reset when it arrives. Clearing never closes a stream.
+- With `presence: true`, the feed first yields one `PresenceSnapshot`,
+  `{ snapshot }`: the current pruned map with each field's `value`, `seen`, and
+  `at`. Live `PresencePatch` values, `{ participant, values, seen, at }`, then
+  interleave with events; `values` is typed by the contract's presence schemas,
+  and `null` marks a cleared field. Over SSE both are named frames, which
+  clients that don't know them skip.
+- The return type widens only under the literal `presence: true`. The option
+  exists only on sessions of contracts that declare `presence`; elsewhere it is
+  a type error, not a runtime throw.
+
+### `session.setPresence(patch)`
+
+```ts
+session.setPresence(patch: {
+  participant: string
+  values: { [field]: payload | null } // partial; null clears a field
+  seen?: number
+  at?: number // the sender's LWW stamp, epoch ms; receipt time when absent
+}): Promise<void>
+```
+
+Validates each field against the contract's `presence` schemas, then
+broadcasts. No log row, no dispatch, no scheduler arm; `history()` and
+`state()` never see it. See [Presence](/client/presence).
+
+- Last writer wins per participant per field, ordered by `at`, the sender's
+  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.
+- A bad payload throws `INVALID_PAYLOAD`, an unknown field throws
+  `UNKNOWN_PRESENCE_FIELD`, and a non-finite or negative `at` throws a
+  `TypeError`.
+- `seen` is the sender's stream frontier, which view code uses to reconcile
+  presence with the fold. See
+  [Reconciling the planes](/client/presence#reconciling-the-planes-seen).
+- Values expire by backend TTL when a participant goes silent (default 60
+  seconds; see [`presence.ttlMs`](#createserveroptions)). Expiry counts on the
+  storage clock, so a hostile stamp can only vandalize its own field, which
+  still expires on schedule.
+- The patch is the push envelope's `presence` sibling; `server.fetch`'s push
+  lane forwards it whole to `session.setPresence(presence)`.
+- `ctx.session.setPresence(...)` is the same operation; `seen` defaults to the
+  triggering event's `index`.
+
+### `session.presence()`
+
+```ts
+session.presence(): Promise<{
+  [participant: string]: {
+    [field: string]: { value: unknown; seen: number; at: Date }
+  }
+}>
+```
+
+The current presence map, expired values pruned: a point-in-time read for
+server renders. Live consumers 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.