experimental-a2 0.19.0 → 0.21.1

package/docs/reference/05-adapters.mdx

@@ -1,351 +0,0 @@
----
-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 or a failed event's retry hold remain; `stalled` means a
-  caught failure in this drain 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, Vercel Queues' maximum. A delay goes out
-  as asked; Vercel Queues refuses one longer than the retention.
-- `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 or stalled, after a durable successor
-  watchdog exists, so each caught failure gets a fresh message and a fresh
-  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/server/01-handlers.mdx

@@ -1,200 +0,0 @@
----
-title: Handlers
-description: Plain async functions that react to events. Concurrent by default, serialized by lanes, retried after failures.
----
-
-```ts server/orders.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ event }) => {
-      // your side effect, e.g. email the shop, idempotent via event.id:
-      // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
-      return { type: 'shop.notified', payload: {} }
-    },
-  },
-})
-```
-
-A handler runs when its event lands: a plain async function that can call a
-database, hit an API, or stream a model response. A2 claims the event while it
-runs and retries it after a crash.
-
-`createServer` from `experimental-a2/server` binds the contract to a
-[store](/server/production#1-choose-a-store) and one complete handler table,
-so a handler can't go missing because its module was never imported. Compose
-the table across files by spreading objects into `handlers`. It is the only
-entry point that touches a store, and it fails loudly in a browser bundle.
-
-## Events without handlers
-
-```ts server/order-history.ts
-import { createServer } from 'experimental-a2/server'
-import { postgres } from 'experimental-a2/store-postgres'
-import { orders } from '@/contracts'
-
-export const orderHistory = createServer({
-  contract: orders,
-  store: postgres({ connectionString: process.env.DATABASE_URL }),
-})
-```
-
-Handlers are optional per event type. An event without one is still logged,
-folded into state, and streamed; it settles in its append transaction, with no
-claim or scheduler message. Adding a handler later doesn't replay settled
-events. Append a new event or run a migration when you want that.
-
-## The context
-
-| Property      | What it is |
-| ------------- | ---------- |
-| `ctx.event`   | The triggering event: `{ id, type, payload, index, sessionId, createdAt }`. |
-| `ctx.attempt` | The durable 1-based dispatch claim for this event. |
-| `ctx.session` | This session's handle: `id`, `append`, `schedule`, `clear`, `history`, `state`, `stream`, and `setPresence` (presence contracts only). |
-| `ctx.signal`  | An `AbortSignal`. Fires on matching `abortOn` events and when the attempt loses its claim (`CLAIM_EXPIRED`, `SUPERSEDED_ATTEMPT`). See [Cancellation](/server/cancellation). |
-
-`ctx.attempt` increments on every durable claim. It can skip a number when a
-process dies between the claim and handler entry.
-
-[`ctx.session.state(reducer)`](/contract/state) folds through
-`ctx.event.index`, so later concurrent appends don't change what this event
-sees. Pass `{ through: 'latest' }` to read the current committed frontier
-instead.
-
-## Return what happens after success
-
-```ts server/return-many.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const fanout = createServer({
-  contract: orders,
-  handlers: {
-    'shop.started': async () => {
-      return orders.batch(
-        { type: 'shop.notified', payload: {} },
-        { type: 'driver.notified', payload: { driverId: 'driver-7' } },
-      )
-    },
-  },
-})
-```
-
-Return one event or an array when it should exist only if the handler
-succeeds. A2 marks the trigger processed and appends the batch in one atomic
-operation, at consecutive positions. If the handler throws or the process dies
-first, none of it exists. Returned events get deterministic ids, so a retry
-after a lost acknowledgement doesn't duplicate them.
-
-`contract.batch(...)` is a type helper that keeps each event's literal type;
-A2 still validates at commit.
-
-## Append what should happen now
-
-```ts server/append-now.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const immediate = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ session }) => {
-      await session.append('notify-shop', {
-        type: 'shop.notified',
-        payload: {},
-      })
-
-      // The shop.notified handler may already be running here.
-      // await continueCurrentWork()
-    },
-    'shop.notified': async () => {},
-  },
-})
-```
-
-`ctx.session.append()` commits immediately, so the appended event can start
-while its parent is still running. Use it for streaming progress, independent
-fan-out, or any fact that stays true even if the handler later fails. Each
-call is atomic.
-
-The first argument names the append within the triggering event. A2 derives
-the ids of events without an `id` from the trigger, the name, and each
-event's position, so a retry gets the existing events back, whatever order
-parallel branches finish in. Keep the name stable; reusing it with a different
-batch conflicts. An explicit `id` wins, so different triggers can converge on
-one fact. Top-level `server.session(id).append(...events)` takes no name.
-
-## Concurrent by default
-
-```ts
-// anywhere on the server:
-await ordersServer.session('order-42').append(
-  { type: 'created', payload: { shopId: 'shop-7', items: [] } },
-  { type: 'shop.started', payload: {} },
-)
-```
-
-Every eligible event has its own claim, so both handlers start without
-waiting for each other. Log order stays stable; handler order doesn't. A
-failure retries that event without holding up unlaned events or other lanes.
-
-## Lanes
-
-```ts server/serial-orders.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const serialOrders = createServer({
-  contract: orders,
-  handlers: {
-    created: {
-      lane: 'order-work',
-      handler: async () => {},
-    },
-    'shop.started': {
-      lane: 'order-work',
-      handler: async () => {},
-    },
-    'driver.notified': {
-      lane: ({ event }) => `driver:${event.payload.driverId}`,
-      handler: async ({ event }) => {
-        // your work for this driver, using event.payload.driverId
-      },
-    },
-  },
-})
-```
-
-Use a lane when events share a resource and must not overlap. Within one
-session, same-lane events run one at a time in log order; different lanes and
-unlaned events stay concurrent. A lane is a constant (a serial queue) or a
-function of the validated event.
-
-A2 stores the resolved lane at append, so a deployment can't reinterpret
-pending work. Lanes are per session, not distributed locks across sessions. If
-a lane's first unfinished event fails, later events in that lane wait; other
-lanes continue.
-
-## Handlers can run twice
-
-Handlers are at-least-once. A crash after your side effect but before A2
-records completion runs the handler again.
-
-- **External side effects take an idempotency key.** `event.id` is stable
-  across attempts.
-- **Named appends are deduplicated.** A retry gets the existing events back.
-- **Returned events commit with completion.** They all exist with the
-  processed marker, or none do.
-
-## When handlers throw
-
-Throwing means "retry me." A2 records the failure and retries with backoff.
-The failed event blocks only its lane. After ten failed attempts it
-dead-letters and keeps blocking its lane until
-[you retry or skip it](/server/production#3-when-an-event-dead-letters).
-
-When someone presses stop, catch the abort and return normally instead. See
-[Cancellation](/server/cancellation).