experimental-a2 0.20.0 → 0.22.0

package/docs/01-quickstart.mdx

@@ -5,7 +5,7 @@ description: Define a contract, react to its events, and make your first durable
 
 ## What you'll build
 
-An order that notifies a shop when it arrives: one contract, one handler, two
+An order that notifies a shop when it arrives: one contract, one consumer, two
 routes, and a log you can read back.
 
 ## 1. Install
@@ -33,28 +33,34 @@ export const orders = a2.contract({
 
 ## 3. Implement it
 
-`createServer` binds the contract to storage and handlers. Same file, below
-the contract:
+A consumer reacts to events, and `createServer` binds the contract to storage
+and its consumers. Same file, below the contract:
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
 
 export const ordersServer = createServer({
   contract: orders,
-  handlers: {
-    created: async ({ event }) => {
-      // your side effect, e.g. email the shop, idempotent via event.id:
-      // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
-      return { type: 'shop.notified', payload: {} }
+  consumers: [
+    {
+      name: 'notify-shop',
+      types: ['created'],
+      run: async ({ event }) => {
+        // your side effect, e.g. email the shop, idempotent via event.id:
+        // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
+        return { type: 'shop.notified', payload: {} }
+      },
     },
-  },
+  ],
 })
 ```
 
-- Handlers can run more than once (at-least-once delivery), so make external
+- `name` is the consumer's identity: A2 keeps its place in every session under
+  it. `types` lists the events it runs on.
+- Consumers can run more than once (at-least-once delivery), so make external
   calls safe to repeat. `event.id` is stable across re-runs: use it as the
   idempotency key.
-- The returned event commits atomically with handler success. If the handler
+- The returned event commits atomically with the consumer's success. If `run`
   throws or the process dies first, `shop.notified` doesn't appear. Return one
   event or an array.
 
@@ -92,7 +98,7 @@ The payload is validated before anything is written; a bad one fails with
 `INVALID_PAYLOAD` and the issues.
 
 When `append` returns, the event is durably in the log and A2 has started the
-`created` handler inline. In production, a queue-backed scheduler wakes pending
+`notify-shop` consumer inline. In production, a queue-backed scheduler wakes pending
 work after a failure or process death. See [Guarantees](/server/guarantees).
 
 ## 5. Read the log back
@@ -122,7 +128,7 @@ curl localhost:3000/api/orders/order-42
 ```
 
 Each event also carries `id`, `sessionId`, and `createdAt` (trimmed here). You
-appended one event and the handler returned the second. Debugging in A2 is
+appended one event and the consumer returned the second. Debugging in A2 is
 reading the log.
 
 ## 6. Fold state out of the log
@@ -165,12 +171,12 @@ State isn't a second record to update. It's a fold over the log; see
 
 ## That's it
 
-You have a validated write path, a handler, a log you can read, and a view
+You have a validated write path, a consumer, a log you can read, and a view
 folded from it. The rest of these docs apply the same two moves, append an
 event and react to it, to timers, cancellation, live UIs, and production.
 
 <CardGroup cols={3}>
-  <Card title="Handlers" href="/server/handlers" icon="file">
+  <Card title="Consumers" href="/server/consumers" icon="file">
     Context, chaining, and re-runs.
   </Card>
   <Card title="Stores" href="/stores/overview" icon="rocket">

package/docs/02-examples.mdx

@@ -24,7 +24,7 @@ work inside the directory.
 
 - `app/counter` is the smallest complete contract, reducer, server, and React
   client.
-- `app/orders` adds handlers and a feature-owned scheduler.
+- `app/orders` adds consumers 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.

package/docs/actors/01-introduction.mdx

@@ -103,8 +103,11 @@ no retry. The message settles, and the caller receives
   backoff while the instance's lane waits; see
   [Errors](/reference/errors).
 - **A crash** re-runs the handler from the pre-message state. `ctx.id`
-  is the message id, stable across re-runs: use it as the idempotency
-  key for external I/O.
+  is the message id, stable across re-runs and unique within the
+  instance: use it as the idempotency key for external I/O. An explicit
+  message `id` that repeats in another instance repeats there too, so
+  derive explicit ids per instance, for example with
+  [`idempotentId()`](/reference/core#idempotentidparts).
 - **A clear** by `handle.session.clear()` before the answer rejects the
   call with an `A2Error` whose code is `SESSION_CLEARED`. The handler
   may already have run. Over HTTP it's a `410`.
@@ -153,3 +156,11 @@ be plain JSON: a `Date`, a `Map`, or `NaN` fails the commit loudly.
 streams, scheduling). The definition exposes its assembled `contract`,
 `server`, and `reducer`, and devtools show the full mailbox. Event
 names starting with `a2.` are reserved for the actor's own bookkeeping.
+
+The server runs the handlers on two of A2's own
+[consumers](/server/consumers): `a2.actor` for serial messages, on one
+lane per instance, and `a2.actor.concurrent` for
+[concurrent](/actors/concurrency#concurrent-handlers) ones. A message
+that keeps failing dead-letters for one of them; list and redrive it
+through `server.session(id)` like any
+[dead letter](/server/consumers#resolve-a-dead-letter).

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,11 @@ 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()`. Derive the message ID from
+the room event's ID with `idempotentId()`, so a retried run converges on the
+same message. Event IDs are unique per session, so when several rooms feed one
+agent session, include the room's session ID too. 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 +376,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 +390,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.
@@ -499,11 +510,11 @@ full handoff rules.
 New-input commands from `inputs.message()`, `inputs.seed()`, and
 `inputs.steer()` use the message ID as their event ID, and hand-written commands
 must too. Caller IDs cannot start with the reserved `a2.ai:` prefix and must be
-unique across the store; include the contract and session when deriving them
-with `idempotentId()`. An identical submission replays without new work, even
-after removal or compaction. Reusing an ID with different content, action, or
-session rejects with `PARTIAL_DUPLICATE_BATCH`: use `queue.edit()` to change a
-pending input and a fresh ID for a new one.
+unique within the session; the same ID in another session is another message.
+An identical submission replays without new work, even after removal or
+compaction. Reusing an ID in the session with different content or action
+rejects with `PARTIAL_DUPLICATE_BATCH`: use `queue.edit()` to change a pending
+input and a fresh ID for a new one.
 
 ### Optimistic conversation display
 
@@ -530,7 +541,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,14 +170,20 @@ 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
 
 A2 records each model call and each tool result as the harness works. When a
 process dies in the middle of a response, the next attempt resumes at the
 interrupted step: finished model calls are not made again and finished tools
-do not run again. A2 stores nothing outside the log: a process that ran the
-last response resumes the harness from its state at the end of that response,
-FX's checkpoint or Pi's session, kept in memory, and any other process replays
-the session from the log. A tool call that a crash cut short reruns unless its
+do not run again. A2 keeps nothing durable outside the log: a process that ran
+the last response resumes the harness from its state at the end of that
+response, FX's checkpoint or Pi's session, kept in memory, and any other
+process replays the session from the log. Under `fx()`, the process that ran a
+step also keeps FX's kernel waiting on that step's tool calls until the session
+has nothing left to run there, so the response's next step, or the first step
+of a response that steers it, continues it without a replay. A tool call that a crash cut short reruns unless its
 `toolRecovery` is `'report'`; see [Delivery semantics](/agents/conversations#delivery-semantics).

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