experimental-a2 0.0.0

package/docs/guides/02-cancellation.mdx

@@ -0,0 +1,107 @@
+---
+title: Cancellation
+description: There is no abort() API. Cancelling is appending, and the running handler finds out through a signal.
+---
+
+## Cancelling is appending
+
+A user presses stop on a streaming AI response. In A2 that's not a special
+operation with its own machinery. It's an event:
+
+```ts
+// in the browser: push from useSession (see Live UI)
+push({ type: 'cancelled', payload: { lastSeenIndex: index } })
+```
+
+Same route, same auth, same log as every other event. Two things then
+happen, at two different speeds.
+
+## The running handler stops
+
+A handler doing abortable work opts in by naming the events that should
+interrupt it:
+
+```ts server/chat.ts
+import { createServer } from 'experimental-a2/server'
+import { chat } from '@/contracts'
+
+export const chatServer = createServer({
+  contract: chat,
+  handlers: {
+    generate: {
+      abortOn: ['cancelled'],
+      handler: async (ctx) => {
+        // your abortable work; hand it ctx.signal:
+        // await streamText({ signal: ctx.signal, ... })
+      },
+    },
+  },
+})
+```
+
+While the handler runs, A2 watches the session's log. The moment a
+`cancelled` event lands (or one already landed before the handler
+started), `ctx.signal` fires. Handlers without `abortOn` pay nothing.
+
+One rule: an aborted handler should catch and return normally. Throwing
+means "retry me", exactly the wrong response to someone pressing stop.
+
+When one session multiplexes work (several generations over its
+lifetime), match by *instance*, not just type, with a predicate:
+
+```ts
+// server/chat.ts, the generate entry, targeted by instance:
+generate: {
+  abortOn: {
+    // only the cancel that names this run fires the signal
+    cancelled: (event, trigger) => event.payload.of === trigger.id,
+  },
+  handler: async (ctx) => {
+    // ...
+  },
+}
+```
+
+The pushing side already knows the id it's cancelling; it's in the
+`events` feed the hook exposes.
+
+Because sessions process serially, the `cancelled` event's own handler runs
+*after* the interrupted one settles. That makes it the natural place for
+cleanup. The signal is the preemption channel; the event is the durable
+record.
+
+## The view cuts
+
+Chunks in flight during the cancel round-trip still land in the log after
+`cancelled`. That's correct. They're true history; the model really did
+generate them. Keeping them out of what the user sees is the reducer's job:
+
+```ts reducer.ts
+case 'chunk':
+  return state.cancelled
+    ? state
+    : { ...state, chunks: [...state.chunks, { index: event.index, delta: event.payload.delta }] }
+case 'cancelled':
+  return {
+    ...state,
+    cancelled: true,
+    chunks: state.chunks.filter((c) => c.index <= event.payload.lastSeenIndex),
+  }
+```
+
+`lastSeenIndex` is the client's stream frontier, a number it already
+tracks to resume subscriptions. Cutting on it makes the trim exact and
+clock-free: chunks the log ordered before `cancelled` but the user never
+saw are removed retroactively, so the optimistic view and the
+authoritative refold agree on the same result. No wall clocks, no skew.
+
+And because the client pushes `cancelled`
+[optimistically](/guides/react#the-client-component), its own fold cuts
+instantly. Stragglers still arriving over the stream hit `state.cancelled`
+and vanish from the view.
+
+:::tip
+Keep chunks at per-chunk granularity in state until the session reaches a
+terminal event, then compact them into one string. That's reducer design,
+fully yours.
+:::

package/docs/guides/03-react.mdx

@@ -0,0 +1,234 @@
+---
+title: Live UI with React
+description: "Synchronize one session from server to browser: render its state, stream new events, and push writes optimistically through one reducer."
+---
+
+## The model
+
+A session can be read live from the browser. The server renders the first
+paint, a stream keeps it fresh, and writes apply instantly. One reducer
+produces every one of those views; server and client fold the same log
+with the same function, so they can't disagree.
+
+That's the trick, really. The client doesn't sync state. It syncs events,
+and folds them locally. State sync is a hard problem. An append-only log
+with positions is not.
+
+This is session sync. The client follows one known session id; it does not
+subscribe to database tables or queries across many sessions. Keep those
+collection views in your [application database](/guides/application-data).
+
+The pieces: two route handlers (read and write), a factory that binds your
+reducer, and the provider + hook it returns.
+
+## The API route
+
+One file exposes a session over HTTP: `GET` streams events, `POST` appends.
+These are ordinary route handlers; put whatever checks you like in front.
+
+```ts app/api/order-events/route.ts
+import { A2Error } from 'experimental-a2'
+import { ordersServer } from '@/server/orders'
+import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const sessionId = searchParams.get('sessionId')
+  if (!sessionId) {
+    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
+  }
+  const startAt = Number(searchParams.get('index')) || 0
+
+  // here's where you'd do auth, or any other checks
+
+  return sseResponse(ordersServer.session(sessionId).stream({ startAt }))
+}
+
+export async function POST(req: Request) {
+  try {
+    const { sessionId, events } = await parsePushBody(req)
+
+    // here's where you'd do auth, or any other checks
+
+    const result = await ordersServer.session(sessionId).append(...events)
+    return Response.json(result)
+  } catch (err) {
+    return errorResponse(err)
+  }
+}
+```
+
+`GET` is the read path. `stream({ startAt })` is a live `AsyncIterable` of
+one session's events starting after a given position, and `sseResponse`
+pipes it into a server-sent events response. Clients pass `index` to resume
+exactly where they left off, after a first paint or a dropped
+connection.
+
+`POST` is the write path. `parsePushBody` validates the envelope (and
+throws `INVALID_PAYLOAD` on garbage), then `append` does the rest. The
+response is the appended events: an ack, not a stream. `errorResponse`
+serializes any thrown [`A2Error`](/reference/errors#over-the-wire) so the
+client can branch on the same codes.
+
+## The session module
+
+Bind your reducer once, in a `'use client'` file, and export the pair:
+
+```tsx app/orders/[orderId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { ordersReducer } from '@/reducer'
+
+export const ordersClient = createClient({
+  reducer: ordersReducer,
+  api: '/api/order-events',
+})
+export const { SessionProvider, useSession } = createReact({ client: ordersClient })
+```
+
+This is the whole client/server seam. `createReact` is a factory (like
+`createContext`): everything it returns is typed by the reducer value;
+the state from its fold, the pushable events from its vocabulary. No type
+arguments anywhere, and nothing in this file touches the server module.
+The client also gives every session a stable in-memory identity. Calling
+`ordersClient.session(orderId)` before navigation and mounting the provider
+after navigation reaches the same optimistic state, with no handoff store.
+
+## The server component
+
+The first paint costs no client JavaScript: fold on the server, pass the
+result down.
+
+```tsx app/orders/[orderId]/page.tsx
+import { ordersServer } from '@/server/orders'
+import { ordersReducer } from '@/reducer'
+import { SessionProvider } from './session'
+import { OrderClient } from './order-client'
+
+export default async function OrderPage({
+  params,
+}: {
+  params: Promise<{ orderId: string }>
+}) {
+  const { orderId } = await params
+  const session = ordersServer.session(orderId)
+  const { state, index } = await session.state(ordersReducer)
+  const initialEvents = (await session.history()).filter(
+    (event) => event.index <= index,
+  )
+
+  return (
+    <SessionProvider
+      sessionId={orderId}
+      initialState={state}
+      initialIndex={index}
+      initialEvents={initialEvents}
+    >
+      <OrderClient />
+    </SessionProvider>
+  )
+}
+```
+
+Three props do the heavy lifting. `initialState` is the fold; `initialIndex`
+is its frontier, the log position the fold reflects; `initialEvents` makes
+the raw feed available in the server render too. Reading state before history
+and filtering at the state frontier gives both values one consistent boundary.
+The client opens its stream at exactly that position. Nothing missed, nothing
+folded twice.
+(No `reducer` or `api` prop: the provider got both from the shared client.)
+
+## The client component
+
+```tsx app/orders/[orderId]/order-client.tsx
+'use client'
+import { useSession } from './session'
+
+export function OrderClient() {
+  const { state, push, events, index } = useSession()
+
+  return (
+    <button onClick={() => push({ type: 'shop.started', payload: {} })}>
+      Start
+    </button>
+  )
+}
+```
+
+What the hook gives you:
+
+- **`state`**: the live view, folded through the shared reducer. It
+  updates three ways: optimistically when you push, corrected when the
+  server acks, and continuously as the stream delivers events, yours and
+  everyone else's.
+- **`push`**: typed against the contract's vocabulary (via the reducer). Payloads are
+  validated locally before anything leaves the browser, apply instantly,
+  swap in the real event when the `POST` acks, and refold without it if
+  the server says no. Rejections carry the same
+  [`A2Error` codes](/reference/errors) the server throws, so both sides
+  branch on `code`. Awaiting `push(...)` gives the server ack; the
+  result also carries **`.confirmed`**, a promise for the moment the
+  live stream delivers the batch back and the view shows server truth.
+  `await push(...).confirmed` is "continue once this is real"; two
+  `performance.now()` calls around the two awaits are a complete
+  push→ack→stream latency meter.
+- **`events`**: the raw feed `state` is folded from, for UI that wants
+  the log itself: an activity feed, a debug panel.
+- **`index`**: the stream frontier, the last server-confirmed log
+  position. This is the `lastSeenIndex` that makes
+  [cancellation](/guides/cancellation) exact.
+- **`connection`**: a discriminated union of `{ status: 'idle' }`,
+  `{ status: 'connecting', reconnects, error }`,
+  `{ status: 'live', reconnects }`, or `{ status: 'closed' }`. A status
+  dot is one ternary away; "reconnecting…" is
+  `status === 'connecting' && reconnects > 0`; `error` (why the last
+  connection ended) only exists while disconnected, so impossible
+  states don't compile. It's honest about silence, too: the server
+  heartbeats the stream (`: ping` every 15s), and a client that hears
+  nothing for two beats treats the connection as dead and reconnects, so
+  `live` means bytes are flowing, not "the socket hasn't errored yet".
+
+The provider opens the stream on mount, closes it on unmount, and
+reconnects with backoff, resuming from `index`, when the connection
+drops. Components that only write don't need the hook; `POST` to the
+route directly, or call `ordersClient.session(id).push(...)` so a later
+provider sees the same optimistic session.
+
+That identity is an in-memory L1, not another source of truth. Repeated
+`session(id)` calls reuse it while active and for five idle minutes by
+default. A newer server fold advances it, pending pushes stay overlaid,
+and a stale server render cannot rewind it. The optional IndexedDB cache
+is the L2: it survives reloads; the memory runtime does not.
+
+One detail worth knowing: every push carries a client-generated event id.
+That id is how the ack finds its optimistic entry, and it makes retrying
+a failed `POST` idempotent for free (`push` auto-retries only
+`LOG_UNAVAILABLE`).
+
+Optimistic pushes are also what make [cancellation](/guides/cancellation)
+feel instant: the `cancelled` event folds locally before the server ever
+sees it.
+
+Sessions can outlive the tab, too: hand `createReact` a `cache` and
+revisits paint from the local copy, the stream resumes from the cached
+frontier, and offline pushes queue and replay. See
+[Local-first](/guides/local-first).
+
+## Keep the backend out of the bundle
+
+The split is structural, not disciplinary. Core `experimental-a2` (the contract,
+reducers, errors) imports no backend, ever; only `experimental-a2/server` can reach
+one, and its exports map resolves to a loud error under the browser
+condition. The layout above rides that:
+
+1. `contracts.ts` and `reducer.ts` import nothing but schemas and `experimental-a2`,
+   isomorphic by construction.
+2. The session module imports the reducer, never `experimental-a2/server`. Client
+   components don't need the server's *type*, even: the factory carries
+   all the typing.
+
+Belt and suspenders: put `import 'server-only'` at the top of your
+server module and enable `verbatimModuleSyntax` in your tsconfig; an
+accidental value import then fails your build too, with your own error
+message.

package/docs/guides/04-local-first.mdx

@@ -0,0 +1,88 @@
+---
+title: Local-first
+description: "Cache one A2 session in the browser: instant revisits, stream resumption, and offline writes."
+---
+
+## One option
+
+```tsx app/orders/[orderId]/session.ts
+'use client'
+import { createReact } from 'experimental-a2/react'
+import { indexedDb } from 'experimental-a2/cache-indexeddb'
+import { ordersReducer } from '@/reducer'
+
+export const { SessionProvider, useSession } = createReact({
+  reducer: ordersReducer,
+  cache: indexedDb(),
+})
+```
+
+This is the [session module](/guides/react#the-session-module) from Live
+UI with one addition. The cache is created here, in client code, where
+live objects belong; server components keep importing `SessionProvider`
+exactly as before; nothing crosses the server boundary.
+
+With `cache` set:
+
+- **Revisits paint instantly.** State folds from the local copy before the
+  network says a word. Works offline too.
+- **The stream resumes from the cached frontier.** Reconnects fetch only
+  what this browser hasn't seen, no matter how long it's been.
+- **Pushes queue while offline**, and replay, in order, when the
+  connection returns.
+
+Without it, nothing changes; the provider behaves exactly as before.
+
+## Why this is safe
+
+Local-first is usually hard because it means syncing state, and state
+needs merging. A2 caches an append-only log with server-assigned positions
+instead. A cached event can never be *wrong*; this browser can only be
+*behind*. Catching up is fetching events after an index, which is what
+`stream({ startAt })` does anyway. There's no merge function because
+there's nothing to merge.
+
+## What gets stored
+
+Three things, in IndexedDB:
+
+| Stored                                        | Invalidated by                                          |
+| --------------------------------------------- | ------------------------------------------------------- |
+| the session's events                          | nothing; they're immutable                              |
+| a folded snapshot, keyed by reducer name | a reducer rename (or a `stateSchema` mismatch, when the reducer declares one): discarded, refolded from cached events |
+| pending pushes                                | the server's ack                                        |
+
+Note the middle row: the reducer's `name` does the same job here that it
+does for [server snapshots](/concepts/state#snapshots-are-a-cache). One
+string, both sides of the wire.
+
+Deleting the cache is always safe. It's a replica of what this browser
+already saw; the log on the server stays the only authority.
+
+## Offline writes
+
+`push` while offline persists the events, client ids and all, and
+applies them optimistically, same as always. On reconnect they replay in
+order. The replay is idempotent by construction: an identical batch is an
+idempotent success, so a flaky reconnect, or a second tab replaying the
+same queue, causes no duplicates. Rejections refold without the event,
+exactly like an online push the server refused.
+
+What this is *not*: local execution. Handlers run on the server, when the
+events arrive. An offline push is a queued intent, not a completed
+action. Design the UI accordingly ("sending…" is honest; "sent" is not).
+
+## Logout
+
+Cached events outlive the session cookie. If your app authenticates,
+clear the cache when the user leaves:
+
+```ts
+// in the browser, wherever your logout flow runs:
+await cache.clear() // everything, or cache.clear(sessionId) for one session
+```
+
+That's the one obligation `cache` puts on you. The cache never *grants*
+access (your routes still authorize every read and write) but it
+*retains* what was legitimately seen, and retained data belongs to the
+person who saw it.

package/docs/guides/05-production.mdx

@@ -0,0 +1,179 @@
+---
+title: Going to production
+description: Point the log at Postgres, add queue-backed recovery, and know what to do when an event dead-letters.
+---
+
+## Two pieces
+
+Development needs zero setup: SQLite appears under `.a2/`, and tests run
+in memory. Production needs two deliberate pieces. Neither changes your
+handlers.
+
+## 1. Choose a log
+
+Production has no default log, on purpose. A server without one throws
+`LOG_NOT_CONFIGURED` at startup. A failed boot beats events written to a
+filesystem that evaporates.
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/log-postgres'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  log: postgres({ connectionString: process.env.DATABASE_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+The Postgres backend uses real transactions; appends serialize per
+session on an advisory lock, and the live stream polls the log with an
+activity-adaptive cadence: 25ms while a session is producing events
+(a token stream reads smoothly, not in clumps), backing off to 250ms
+when it goes quiet (a LISTEN/NOTIFY upgrade could still land without
+any API change). Any Postgres works: Neon, Supabase, RDS, your own
+box; transaction-mode poolers included, which is exactly why polling
+is the default. `pg` is an optional peer dependency; pass
+`connectionString`, or inject your own pool as `client`.
+
+This configures storage for A2's session logs. It does not connect A2 to your
+application tables or make them part of the append transaction. See
+[A2 and your database](/guides/application-data) for that boundary.
+
+## 2. Add recovery
+
+Recovery is what puts a clock on healing. `experimental-a2/recovery-vercel` rides
+Vercel Queues (`@vercel/queue` is a peer
+dependency). Same `server/orders.ts`, now with `recovery`:
+
+```ts
+// server/orders.ts, now with recovery:
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/log-postgres'
+import { vercelQueues } from 'experimental-a2/recovery-vercel'
+import { orders } from '@/contracts'
+
+export const recovery = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  log: postgres({ connectionString: process.env.DATABASE_URL }),
+  recovery,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+One recovery instance is shared by every server, and mounted once:
+
+```ts app/api/a2/recovery/route.ts
+import { recovery, ordersServer, billingServer } from '@/server'
+
+export const POST = recovery.handler(ordersServer, billingServer)
+```
+
+```json vercel.json
+{
+  "functions": {
+    "app/api/a2/recovery/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2"
+        }
+      ]
+    }
+  }
+}
+```
+
+The trigger makes the route private. Only queue infrastructure can invoke
+it, so it needs no auth of its own.
+
+One route, one job. Every top-level append starts a delayed, coalesced
+"drain this session" arm alongside its inline handler. The handler does not
+wait for the queue, while `append` joins the initial arm for up to two seconds
+before it returns. An unresponsive queue therefore cannot hold the append open
+indefinitely. Every lease renewal arms another watchdog for just after that
+lease window. A live holder keeps moving the watchdog forward. A killed holder
+stops heartbeating, its lease expires, and the next watchdog retries the
+pending event. When Vercel exposes the function deadline, A2 caps the final
+lease window there so timeout recovery starts promptly. A failing handler
+keeps the current message and redelivers with backoff until the session
+settles.
+
+Due times are rounded to one-second slots. Top-level arms, lease renewals, and
+racing deliveries targeting the same slot deduplicate into one queue message.
+Busy deliveries continue the current message's heartbeat-aligned slot series,
+so they do not create an independent stream of watchdog callbacks.
+Events appended by handlers ride their current execution window and add no
+recovery operation of their own.
+
+No cron, no sweep, no notification bookkeeping. The queue message is
+the recovery state, and the log is the only thing it consults.
+
+## 3. When an event dead-letters
+
+After ten caught handler failures, A2 stops retrying an event and the session
+stalls at it; [Durability](/concepts/durability#when-a-handler-keeps-failing)
+explains why stalling is the honest choice. Resolution is manual, and has
+exactly two shapes:
+
+- **Fix and retry.** Deploy the handler fix, clear the event's failure
+  marker.
+- **Skip.** Mark the event processed, accepting that its effects never
+  happened.
+
+Both are one-column updates on the events table.
+
+## Watch it in traces
+
+A2 takes an optional `telemetry`, an instrumentation hook that
+`experimental-a2/otel` implements over OpenTelemetry (`@opentelemetry/api` is a peer
+dependency):
+
+```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,
+  // ...log, recovery, and handlers as above
+  telemetry: otel(),
+})
+```
+
+With any OTel setup registered (on Vercel, `@vercel/otel`), the happy
+path lands in a single trace: the request → `a2.append` → the inline
+`a2.drain` → an `a2.event` span per handler → the appends those handlers
+make: the whole causal chain, visually. Handler failures mark their `a2.event`
+span with the exception, each dispatch reports `ctx.attempt` as
+`a2.event.attempt`, and `a2.event.outcome = dead_lettered` is the attribute to
+alert on when a session [stalls for manual
+resolution](#3-when-an-event-dead-letters). See the
+[API reference](/reference/api#a2otel) for the span catalogue.
+
+## Running without a queue
+
+Skip `recovery`, and the only wakeups are a top-level append or explicit
+`server.drain()`. Reads never wake the session.
+
+That's a real configuration, not a broken one. Fine for internal tools
+and low-stakes apps where "heals on the next write" is acceptable. But
+there's no clock in it: a session nobody wakes stays stuck until someone does.
+For production, configure recovery.
+
+## Checklist
+
+| Piece               | Done when                                                            |
+| ------------------- | -------------------------------------------------------------------- |
+| Log                 | `log: postgres(...)` on every server                                  |
+| Recovery            | one shared `vercelQueues()`, route mounted, trigger in `vercel.json`  |
+| Idempotent handlers | external side effects take `event.id` as an idempotency key           |
+| Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |