experimental-a2 0.8.0 → 0.9.0

package/docs/actors/04-routes.mdx

@@ -0,0 +1,352 @@
+---
+title: Routes, clients, and React
+description: "One route serves an instance: GET streams live state, POST answers calls. Authorize per operation, project per mount, and mount it in React with one hook."
+---
+
+## The actor for this page
+
+A vault with one internal field, so the projection section below has
+something to hide:
+
+```ts vault.ts
+import { NonRetriableError } from 'experimental-a2'
+import { actor } from 'experimental-a2/actor'
+
+interface Vault {
+  state: {
+    balance: number
+    /** Internal bookkeeping; not for subscribers. */
+    audit: string[]
+  }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+  }
+}
+
+export type VaultState = Vault['state']
+
+export const vault = actor<Vault>({
+  name: 'vault',
+  state: { balance: 0, audit: [] },
+  handlers: {
+    deposit: (ctx, input) => {
+      ctx.state.balance += input.amount
+      ctx.state.audit.push(`deposit ${input.amount}`)
+    },
+    withdraw: (ctx, input) => {
+      if (ctx.state.balance < input.amount) {
+        throw new NonRetriableError('insufficient funds')
+      }
+      ctx.state.balance -= input.amount
+      ctx.state.audit.push(`withdraw ${input.amount}`)
+    },
+  },
+})
+```
+
+## The route
+
+`handle.fetch` serves one instance over HTTP. Your route authenticates
+and picks the instance; the library serves the rest.
+
+```ts app/vault/[vaultId]/route.ts
+import { vault } from '@/vault'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd do auth, or any other checks
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond
+```
+
+`GET` is the live stream: a server-sent events response of the
+instance's state commits, resumed after the `index` query parameter,
+with heartbeats. The stream carries state and nothing else: subscribers
+see what the actor is, never other callers' inputs, and a refusal
+answers only its caller. The full mailbox stays server-side.
+
+`POST` is the call lane. The body names a declared event:
+
+```json
+{ "event": "deposit", "input": { "amount": 100 }, "messageId": "m-1" }
+```
+
+The response is the answer: `{ state, index }` on success, `409` with
+the refusal's message when the handler says no, `400` for an undeclared
+event. `messageId` is optional; send one to make retrying the request
+idempotent.
+
+## Authorize
+
+`authorize` is per-operation policy, checked before any write or
+subscription. Authentication (who is asking) stays in your route;
+`authorize` decides whether this operation is allowed.
+
+```ts
+// app/vault/[vaultId]/route.ts, now with per-operation policy:
+import { vault } from '@/vault'
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    authorize: (operation) =>
+      operation.type === 'call' && operation.event !== 'withdraw',
+  })
+}
+```
+
+The operation is a discriminated union: `{ type: 'stream', id,
+startAfter }` for subscriptions, `{ type: 'call', id, event, input,
+messageId? }` for calls. Returning `false` answers `403`.
+
+## Views: what each mount shows
+
+State can be mixed-audience: internal bookkeeping next to public
+fields. The definition stays audience-blind; audiences are a route
+concern, like auth. A `view` is a request-time projection applied to
+everything that mount serves: every state frame on the stream and
+every call answer (the two must agree, or the call lane would leak
+what the stream hides).
+
+```ts
+// app/vault/[vaultId]/public/route.ts, a projected mount of the same actor:
+import { vault } from '@/vault'
+
+export async function GET(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    view: (state) => ({ balance: state.balance }),
+  })
+}
+```
+
+Different routes project the same actor differently: an admin mount
+with no view sees everything, the public mount above hides `audit`.
+Per-viewer views need no extra machinery, because the route already
+holds the identity; a closure does it
+(`view: (state) => ({ ...visible, mine: state.perUser[user.id] })`).
+View output holds to the same plain-JSON floor as state itself.
+
+Views are for internal-but-not-secret fields. Secrets do not belong in
+state at all: state commits are log rows, and the log is forever. Keep
+secrets outside, pass references, resolve them inside handlers.
+
+## Any client
+
+`createActorClient` is the typed call surface over that route's `POST`
+lane. It works anywhere: browsers, other frameworks, other servers.
+
+```ts
+// in the browser, or any client at all:
+import {
+  ActorRefusedError,
+  createActorClient,
+} from 'experimental-a2/actor/client'
+import type { vault } from '@/vault'
+
+const savings = createActorClient<typeof vault>({ api: '/vault/savings' })
+
+try {
+  const { state } = await savings.call.deposit({ amount: 100 })
+  // state is the answer: the fold after this deposit
+} catch (error) {
+  if (error instanceof ActorRefusedError) {
+    // the server's refusal, revived with its message
+  }
+}
+```
+
+The import of `vault` is type-only, so it is erased at build time: the
+server module never enters a client bundle. On a view-projected mount,
+pass the projected shape as the second type argument
+(`createActorClient<typeof vault, PublicVault>`) so answers carry it.
+
+## React
+
+One hook. The server component hands down the first fold, the hook
+keeps it live and exposes the same typed calls.
+
+```tsx app/vault/[vaultId]/page.tsx
+import { vault } from '@/vault'
+import { VaultClient } from './vault-client'
+
+export default async function VaultPage({
+  params,
+}: {
+  params: Promise<{ vaultId: string }>
+}) {
+  const { vaultId } = await params
+  const initial = await vault.actor(vaultId).state()
+  return <VaultClient vaultId={vaultId} initial={initial} />
+}
+```
+
+```tsx app/vault/[vaultId]/vault-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { vault, VaultState } from '@/vault'
+
+export function VaultClient({
+  vaultId,
+  initial,
+}: {
+  vaultId: string
+  initial: ActorSnapshot<VaultState>
+}) {
+  const { state, call, connection } = useActor<typeof vault>({
+    api: `/vault/${vaultId}`,
+    id: vaultId,
+    initial,
+  })
+
+  return (
+    <div>
+      <p>
+        Balance: {state.balance}
+        {connection.status === 'live' ? '' : ' (reconnecting)'}
+      </p>
+      <button onClick={() => void call.deposit({ amount: 25 })}>
+        Deposit $25
+      </button>
+    </div>
+  )
+}
+```
+
+What the hook gives you:
+
+- **`state`**: the live view. Every commit streams in and replaces it;
+  the fold is library code, so no reducers, schemas, or contracts
+  appear in browser code.
+- **`call`**: the same typed surface as `createActorClient`, because it
+  is one; `useActor` is a thin React wrapper over the client primitive
+  and the stream.
+- **`index`**: the stream frontier, and **`events`**: the state-commit
+  feed this browser has observed, for activity-feed UI.
+- **`connection`**: the same discriminated union as
+  [`useSession`](/guides/react#the-client-component), heartbeat
+  watchdog included.
+
+Live, not optimistic. Handlers are server code deciding against
+serialized fresh state, so there is nothing correct for the browser to
+apply early; a local guess would be wrong exactly when the actor
+matters. If a control needs pending UI, `await call.deposit(...)` is a
+promise like any other.
+
+On a view-projected mount, pass the projected shape as the second type
+argument (`useActor<typeof vault, PublicVault>`); `initial`, `state`,
+and the call answers all carry it.
+
+## Presence
+
+Who is here, live: cursors, names, viewer counts. Presence is
+ephemeral audience state. It replicates to the instance's subscribers
+and expires; it never enters the log, and handlers cannot see it (an
+actor decides from its log, never from who is watching).
+
+Declare the vocabulary in the protocol as types, and arm the wire with
+`presence: true`:
+
+```ts board.ts
+import { actor } from 'experimental-a2/actor'
+
+interface Board {
+  state: { strokes: number }
+  events: { draw: { path: string } }
+  presence: { cursor: { x: number; y: number }; name: string }
+}
+
+export const board = actor<Board>({
+  name: 'board',
+  state: { strokes: 0 },
+  presence: true,
+  handlers: {
+    draw: (ctx) => {
+      ctx.state.strokes += 1
+    },
+  },
+})
+```
+
+The route does not change: the same `GET` stream interleaves presence
+updates between state commits, and the same `POST` lane accepts
+presence announcements. In React, pass a `participant` identity and
+use the map:
+
+```tsx app/board/[boardId]/board-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { board } from '@/board'
+
+export function BoardClient({
+  boardId,
+  initial,
+  user,
+}: {
+  boardId: string
+  initial: ActorSnapshot<{ strokes: number }>
+  user: string
+}) {
+  const { presence, setPresence } = useActor<typeof board>({
+    api: `/board/${boardId}`,
+    id: boardId,
+    initial,
+    participant: user,
+  })
+
+  return (
+    <div
+      onPointerMove={(event) =>
+        setPresence({ cursor: { x: event.clientX, y: event.clientY } })
+      }
+    >
+      {Object.keys(presence).length} here
+    </div>
+  )
+}
+```
+
+`setPresence` is fire-and-forget: throttled on the way out, resent
+after a reconnect, `null` clears a field. The map holds each
+participant's latest fields with their stamps; how long a value stays
+painted is render logic, decided against `at`.
+
+Three guards stand where presence enters, and none of them is a
+schema:
+
+- **Types**: the protocol types `setPresence` and the map, so honest
+  clients cannot send the wrong shape.
+- **The floor**: the library rejects values that are not plain JSON
+  trees, values over 8 KB, and object-plumbing field names.
+- **`authorize`**: every announcement arrives as
+  `{ type: 'presence', id, participant, values }` before it is
+  accepted. Clamp, verify the participant matches the authenticated
+  user, or rate-limit here.
+
+What no guard does is make peer values trustworthy. Presence is
+authored by whoever holds a connection: render it like user input.
+
+## The session wire underneath
+
+`handle.fetch` serves the actor's two lanes and nothing else. When you
+want the raw session protocol instead (the full event feed, pushes,
+presence, the `ws` transport), the definition exposes the underlying
+server: mount `def.server.fetch` and use the core
+[client](/guides/react) against it. That wire shows the whole mailbox
+to its subscribers, inputs included, so reserve it for trusted
+audiences.

package/docs/actors/meta.ts

@@ -0,0 +1 @@
+export default { order: 4 }

package/docs/concepts/meta.ts

@@ -0,0 +1 @@
+export default { order: 2 }

package/docs/guides/07-examples.mdx

@@ -0,0 +1,56 @@
+---
+title: Complete examples
+description: Read or copy the complete Next.js playground that ships inside the experimental-a2 package.
+---
+
+## Shipped with the package
+
+Every `experimental-a2` installation includes a complete Next.js playground at
+`node_modules/experimental-a2/examples/playground`.
+
+The playground is not a collection of isolated snippets. Each feature owns its
+contract, reducer, server, route handlers, client session, and scheduler when it
+needs one. It uses only public package entry points.
+
+Copy it into a new directory to run or modify it:
+
+```sh
+cp -R node_modules/experimental-a2/examples/playground ./a2-playground
+cd a2-playground
+pnpm install
+pnpm dev
+```
+
+The copied `package.json` is standalone. Its A2 dependency is pinned to the
+version that supplied the example.
+
+The snapshot also includes an `AGENTS.md` file. Coding agents that support
+repository instructions discover the example's structure as soon as they work
+inside the copied directory.
+
+## Find the right example
+
+- `app/counter` is the smallest complete contract, reducer, server, and React
+  client.
+- `app/orders` adds handlers and a feature-owned scheduler.
+- `app/chat` shows request-scoped authorization and durable AI generation.
+- `app/agent` shows tools, approvals, reminders, and sandboxed commands.
+- `app/canvas` adds optimistic state, presence, and WebSocket upgrades.
+- `app/documents` combines A2 events with a collaborative document protocol.
+- `app/recovery` demonstrates queue recovery across function invocations.
+
+## Guidance for coding agents
+
+When A2 is installed locally, read these package directories in this order:
+
+1. `node_modules/experimental-a2/docs` for the supported API and guarantees.
+2. `node_modules/experimental-a2/examples/playground` for complete application
+   structure.
+3. `node_modules/experimental-a2/src` only when implementation details are
+   relevant.
+
+Do not infer application patterns from `dist`. The playground is the reference
+for how the public pieces fit together in a real Next.js application.
+
+The npm snapshot is generated from `apps/playground` in the A2 repository when
+the package is published, so the runnable app remains the canonical source.

package/docs/guides/meta.ts

@@ -0,0 +1 @@
+export default { order: 3 }

package/docs/index.mdx

@@ -250,6 +250,16 @@ See [A2 and your database](/guides/application-data).
 
 </details>
 
+<details>
+<summary>Does the package include complete examples?</summary>
+
+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).
+
+</details>
+
 ## Where to next
 
 <CardGroup cols={2}>
