experimental-a2 0.20.0 → 0.21.1

package/docs/actors/02-concurrency.mdx

@@ -5,7 +5,7 @@ description: "Each instance processes one message at a time. Slow work goes in c
 
 ## One message at a time
 
-Every message runs on the instance's [lane](/server/handlers#lanes):
+Every message runs on the instance's [lane](/server/consumers#lanes):
 one handler at a time, in arrival order. A handler sees the state every
 previous message produced, no other message can race its checks, and
 its changes commit before the next message runs.

package/docs/agents/01-introduction.mdx

@@ -22,7 +22,7 @@ export const assistant = agent({
 ```
 
 `agent()` is the whole server: the AI protocol, the agent's loop, and A2's
-store, scheduler, and handlers. `name` is its identity. The loop is the
+store, scheduler, and consumers. `name` is its identity. The loop is the
 agent's `harness`. By default it's `{ type: 'ai-sdk' }`: each response runs as
 durable one-step `streamText()` generations, tuned with `harness.generation`
 and `maxSteps`, listed under [`agent()`](/reference/ai#agentoptions). The same

package/docs/agents/02-tools.mdx

@@ -42,11 +42,11 @@ Approval policy lives in `harness.generation.toolApproval`, beside the other
 per-step settings. Later examples that import `assistant` use the agent from
 [Agents](/agents/introduction#define-the-agent).
 
-### Read the handler context
+### Read the tool's context
 
 ```ts server/set-reminder.ts
 import { tool } from 'ai'
-import { handlerContext, inputs } from 'experimental-a2/ai'
+import { consumerContext, inputs } from 'experimental-a2/ai'
 import { z } from 'zod'
 
 export const setReminder = tool({
@@ -56,7 +56,7 @@ export const setReminder = tool({
     reminder: z.string(),
   }),
   execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
-    const ctx = handlerContext()
+    const ctx = consumerContext()
     await ctx.session.schedule(
       `reminder:${toolCallId}`,
       { delay: `${delaySeconds}s` },
@@ -72,11 +72,12 @@ export const setReminder = tool({
 })
 ```
 
-`handlerContext()` returns the running tool's durable handler context: `event`,
-`attempt`, `session`, and `signal`. It works anywhere below `execute`, including
+`consumerContext()` returns the running tool's
+[consumer context](/server/consumers#the-context): `event`, `attempt`,
+`session`, and `signal`. It works anywhere below `execute`, including
 awaited helpers, and throws outside a tool execution. Pass a shared
 `agentContract()` to type application events; A2 checks it against the
-executing agent. See [`handlerContext()`](/reference/ai#handlercontextcontract)
+executing agent. See [`consumerContext()`](/reference/ai#consumercontextcontract)
 for the event payload.
 
 This tool schedules a reminder as a new user message. `ctx.session` belongs to
@@ -86,12 +87,12 @@ Naming the timer after `toolCallId` and the message after the triggering
 event's ID makes a retry converge on the same timer and message, even if a
 provider reuses tool-call IDs. The six-day maximum is Vercel Queues'
 [delay limit](/server/timers#provider-limits); adjust it for your scheduler. A
-transient or ambiguous scheduler failure retries the handler with the same
+transient or ambiguous scheduler failure retries the tool's run with the same
 identity and target time; a deterministic rejection or a missing scheduler is
 an ordinary tool error.
 
-To test a context-reading tool, call it inside `runWithHandlerContext(ctx, fn)`
-from `experimental-a2/ai/server`; within `fn`, `handlerContext()` returns `ctx`.
+To test a context-reading tool, call it inside `runWithConsumerContext(ctx, fn)`
+from `experimental-a2/ai/server`; within `fn`, `consumerContext()` returns `ctx`.
 
 ### Answer approvals
 
@@ -125,8 +126,8 @@ request as `ai.approval.requested`, and the reducer adds it to
 `state.pendingApprovals`. `approve()` and `deny()` copy
 the request, message, generation, and approval IDs from it, so a delayed click
 cannot authorize a later model step. The decision updates the approval part in
-the message, and a built-in handler then runs the approved tool or records the
-denied result.
+the message, and A2 then runs the approved tool or records the denied
+result.
 
 A policy can also be a function that returns `'user-approval'` or
 `'approved'` from the validated input. It runs during the model step and again

package/docs/agents/03-conversations.mdx

@@ -50,12 +50,12 @@ Provider-executed tools, structured output, and forced tool choices skip
 automatic compaction, and configuring it for them throws; use custom callbacks.
 
 The first generation with each Gateway model in a session records
-`ai.model.metadata.requested`; a separate handler fetches the catalog and
-records `ai.model.metadata.resolved`, without delaying or failing the
-generation. `state.modelMetadata` holds each model's limits and status:
+`ai.model.metadata.requested`; A2's `a2.ai.metadata` consumer fetches the
+catalog and records `ai.model.metadata.resolved`, without delaying or failing
+the generation. `state.modelMetadata` holds each model's limits and status:
 pending, resolved, or unavailable (absent from the catalog). A lookup that
-exhausted its retries stays pending without a new lookup each turn, so inspect
-that handler's failure or set a threshold. The estimate is serialized UTF-8
+exhausted its retries stays pending without a new lookup each turn, so check
+the session's dead letters for `a2.ai.metadata` or set a threshold. The estimate is serialized UTF-8
 bytes divided by four, calibrated by the previous same-model call's usage. It is
 not a tokenizer, makes no remote calls, and does not precisely measure new image
 or audio tokens.
@@ -191,11 +191,13 @@ transcript. The session's state is `AIState` merged with yours, so a key that
 shadows one of `AIState`'s is a type error. The reducer's `name` is its snapshot
 identity: rename it when `fold` changes.
 
-Serve it with `agent({ contract })`. Every resolver receives your state as
+Serve it with `agent({ contract })`, and react to your own events with
+`consumers`, next to the agent's. Every resolver receives your state as
 `state`:
 
 ```ts server/support-desk.ts
 import { agent } from 'experimental-a2/ai/server'
+import { consumer } from 'experimental-a2/server'
 import { supportDesk } from '../support-desk'
 
 export const supportDeskAgent = agent({
@@ -204,12 +206,16 @@ export const supportDeskAgent = agent({
     state.plan === 'pro'
       ? { model: 'openai/gpt-5.6-terra', reasoning: 'high' }
       : { model: 'openai/gpt-5.6-luna', speed: 'fast' },
-  handlers: {
-    'ticket.flagged': async ({ event }) => {
-      // your side effect; event.id makes a stable idempotency key:
-      // await notifyOnCall(event.payload.ticketId, { idempotencyKey: event.id })
+  consumers: [
+    {
+      name: 'page-on-call',
+      types: ['ticket.flagged'],
+      run: async ({ event }) => {
+        // your side effect; event.id makes a stable idempotency key:
+        // await notifyOnCall(event.payload.ticketId, { idempotencyKey: event.id })
+      },
     },
-  },
+  ],
 })
 ```
 
@@ -277,7 +283,7 @@ export const POST = handle
 Server appends, such as
 `supportDeskAgent.session(id).append({ type: 'plan.changed', payload })`, are
 trusted and skip `authorize`. `push()` also accepts any `inputs` builder, and
-`handlerContext(supportDesk)` types application events inside tools.
+`consumerContext(supportDesk)` types application events inside tools.
 
 The contract-free client, `createAgentClient()` or `useAgent({ api | client })`
 with a type-only import, folds only the built-in reducer. It accepts
@@ -285,10 +291,10 @@ with a type-only import, folds only the built-in reducer. It accepts
 no `reducer`; the types enforce this through `AI_STATE_REDUCER`.
 
 When the agent belongs inside something larger, such as a shared chat room,
-keep two sessions. The room's handler appends each message the agent should see
-to the agent's session with `inputs.message()`. Event IDs are unique across a
-store's sessions, so derive the message ID from the room event's ID with
-`idempotentId()`; a retried handler then converges on the same message. A tool
+keep two sessions. A consumer of the room appends each message the agent should
+see to the agent's session with `inputs.message()`. Event IDs are unique across
+a store's sessions, so derive the message ID from the room event's ID with
+`idempotentId()`; a retried run then converges on the same message. A tool
 the agent calls to speak appends to the room with an `idempotentId()` of its
 `toolCallId`. Neither fold reads the other's state.
 
@@ -369,8 +375,12 @@ completed input.
 
 ## Delivery semantics
 
-Model steps and tools run inside at-least-once A2 handlers. A successful
-completion commits atomically with its terminal events, and deterministic IDs
+The agent runs on four of A2's own at-least-once
+[consumers](/server/consumers): `a2.ai.control` applies commands and work
+reports one at a time, `a2.ai.model` runs model steps on one lane, `a2.ai.tools` runs local
+tools, and `a2.ai.metadata` looks up model limits. A dead letter names the one
+that failed. A successful completion commits atomically with its terminal
+events, and deterministic IDs
 make scheduling and lifecycle appends effectively once. An incomplete model
 attempt is marked `superseded` before its replacement starts. An expired claim
 or superseded attempt keeps its abort reason through model, resolver,
@@ -379,7 +389,7 @@ attempt; an explicit interruption stays terminal. A retried tool can stream
 different preliminary output under the same tool-call ID.
 
 Provider calls and external side effects sit outside that transaction, so
-recovery may repeat a call whose effect landed before its handler committed.
+recovery may repeat a call whose effect landed before its run committed.
 Give side-effecting tools their own idempotency, normally keyed by the AI SDK
 `toolCallId`. A fast tool can also start before its model step fails; the
 failure blocks the continuation but cannot undo the effect.
@@ -530,7 +540,7 @@ application, with `commandId` (the submitted event's ID) and an `outcome` of
 in flight, each action resolves to its persisted command events, whose `id` is
 the receipt's `commandId`, or to an empty array when there is nothing to
 address, such as Stop with no active turn. A rejection is a normal result and
-spends no handler retry.
+spends no retry.
 
 ### Pause and resume
 

package/docs/agents/04-harnesses.mdx

@@ -31,7 +31,7 @@ everything it can call:
 import { tool } from 'ai'
 import { Sandbox } from '@vercel/sandbox'
 import { z } from 'zod'
-import { handlerContext } from 'experimental-a2/ai'
+import { consumerContext } from 'experimental-a2/ai'
 import { agent } from 'experimental-a2/ai/server'
 import { fx } from 'experimental-a2/ai/fx'
 
@@ -45,7 +45,7 @@ export const coder = agent({
       description: 'Run a shell command in the repository.',
       inputSchema: z.object({ command: z.string() }),
       execute: async ({ command }) => {
-        const { session, signal } = handlerContext()
+        const { session, signal } = consumerContext()
         // One Vercel Sandbox per session, created on first use.
         const sandbox = await Sandbox.getOrCreate({
           name: session.id,
@@ -125,7 +125,8 @@ turn, so a process keeps the images it fetched instead of fetching them again.
 
 A file that isn't an image, or that A2 can't fetch, fails the turn with an
 error that names it. So does a steer with files under FX, which steers with
-text only. The harness applies its own rules to the images it gets: FX fails a
+text only. A steer that joins the turn's prompt, as described below, sends its
+files with the prompt. The harness applies its own rules to the images it gets: FX fails a
 turn whose model doesn't take images, and Pi resizes them. Every step sends the
 conversation so far, files and all, so a file that fails one turn fails the
 turns after it too.
@@ -169,6 +170,9 @@ sets `needsApproval` is rejected. It hands the engine only tools A2 runs, so a
 provider-defined tool, such as a provider's web search, is rejected too. `maxSteps` limits the model calls in one
 response under every harness. Steering enters at the next step, as with any
 agent: the harness sees the steered message before its next model call.
+Steering that hands off before any of the turn's model calls finished, as after
+a pause during the first one, joins the turn's prompt instead, so the turn's
+first model call sees it.
 
 ## Recovery
 

package/docs/client/03-presence.mdx

@@ -13,7 +13,7 @@ replay value, and a lost update is repainted by the next one. The test:
 > passes? Yes: event, in the log. No: presence.
 
 Messages, document updates, cancellations: events. Cursors, selections,
-typing, "who's online", a handler's live progress: presence.
+typing, "who's online", a consumer's live progress: presence.
 
 Presence rides the session you already have: same contract, route, auth, and
 stream. A2 replicates each participant's latest field values to every
@@ -167,30 +167,34 @@ render-time rule:
 The durable event at index 214 beats any presence stamped 213 or lower. A2
 carries the stamp; the comparison is yours, in view code.
 
-## Handlers broadcast too
+## Consumers broadcast too
 
-`ctx.session.setPresence` is the same operation, so a handler can publish live
+`ctx.session.setPresence` is the same operation, so a consumer can publish live
 progress without writing non-facts to the log:
 
 ```ts server/canvas.ts
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 import { canvas } from '@/contracts'
 
+const thumbnails = consumer({
+  contract: canvas,
+  name: 'thumbnails',
+  types: ['shape.created'],
+}).run(async (ctx) => {
+  // long work; broadcast progress as it goes:
+  // await ctx.session.setPresence({
+  //   participant: 'system:thumbnails',
+  //   values: { progress: { step: 2, of: 5 } },
+  // })
+})
+
 export const canvasServer = createServer({
   contract: canvas,
-  handlers: {
-    'shape.created': async (ctx) => {
-      // long work; broadcast progress as it goes:
-      // await ctx.session.setPresence({
-      //   participant: 'system:thumbnails',
-      //   values: { progress: { step: 2, of: 5 } },
-      // })
-    },
-  },
+  consumers: [thumbnails],
 })
 ```
 
-The participant id is the handler's choice; a `system:` prefix keeps robots
+The participant id is the consumer's choice; a `system:` prefix keeps robots
 apart from humans in the map. When the work completes, append the outcome as
 an event: the progress was never a fact, the result is.
 

package/docs/contract/01-events.mdx

@@ -33,7 +33,7 @@ schema for its payload. These docs use Zod, but any
 your own.
 
 The contract is a plain, importable, **isomorphic** value. The server
-implements it with [handlers](/server/handlers), [reducers](/contract/state)
+implements it with [consumers](/server/consumers), [reducers](/contract/state)
 derive the current view from it, and the browser types its pushes off it.
 
 ## Validation
@@ -52,6 +52,6 @@ typing, live progress) that is replicated but never stored in the log. See
 :::tip
 Events are facts, so name them in past tense: `created`, `expired`,
 `shop.notified`. A name that reads like a command (`notifyShop`) describes
-what a handler should do, not what happened. Dots are a naming convention, not
+what a consumer should do, not what happened. Dots are a naming convention, not
 a namespace.
 :::

package/docs/contract/02-state.mdx

@@ -11,8 +11,8 @@ const events = await ordersServer.session(orderId).history()
 ```
 
 Every event in the session, oldest first: always the raw log, never a summary
-or snapshot. Use it for audits, debugging, and handler questions like "did the
-shop already start?" Pass inclusive `gte` or `lte` indexes to read a slice.
+or snapshot. Use it for audits, debugging, and consumer questions like "did
+the shop already start?" Pass inclusive `gte` or `lte` indexes to read a slice.
 
 ## Reducers
 
@@ -72,7 +72,7 @@ server-only app can keep the contract next to `createServer` instead.
 
 ## Read boundaries
 
-A root session reads the latest committed frontier. A handler's session stops
+A root session reads the latest committed frontier. A consumer's session stops
 at its triggering event by default, stable across concurrent appends and
 retries:
 
@@ -83,23 +83,27 @@ import { ordersReducer } from './reducer'
 
 export const ordersServer = createServer({
   contract: orders,
-  handlers: {
-    created: async ({ event, session }) => {
-      const atTrigger = await session.state(ordersReducer)
-      // atTrigger.index === event.index
-
-      const latest = await session.state(ordersReducer, { through: 'latest' })
-      // latest also folds events appended after this one
+  consumers: [
+    {
+      name: 'read-status',
+      types: ['created'],
+      run: async ({ event, session }) => {
+        const atTrigger = await session.state(ordersReducer)
+        // atTrigger.index === event.index
+
+        const latest = await session.state(ordersReducer, { through: 'latest' })
+        // latest also folds events appended after this one
+      },
     },
-  },
+  ],
 })
 ```
 
 Use `{ through: 'latest' }` for joins or other logic that intentionally
 observes later events. A numeric `{ through: index }` reads any inclusive log
 boundary; `through: 0` returns `initialState`. `state()` is observational: it
-never runs handlers or waits for pending work, and its index marks committed
-history, not handler completion.
+never runs consumers or waits for pending work, and its index marks committed
+history, not consumer progress.
 
 A latest read and a following `ctx.session.append(name, ...events)` are
 separate operations, and concurrent appends and retries can move the frontier
@@ -125,7 +129,7 @@ telemetry span (or `console.error` by default) without snapshot contents, and
 the next read folds the missing tail again.
 
 Each session and reducer has one latest snapshot. Older ones exist only while
-handler events that read at their boundary are unfinished (not yet completed
+consumer runs that read at their boundary are unfinished (not yet completed
 or dead-lettered). This is automatic: there is no TTL, history limit, or
 retention setting.
 

package/docs/contract/03-sessions.mdx

@@ -4,7 +4,7 @@ description: "A session is one instance of a contract, with its own ordered log,
 ---
 
 ```ts
-// anywhere on the server: a route, a handler, a script
+// anywhere on the server: a route, a consumer, a script
 const order = ordersServer.session('order-42')
 ```
 
@@ -19,7 +19,7 @@ Put events in one session when they form one history, fold, recovery unit, or
 live view. Split what should be read and recovered independently.
 
 A session is not a table or a general query boundary: one `orders` contract can
-serve millions of order sessions through the same server and handlers.
+serve millions of order sessions through the same server and consumers.
 Collections, joins, search, and constraints across many records belong in
 [your database](#sessions-and-your-database).
 
@@ -48,7 +48,7 @@ same atomic step that appends the marker; if another event landed first, the
 clear skips and returns `{ cleared: false, index }` with the current head. A
 conditional clear is safe to retry.
 
-The old lifetime's pending events are never dispatched, and a handler still
+The old lifetime's pending events are never dispatched, and a consumer still
 running for one can't append, return events, or read the new lifetime's state.
 Clearing can't stop code that is already running or undo its side effects.
 
@@ -70,7 +70,7 @@ authorize your own route before calling it.
 
 ### Scheduling a clear
 
-With a [scheduler](/schedulers/overview) configured, a handler can schedule a
+With a [scheduler](/schedulers/overview) configured, a consumer can schedule a
 clear. This one clears an idle cart a day after its last activity:
 
 ```ts server/carts.ts
@@ -89,20 +89,24 @@ export const carts = a2.contract({
 export const cartsServer = createServer({
   contract: carts,
   scheduler: vercelQueues(),
-  handlers: {
-    'item.added': async ({ event, session }) => {
-      await session.schedule.clear('idle', {
-        delay: '1d',
-        ifLastIndex: event.index,
-      })
+  consumers: [
+    {
+      name: 'clear-idle',
+      types: ['item.added'],
+      run: async ({ event, session }) => {
+        await session.schedule.clear('idle', {
+          delay: '1d',
+          ifLastIndex: event.index,
+        })
+      },
     },
-  },
+  ],
 })
 ```
 
 The delay counts from the event's stored time. A later event moves the head
-past `event.index`, so this delivery skips and that event's handler schedules
-the next check; only events with a handler extend the policy. A handler's own
+past `event.index`, so this delivery skips and that event's run schedules the
+next check; only events the consumer takes extend the policy. A consumer's own
 writes move the head too, so one that appends should pass the index its last
 append returned.
 
@@ -148,27 +152,30 @@ attached to it:
 The investigation's session refers to the issue id without becoming a second
 owner of the issue. A2 can own individual issues when their history and live
 state are the center of the product, but boards and search then span many
-sessions and need another query model. Don't put a whole workspace in one
-session for cross-issue queries: every event joins one growing log that every
-client follows.
+sessions and need another query model. A whole workspace can live in one
+session when its pages read from [your tables](/server/sql-projections) instead
+of folding the log, but every client following that session's live stream
+receives every event, so weigh that traffic before many people share one.
 
-### Database writes from handlers
+### Database writes from consumers
 
-Handlers may call your database like any other side effect. They are
+Consumers may call your database like any other side effect. They are
 at-least-once, so make the write idempotent with `event.id`; it runs after the
 event is durable and may be retried. That is not one atomic write across A2
 and your tables: if a relational change must commit before the request
 succeeds, make it through the database's write path.
 
-### Cross-session indexes
+### Tables kept from the logs
 
-A handler can maintain a small database index over A2-owned sessions, such as a
-list of active imports. Treat it as an advanced integration:
+A consumer can keep a table in your database from A2-owned sessions, such as a
+list of active imports. Committing its position in the same transaction as the
+rows applies each event exactly once; [SQL projections](/server/sql-projections)
+shows how. The table:
 
-- it is eventually consistent with the session logs;
-- writes must be idempotent;
-- A2 orders events within one session, not across sessions;
-- no A2 API scans and replays every session to rebuild it.
+- is eventually consistent with the session logs;
+- has each session's events in order, not an order across sessions;
+- fills from history with `backfill`, one session at a time, as each next
+  runs: nothing enumerates sessions, so to fill it for idle ones, consume each.
 
 Back up and migrate it like application data. If search, joins, and
 cross-session reporting are central, the database should probably own that

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)`
 
@@ -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.