experimental-a2 0.17.0 → 0.18.1

package/docs/index.mdx

@@ -1,27 +1,20 @@
 ---
 title: Introduction
-description: A2 is durable sync and reactions for things with a lifecycle. Append or schedule events, run handlers, and keep one live view from server to browser.
+description: A2 syncs your immutable event log, from server to browser.
 ---
 
 ```bash
 pnpm add experimental-a2
 ```
 
-A2 is durable sync and reactions for things with a lifecycle.
-
-An order, agent run, approval, or import gets a session. You append events.
-Handlers react to them, and usually return the next one. The browser follows
-the same log and folds the same state as the server. That's the whole model;
-the rest of this page is it happening.
-
-Events record facts, reducers compute the current view, and handlers perform
-the reactions.
+```bash
+npx skills add vercel-labs/a2
+```
 
-## Define a contract
+## Define a shared contract
 
-Events are the vocabulary. A contract names them once, as a plain
-importable value. The server implements it, and the browser types itself
-off it later.
+Name the events once. The server implements the contract, and the browser
+types itself off it.
 
 ```ts contracts.ts
 import { z } from 'zod'
@@ -30,144 +23,143 @@ import * as a2 from 'experimental-a2'
 export const orders = a2.contract({
   name: 'orders',
   events: {
-    created: z.object({ items: z.array(z.string()) }),
-    'shop.notified': z.object({}),
-    cancelled: z.object({}),
+    'order.created': z.object({
+      shopId: z.string(),
+      items: z.array(z.string()),
+    }),
+    'shop.notified': z.object({ shopId: z.string() }),
+    'courier.assigned': z.object({ courierId: z.string() }),
+    'order.delivered': z.object({ signedBy: z.string() }),
+    'order.cancelled': z.object({ reason: z.string() }),
   },
   reducer: {
     name: 'order-status',
     initialState: { status: 'new' },
-    fold: (state, event) => ({ status: event.type === 'shop.notified' ? 'notified' : event.type }),
+    fold: (state, event) => ({ status: event.type }),
   },
 })
 ```
 
-## React to events
+## Implement the server
 
