experimental-a2 0.20.0 → 0.22.0

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">
@@ -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,7 +214,7 @@ 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
 [Stores](/stores/overview) and [Schedulers](/schedulers/overview).

package/docs/reference/01-core.mdx

@@ -11,7 +11,7 @@ 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` |
@@ -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)`
 
@@ -110,8 +110,9 @@ export const id = await idempotentId('orders', 'shop-7', 'request-42')
 - 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.
+  by convention. Include enough context to distinguish operations within a
+  session: event IDs are unique per session, so the same ID in another session
+  names a different event.
 - 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.
@@ -120,7 +121,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.