@@ -271,4 +281,10 @@ See [A2 and your database](/guides/application-data).
   <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/02-errors.mdx

@@ -58,6 +58,39 @@ contains the same id twice, and an id that was already used in a
 *different* session (event ids are globally unique). In every case,
 nothing is written.
 
+## NonRetriableError
+
+The second exported error class. Throw it (or a subclass, matched by
+`instanceof`) from a handler when the failure is deterministic: the
+event dead-letters immediately instead of consuming the ten-failure
+retry budget, because a guard that refuses this attempt will refuse
+every retry identically. 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
+    },
+  },
+})
+```
+
 ## What append never throws for
 
 - **A failing handler.** Appends always land; handler failures are retried

package/docs/reference/meta.ts

@@ -0,0 +1 @@
+export default { order: 5 }

package/examples/README.md

@@ -0,0 +1,15 @@
+# A2 examples
+
+The complete Next.js playground is included at `examples/playground` in the
+published `experimental-a2` package. It uses only public package entry points
+and can be copied into a new directory as a standalone application.
+
+For coding agents, inspect these paths before inventing an integration:
+
+- `docs/` defines the supported API.
+- `examples/playground/` shows complete applications using that API.
+- `src/` is the library implementation, not the recommended application
+  structure.
+
+The playground snapshot is generated from the repository's `apps/playground`
+directory when the package is packed.

package/examples/playground/AGENTS.md

@@ -0,0 +1,11 @@
+# A2 playground
+
+This is a standalone reference application for `experimental-a2`.
+
+- Read `node_modules/experimental-a2/docs` for the supported API.
+- Treat each directory under `app/` as a self-contained feature.
+- Keep its contract and reducer in `model.ts`.
+- Keep handlers and scheduler configuration in `server.ts`.
+- Expose A2 through the feature's `events/route.ts` using `server.fetch`.
+- Add a feature-owned `scheduler/route.ts` only when handlers or timers need it.
+- Use only public `experimental-a2` package entry points.

package/examples/playground/DEPLOY.md

@@ -0,0 +1,106 @@
+# Deploying the playground
+
+The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
+no scheduler). The Agent demo also needs AI Gateway and Vercel Sandbox
+credentials. Production needs the deliberate pieces from
+`node_modules/experimental-a2/docs/guides/05-production.mdx`.
+
+## 1. A store
+
+Two options — set one of:
+
+```
+REDIS_URL=rediss://…      # push-native streams (Upstash; recommended here)
+DATABASE_URL=postgres://… # any Postgres (Neon, Supabase, RDS)
+```
+
+`lib/store.ts` prefers Redis when both are set — the chat, document,
+and canvas demos are stream-latency-sensitive, and the Redis backend
+delivers to parked subscribers in single-digit milliseconds (Postgres
+streams poll adaptively, 25–250ms). The canvas demo's presence plane
+(cursors, drag ghosts) also rides the backend's delivery tier: push on
+Redis, poll cadence elsewhere. Upstash is durable by default; use its TCP
+`rediss://` URL, not the REST one. Each feature creates its own server with
+the shared store; storage remains namespaced per contract. Without either variable, a
+production boot fails fast with `STORE_NOT_CONFIGURED` (by design).
+Schemas/keys are created lazily on first use; no migration step.
+
+To verify a provider before leaning on it, run the full conformance
+kit against it (throwaway database; the suite isolates by key prefix
+and sweeps after itself):
+
+```sh
+TEST_REDIS_URL=rediss://… pnpm --filter a2 exec vitest run test/store-redis.conformance.test.ts
+```
+
+`pg` and `ioredis` are optional peer dependencies of `experimental-a2` and direct
+dependencies of this app.
+
+## 2. Vercel Queues scheduler
+
+Queues need no configuration beyond the triggers in `vercel.json`. Orders,
+Chat, Agent, and Recovery each own a scheduler route and queue topic alongside
+their contract and server. Each topic is created on first send, and its trigger
+makes the scheduler route private (no public URL). Schedulers turn on
+automatically when `VERCEL` is set (every deployment).
+
+To exercise the scheduler locally against a linked project:
+
+```sh
+vercel link
+vercel env pull   # OIDC credentials for the @vercel/queue SDK
+A2_QUEUES=1 pnpm dev
+```
+
+## 3. AI Gateway
+
+The Agent demo uses the AI SDK with `openai/gpt-5.6-luna`, while the Chat demo
+uses `openai/gpt-5.4`. Both resolve through Vercel AI Gateway. Vercel
+deployments use their OIDC token automatically. For local generation, link the
+project and pull its environment or set an `AI_GATEWAY_API_KEY`:
+
+```sh
+vercel link
+vercel env pull
+```
+
+New Chat rooms invoke the model only for `@agent` mentions. Participants can
+enable ambient mode for the room to invoke it for every subsequent message.
+
+The Counter, Orders, Canvas, and Documents demos do not call a model.
+
+## 4. Vercel Sandbox
+
+The Agent demo's Bash tool executes commands in a named, persistent Vercel
+Sandbox. Every A2 agent session gets its own sandbox, so files remain available
+to later Bash calls in that conversation. Vercel deployments authenticate with
+OIDC automatically; the `vercel link` and `vercel env pull` commands above
+supply the same credentials during local development.
+
+## 5. WebSockets for the canvas
+
+Deployed, the canvas demo upgrades its route to a WebSocket
+(`experimental_upgradeWebSocket` from `@vercel/functions`, with `ws`
+as the server-side socket — both direct dependencies of this app).
+Vercel WebSockets need Fluid compute, which is the default on new
+projects. Under `next dev` the upgrade never reaches the route (the
+dev server drops the handshake), so the demo's session module picks
+the SSE + POST pair in development — same route, same protocol
+semantics, different wire.
+
+## 6. Deploy
+
+```sh
+vercel deploy
+```
+
+The Recovery lab tests a real function timeout. Its dedicated trigger and
+queue consumer both export `maxDuration = 20`. The pipeline has four 8-second
+handlers, so every handler fits in a fresh invocation but the 32-second chain
+does not. A2 keeps dispatching events. Vercel stops the first invocation while
+the third handler is running, leaving that event without a processed marker.
+The deadline-capped claim expires, its watchdog retries the same event in a
+fresh function, and already completed events do not run again. The dedicated
+`a2-recovery` topic keeps this artificial budget away from the
+playground's other recovery workloads. This example is disabled under
+`next dev`, which supplies neither a Vercel deadline nor queue delivery.

package/examples/playground/README.md

@@ -0,0 +1,19 @@
+# A2 playground
+
+This is a standalone snapshot of the A2 playground included with the
+`experimental-a2` npm package. It uses only public package entry points.
+
+## Run it
+
+```sh
+pnpm install
+pnpm dev
+```
+
+Each directory under `app/` owns its contract, reducer, server, routes, and
+scheduler when one is needed. Start with `app/counter` for the smallest
+example, then read `app/orders`, `app/chat`, or `app/agent` for complete
+handler-driven applications.
+
+The canonical source lives in `apps/playground` in the A2 repository. This
+copy is generated from it when the package is published.

package/examples/playground/activity-feed.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest'
+import { formatActivityTime } from './app/components/activity-feed'
+
+describe('activity feed', () => {
+  it('formats event times identically on the server and client', () => {
+    expect(formatActivityTime(new Date('2026-08-18T01:16:09.123Z'))).toBe(
+      '01:16:09 UTC',
+    )
+  })
+})