experimental-a2 0.16.1 → 0.18.0

package/docs/server/04-routes.mdx

@@ -0,0 +1,243 @@
+---
+title: Routes
+description: Serve every session with `server.fetch` over HTTP or a WebSocket, or build your own route from session methods.
+---
+
+## The HTTP route
+
+```ts app/api/public-order-events/route.ts
+import { ordersServer } from '@/server/orders'
+
+export const GET = ordersServer.fetch
+export const POST = ordersServer.fetch
+```
+
+`server.fetch` is bound, so an unprotected route is two exports. A plain GET
+streams one session over SSE, a GET with `gte` and `lte` returns a history
+slice, and POST appends the pushed events. If the contract declares presence,
+the same route streams and accepts it.
+
+Wrap the call when the route needs authentication or authorization:
+
+```ts app/api/protected-order-events/route.ts
+import { ordersServer } from '@/server/orders'
+
+async function fetchOrders(request: Request): Promise<Response> {
+  // your authentication:
+  const user = { id: 'user-1' }
+  if (!user) return new Response(null, { status: 401 })
+
+  return ordersServer.fetch(request, {
+    authorize(operation) {
+      // your per-session and per-operation authorization:
+      // return canAccess(user, operation)
+      return true
+    },
+  })
+}
+
+export const GET = fetchOrders
+export const POST = fetchOrders
+```
+
+Authenticate in the route, where headers, cookies, and framework context
+live. `authorize` then checks each typed operation (`stream`, `history`, or
+`push` with its parsed events and presence patch) after A2 parses it and
+before schema validation or durable I/O. Return `false` to answer
+`FORBIDDEN` (403). A throw is an infrastructure failure and answers
+`STORE_UNAVAILABLE`.
+
+If a URL or connection token is scoped to one session, `authorize` must
+compare that scope to `operation.sessionId`. Keep URL tokens short-lived:
+URLs can appear in infrastructure logs.
+
+## The WebSocket route
+
+```ts app/api/socket-order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { ordersServer } from '@/server/orders'
+
+export const POST = ordersServer.fetch
+
+export function GET(request: Request): Promise<Response> {
+  return ordersServer.fetch(request, {
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}
+```
+
+Pass the platform's upgrade capability on GET; POST can stay a direct export.
+The socket is bound to the `sessionId` in its upgrade URL: A2 authorizes that
+session before upgrading, and frames can't switch sessions. Each connected
+session has its own socket.
+
+Authenticate the upgrade request before calling `server.fetch`. For browser
+sockets authenticated by cookies, validate the request's `Origin` too: a
+WebSocket handshake has no CORS preflight. Then `authorize` checks the session
+stream and every push or presence frame. There is no separate upgrade
+operation.
+
+To share one socket across sessions, opt in on the route and set
+`multiplex: true` on the [client](/client/transports):
+
+```ts app/api/multiplexed-order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { ordersServer } from '@/server/orders'
+
+export function GET(request: Request): Promise<Response> {
+  return ordersServer.fetch(request, {
+    multiplexWebSocket: true,
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}
+```
+
+Enable multiplexing only when the request's authentication context may open
+more than one session and `authorize` checks each session id. Subscribe frames
+open sessions after the upgrade.
+
+Denials stay scoped:
+
+- A denied subscribe on a multiplexed socket gets an `unsubscribed` notice
+  with `FORBIDDEN` and leaves other sessions connected. A failed stream or a
+  thrown authorization check carries `STORE_UNAVAILABLE`. The client hands
+  these to its reconnection policy as `A2ClientError`s.
+- A denied event push gets a non-retryable `FORBIDDEN` ack.
+- Denied presence is dropped silently; presence repaints on the next update.
+
+A2 reads the platform's invocation deadline and closes the socket cleanly
+before it.
+
+## Build your own
+
+`server.fetch` speaks the wire A2's client expects. For anything else, such as
+another framework, your own framing, or a consumer that isn't A2's client,
+build the route from session methods. It's just an event log: read a snapshot,
+follow the stream, append.
+
+```ts app/api/orders/[orderId]/live/route.ts
+import { orders } from '@/contracts'
+import { ordersServer } from '@/server/orders'
+
+type Params = { params: Promise<{ orderId: string }> }
+
+const encoder = new TextEncoder()
+const frame = (name: string, data: unknown): Uint8Array =>
+  encoder.encode(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`)
+
+export async function GET(
+  _request: Request,
+  { params }: Params,
+): Promise<Response> {
+  const { orderId } = await params
+  // here's where you'd do auth, or any other checks
+  const session = ordersServer.session(orderId)
+  const snapshot = await session.state(orders.reducer)
+  const events = session
+    .stream({ startAfter: snapshot.index })
+    [Symbol.asyncIterator]()
+
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(frame('snapshot', snapshot))
+    },
+    async pull(controller) {
+      const next = await events.next()
+      if (next.done) return controller.close()
+      const event = next.value
+      const name = event.type === 'a2.cleared' ? 'cleared' : 'event'
+      controller.enqueue(frame(name, event))
+    },
+    // the browser left: end the subscription
+    async cancel() {
+      await events.return?.()
+    },
+  })
+  return new Response(body, {
+    headers: { 'content-type': 'text/event-stream' },
+  })
+}
+```
+
+`session.state()` returns the snapshot's `index`, so the stream picks up
+exactly where the snapshot ends. A clear arrives as an `a2.cleared` marker in
+the same stream. Writes go through `session.append`, which validates against
+the contract:
+
+```ts app/api/orders/[orderId]/live/route.ts
+import { A2Error } from 'experimental-a2'
+
+export async function POST(
+  request: Request,
+  { params }: Params,
+): Promise<Response> {
+  const { orderId } = await params
+  // here's where you'd do auth, or any other checks
+  const { shopId, items } = await request.json()
+  try {
+    const [event] = await ordersServer.session(orderId).append({
+      type: 'created',
+      payload: { shopId, items },
+    })
+    return Response.json(event)
+  } catch (error) {
+    if (error instanceof A2Error && error.code === 'INVALID_PAYLOAD') {
+      return Response.json({ issues: error.details }, { status: 400 })
+    }
+    throw error
+  }
+}
+```
+
+The browser follows it with `EventSource` and folds with the contract's own
+reducer, the same fold the server runs:
+
+```ts app/orders/[orderId]/follow-order.ts
+'use client'
+import { orders } from '@/contracts'
+
+type OrderState = typeof orders.reducer.initialState
+
+export function followOrder(
+  orderId: string,
+  onChange: (state: OrderState) => void,
+): () => void {
+  const url = `/api/orders/${encodeURIComponent(orderId)}/live`
+  const source = new EventSource(url)
+  let state = orders.reducer.initialState
+  const update = (next: OrderState): void => {
+    state = next
+    onChange(state)
+  }
+  source.addEventListener('snapshot', (message) => {
+    update(JSON.parse(message.data).state)
+  })
+  source.addEventListener('event', (message) => {
+    update(orders.reducer.fold(state, JSON.parse(message.data)))
+  })
+  source.addEventListener('cleared', () => {
+    update(orders.reducer.initialState)
+  })
+  return () => source.close()
+}
+```
+
+`EventSource` reconnects on its own, and each connection starts from a fresh
+snapshot. What `server.fetch` adds on top, and a custom route takes on itself:
+
+- resuming a stream from the client's last `index` instead of a new snapshot
+- bounded history reads (`gte` and `lte`)
+- the push envelope with acks and `.confirmed`, and presence
+- WebSocket upgrades
+- `authorize` on every operation; direct `session.append` bypasses it, so the
+  route is where your checks go
+- closing streams before the platform's invocation deadline
+
+A2's client, `createClient` and `useSession`, talks to `server.fetch`. Pair a
+custom route with your own client.

package/docs/server/05-production.mdx

@@ -0,0 +1,322 @@
+---
+title: Production
+description: Choose a durable store, add a scheduler for recovery and timers, and know what to do when an event dead-letters.
+---
+
+## 1. Choose a store
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+| Entry point | Backend | Use it for |
+| --- | --- | --- |
+| `experimental-a2/store-redis` | Redis | Production (recommended) |
+| `experimental-a2/store-redis-http` | Redis over a REST API | Production |
+| `experimental-a2/store-postgres` | Postgres | Production |
+| `experimental-a2/store-sqlite` | SQLite | Development: the default, at `.a2/dev.db` |
+| `experimental-a2/store-memory` | In-memory | Tests: the default when `NODE_ENV=test` |
+
+When you omit `store`, development gets SQLite (state survives `next dev`
+restarts) and tests get memory. Production has no default, on purpose: the
+server throws `STORE_NOT_CONFIGURED` at startup rather than write events to a
+filesystem that evaporates.
+
+The store holds A2's session histories. It does not connect A2 to your
+application tables; see [Sessions and your database](/contract/sessions#sessions-and-your-database).
+
+### Redis (recommended)
+
+`redis({ url })` from `experimental-a2/store-redis` stores each session as a
+Redis Stream and streams push-natively, so connections scale with your
+processes, not your audience. `ioredis` is an optional peer dependency; pass
+`url` or inject a client. It works on single instances and non-cluster
+providers such as Upstash, where durability is on by default.
+
+On providers that bill per command, such as Upstash, appending an event with a
+handler and running it takes 24 commands, and an idle live stream takes 6 a
+minute. See
+[`experimental-a2/store-redis`](/reference/adapters#experimental-a2store-redis)
+for how live streams recover a lost wake-up.
+
+When only a REST API is available, `redisHttp({ url, token })` from
+`experimental-a2/store-redis-http` speaks the same storage over `fetch`, with
+no client dependency or extra setup. Live events and presence use Upstash's
+HTTP `SUBSCRIBE` endpoint with the same URL and token. If that endpoint answers
+404, 405, or 501, the store polls instead; other errors stay errors. See
+[`experimental-a2/store-redis-http`](/reference/adapters#experimental-a2store-redis-http)
+for its subscriptions, reconnects, and fallback.
+
+:::warning
+`redisHttp` live streams trust the messages on the store's `:notify`
+channels. Browsers never hold Redis credentials, so they can't reach those
+channels. The risk is a Redis credential that can publish but not write, such
+as a token another service uses: it could add or hide events in live views.
+Grant publish access only to credentials that can also write the store.
+:::
+
+### Postgres
+
+Any Postgres works: Neon, Supabase, RDS, or your own box, including
+transaction-mode poolers. `pg` is an optional peer dependency. Pass
+`connectionString`, or inject your own pool as `client`; an injected pool's
+platform lifecycle is yours to manage.
+
+Live streams poll by default, backing off when a session goes quiet. For
+native notifications, also pass `listenConnectionString`: a direct connection
+to the same database. It installs notification triggers on A2's event and
+presence tables, which stay installed and also cover writes from instances
+without the option. Stores in one runtime share a listener, but every
+serverless instance opens its own direct connection, so leave connection
+headroom. See
+[`experimental-a2/store-postgres`](/reference/adapters#experimental-a2store-postgres)
+for live-stream latency and recovery.
+
+## 2. Add a scheduler for handlers and timers
+
+The scheduler puts a clock on recovery and on [timers](/server/timers).
+Vercel Queues is the recommended default on Vercel. QStash delivers over HTTP
+from separate infrastructure. Either adapter carries recovery and
+`session.schedule` tasks through one route. Scheduled delays must fit the
+[provider's limit](/server/timers#provider-limits).
+
+### Vercel Queues (recommended)
+
+```ts
+// server/orders.ts, now with a scheduler:
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+`@vercel/queue` is a peer dependency. Share one scheduler instance across
+servers, and mount its handler once with every server it may deliver to:
+
+```ts app/api/a2/scheduler/route.ts
+import { billingServer, ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer, billingServer)
+```
+
+`scheduler.handler(...)` checks its servers when the module loads: at least
+one drainable server, with unique contract names. A bad route fails at
+startup, or in a build that evaluates route modules.
+
+```json vercel.json
+{
+  "functions": {
+    "app/api/a2/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2"
+        }
+      ]
+    }
+  }
+}
+```
+
+The trigger is required. It connects the route to Vercel Queues and makes the
+function private, so only queue infrastructure can invoke it. Don't expose the
+callback as a public route or wrap it in a second authentication scheme.
+
+The adapter keeps messages for 7 days (Vercel Queues' default is 24 hours) and
+accepts scheduled appends and clears up to 6 days out.
+
+### QStash
+
+```ts
+// server/orders.ts, with QStash instead:
+import { createServer } from 'experimental-a2/server'
+import { qstash } from 'experimental-a2/scheduler-qstash'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const scheduler = qstash()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+`@upstash/qstash` 2.11.0 or newer is a peer dependency. Mount
+`scheduler.handler(...)` in the same `app/api/a2/scheduler/route.ts`, and set
+`QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY`.
+
+- **Callback URL:** inferred from `PORT` locally, and from
+  `VERCEL_PROJECT_PRODUCTION_URL` or `VERCEL_BRANCH_URL` on Vercel. Pass `url`
+  anywhere else.
+- **Local development:** A2 starts QStash's development server on the first
+  publish or verification, with no QStash variables needed.
+- **Security:** the route verifies `Upstash-Signature` before touching the
+  store and answers unsigned traffic with 401. Behind Deployment Protection,
+  pass an automation bypass as a callback header.
+- **Outages:** delivery is at least once and A2 keeps recovery going, but when
+  QStash can't reach the route at all, redrive its DLQ.
+
+The [adapter reference](/reference/adapters#experimental-a2scheduler-qstash)
+covers the options, protected previews, Edge runtimes, and body limits.
+
+### More than one scheduler
+
+Servers with different scheduler instances need separate routes, even from the
+same adapter. Each extra QStash instance passes its own `url`. Each Vercel
+Queues instance needs its own `topic` and a matching `experimentalTriggers`
+entry.
+
+### Dispatch in a fresh invocation
+
+Ordinary `append` starts handlers inline and uses the scheduler as a watchdog.
+`append.dispatch` persists the input and hands the pending work straight to the
+queue instead:
+
+```ts app/api/imports/route.ts
+import { ordersServer } from '@/server'
+
+export async function POST(request: Request) {
+  const { orderId, shopId, items } = await request.json()
+  await ordersServer.session(orderId).append.dispatch({
+    id: `created:${orderId}`,
+    type: 'created',
+    payload: { shopId, items },
+  })
+  return Response.json({ accepted: true }, { status: 202 })
+}
+```
+
+It requires a scheduler. The call awaits the queue send and starts no inline
+drain. If the send fails, the event may already be durable; its explicit id
+makes the retry idempotent. Dispatch controls the wakeup, not which worker
+claims the event.
+
+### Running without a scheduler
+
+If no event type has a handler and nothing calls `session.schedule`, skip
+`scheduler`. Events settle in their append transaction, with no drains, claims,
+or queue messages. That's a complete production configuration: a durable event
+log for history, reducers, and live sync.
+
+With handlers, skipping it means the only wakeups are a top-level append or an
+explicit `server.drain()`. Reads never wake a session, so one nobody wakes
+stays stuck. That's fine for internal tools where "heals on the next write" is
+acceptable. For production, configure a scheduler.
+
+## 3. When an event dead-letters
+
+A [dead-lettered](/server/guarantees#when-a-handler-keeps-failing) event waits
+for you. List a session's dead letters, then resolve each one:
+
+```ts
+// anywhere on the server, behind your own operator checks:
+import { ordersServer } from '@/server'
+
+const order = ordersServer.session(orderId)
+const [dead] = await order.deadLetters()
+if (dead) {
+  // dead.lastError says why; deploy the handler fix first, then:
+  await order.redrive(dead.index, { action: 'retry' })
+}
+```
+
+- **Fix and retry.** `{ action: 'retry' }` runs the handler again with a fresh
+  ten-failure budget. Once it completes, its lane continues.
+- **Skip.** `{ action: 'skip' }` marks the event processed without running it,
+  accepting that its effects never happen. The next event in its lane runs.
+
+Each redrive is one atomic store operation, and it wakes the session the way an
+append does, so the lane resumes without another write. An event that isn't
+dead-lettered anymore is left alone: `redrive` reports `{ redriven: false }`.
+
+## 4. Deploy safely
+
+The Vercel adapter's `deploymentId` applies to every task: recovery, scheduled
+appends, and scheduled clears. Omit it to use the publishing deployment, pass
+a deployment ID to target one, or pass `null` for deploymentless delivery.
+Publishing and consuming clients must use the same scope.
+
+- **Pinned tasks stay put.** Promoting a new deployment doesn't move them;
+  older deployments keep receiving their own work until it is acknowledged or
+  expires. Upgrading doesn't repair an older deployment's callback handler.
+- **Deploymentless doesn't mean latest.** Vercel picks an eligible consumer,
+  not the latest production deployment. Every eligible consumer must use
+  `deploymentId: null` and stay compatible with pending tasks and session work.
+- **Changing the setting doesn't move queued tasks.** Keep consumers for the
+  original scope until those tasks finish.
+
+QStash's inferred production and branch URLs are moving aliases, so pending
+tasks can reach a later deployment. Keep task envelopes and event schemas
+compatible across deployments, and keep the same `maxBodyBytes` on every
+deployment that can receive the callback: lowering it mid-rollout can reject
+tasks the previous deployment accepted.
+
+:::warning
+Don't roll back to an A2 version without timer delivery while scheduled tasks
+are outstanding.
+An old route can acknowledge a new append task as a recovery message without
+writing its events. Rolling back past scheduled clears fails too: an old
+Vercel Queues route keeps failing a clear task until retention ends, and an
+old QStash route rejects it as non-retryable, moving it to QStash's
+dead-letter queue. Roll forward, or wait for those tasks to deliver or remove
+them through the provider first.
+:::
+
+## Watch it in traces
+
+```ts
+// server/orders.ts, with telemetry:
+import { createServer } from 'experimental-a2/server'
+import { otel } from 'experimental-a2/otel'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  // ...store, scheduler, and handlers as above
+  telemetry: otel(),
+})
+```
+
+`telemetry` takes an instrumentation hook; `experimental-a2/otel` implements
+it over OpenTelemetry (`@opentelemetry/api` is a peer dependency). With any
+OTel setup registered (on Vercel, `@vercel/otel`), one trace shows the request,
+`a2.append`, the inline `a2.drain`, an `a2.event` span per handler, and the
+appends those handlers make. Failures mark their `a2.event` span,
+`a2.event.attempt` reports `ctx.attempt`, and `a2.event.outcome =
+dead_lettered` is the attribute to alert on. Agent servers add `a2.ai.*`
+spans. See the [span catalogue](/reference/adapters#the-span-catalogue).
+
+## Checklist
+
+| Piece               | Done when                                                            |
+| ------------------- | -------------------------------------------------------------------- |
+| Store               | `store: redis(...)` (or `postgres(...)`) on every server              |
+| Scheduler           | for servers with handlers or timers: one shared adapter, route, and provider config |
+| Idempotent handlers | external side effects take `event.id` as an idempotency key           |
+| Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |

package/docs/server/06-guarantees.mdx

@@ -0,0 +1,123 @@
+---
+title: Guarantees
+description: Appends are effectively-once, handlers are at-least-once, and retries keep event identity across crashes.
+---
+
+## In short
+
+- **Appends are effectively-once.** Event ids deduplicate writes. A batch commits
+  before its handlers start; they may start before `append` resolves.
+- **Handlers are at-least-once.** They may run again after a crash, so
+  [side effects use idempotency keys](/server/handlers#handlers-can-run-twice).
+- **The log stays ordered.** Every session has one immutable append order.
+- **Handlers are concurrent by default.** Log order does not serialize them.
+  Only events in the same lane run one at a time in log order.
+
+## One event, many attempts
+
+An event is pending until A2 marks it processed. Every wakeup (an append, a
+scheduler watchdog, or `server.drain()`) claims the session's eligible events,
+and the log decides what remains. Reads never dispatch handlers.
+
+Each claim expires. If its holder dies, the claim lapses and the next wakeup
+claims the event again with a larger `ctx.attempt`. The retry gets the same
+event id, index, type, and payload. A kill after the claim can use up an
+attempt before your code runs, but it doesn't count as a caught failure. An
+older attempt can never overwrite a newer one's completion or failure.
+
+:::note[Recovery is not an event]
+A2 does not append `recovered` or `continued`. Recovery retries the same event.
+Your log contains only application facts.
+:::
+
+## Immediate and dependent events
+
+[`ctx.session.append(name, ...events)`](/server/handlers#append-what-should-happen-now)
+commits immediately: its events stay in the log if the parent later crashes,
+and run concurrently with it unless both share a lane.
+[Returned events](/server/handlers#return-what-happens-after-success) commit
+with the parent's completion, in one transaction.
+
+If the handler throws or dies before that transaction, neither the completion
+nor the returned events exist, and the retry produces the same deterministic
+ids. If the transaction commits but its acknowledgement is lost, the retry gets
+the committed rows back. A partial or changed batch is rejected.
+
+The transaction covers only A2's log. An HTTP call, database write, or other
+external effect can't join it, so a crash after the effect but before
+completion repeats it. Use `event.id` as an idempotency key or add fencing in
+the external system.
+
+## Lanes
+
+[Lanes](/server/handlers#lanes) are session-scoped serial groups. Only the
+lowest-index unfinished event in a lane is eligible, so a failure blocks later
+events in that lane, not the whole session. Unlaned events and different lanes
+run concurrently. A2 stores the lane at append, so a changed lane resolver
+affects only new events.
+
+A lane controls A2 dispatch, not the outside world. A2 claims every eligible
+event, with no global concurrency limit or priority queue. Put capacity limits
+near the constrained resource, such as an API client, connection pool, or
+runtime.
+
+## Append and scheduling
+
+A top-level append commits before any wakeup. A2 then starts the handlers
+inline and, with a scheduler, arms a watchdog in parallel. Handlers never wait
+for the queue, and a handler may start before `append` returns. `append` waits
+up to two seconds for the watchdog send, never for handlers. A failed arm
+records `a2.append.armed = false` on the trace. Handler appends and returned
+events join the running drain and add no arm.
+
+[`append.dispatch`](/server/production#dispatch-in-a-fresh-invocation) skips
+the inline drain and hands the work to the scheduler instead.
+
+An event type without a handler settles in the append transaction. It starts
+no drain or arm unless older handled work in the session is still pending.
+
+## Causal trees are durable
+
+Every event a handler appends or returns stores a `cause`: the triggering
+event's index and dispatch attempt. Top-level appends store `null`. Children
+of one handler are siblings, nested handlers add levels, and a retried child
+keeps its original cause.
+
+## A chain that crosses the function timeout
+
+A function killed mid-handler restarts that handler from its entry point in a
+fresh invocation: same event, new attempt, no caught failure. Events already
+processed stay processed, so a chain of handlers can outlast one invocation,
+but each handler must fit in a fresh one. Split longer work into smaller
+events or increase the function duration. On Vercel, A2 caps the claim window
+at the function deadline when the platform exposes it, so a retry starts
+promptly after a timeout.
+
+## When a handler keeps failing
+
+A caught failure counts against that event, releases its claim, and leaves
+other eligible events running. A2 retries it with backoff. Ten caught failures
+dead-letter the event: later events in its lane stay blocked, while unlaned
+events and other lanes continue. Hard kills don't consume this budget.
+The event waits until you
+[retry or skip it](/server/production#3-when-an-event-dead-letters) with
+`session.redrive()`.
+
+## Limits
+
+| Situation | Result |
+| --- | --- |
+| Process dies before the first arm is durable | Retry with the same ids, append again later, or call `drain()`. |
+| No scheduler configured | A later top-level append or explicit `drain()` wakes the session. Reads never do. |
+| Scheduler invocation dies after claiming but before arming | Its unacknowledged queue delivery is the slower fallback. |
+| Store backend unavailable | Safe progress stops until it returns. |
+| External effect succeeds before A2 completion | The handler may repeat it. Use idempotency or external fencing. |
+
+## What append never throws for
+
+A failing handler never makes `append` throw. Handler failures are retried and,
+if persistent, [dead-letter the event](#when-a-handler-keeps-failing).
+
+Append success means the event is durable, not that its handlers finished. An
+identical batch retry returns rows with the same ids. A mixed batch throws
+[`PARTIAL_DUPLICATE_BATCH`](/reference/errors).