experimental-a2 0.19.0 → 0.21.1

package/docs/index.mdx

@@ -42,8 +42,8 @@ export const orders = a2.contract({
 
 ## Implement the server
 
-Bind the contract to a store, a scheduler, and the handlers that react to its
-events.
+Bind the contract to a store, a scheduler, and the consumers that react to
+its events.
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
@@ -55,14 +55,18 @@ export const ordersServer = createServer({
   contract: orders,
   store: redis({ url: process.env.REDIS_URL }),
   scheduler: vercelQueues(),
-  handlers: {
-    'order.created': async ({ event }) => {
-      // your side effect; event.id makes a stable idempotency key:
-      // await notifyShop(event.payload, { idempotencyKey: event.id })
-      const { shopId } = event.payload
-      return { type: 'shop.notified', payload: { shopId } }
+  consumers: [
+    {
+      name: 'notify-shop',
+      types: ['order.created'],
+      run: async ({ event }) => {
+        // your side effect; event.id makes a stable idempotency key:
+        // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
+        const { shopId } = event.payload
+        return { type: 'shop.notified', payload: { shopId } }
+      },
     },
-  },
+  ],
 })
 ```
 
@@ -130,18 +134,18 @@ from the log.
 
 - 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.
+- Consumers are at-least-once.
+- Returned events commit with the consumer's completion.
+- Consumers run concurrently, unless they share a lane.
 - Failures stay contained.
-- A failing handler never makes `append` throw.
+- A failing consumer never makes `append` throw.
 
 [Guarantees](/server/guarantees) has the details and the limits.
 
 ## Go further...
 
 <CardGroup cols={2}>
-  <Card title="Handlers" href="/server/handlers" icon="zap">
+  <Card title="Consumers" href="/server/consumers" icon="zap">
     Retries, lanes, and idempotency.
   </Card>
   <Card title="State" href="/contract/state" icon="layers">
@@ -156,7 +160,7 @@ from the log.
   <Card title="Timers" href="/server/timers" icon="clock">
     Schedule an event for later.
   </Card>
-  <Card title="Production" href="/server/production" icon="rocket">
+  <Card title="Production" href="/stores/overview" icon="rocket">
     A store and a scheduler.
   </Card>
 </CardGroup>
@@ -164,14 +168,14 @@ from the log.
 ## FAQ
 
 <details>
-<summary>Can I use A2 without handlers?</summary>
+<summary>Can I use A2 without consumers?</summary>
 
-Yes. Omit `handlers` and use `append`, `history`, reducers, and live streams as
+Yes. Omit `consumers` and use `append`, `history`, reducers, and live streams as
 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.
+claim, or queue message. A contract can also mix consumed and history-only
+event types. A2 decides per event type.
 
-See [Events without handlers](/server/handlers#events-without-handlers).
+See [Servers without consumers](/server/consumers#servers-without-consumers).
 
 </details>
 
@@ -188,18 +192,19 @@ event ids stay stable across retries. See [Timers](/server/timers).
 <details>
 <summary>How do I cancel work that's already running?</summary>
 
-Cancellation is an event too: same route, same auth, same log. Handlers
+Cancellation is an event too: same route, same auth, same log. Consumers
 opt in with `abortOn` and receive a live `AbortSignal`; reducers cut the
 derived view exactly. See [Cancellation](/server/cancellation).
 
 </details>
 
 <details>
-<summary>What happens when a handler keeps failing?</summary>
+<summary>What happens when a consumer keeps failing?</summary>
 
 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.
+the consumer threw or its process ended. Later events in the same lane wait
+until you retry or skip it; unlaned events, other lanes, and other consumers
+continue.
 [Guarantees](/server/guarantees) has the exact guarantees and the
 recovery story behind them.
 
@@ -209,10 +214,10 @@ recovery story behind them.
 <summary>What does production need?</summary>
 
 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
+when the server has consumers 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
-[Production](/server/production).
+[Stores](/stores/overview) and [Schedulers](/schedulers/overview).
 
 </details>
 

package/docs/reference/01-core.mdx

@@ -11,21 +11,21 @@ description: "Every entry point, and the isomorphic `experimental-a2` core: cont
 | `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` | `agentContract`, `consumerContext`, `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/store-postgres`](/stores/postgres) | `postgres`: Postgres store backend | `pg` (or inject a client) |
+| [`experimental-a2/store-redis`](/stores/redis) | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
+| [`experimental-a2/store-redis-http`](/stores/redis-http) | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |
+| [`experimental-a2/store-sqlite`](/stores/sqlite) | SQLite store backend | none |
+| [`experimental-a2/store-memory`](/stores/memory) | in-memory store backend | none |
+| [`experimental-a2/scheduler-vercel`](/schedulers/vercel-queues) | `vercelQueues`: recovery and timers | `@vercel/queue` |
+| [`experimental-a2/scheduler-qstash`](/schedulers/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/otel`](/reference/telemetry) | `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
@@ -63,8 +63,8 @@ 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).
+heterogeneous array a consumer returns. A2 validates them when the consumer
+completes. See [Consumers](/server/consumers#return-what-happens-after-success).
 
 ### `reducer(options)`
 
@@ -120,7 +120,7 @@ export const id = await idempotentId('orders', 'shop-7', 'request-42')
 
 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
+`session.stream()`. It never reaches consumers 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.