-Handlers are plain async functions. Each one reacts to a fact and usually
-returns the next one.
+Bind the contract to a store, a scheduler, and the handlers that react to its
+events.
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { redis } from 'experimental-a2/store-redis'
 import { orders } from '@/contracts'
 
 export const ordersServer = createServer({
   contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler: vercelQueues(),
   handlers: {
-    created: async ({ event }) => {
+    'order.created': async ({ event }) => {
       // your side effect; event.id makes a stable idempotency key:
       // await notifyShop(event.payload, { idempotencyKey: event.id })
-      return { type: 'shop.notified', payload: {} }
+      const { shopId } = event.payload
+      return { type: 'shop.notified', payload: { shopId } }
     },
   },
 })
 ```
 
-## Open a session
-
-A session is one instance of the contract, with its own ordered log. It is the
-thing A2 keeps durable and live. The id is yours:
-
-- `session('order-8194')`: an order moving through fulfillment
-- `session('chat-a8c1')`: an agent chat streaming its reply
-- `session('cart-julian')`: a shopping cart
-- `session('doc-roadmap')`: a document with three people typing in it
-
-Anything whose story spans more than one request. Put events in the same
-session when they form one history or view. Handlers are concurrent unless
-they share a lane. Any server code can open
-one and append: a route handler, a webhook, a cron job.
+One route serves every session to the browser:
 
 ```ts app/api/orders/route.ts
 import { ordersServer } from '@/server/orders'
 
-export async function POST(req: Request) {
-  const body = await req.json()
-  await ordersServer.session(body.orderId).append({
-    type: 'created',
-    payload: { items: body.items },
-  })
-  return Response.json({ ok: true })
-}
+export const GET = ordersServer.fetch
+export const POST = ordersServer.fetch
 ```
 
-A2 commits the event before its handler can start. The handler may begin before
-`append` returns; the return confirms durability, not handler completion.
-A queue-backed scheduler wakes pending work after a crash or timeout. The same
-scheduler lets a session append a typed event later with
-`session.schedule(name, { delay: '30s' }, event)`.
-
-## State is a fold
+## Implement the client
 
-There is no separate state record for the session to keep in sync. Fold its log
-through a reducer, a pure function derived from the contract. It imports
-nothing server-only, which is about to matter.
+The browser follows a session over SSE or a
+[WebSocket](/client/transports) and folds the same state. `push` applies
+instantly and rolls back if the server says no.
 
-```ts reducer.ts
+```tsx app/orders/[orderId]/order.tsx
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { useSession } from 'experimental-a2/react'
 import { orders } from '@/contracts'
 
-export const orderStatus = orders.reducer
-```
-
-```ts
-// anywhere on the server:
-import { ordersServer } from '@/server/orders'
-import { orders } from '@/contracts'
+const ordersClient = createClient({
+  contract: orders,
+  // SSE; for a WebSocket: { type: 'ws', url: '/api/orders' }
+  api: '/api/orders',
+})
 
-const { state } = await ordersServer.session(orderId).state()
-// state → { status: 'notified' }
+export function Order({ orderId }: { orderId: string }) {
+  const { state, push } = useSession(ordersClient, orderId)
+  return (
+    <button
+      onClick={() =>
+        void push({ type: 'order.cancelled', payload: { reason: 'customer' } })
+      }
+    >
+      {state.status} · cancel
+    </button>
+  )
+}
 ```
 
-## The browser joins the session
+## It's just an event log
 
-The reducer is isomorphic, so the browser runs the same fold the server
-does. A session streams to the client live and takes optimistic writes,
-all typed by the one contract:
-
-```ts app/orders/[orderId]/session.ts
-'use client'
-import { createReact } from 'experimental-a2/react'
-import { orders } from '@/contracts'
+```ts
+// anywhere on the server: a route, a webhook, a cron job
+import { ordersServer } from '@/server/orders'
 
-export const { SessionProvider, useSession } = createReact({
-  contract: orders,
+const order = ordersServer.session('order-8194')
+await order.append({
+  type: 'courier.assigned',
+  payload: { courierId: 'courier-7' },
 })
+const events = await order.history()
+// order.created, shop.notified, courier.assigned
 ```
 
-```tsx app/orders/[orderId]/order-client.tsx
-'use client'
-import { useSession } from './session'
+A session is the ordered list of what happened. State is a fold over it, on
+both sides of the wire. Everything else A2 keeps is a cache it can rebuild
+from the log.
 
-export function OrderStatus() {
-  const { state, connection, push } = useSession()
-  return (
-    <div>
-      {state.status}
-      {connection.status === 'live' ? ' · live' : ''}
-      <button onClick={() => void push({ type: 'cancelled', payload: {} })}>
-        Cancel order
-      </button>
-    </div>
-  )
-}
-```
+## With strong guarantees
+
+- Appends are effectively-once.
+- The log stays ordered.
+- Handlers are at-least-once.
+- Returned events commit with the handler's completion.
+- Handlers run concurrently, unless they share a lane.
+- Failures stay contained.
+- A failing handler never makes `append` throw.
 
-`push` applies instantly, validates against the contract before anything
-leaves the browser, and rolls back if the server says no. Mounting
-`SessionProvider` and the small stream route it talks to takes about
-twenty lines; [Live UI](/guides/react) wires it end to end.
+[Guarantees](/server/guarantees) has the details and the limits.
 
-## The properties
+## Go further...
 
-- **Handlers are plain async functions.** They run concurrently by default.
-  Use a lane for selective FIFO execution.
-- **Handlers are optional per event type.** A history-only event settles during
-  append and creates no reaction or scheduler work.
-- **History is real.** [`history()`](/concepts/state) returns what
-  actually happened, in order. Debugging is reading, not reconstructing.
-- **Nothing inside a session is sacred except its log.** Snapshots, claims, queue
-  messages: all disposable caches. Delete them and A2 rebuilds
-  everything from the log.
+<CardGroup cols={2}>
+  <Card title="Handlers" href="/server/handlers" icon="zap">
+    Retries, lanes, and idempotency.
+  </Card>
+  <Card title="State" href="/contract/state" icon="layers">
+    Reducers and the current view.
+  </Card>
+  <Card title="History" href="/contract/state#history" icon="history">
+    The raw log, oldest first.
+  </Card>
+  <Card title="AI" href="/agents/introduction" icon="bot">
+    Agents with tools and approvals.
+  </Card>
+  <Card title="Timers" href="/server/timers" icon="clock">
+    Schedule an event for later.
+  </Card>
+  <Card title="Production" href="/server/production" icon="rocket">
+    A store and a scheduler.
+  </Card>
+</CardGroup>
 
 ## FAQ
 
@@ -179,7 +171,7 @@ a durable event log. Events settle in their append transaction, with no drain,
 claim, or queue message. A contract can also mix handled and history-only event
 types. A2 decides per event type.
 
-See [Events without handlers](/concepts/handlers#events-without-handlers).
+See [Events without handlers](/server/handlers#events-without-handlers).
 
 </details>
 
@@ -189,7 +181,7 @@ See [Events without handlers](/concepts/handlers#events-without-handlers).
 Configure Vercel Queues or QStash, then call
 `session.schedule(name, { delay: '30s' }, event)` or use `{ at: Date }`. The
 same scheduler route handles recovery and the delayed append. Names and omitted
-event ids stay stable across retries. See [Timers](/guides/timers).
+event ids stay stable across retries. See [Timers](/server/timers).
 
 </details>
 
@@ -198,16 +190,17 @@ event ids stay stable across retries. See [Timers](/guides/timers).
 
 Cancellation is an event too: same route, same auth, same log. Handlers
 opt in with `abortOn` and receive a live `AbortSignal`; reducers cut the
-derived view exactly. See [Cancellation](/guides/cancellation).
+derived view exactly. See [Cancellation](/server/cancellation).
 
 </details>
 
 <details>
 <summary>What happens when a handler keeps failing?</summary>
 
-It retries with backoff, then dead-letters after ten caught failures. Later
-events in the same lane wait; unlaned events and other lanes continue.
-[Durability](/concepts/durability) has the exact guarantees and the
+It retries with backoff, then dead-letters after ten failed attempts, whether
+the handler threw or its process ended. Later events in the same lane wait
+until you retry or skip it; unlaned events and other lanes continue.
+[Guarantees](/server/guarantees) has the exact guarantees and the
 recovery story behind them.
 
 </details>
@@ -219,7 +212,7 @@ A durable store backend, such as Postgres or Redis. Add a queue-backed scheduler
 when the contract has handlers or calls `session.schedule`. A history-only
 contract with no timers needs no reaction infrastructure. Development needs
 neither: SQLite appears under `.a2/` and state survives restarts. See
-[Going to production](/guides/production).
+[Production](/server/production).
 
 </details>
 
@@ -235,10 +228,10 @@ does not replicate database tables or subscribe to queries across sessions.
 <details>
 <summary>Where does my application database fit?</summary>
 
-A2 does not replace it. Use A2 for things with a lifecycle. Keep collections,
+A2 does not replace it. Keep collections,
 relationships, constraints, search, and reporting in your application
 database. Split ownership instead of writing the same fact through both paths.
-See [A2 and your database](/guides/application-data).
+See [Sessions and your database](/contract/sessions#sessions-and-your-database).
 
 </details>
 
@@ -248,35 +241,6 @@ See [A2 and your database](/guides/application-data).
 Yes. Every installation includes a standalone Next.js playground at
 `node_modules/experimental-a2/examples/playground`. It contains complete
 contracts, reducers, servers, route handlers, clients, and schedulers using only
-public package entry points. See [Complete examples](/guides/examples).
+public package entry points. See [Complete examples](/examples).
 
 </details>
-
-## Where to next
-
-<CardGroup cols={2}>
-  <Card title="Quickstart" href="/quickstart" icon="rocket">
-    A contract, a handler, and a durable append in five minutes.
-  </Card>
-  <Card title="Contracts and sessions" href="/concepts/contracts" icon="folder">
-    The two nouns you'll use everywhere.
-  </Card>
-  <Card title="Durability" href="/concepts/durability" icon="wrench">
-    What A2 guarantees, and exactly how.
-  </Card>
-  <Card title="Live UI with React" href="/guides/react" icon="lightbulb">
-    Stream a session to the browser with optimistic writes.
-  </Card>
-  <Card title="Durable AI agents" href="/guides/ai-agents" icon="bot">
-    Run AI SDK agents with durable messages, progress, tools, and approvals.
-  </Card>
-  <Card title="A2 and your database" href="/guides/application-data" icon="database">
-    Decide what belongs in a session and what belongs in ordinary tables.
-  </Card>
-  <Card title="Actors" href="/actors/introduction" icon="boxes">
-    Durable objects on the log: typed state, one message at a time.
-  </Card>
-  <Card title="Complete examples" href="/guides/examples" icon="code">
-    Read or copy the standalone Next.js playground included with the package.
-  </Card>
-</CardGroup>

package/docs/reference/01-core.mdx

@@ -0,0 +1,139 @@
+---
+title: Core
+description: "Every entry point, and the isomorphic `experimental-a2` core: contracts, reducers, IDs, and the event shape."
+---
+
+## Entry points
+
+| Entry point | Ships | Peer dependency |
+| --- | --- | --- |
+| `experimental-a2` | `contract`, `A2Error`: isomorphic core | none |
+| `experimental-a2/server` | `createServer`: implement a contract | none |
+| `experimental-a2/client` | `createClient`: framework-agnostic session client | none |
+| `experimental-a2/react` | `createReact` | `react` |
+| `experimental-a2/ai` | `agentContract`, `handlerContext`, `inputs`, and the AI reducer: isomorphic | `ai` |
+| `experimental-a2/ai/server` | `agent`: an agent's loop as an A2 server | `ai` |
+| `experimental-a2/ai/fx` | `fx`: the FX harness for `agent()` | `ai`, `libfx` |
+| `experimental-a2/ai/pi` | `pi`: the Pi harness for `agent()` | `ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai` |
+| `experimental-a2/ai/client` | `createAgentClient`: contract-free agent client | `ai` |
+| `experimental-a2/ai/react` | `useAgent` | `ai`, `react` |
+| [`experimental-a2/store-postgres`](/reference/adapters#experimental-a2store-postgres) | `postgres`: Postgres store backend | `pg` (or inject a client) |
+| [`experimental-a2/store-redis`](/reference/adapters#experimental-a2store-redis) | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
+| [`experimental-a2/store-redis-http`](/reference/adapters#experimental-a2store-redis-http) | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |
+| `experimental-a2/store-sqlite` | SQLite store backend | none |
+| `experimental-a2/store-memory` | in-memory store backend | none |
+| `experimental-a2/scheduler-vercel` | `vercelQueues`: recovery and timers | `@vercel/queue` |
+| `experimental-a2/scheduler-qstash` | `qstash`: signed recovery and timers | `@upstash/qstash` |
+| `experimental-a2/cache-indexeddb` | `indexedDb` browser cache | none |
+| `experimental-a2/otel` | `otel` telemetry adapter | `@opentelemetry/api` |
+
+`experimental-a2` imports none of the backends, and a browser-bundle test in CI
+enforces it. Importing a backend's entry point, such as
+`experimental-a2/store-postgres`, is what pulls that backend in; core never puts
+one in your client bundle.
+
+## `experimental-a2`
+
+### `a2.contract(options)`
+
+```ts
+a2.contract(options: {
+  name: string
+  events: Record<string, StandardSchemaV1>
+  presence?: Record<string, StandardSchemaV1>
+  reducer?: { name: string; initialState: S; stateSchema?: StandardSchemaV1; fold: (state: S, event: Event) => S }
+}): Contract
+```
+
+Defines one kind of lifecycle. The result is a plain, importable,
+**isomorphic** value: the server implements it, reducers derive from it, and
+the browser types its pushes off it. See [Events](/contract/events).
+
+| Option | Meaning |
+| --- | --- |
+| `name` | Unique per app; identifies the contract in storage and queue messages. May not contain the control character U+001F. |
+| `events` | Event type to payload schema. Types may not start with `a2.`, which A2 reserves for its own events, such as `a2.cleared`. |
+| `presence` | Optional. Field to schema for one participant's ephemeral state. Replicated last-writer-wins, never stored in the log, invisible to reducers. See [Presence](/client/presence). |
+| `reducer` | Optional. The one reducer the contract publishes to clients; an inline definition includes `fold`. See [`reducer(options)`](#reduceroptions). |
+
+Schemas are [Standard Schema](https://standardschema.dev): Zod, Valibot,
+ArkType, anything that implements it. Validators must be synchronous; async
+ones are rejected at definition time. The validated output is what's stored.
+
+### `contract.batch(...events)`
+
+Returns the same events as a readonly tuple, preserving each literal type in a
+heterogeneous handler-returned array. A2 validates them when the handler
+completes. See [Handlers](/server/handlers#return-what-happens-after-success).
+
+### `reducer(options)`
+
+```ts
+reducer(options: {
+  contract: Contract
+  name: string                // identity; keys cached snapshots
+  initialState: S             // the seed (schema input, when stateSchema is set)
+  stateSchema?: StandardSchemaV1 // declares S, checks initialState, guards cached folds
+}): { fold(fn: (state: S, event: Event) => S): Reducer<S> }
+```
+
+Builds a standalone reducer for server reads or for the contract's `reducer`
+field. See [State](/contract/state#reducers).
+
+- The first call fixes the state and event types, so `.fold()` receives
+  concrete ones. Literal unions in your state survive with zero annotations.
+- `name` keys cached snapshots, so two reducers never fight over a cache
+  entry. Rename it when the fold's logic changes: a rename (or a `stateSchema`
+  mismatch, when present) invalidates, and the next read refolds from raw
+  events.
+
+### `A2Error`
+
+The shared base for A2 failures, discriminated by `code`. The session client
+exposes its `A2ClientError` subclass. See [Errors](/reference/errors).
+
+### `idempotentId(...parts)`
+
+`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
+from an ordered tuple of strings. It performs no I/O and runs on the server and
+in the browser.
+
+```ts shared/request-id.ts
+import { idempotentId } from 'experimental-a2'
+
+export const id = await idempotentId('orders', 'shop-7', 'request-42')
+```
+
+- Pass the result as an event's `id` when retries should converge on the same
+  event.
+- The same tuple produces the same ID across runtimes and A2 versions.
+- String boundaries, order, and case matter; strings are not normalized. Empty
+  strings and an empty tuple are valid.
+- Every argument has the same role; a prefix such as `'orders'` is a namespace
+  by convention. Include enough context to distinguish operations across
+  contracts and sessions: event IDs are globally unique within a store.
+- A2 preserves explicit IDs and does not change its automatic ID generation.
+  Changing an existing recipe changes retry identity, so retries of already
+  committed requests must keep their original IDs.
+
+### `SessionCleared`
+
+An `Event` whose `type` is `'a2.cleared'` and whose `payload` is `null`: the
+marker a [clear](/reference/server#sessionclearoptions) leaves in
+`session.stream()`. It never reaches handlers or `history()`. Comparing
+`event.type` with that string narrows a stream item to `SessionCleared`. The
+session client handles the marker itself, so it matters only when you read the
+server stream yourself.
+
+## Event
+
+```ts
+type Event = {
+  id: string
+  type: string
+  payload: unknown // typed by the contract's schema for `type`
+  index: number // position in the session's log, from 1
+  sessionId: string
+  createdAt: Date
+}
+```