experimental-a2 0.17.0 → 0.18.0

package/docs/reference/05-adapters.mdx

@@ -0,0 +1,351 @@
+---
+title: Adapters
+description: "Stores, schedulers, and OpenTelemetry."
+---
+
+## `experimental-a2/otel`
+
+```ts
+otel(options?: { tracer?: Tracer; tracerName?: string }): A2Telemetry
+```
+
+OpenTelemetry instrumentation for a server (`@opentelemetry/api` is a peer
+dependency). Pass it as `telemetry`. Spans nest through the active context, so
+the happy path lands in one trace: request → append → drain → each handler →
+the events those handlers append. `A2Telemetry` is a one-method interface:
+anything with `span(name, attributes, fn)` works, and `otel()` is the adapter
+A2 ships. See [Watch it in traces](/server/production#watch-it-in-traces).
+
+### The span catalogue
+
+This catalogue is a contract: renames and additions are breaking for
+dashboards and are called out in the package's `CHANGELOG.md`. All spans carry
+`a2.contract` and `a2.session_id`. Core spans describe the durable runtime;
+`a2.ai.*` spans describe the built-in AI handlers.
+
+| Layer | Span | Wraps |
+| ----- | ---- | ----- |
+| Core | `a2.append` | validation + the store write (one batch) |
+| Core | `a2.drain` | one drain pass, including concurrent handlers |
+| Core | `a2.event` | one claimed dispatch, including its handler and completion |
+| Core | `a2.claim` | one `claimAvailable` store operation |
+| Core | `a2.commit` | one `completeAttempt` or `failAttempt` store operation |
+| Core | `a2.state` | one `state()` read: snapshot-plus-tail load + reducer fold |
+| Core | `a2.snapshot` | one background batch of checkpoint writes |
+| Core | `a2.redrive` | one `session.redrive()`: the store operation and starting the session's wakeup |
+| AI | `a2.ai.control` | applying an input/work report/session-close decision and preparing its returned events |
+| AI | `a2.ai.generate` | one generation handler, including Core calls and model/SDK work |
+| AI | `a2.ai.context` | constructing model messages, including tool prompt reconstruction when uncached |
+| AI | `a2.ai.compaction` | automatic summarization or the custom compaction callback |
+| AI | `a2.ai.tool` | one durable tool handler, including application execution |
+| AI | `a2.ai.ack` | waiting for a persisted work report's canonical events and control receipt |
+
+Durations include nested work: `a2.event` contains its AI handler and later
+commit, AI handlers call Core, and `a2.state` includes reducer code.
+Acknowledgements overlap control processing, claims can cover several events,
+and snapshots run in the background, so summing spans, or subtracting summed
+children, does not yield exclusive Core or AI overhead. Model and application
+I/O is included; its child spans have the detail.
+
+Attributes arrive in two waves: **at start** (passed to `span()`) and
+**mid-span** (via `handle.setAttribute`, for outcomes and counts known only
+after the work ran). A recorder must merge both; the ones you alert on are all
+mid-span.
+
+| Attribute             | Span        | When  | Values                                                |
+| --------------------- | ----------- | ----- | ----------------------------------------------------- |
+| `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
+| `a2.append.mode`      | `a2.append` | start | `inline` \| `dispatch`                                |
+| `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
+| `a2.append.count`     | `a2.append` | start | batch size                                            |
+| `a2.append.armed`     | `a2.append` | mid   | `false` when the scheduler arm failed and this append degraded to append-driven healing |
+| `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled`                      |
+| `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
+| `a2.claim.outcome` | `a2.claim` | mid | `claimed` \| `busy` \| `settled` |
+| `a2.claim.count` | `a2.claim` | mid | number of claimed events, or zero |
+| `a2.commit.operation` | `a2.commit` | start | `complete` \| `fail` |
+| `a2.commit.index` | `a2.commit` | start | event log position |
+| `a2.commit.attempt` | `a2.commit` | start | durable 1-based attempt ordinal |
+| `a2.commit.outcome` | `a2.commit` | mid | `completed` \| `failed` \| `dead_lettered` \| `superseded` |
+| `a2.event.type`       | `a2.event`  | start | the event's type                                      |
+| `a2.event.index`      | `a2.event`  | start | log position                                          |
+| `a2.event.id`         | `a2.event`  | start | event id                                              |
+| `a2.event.attempt`    | `a2.event`  | start | same durable 1-based ordinal as `ctx.attempt`          |
+| `a2.event.lane`       | `a2.event`  | start | stored lane value; absent for concurrent unlaned work  |
+| `a2.event.handled`    | `a2.event`  | start | normally `true`; `false` when a custom-adapter row has no handler |
+| `a2.event.outcome`    | `a2.event`  | mid   | `processed` \| `failed` \| `dead_lettered` \| `superseded` \| `surrendered` |
+| `a2.event.aborted`    | `a2.event`  | mid   | `true` when `abortOn` fired during the run            |
+| `a2.state.reducer`    | `a2.state`  | start | the reducer's name                                    |
+| `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) \| `memory` (served from the server's in-memory state) |
+| `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
+| `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
+| `a2.snapshot.reducer` | `a2.snapshot` | start | the reducer's name                                  |
+| `a2.snapshot.index`   | `a2.snapshot` | start | greatest checkpoint index in the write batch       |
+| `a2.snapshot.count`   | `a2.snapshot` | start | number of checkpoints in the write batch           |
+| `a2.redrive.index` | `a2.redrive` | start | log position of the event being redriven |
+| `a2.redrive.action` | `a2.redrive` | start | `retry` \| `skip` |
+| `a2.redrive.redriven` | `a2.redrive` | mid | `true` when the event was dead-lettered and is now resolved |
+| `a2.redrive.armed` | `a2.redrive` | mid | `false` when the scheduler arm failed and the wakeup degraded to append-driven healing |
+| `a2.ai.control.type` | `a2.ai.control` | start | `ai.control.requested` \| `ai.work.reported` \| `ai.session.closed` |
+| `a2.ai.control.id` | `a2.ai.control` | start | triggering event id |
+| `a2.ai.control.attempt` | `a2.ai.control` | start | durable 1-based attempt ordinal |
+| `a2.ai.generate.request_id` | `a2.ai.generate` | start | generation request event id |
+| `a2.ai.generate.attempt` | `a2.ai.generate` | start | durable 1-based attempt ordinal |
+| `a2.ai.context.request_id` | `a2.ai.context` | start | generation request event id |
+| `a2.ai.context.phase` | `a2.ai.context` | start | `generation` \| `refresh` \| `tool` |
+| `a2.ai.compaction.request_id` | `a2.ai.compaction` | start | generation request event id |
+| `a2.ai.compaction.generation_id` | `a2.ai.compaction` | start | generation attempt id |
+| `a2.ai.compaction.policy` | `a2.ai.compaction` | start | `automatic` \| `custom` |
+| `a2.ai.tool.request_id` | `a2.ai.tool` | start | originating generation request event id |
+| `a2.ai.tool.call_id` | `a2.ai.tool` | start | tool call id |
+| `a2.ai.tool.name` | `a2.ai.tool` | start | tool name |
+| `a2.ai.tool.attempt` | `a2.ai.tool` | start | durable 1-based attempt ordinal |
+| `a2.ai.ack.request_id` | `a2.ai.ack` | start | reporting worker event id |
+| `a2.ai.ack.report_id` | `a2.ai.ack` | start | work report event id, matching the control span's id |
+
+- Drain outcomes: `settled` means nothing actionable is left; `busy` means live
+  per-event claims remain; `stalled` means a caught failure needs a later
+  retry.
+- A failing handler marks its `a2.event` span with the exception and error
+  status. Alert on `a2.event.outcome = dead_lettered`. A dead-lettered event
+  blocks only later events in its lane, until `session.redrive()` resolves it;
+  other lanes stay eligible.
+- `superseded` means a stale completion or failure did not change the log.
+
+## `experimental-a2/store-postgres`
+
+`postgres({ connectionString })` returns an `A2Store` on Postgres; pass
+`client` to inject your own pool. See [Postgres](/server/production#postgres)
+for setup.
+
+- Without `listenConnectionString`, a live stream polls with an adaptive
+  cadence: every 25ms while the session is producing events, backing off to
+  two seconds when it goes quiet. After a quiet period, an update from another
+  client can take up to the idle interval plus query latency to arrive.
+- A client's own `push()` refreshes its idle stream immediately from the
+  current cursor, even when the write and stream routes run in different
+  invocations. A WebSocket push wakes the attached stream without reopening
+  the socket.
+- With `listenConnectionString`, notifications arrive after commit, and a
+  reconnect catches up from the cursor. Native event and presence
+  subscriptions also reconcile every ten seconds.
+
+## `experimental-a2/store-redis`
+
+`redis({ url })` returns an `A2Store` that keeps each session as a Redis
+Stream; pass `client` to inject your own. See
+[Redis](/server/production#redis-recommended) for setup and per-command costs.
+
+- Every write publishes a wake-up, so live streams are push-driven, not
+  polled.
+- A wake-up is disposable: a safety re-read recovers a lost one within ten
+  seconds.
+
+## `experimental-a2/store-redis-http`
+
+`redisHttp({ url, token })` returns the same Redis store over `fetch`, for
+providers that expose only a REST API, such as Upstash. See
+[Redis](/server/production#redis-recommended) for setup and the trust warning.
+
+- Live events and presence use Upstash's HTTP `SUBSCRIBE` endpoint (SSE), with
+  the same URL and token. Each active channel holds one outbound HTTP
+  subscription per store instance, shared by its local viewers and closed when
+  the last viewer leaves.
+- Writes publish their wake-ups in the same Redis script as the append. A
+  rejected notification does not fail the applied write.
+- Idle event streams re-read every ten seconds to recover missed
+  notifications. Subscriptions reconnect on their own and catch up from the
+  event cursor.
+- After a reconnect, A2 re-reads the current presence fields and clears fields
+  deleted during the gap, so presence may repeat its latest values. Updates
+  received during that read take precedence.
+- If the subscribe endpoint answers 404, 405, or 501, events and presence use
+  adaptive polling instead, from 25ms to two seconds while idle.
+
+## `experimental-a2/scheduler-vercel`
+
+`vercelQueues(options?)` returns an `A2Scheduler` backed by Vercel Queues.
+
+```ts server/scheduler-vercel.ts
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+
+export const scheduler = vercelQueues()
+```
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `topic` | `string` matching `[A-Za-z0-9_-]+` | `'a2'` |
+| `deploymentId` | `string \| null` | `VERCEL_DEPLOYMENT_ID` |
+| `transport` | `QueueTransport` | lazy `@vercel/queue` client |
+| `clock` | `{ now(): Date }` | system clock |
+
+- `deploymentId` passes to the Queue SDK unchanged and applies to every task,
+  recovery watchdogs included. Omit it for `VERCEL_DEPLOYMENT_ID`, pass an ID
+  to target that deployment, or pass `null` for deploymentless delivery.
+  Publishing and consuming clients must use the same deployment scope.
+- One configured client handles sends, payload fetches, acknowledgements, and
+  visibility changes; callback contents never choose the client.
+- Pinned tasks stay with their target deployment after another is promoted.
+  Deploymentless delivery lets Vercel choose an eligible consumer, not the
+  latest production deployment; every eligible consumer must use
+  `deploymentId: null` and stay compatible with pending tasks and session work.
+- Tasks are retained for seven days. Delays are accepted through six days,
+  leaving the final day for delivery and retries.
+- `transport` and `clock` are advanced injection seams for tests and custom
+  delivery. An injected transport receives the topic, an exact
+  `SchedulerTask`, and send options, and owns its provider configuration;
+  `deploymentId` configures only the built-in client.
+
+See [Vercel Queues](/server/production#vercel-queues-recommended).
+
+## `experimental-a2/scheduler-qstash`
+
+`qstash(options?)` returns an `A2Scheduler` backed by QStash HTTP delivery.
+Vercel Queues remains the recommended default on Vercel; use QStash for a
+scheduler that calls a stable public endpoint.
+
+```ts server/scheduler-qstash.ts
+import { qstash } from 'experimental-a2/scheduler-qstash'
+
+export const scheduler = qstash()
+```
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `url` | `string` | conventional local or Vercel callback; required for process-less runtimes, other production, and custom routes |
+| `token` | `string` | `QSTASH_TOKEN` |
+| `currentSigningKey` | `string` | `QSTASH_CURRENT_SIGNING_KEY` |
+| `nextSigningKey` | `string` | `QSTASH_NEXT_SIGNING_KEY` |
+| `headers` | `Readonly<Record<string, string>>` | no additional callback headers |
+| `client` | `QStashPublishingClient` | lazy `@upstash/qstash` client |
+| `retries` | non-negative integer | the QStash provider default |
+| `maxBodyBytes` | positive integer | `1_048_576` (1 MiB) for callbacks and reserved outbound bodies |
+| `transport` | `QStashTransport` | lazy `@upstash/qstash` client and receiver |
+| `clock` | `{ now(): Date }` | system clock |
+
+Mount the application handler once and pass every server that shares the
+scheduler:
+
+```ts app/api/a2/scheduler/route.ts
+import { billingServer, ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer, billingServer)
+```
+
+**Callback URL.** An explicit `url` always wins. Otherwise:
+
+- Vercel production: `https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler`.
+  Preview: `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`. Both are moving
+  aliases, so pending tasks can reach later deployments on the same URL.
+- A runtime that exposes `process.env`, outside `NODE_ENV=production`:
+  `http://localhost:${PORT ?? 3000}/api/a2/scheduler`, with `devMode: true` on
+  the SDK client and receiver. `QSTASH_DEV` is not required, and
+  `QSTASH_DEV=false` does not disable it. `PORT` must be an integer from 1
+  through 65535; `QSTASH_DEV_PORT` configures the local QStash server, not the
+  callback.
+- Automatic local startup needs `@upstash/qstash` 2.11.0 or newer in Node.js;
+  the lazy transport starts it on the first publish or verification. An Edge
+  runtime that exposes `process.env` infers the local URL but must start the
+  development server separately.
+- Non-Vercel production, process-less runtimes, custom hosts or paths, ports
+  not available through `PORT`, and Docker networking need an explicit
+  absolute URL.
+- Outside production, an explicit URL leaves SDK development mode to
+  `QSTASH_DEV` or a manual `QSTASH_URL` plus credentials. In production, A2
+  passes `devMode: false`.
+
+**Options.**
+
+- `headers`: static headers on every callback delivery, recovery successors
+  included. Validated and snapshotted when `qstash()` runs; A2 asks QStash to
+  redact every value from its dashboard and API, but QStash still receives,
+  stores, and delivers them. Names are case-insensitive. Reserved:
+  provider-owned `Upstash-*`, `Content-Type*`, HTTP framing headers, and A2's
+  managed Vercel identity headers.
+- `client`: the structural `publishJSON(...)` part of a configured
+  `@upstash/qstash` `Client`, for its API endpoint, publish-request retry
+  policy, or telemetry. Not combinable with `token` or `transport`; A2 still
+  creates the `Receiver` lazily from the signing keys. Put callback credentials
+  in `headers`, since client-global callback headers and redaction are outside
+  A2's merge contract. The client receives raw callback credentials, including
+  an automatic preview identity, and must honor per-publish redaction.
+- `transport`, `clock`: advanced injection seams for tests and custom delivery.
+  A `QStashTransport` implements `publish(request)` and `verify(request)`.
+  Publish requests carry the callback `url`, a complete `SchedulerTask` body
+  (plus provider-private generation metadata for store-outage successors),
+  optional `headers` and `redact.header` names, an optional Unix-seconds
+  `notBefore`, and a deterministic `deduplicationId`; preserve the body,
+  deliver every header, and apply every redaction. Verify requests carry the
+  signature, raw body, exact callback URL, and optional Upstash region.
+- `retries`: omitted, QStash uses its provider default; an explicit value is
+  forwarded. Every delivery attempt is billable.
+- `maxBodyBytes`: the adapter reserves room for a task's largest possible
+  store-outage lineage before its initial publish, so an accepted task never
+  exceeds the limit later. Raise it for a larger paid-plan payload limit. Keep
+  one value across every deployment that receives this URL: a lower value can
+  return a non-retryable 489 for a task an older value accepted.
+
+**The route.**
+
+- Must be reachable by the selected QStash server after any platform edge
+  authentication; the development server calls localhost directly.
+- Reads the raw body once and verifies `Upstash-Signature`, the exact URL, and
+  `Upstash-Region` before parsing or touching a server. Missing or invalid
+  signatures return 401.
+- A signed malformed envelope, or a declared or streamed body over
+  `maxBodyBytes`, returns 489 with `Upstash-NonRetryable-Error: true`.
+- Returns 200 when settled; when busy, after a durable successor watchdog
+  exists; when stalled, after publishing a fresh successor, which resets the
+  per-message retry budget. Append tasks return 200 after their fixed-id append
+  succeeds and any recovery watchdog for pending handler work is durable; clear
+  tasks after their conditional clear and its deletion finish.
+- A retryable store outage hands drain, append, and clear tasks to a fresh
+  successor before acknowledging: 30 seconds, times four per signed
+  generation, capped at one day. The generation keeps increasing past the cap,
+  so each handoff gets a new deduplication id, and duplicate deliveries of one
+  generation publish the same successor.
+- Unknown contracts, missing scheduler configuration, schema failures, and
+  successor publish failures keep the delivery retryable.
+
+**Delivery.**
+
+- At least once, so handler side effects need idempotency keys. QStash's
+  documented 10-minute deduplication window can reduce duplicate watchdogs but
+  is not part of A2's correctness model; stable scheduled-event ids keep timer
+  redelivery safe after it.
+- During a prolonged outage where QStash cannot reach the callback, nothing
+  publishes a successor: monitor the DLQ and redrive.
+- One-shot delays are capped at 7 days on free plans and 1 year on usage-based
+  plans, with no fixed maximum on fixed plans. Leave one second of margin at a
+  plan maximum: `notBefore` uses whole Unix seconds.
+- Carries both recovery watchdogs and `session.schedule` tasks.
+
+**Protected previews.** For an inferred preview callback, each publish
+forwards the invocation's `x-vercel-oidc-token` as
+`x-vercel-trusted-oidc-idp-token`, with redaction requested, when it is a
+parseable JWT that expires at least 60 seconds after the task's first due time,
+so a matching Vercel Trusted Sources rule can admit the first delivery. QStash
+still receives it. This is opportunistic: missing, malformed, and near-expiry
+tokens fall back to an ordinary publish; an explicit `url` opts out; inferred
+production and local callbacks never forward it; and QStash reuses the stored
+header on retries, so delayed tasks and retries can outlive it. When every
+protected delivery must stay authorized, use an explicit automation bypass
+through `headers` (pending messages keep the captured value after rotation) or
+public ingress. Signature verification still applies after the edge-access
+check.
+
+See [QStash](/server/production#qstash).
+
+## Scheduler send errors
+
+Both built-in adapters preserve the original provider error from a rejected
+send.
+
+- Terminal: a recognized definite 4xx status or error, except 408, 409, 425,
+  and 429. The Vercel adapter also treats the SDK's name-only
+  `BadRequestError`, `UnauthorizedError`, and `ForbiddenError` as terminal.
+- Retryable: 408, 409, 425, 429, 5xx responses, network failures, and errors
+  with no recognized status.
+- The Vercel adapter's native duplicate-message error is success.
+- A2's durable AI tool execution uses this private classification. Direct
+  `session.schedule()` calls still reject with the original error object.

package/docs/reference/06-errors.mdx

@@ -0,0 +1,138 @@
+---
+title: Errors
+description: Every A2 error code, when it's thrown, whether it's retryable, and how it crosses the wire.
+---
+
+## `A2Error`
+
+A2 failures carry an `A2Error` with a stable `code`. The session client
+exposes `A2ClientError`, which extends `A2Error`, for server failures and local
+ones alike, so `instanceof A2Error` matches both.
+
+```ts
+// e.g. in a route handler:
+import { A2Error } from 'experimental-a2'
+
+export async function POST(req: Request) {
+  const { orderId, payload } = await req.json()
+  try {
+    const events = await ordersServer
+      .session(orderId)
+      .append({ type: 'created', payload })
+    return Response.json(events)
+  } catch (err) {
+    if (err instanceof A2Error && err.code === 'INVALID_PAYLOAD') {
+      // err.details carries the schema issues, in Standard Schema format
+      return Response.json({ issues: err.details }, { status: 400 })
+    }
+    throw err
+  }
+}
+```
+
+## The codes
+
+| Code | Thrown when | Retryable |
+| --- | --- | --- |
+| `INVALID_PAYLOAD` | a payload fails its schema; nothing was written. `details` carries the issues in [Standard Schema](https://standardschema.dev) format | no |
+| `FORBIDDEN` | `server.fetch` authorization denies a parsed stream, history read, push, or presence update | no |
+| `UNKNOWN_EVENT_TYPE` | an event type isn't in the contract's `events` map | no |
+| `UNKNOWN_PRESENCE_FIELD` | a presence field isn't in the contract's `presence` map | no |
+| `PRESENCE_NOT_SUPPORTED` | the contract declares `presence` but the store has no presence capability. Thrown at construction; for environment-resolved stores, at first store use | no |
+| `PARTIAL_DUPLICATE_BATCH` | a batch mixes already-appended and fresh events, contains the same id twice, or uses an id already used in a different session (event ids are globally unique). Always a caller bug; nothing was written | no |
+| `SUPERSEDED_ATTEMPT` | a handler append or clear comes from an attempt that a recovery claim or a session clear replaced; nothing was written. Also the abort reason on that handler's `ctx.signal` | no |
+| `SESSION_CLEARED` | a state read reaches below the latest clear, a handler reads state past a clear of its event, or an actor call is cleared before it receives its answer | no |
+| `CLAIM_EXPIRED` | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no |
+| `STORE_UNAVAILABLE` | the store backend failed; nothing was written. The original error is the `cause` | **yes** |
+| `STORE_NOT_CONFIGURED` | production boots with no `store` configured (during `next build` page collection, deferred to first use) | no |
+
+Retrying an *identical* batch is not `PARTIAL_DUPLICATE_BATCH`: it's an
+idempotent success that returns the previously appended events. A failing
+handler never makes `append` throw; handler failures retry and, if persistent,
+[dead-letter the event](/server/guarantees#when-a-handler-keeps-failing). See
+[What append never throws for](/server/guarantees#what-append-never-throws-for).
+
+## `A2ClientError`
+
+Import `A2ClientError` from `experimental-a2/client`. Connection, push, and
+history read failures, and local A2 validation failures, use this class. Server
+failures keep their `code`, `message`, and `details`; unexpected thrown values
+are kept as `cause`. Invalid API arguments can still throw a native `TypeError`
+or `RangeError`.
+
+| Client code | Meaning |
+| --- | --- |
+| `TIMEOUT` | A stream stall (`phase: 'stream'`, 35 seconds of silence after connection) or an unconfirmed multiplexed subscription (`phase: 'subscribe'`, 35 seconds without confirmation). `timeoutMs` is the expired deadline. |
+| `HTTP_ERROR` | An unsuccessful HTTP response without a recognized A2 error body. `status` carries the HTTP status. |
+| `CONNECTION_FAILED` | The transport could not establish or retain a connection. WebSocket close events keep `closeCode` and `closeReason` when available. |
+| `UNKNOWN` | An unexpected client failure. The original value is the `cause`. |
+
+- HTTP failures keep `status` even when they carry a recognized server code.
+- A browser WebSocket handshake rejection has no readable HTTP status or body,
+  so it stays `CONNECTION_FAILED`. A2 never infers an authorization failure or
+  a timeout from an opaque socket error.
+- A2 sets no initial connection deadline for HTTP or single-session WebSockets.
+- A clean stream end is not an error: the reconnection callback and the
+  connection snapshot carry `null`.
+- Pushes retry `STORE_UNAVAILABLE` and client transport failures, up to three
+  attempts. No other server code is retried.
+- The [reconnection policy](/client/transports#lifecycle) controls only the
+  live stream. Pausing the stream preserves the writer, but a push can still
+  fail while its WebSocket is unavailable.
+
+## NonRetriableError
+
+Throw it (or a subclass, matched by `instanceof`) from a handler when the
+failure is deterministic: a guard that refuses this attempt refuses every
+retry identically. The event dead-letters immediately instead of consuming the
+ten-failure retry budget. Any other thrown error keeps the
+ordinary retry contract.
+
+```ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+import { NonRetriableError } from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+
+const orders = a2.contract({
+  name: 'orders',
+  events: { created: z.object({ chargeable: z.boolean() }) },
+})
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      if (!event.payload.chargeable) {
+        throw new NonRetriableError('this order cannot be charged')
+      }
+      // transient failures below retry as usual
+    },
+  },
+})
+```
+
+## Over the wire
+
+`server.fetch` owns HTTP serialization. The push route sends an `A2Error` as:
+
+```json
+{ "error": { "code": "INVALID_PAYLOAD", "message": "...", "details": [] } }
+```
+
+with a mapped status:
+
+| Status | Codes |
+| --- | --- |
+| 400 | `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, `PARTIAL_DUPLICATE_BATCH` |
+| 403 | `FORBIDDEN` |
+| 409 | `SUPERSEDED_ATTEMPT` |
+| 503 | `STORE_UNAVAILABLE` |
+
+- Unknown server exceptions become `STORE_UNAVAILABLE`; their private causes
+  are not sent to clients.
+- The session client deserializes the body into an `A2ClientError`, so client
+  and server code branch on identical server codes.
+- Multiplexed WebSocket subscription failures carry the same envelope in their
+  `unsubscribed` frame, alongside the legacy `reason` string. Older reason-only
+  frames read as `CONNECTION_FAILED`.

package/docs/reference/meta.ts

@@ -1 +1 @@
-export default { order: 5 }
+export default { order: 7 }