experimental-a2 0.0.0 → 0.2.0

package/docs/index.mdx

@@ -10,7 +10,7 @@ pnpm add experimental-a2
 A2 is durable sync and reactions for things with a lifecycle.
 
 An order, agent run, approval, or import gets a session. You append events.
-Handlers react to them, and usually append the next one. The browser follows
+Handlers react to them, and usually return the next one. The browser follows
 the same log and folds the same state as the server. That's the whole model;
 the rest of this page is it happening.
 
@@ -41,7 +41,7 @@ export const orders = a2.contract({
 
 Handlers are plain async functions: no determinism rules, no replay, no
 wrappers around side effects. Each one reacts to a fact and usually
-appends the next one.
+returns the next one.
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
@@ -50,10 +50,10 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    created: async ({ event, append }) => {
+    created: async ({ event }) => {
       // your side effect; event.id makes a stable idempotency key:
       // await notifyShop(event.payload, { idempotencyKey: event.id })
-      await append({ type: 'shop.notified', payload: {} })
+      return { type: 'shop.notified', payload: {} }
     },
   },
 })
@@ -61,8 +61,8 @@ export const ordersServer = createServer({
 
 ## Open a session
 
-A session is one instance of the contract, with its own log and its own
-ordering. It is the thing A2 keeps durable and live. The id is yours:
+A session is one instance of the contract, with its own ordered log. It is the
+thing A2 keeps durable and live. The id is yours:
 
 - `session('order-8194')`: an order moving through fulfillment
 - `session('chat-a8c1')`: an agent chat streaming its reply
@@ -70,7 +70,8 @@ ordering. It is the thing A2 keeps durable and live. The id is yours:
 - `session('doc-roadmap')`: a document with three people typing in it
 
 Anything whose story spans more than one request. Put events in the same
-session when they must be ordered or viewed together. Any server code can open
+session when they form one history or view. Handlers are concurrent unless
+they share a lane. Any server code can open
 one and append: a route handler, a webhook, a cron job.
 
 ```ts app/api/orders/route.ts
@@ -165,11 +166,13 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 ## The properties
 
-- **Handlers are plain async functions.** If it runs on your laptop, it
-  runs in production.
+- **Handlers are plain async functions.** They run concurrently by default.
+  Use a lane for selective FIFO execution.
+- **Handlers are optional per event type.** A log-only event settles during
+  append and creates no reaction or recovery work.
 - **History is real.** [`history()`](/concepts/state) returns what
   actually happened, in order. Debugging is reading, not reconstructing.
-- **Nothing inside a session is sacred except its log.** Snapshots, leases, queue
+- **Nothing inside a session is sacred except its log.** Snapshots, claims, queue
   messages: all disposable caches. Delete them and A2 rebuilds
   everything from the log.
 
@@ -201,6 +204,18 @@ framework. A contract, a log, handlers, reducers.
 
 </details>
 
+<details>
+<summary>Can I use A2 without handlers?</summary>
+
+Yes. Omit `handlers` 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 log-only event
+types. A2 decides per event type.
+
+See [Events without handlers](/concepts/handlers#events-without-handlers).
+
+</details>
+
 <details>
 <summary>How do I wait five days?</summary>
 
@@ -223,8 +238,8 @@ derived view exactly. See [Cancellation](/guides/cancellation).
 <details>
 <summary>What happens when a handler keeps failing?</summary>
 
-It retries with backoff, then dead-letters after ten caught failures, and the
-session stalls at that event, visibly, instead of silently skipping it.
+It retries with backoff, then dead-letters after ten caught failures. Later
+events in the same lane wait; unlaned events and other lanes continue.
 [Durability](/concepts/durability) has the exact guarantees and the
 recovery story behind them.
 
@@ -233,8 +248,9 @@ recovery story behind them.
 <details>
 <summary>What does production need?</summary>
 
-Two decisions: a log backend (Postgres or Redis) and queue-backed
-recovery. Development needs neither. SQLite appears under `.a2/` and
+A durable log backend, such as Postgres or Redis. Add queue-backed recovery
+when the contract has handlers. A log-only contract needs no reaction
+infrastructure. Development needs neither: SQLite appears under `.a2/` and
 state survives restarts. See [Going to production](/guides/production).
 
 </details>

package/docs/reference/01-api.mdx

@@ -25,6 +25,12 @@ ArkType, anything that implements it. Validators must be synchronous
 (async ones are rejected here, at definition time), and the validated
 output is what's stored.
 
+### `contract.batch(...events)`
+
+Preserves the literal types in a heterogeneous handler-returned event array.
+It returns the same events as a readonly tuple; A2 validates them when the
+handler completes.
+
 ### `contract.reducer(options)`
 
 ```ts
@@ -60,12 +66,21 @@ createServer(options: {
   log?: A2Log        // default: sqlite in dev, memory in tests, required in prod
   recovery?: A2Recovery
   telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
+  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>
   handlers?: {
     [type]:
-      | (ctx: Context) => Promise<void>
-      | { abortOn: AbortSpec; handler: (ctx: Context) => Promise<void> }
+      | Handler
+      | {
+          abortOn?: AbortSpec
+          lane?: string | ((ctx: LaneContext) => string)
+          handler: Handler
+        }
   }
 }): A2Server
+
+type Handler = (
+  ctx: Context,
+) => Promise<void | AppendInput | readonly AppendInput[]>
 ```
 
 Implements a contract: binds the vocabulary to storage and reactions.
@@ -74,43 +89,118 @@ be silently missing because the module that registered it wasn't
 imported. Compose across files by spreading objects into `handlers`
 (note: a duplicate key under spread silently last-wins).
 
+Handlers are concurrent by default. A2 starts every eligible event after its
+append commits. Add `lane` when events share a resource and must not overlap.
+Within one session, events with the same lane value run one at a time in log
+order. Different lanes and events without a lane run concurrently. A lane
+resolver receives `{ sessionId, event }`; A2 resolves and stores the value when
+the event is appended, so a later deployment cannot reinterpret pending work.
+For example, `lane: ({ event }) => event.payload.warehouseId` serializes work
+per warehouse while different warehouses continue concurrently.
+
+Handlers can return one event or an array. A2 marks the triggering event
+processed and appends the returned batch in one atomic log operation. Returned
+events do not exist when the handler throws. `ctx.session.append(name, ...events)`
+is different: it commits immediately, so its events may run while the current
+handler is still active unless a lane orders them.
+
+Handlers are optional per event type. An event type without one settles in
+the append transaction with no dispatch attempt. If the session has no older
+pending handler work, A2 starts no drain or recovery arm. A server with no
+handlers is a durable event log with no reaction infrastructure. See
+[Events without handlers](/concepts/handlers#events-without-handlers).
+
 Server-only by construction: `experimental-a2/server` is the only entry point that
 can reach a log backend, and its exports map resolves to a loud error
 under the browser condition.
 
+`validatePush({ sessionId, events })` runs only when `events` came from
+`parsePushBody()`. It runs before contract schema validation and before the log
+append, so throwing rejects the complete push without writing anything. Direct
+trusted server appends and handler appends bypass it. `parsePushBody()` creates
+the runtime provenance brand after reading the envelope; a caller-supplied
+field with the same name is ignored, and the brand is not stored in the log.
+
 `abortOn` names the events that fire `ctx.signal` while a handler runs.
 an array matches by type; an object takes per-type predicates for
 targeted cancellation:
 
 ```ts
 generate: {
-  abortOn: { cancelled: (event, trigger) => event.payload.of === trigger.id },
+  abortOn: {
+    cancelled: (event, trigger, { attempt }) =>
+      event.payload.of === `${trigger.id}:${attempt}`,
+  },
   handler: async (ctx) => { /* ... */ },
 }
 ```
 
+The predicate's third argument contains the triggering event's durable
+`attempt`, so a cancellation can fence a specific recovered run.
+
 The context every handler receives:
 
-| Property           | Type                                       |
-| ------------------ | ------------------------------------------ |
-| `ctx.event`        | `Event`: the triggering event              |
-| `ctx.attempt`      | durable 1-based dispatch claim ordinal     |
-| `ctx.append(...e)` | append to this session, typed, atomic      |
-| `ctx.history()`    | `Promise<Event[]>`: raw log, oldest first  |
-| `ctx.signal`       | `AbortSignal`: active only with `abortOn`  |
+| Property      | Type                                                      |
+| ------------- | --------------------------------------------------------- |
+| `ctx.event`   | `Event`: the triggering event                             |
+| `ctx.attempt` | durable 1-based dispatch claim ordinal                    |
+| `ctx.session` | this session's `id`, `append`, `history`, `state`, `stream` |
+| `ctx.signal`  | `AbortSignal`: active only with `abortOn`                 |
 
 `ctx.attempt` starts at `1` and increments on every durable claim. It may skip
 when a process dies before handler entry.
 
+`ctx.session.id` equals `ctx.event.sessionId`. Its `history`, `state`, and
+`stream` methods are the same session operations returned by
+`server.session(id)`. `ctx.session.state(reducer)` reads the cached snapshot
+plus immutable log tail and returns `{ state, index }`. The index is a
+consistent committed frontier captured when the call runs. It includes the
+triggering event and may include events committed later while another handler
+is active.
+
+The handler-local append is specialized:
+
+```ts
+ctx.session.append(name: string, ...events: AppendInput[]): Promise<Event[]>
+```
+
+The name is an idempotency key scoped to the triggering event for events whose
+`id` is omitted. A2 derives each omitted id from the trigger id, name, and event
+position. The same name and generated-id batch returns the existing rows
+across retries. Changing that batch conflicts with those rows. An explicit
+event `id` wins over the generated id, which lets different triggering events
+converge on one fact. A root `server.session(id).append(...events)` takes no
+name.
+
+A state read and following append are not atomic. Concurrent appends and
+retries may move the frontier between them. A generic join should use a
+monotone readiness predicate and a stable explicit output event `id`, so every
+eligible attempt converges on the same append.
+
 ### `server.session(id)`
 
 ```ts
 server.session(id: string): Session
 ```
 
-A handle on one instance of the contract. The session is the unit of ordering,
-recovery, state, and live sync. Creating the handle does no I/O; nothing loads
-until you append, read, or stream.
+A handle on one instance of the contract. The session is the unit of log
+ordering, lane keys, recovery, state, and live sync. Handler execution is
+concurrent unless events share a lane. Creating the handle does no I/O;
+nothing loads until you append, read, or stream.
+
+```ts
+const session = server.session('order-42')
+
+session.id
+session.append(...events)
+session.history()
+session.state(reducer)
+session.stream({ startAt })
+```
+
+`session.id` is the id passed to `server.session(id)`. Root `append` takes only
+events. The handler-local form at `ctx.session.append` adds its required name
+before the events.
 
 ### `server.drain(sessionId)`
 
@@ -118,10 +208,11 @@ until you append, read, or stream.
 server.drain(sessionId: string): Promise<{ settled: boolean }>
 ```
 
-Processes the session's pending events in order. `settled` means every
-event is processed or dead-lettered. You'll rarely call this yourself;
-it's the primitive recovery callbacks use. The public result stays this
-simple boolean. Recovery retries the first event without a processed marker.
+Claims every currently eligible event and runs their handlers concurrently.
+`settled` means no actionable or live-claimed work remains. A dead-lettered
+event can leave later work in its lane blocked while other lanes continue.
+You'll rarely call this yourself; it is the primitive recovery callbacks use.
+The public result stays this simple boolean.
 
 ### `A2Log`
 
@@ -132,15 +223,31 @@ Custom adapters implement these atomic drain methods:
 type EventCause = {
   index: number
   attempt: number
+  batchSize?: number // present on named handler appends
 }
 
+type AppendEvent = {
+  type: string
+  payload: unknown
+  id?: string
+  cause?: EventCause
+  lane?: string
+  settled?: true // internal: no handler is registered for this event type
+}
+
+type ReturnedEvent = AppendEvent & { id: string }
+
 type StoredEvent = Event & {
   cause: EventCause | null
+  lane: string | null
   processedAt: Date | null
   processedByAttempt: number | null
+  returnedEventIds: string[] | null
   firstClaimedAt: Date | null
   lastClaimedAt: Date | null
   attemptCount: number
+  claimHolder: string | null
+  claimExpiresAt: Date | null
   failureCount: number
   lastFailedAt: Date | null
   lastFailedAttempt: number | null
@@ -148,31 +255,48 @@ type StoredEvent = Event & {
   failedAt: Date | null
 }
 
-type LogClaimResult =
-  | { outcome: 'claimed'; event: StoredEvent }
-  | { outcome: 'busy' }
+type LogAppendResult = {
+  events: StoredEvent[]
+  hasPending: boolean
+}
+
+type LogClaimAvailableResult =
+  | { outcome: 'claimed'; events: StoredEvent[] }
+  | { outcome: 'busy'; retryAt: Date }
   | { outcome: 'settled' }
 
-type LogHandoffResult =
-  | LogClaimResult
+type CompleteAttemptResult =
+  | { outcome: 'completed'; events: StoredEvent[] }
   | { outcome: 'superseded' }
 
 interface A2Log {
-  claimNext(options: {
+  append(
+    sessionId: string,
+    events: AppendEvent[],
+  ): Promise<LogAppendResult>
+
+  claimAvailable(options: {
     sessionId: string
     holder: string
     ttlMs: number
     expiresAtMs?: number
-    maxIndex?: number
-  }): Promise<LogClaimResult>
+    excludeIndexes?: readonly number[]
+  }): Promise<LogClaimAvailableResult>
 
-  completeAndClaimNext(options: {
+  renewClaims(options: {
     sessionId: string
     holder: string
-    completedIndex: number
+    indexes: number[]
+    ttlMs: number
+    expiresAtMs?: number
+  }): Promise<number[]>
+
+  completeAttempt(options: {
+    sessionId: string
+    index: number
     attempt: number
-    maxIndex?: number
-  }): Promise<LogHandoffResult>
+    events: ReturnedEvent[]
+  }): Promise<CompleteAttemptResult>
 
   failAttempt(options: {
     sessionId: string
@@ -189,17 +313,21 @@ interface A2Log {
 
 | Method | Atomic effect |
 | --- | --- |
-| `claimNext` | Select the ordered head, respect optional `maxIndex`, acquire the lease, increment `attemptCount`, and update claim timestamps. |
-| `completeAndClaimNext` | Complete the current attempt once; record `processedByAttempt`; claim and timestamp the next only while the same holder owns a live lease. Stale attempts return `superseded`. |
-| `failAttempt` | Record a current caught failure, `lastFailedAt`, and `lastFailedAttempt`; dead-letter at `maxFailures`. Stale attempts return `superseded`. |
+| `append` | Write a consecutive batch. Events carrying core's internal `settled` flag receive `processedAt` in the same transaction, with no dispatch attempt. |
+| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. |
+| `renewClaims` | Extend the listed live claims still owned by the holder. Expired, completed, failed, and superseded claims are omitted and cannot be revived. |
+| `completeAttempt` | Fence on the current attempt, mark the parent processed, store its exact ordered `returnedEventIds`, and append the returned batch in the same transaction. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
+| `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. A repeated failure acknowledgment is idempotent; stale attempts return `superseded`. |
 
 `attemptCount` counts claims, including abandoned ones. `failureCount` counts
 caught failures and dead-letters at ten. See
 [Durability](/concepts/durability#one-event-many-attempts) for the recovery
-model. `cause` identifies the event and handler attempt whose `ctx.append`
-first persisted the child. A null cause means a root or a legacy event whose
-origin is unknown. Migrated rows can have `firstClaimedAt === null` with a
-nonzero `attemptCount`; the historical first claim is unknowable. Lifecycle
+model. `cause` identifies the event and handler attempt whose
+`ctx.session.append` or return value first persisted the child. A null cause
+means a top-level event.
+`lane` is the session-scoped serialized group resolved before append.
+`returnedEventIds` makes a lost completion
+acknowledgment recoverable without accepting a partial child batch. Lifecycle
 timestamps are adapter clock values for their atomic log operations, not exact
 database commit times.
 Built-in adapters persist these fields inside their existing atomic operations,
@@ -223,6 +351,36 @@ identical batch returns the original rows. (Events parsed by
 `parsePushBody` are accepted directly, the push-route path.) See
 [Durability](/concepts/durability).
 
+After the write, A2 dispatches only event types with registered handlers.
+Other event types are already settled by the append itself. An unhandled
+append still starts session healing when older handled work is pending. The
+log reports that session-wide pending state as part of the atomic append, so
+this decision needs no follow-up read.
+
+### `session.append.dispatch(...events)`
+
+```ts
+session.append.dispatch(
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+Commits the same atomic batch, but sends pending work directly to configured
+recovery instead of starting an inline drain. The call awaits acceptance of an
+immediate recovery message. It throws before writing if the server has no
+recovery adapter.
+
+If the queue send fails, the events are already durable. Give them explicit
+IDs and retry the same dispatch safely. A batch that leaves no pending handler
+work does not send a recovery message. Dispatch chooses how this append wakes
+the session; it does not reserve events for one worker. A drain that is already
+active may still claim newly eligible work first.
+
+`dispatch` exists only on a server session's top-level append. Handler-scoped
+`ctx.session.append(name, ...events)` already runs inside an active drain and
+does not expose `dispatch`. Its immediate children and atomically returned
+children become eligible in that drain.
+
 ### `session.history()`
 
 ```ts
@@ -375,18 +533,38 @@ Pure typed inputs for `append()` and `push()`:
 
 | Input | Events |
 | --- | --- |
-| `inputs.message(message)` | `ai.message.created`, plus `ai.generation.requested` for a user message |
-| `inputs.seed(message)` | `ai.message.created` only |
-| `inputs.approval(response)` | `ai.approval.responded` + continuation request |
-| `inputs.input(response)` | `ai.input.responded` + continuation request |
-| `inputs.requestInput(request)` | `ai.input.requested` |
-| `inputs.retry(options)` | a fresh `ai.generation.requested` for a failed response |
+| `inputs.message(message)` | `ai.message.created`; the server schedules a user turn |
+| `inputs.seed(message)` | `ai.message.created` for a trusted server append |
+| `inputs.approval(response)` | `ai.approval.responded` only |
+| `inputs.input(response)` | `ai.input.responded` only |
+| `inputs.requestInput(request)` | `ai.input.requested` for a trusted server append |
+| `inputs.retry(options)` | `ai.retry.requested` |
 | `inputs.interrupt(options)` | `ai.message.interrupted` |
 
-`inputs` deliberately has no session lifecycle methods. Push explicit
-`ai.session.created` and `ai.session.closed` events directly when an
-application uses them. Input event ids are stable for the interaction they
-describe, so a lost append acknowledgment can be resent safely.
+`inputs` deliberately has no session lifecycle methods. Append explicit
+`ai.session.created` and `ai.session.closed` events from trusted server code
+when an application uses them. Input event ids are stable for the interaction
+they describe, so a lost append acknowledgment can be resent safely. Browser
+ingress accepts user messages, approval and input responses, interruptions,
+and explicit retries. Only built-in server handlers append generation requests
+and AI lifecycle events. `inputs.seed()` and `inputs.requestInput()` are for
+trusted server appends.
+
+Approval and input request/response payloads require the active
+`generationId`. Clients copy it from the pending request, which prevents a
+delayed response from satisfying a newer model step.
+
+`ai.retry.requested` carries `{ messageId, responseMessageId, retryId }`.
+`retryId` identifies one user action. The server converts the fact into an
+`ai.generation.requested` whose reason is `retry`.
+
+`ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
+continuation before another model step starts.
+
+`ai.message.interrupted` carries `{ messageId, generationId?, reason?,
+lastSeenIndex? }`. Omit `generationId` only while the matching response is in
+the requested phase and `activeGeneration` does not exist yet. Once a
+generation starts, include its id to fence delayed interruption actions.
 
 ### `events` and `createEvents(options?)`
 
@@ -402,9 +580,16 @@ createReducer({ contract, name? }): Reducer<AIState>
 
 Builds the standard AI projection for a compatible contract. `AIState`
 contains session lifecycle, messages, generation status, pending approvals
-and input, tool activity, compaction, usage, and the last error.
+and input, tool activity, compaction, usage, the last error, and
+`activeRequestId` and `activeResponseMessageId`, plus
+`responseGenerationIds: Record<string, string>`.
+`activeRequestId` is the server-authorized generation request and fences
+delayed requests before their generation starts. `activeResponseMessageId`
+identifies the requested response until `activeGeneration` exists.
 `activeProjection` holds the indexed chunk/tool frontier only while a
-generation is active; terminal events clear it. Extension events are ignored.
+generation is active; terminal events clear it. `responseGenerationIds` keeps
+the latest generation owner for each response message, so late events from a
+superseded owner cannot alter the projection. Extension events are ignored.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
@@ -423,6 +608,7 @@ createAgentServer({
   tools?,
   instructions?,
   generation?,
+  maxSteps?,
   generate?,
   compaction?,
   progress?,
@@ -430,21 +616,58 @@ createAgentServer({
 }): A2Server
 ```
 
-Creates the standard server for an agent. A2 runs an AI SDK `ToolLoopAgent`,
-persists each `UIMessageChunk` once in a durable progress batch, projects
-messages synchronously, extracts tool and approval lifecycle events, and
-records completion, usage, interruption, and failure. `model` accepts an AI
-SDK model string or provider model. `model` and `instructions` can be values or per-generation async
-resolvers. `generation` accepts the remaining `ToolLoopAgent` settings, such
-as `temperature`, `maxOutputTokens`, `topP`, stop conditions, and provider
-options. Support for individual settings depends on the selected model and
-provider.
+Creates the standard server for an agent. A2 runs one AI SDK `streamText()`
+model step per durable generation, persists each `UIMessageChunk` once in a
+durable progress batch, projects messages synchronously, extracts tool and
+approval lifecycle events, executes local tools, and records completion,
+usage, interruption, and failure. `model` accepts an AI SDK model string or
+provider model. `model` and `instructions` can be values or per-generation
+async resolvers.
+
+`generation` contains per-step settings such as `temperature`,
+`maxOutputTokens`, `topP`, provider options, and tool approval policy. A2 owns
+the one-step stop condition, local tool execution, and continuation. `maxSteps`
+limits one complete assistant response and defaults to 20. Support for
+individual model settings depends on the selected model and provider.
+`generation` excludes `stopWhen`, tool execution callbacks, tool callers, tool
+context, sandbox execution, and the tool approval secret. Model-step timeouts
+remain available; tool-execution timeouts do not.
 
 `generate(context)` optionally replaces the default AI SDK generation. It
 receives messages, the resolved model and instructions, tools, generation
-settings, request state, and the abort signal. It returns a
-`ReadableStream<UIMessageChunk>`. A2 continues to own the durable lifecycle
-around that stream.
+settings, request state, and the abort signal. It returns exactly one model
+step as a `ReadableStream<UIMessageChunk>`. A2 continues to own tool execution,
+continuation, and the durable lifecycle around that stream.
+
+Generation requests use one durable lane, so model calls for a session do not
+overlap. Queued-turn policy also waits to schedule a later user message until
+the active assistant response, including its complete tool loop, reaches a
+terminal event. The policy matters in addition to lane FIFO because a tool
+continuation may be appended after the later user message. A generation
+failure keeps later messages queued until the failed response is explicitly
+retried or interrupted.
+
+Independent authorized tool handlers run concurrently without a fixed
+concurrency limit. A private coordinator reducer tracks generation closure,
+cancellation, calls, approvals, and terminal results for the active response.
+Completed responses do not accumulate in its state. Its `ctx.session.state()` reads the
+durable snapshot plus log tail. Process memory is not authoritative. Concurrent
+join checks return the same deterministic continuation event, so they use
+`ctx.session.append()` and storage deduplicates the race.
+
+Tool results and generation completion have no fixed relative order. The
+continuation predicate needs both the closed model step and every required
+terminal result.
+
+Single-owner terminal events use returned-event causality. They commit
+atomically with parent completion and receive the parent's durable cause.
+Many-owner joins and preliminary streaming outputs use immediate idempotent
+appends. Provider calls and external tool side effects are at least once and
+require their own idempotency. Approved provider-executed calls may satisfy the
+join from the approval response. Provider tools with declared deferred-result
+support wait for their provider result instead of a local executor. An
+authenticated provider callback appends the terminal `ai.tool.result` through
+the trusted server session API; the browser push allowlist rejects it.
 
 `compaction` has `shouldCompact(context)` and `compact(context)` callbacks.
 When selected, both the request and the replacement messages enter the log.
@@ -456,8 +679,20 @@ This entry point is server-only and resolves to a throwing browser stub.
 
 Returns the built-in A2 handler table without constructing a server. Spread
 it into `createServer({ handlers })` beside application handlers when you need
-a custom assembly. Application handlers spread later can deliberately replace
-a built-in handler.
+a custom assembly. The table handles input facts, generation requests, model
+step completion, tool calls, approval responses, and terminal tool results.
+Application handlers spread later can deliberately replace a built-in
+handler. Custom assemblies pass `validateAgentPush` as
+`createServer({ validatePush })` to preserve the browser boundary.
+
+### `validateAgentPush(context)`
+
+`validateAgentPush({ sessionId, events }): void`
+
+Accepts the browser interaction allowlist: user messages, approval and input
+responses, interruptions, and explicit retries. It rejects server-authored
+scheduling and lifecycle events, trusted seed messages, and input requests.
+`createAgentServer()` installs it automatically.
 
 See [Durable AI agents](/guides/ai-agents) for the protocol and complete
 examples.
@@ -545,29 +780,29 @@ alert on are all mid-span.
 | Attribute             | Span        | When  | Values                                                |
 | --------------------- | ----------- | ----- | ----------------------------------------------------- |
 | `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
+| `a2.append.mode`      | `a2.append` | start | `inline` \| `dispatch`                                |
 | `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
 | `a2.append.count`     | `a2.append` | start | batch size                                            |
 | `a2.append.armed`     | `a2.append` | mid   | `false` when the recovery arm failed and this append degraded to append-driven healing |
-| `a2.drain.scope`      | `a2.drain`  | start | `full` \| `tree`                                      |
-| `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled` \| `handed_off` |
+| `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled`                      |
 | `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
 | `a2.event.type`       | `a2.event`  | start | the event's type                                      |
 | `a2.event.index`      | `a2.event`  | start | log position                                          |
 | `a2.event.id`         | `a2.event`  | start | event id                                              |
 | `a2.event.attempt`    | `a2.event`  | start | same durable 1-based ordinal as `ctx.attempt`          |
-| `a2.event.handled`    | `a2.event`  | start | `false` when no handler is registered                 |
+| `a2.event.lane`       | `a2.event`  | start | stored lane value; absent for concurrent unlaned work  |
+| `a2.event.handled`    | `a2.event`  | start | normally `true`; `false` when a custom-adapter row has no handler |
 | `a2.event.outcome`    | `a2.event`  | mid   | `processed` \| `failed` \| `dead_lettered` \| `superseded` |
 | `a2.event.aborted`    | `a2.event`  | mid   | `true` when `abortOn` fired during the run            |
-| `a2.event.lease_lost` | `a2.event`  | mid   | `true` when the lease was lost mid-handler            |
 | `a2.state.reducer`    | `a2.state`  | start | the reducer's name                                    |
 | `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) |
 | `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
 | `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
 
-Drain outcomes: `settled` means nothing actionable is left; `busy` means
-another drainer holds the session (in-process slot or cross-process lease);
-`stalled` means blocked at a dead-lettered event; `handed_off` means leftovers
-went to a scheduled in-process drain.
+Drain outcomes: `settled` means nothing actionable is left; `busy` means live
+per-event claims remain; `stalled` means a caught failure needs a later retry.
+A dead-lettered event blocks only later events in its lane. Other lanes remain
+eligible.
 
 A failing handler marks its `a2.event` span with the exception and
 error status; `a2.event.outcome = dead_lettered` is the attribute to