experimental-a2 0.0.0 → 0.2.0

package/docs/guides/05-production.mdx

@@ -1,13 +1,13 @@
 ---
 title: Going to production
-description: Point the log at Postgres, add queue-backed recovery, and know what to do when an event dead-letters.
+description: Point the log at durable storage, add recovery for handler work, and know what to do when an event dead-letters.
 ---
 
 ## Two pieces
 
 Development needs zero setup: SQLite appears under `.a2/`, and tests run
-in memory. Production needs two deliberate pieces. Neither changes your
-handlers.
+in memory. Every production server needs a durable log. Servers with handlers
+also need recovery. Neither choice changes your event contract.
 
 ## 1. Choose a log
 
@@ -30,7 +30,8 @@ export const ordersServer = createServer({
 ```
 
 The Postgres backend uses real transactions; appends serialize per
-session on an advisory lock, and the live stream polls the log with an
+session on an advisory lock, while handler claims remain concurrent. The live
+stream polls the log with an
 activity-adaptive cadence: 25ms while a session is producing events
 (a token stream reads smoothly, not in clumps), backing off to 250ms
 when it goes quiet (a LISTEN/NOTIFY upgrade could still land without
@@ -43,7 +44,7 @@ This configures storage for A2's session logs. It does not connect A2 to your
 application tables or make them part of the append transaction. See
 [A2 and your database](/guides/application-data) for that boundary.
 
-## 2. Add recovery
+## 2. Add recovery for handlers
 
 Recovery is what puts a clock on healing. `experimental-a2/recovery-vercel` rides
 Vercel Queues (`@vercel/queue` is a peer
@@ -94,33 +95,60 @@ export const POST = recovery.handler(ordersServer, billingServer)
 The trigger makes the route private. Only queue infrastructure can invoke
 it, so it needs no auth of its own.
 
-One route, one job. Every top-level append starts a delayed, coalesced
-"drain this session" arm alongside its inline handler. The handler does not
-wait for the queue, while `append` joins the initial arm for up to two seconds
-before it returns. An unresponsive queue therefore cannot hold the append open
-indefinitely. Every lease renewal arms another watchdog for just after that
-lease window. A live holder keeps moving the watchdog forward. A killed holder
-stops heartbeating, its lease expires, and the next watchdog retries the
-pending event. When Vercel exposes the function deadline, A2 caps the final
-lease window there so timeout recovery starts promptly. A failing handler
-keeps the current message and redelivers with backoff until the session
-settles.
-
-Due times are rounded to one-second slots. Top-level arms, lease renewals, and
+One route, one job. A top-level append that leaves or finds pending handler
+work starts a delayed, coalesced "drain this session" arm alongside its inline
+handler. The handler does not wait for the queue, while `append` joins the
+initial arm for up to two seconds before it returns. An unresponsive queue
+therefore cannot hold the append open indefinitely. Claim renewals arm another
+watchdog for just after the current window. Live handlers keep moving their
+per-event claims and the watchdog forward. A killed holder stops heartbeating,
+its claims expire, and the next watchdog retries those pending events. When
+Vercel exposes the
+function deadline, A2 caps the final claim window there so timeout recovery
+starts promptly. A failing handler keeps the current message and redelivers
+with backoff. Work outside its lane continues.
+
+Due times are rounded to one-second slots. Top-level arms, claim renewals, and
 racing deliveries targeting the same slot deduplicate into one queue message.
 Busy deliveries continue the current message's heartbeat-aligned slot series,
 so they do not create an independent stream of watchdog callbacks.
-Events appended by handlers ride their current execution window and add no
-recovery operation of their own.
+Events appended or returned by handlers ride their current execution window
+and add no recovery operation of their own.
 
 No cron, no sweep, no notification bookkeeping. The queue message is
 the recovery state, and the log is the only thing it consults.
 
+### Dispatch in a fresh invocation
+
+Ordinary `append` starts handlers inline and uses recovery as the watchdog.
+Use `append.dispatch` when the current request should only persist the input
+and hand pending work directly to the queue:
+
+```ts app/api/imports/route.ts
+import { ordersServer } from '@/server'
+
+export async function POST(request: Request) {
+  const { orderId, shopId, items } = await request.json()
+  await ordersServer.session(orderId).append.dispatch({
+    id: `created:${orderId}`,
+    type: 'created',
+    payload: { shopId, items },
+  })
+  return Response.json({ accepted: true }, { status: 202 })
+}
+```
+
+The call awaits the immediate queue send and does not start an inline drain.
+If the send fails, the event may already be durable. Its explicit ID makes the
+retry idempotent. An existing drain for the same session can still claim the
+event first; dispatch controls the wakeup path, not worker affinity.
+
 ## 3. When an event dead-letters
 
-After ten caught handler failures, A2 stops retrying an event and the session
-stalls at it; [Durability](/concepts/durability#when-a-handler-keeps-failing)
-explains why stalling is the honest choice. Resolution is manual, and has
+After ten caught handler failures, A2 stops retrying an event. It blocks later
+events in the same lane; unlaned events and other lanes continue.
+[Durability](/concepts/durability#when-a-handler-keeps-failing) explains this
+boundary. Resolution is manual, and has
 exactly two shapes:
 
 - **Fix and retry.** Deploy the handler fix, clear the event's failure
@@ -155,14 +183,20 @@ path lands in a single trace: the request → `a2.append` → the inline
 make: the whole causal chain, visually. Handler failures mark their `a2.event`
 span with the exception, each dispatch reports `ctx.attempt` as
 `a2.event.attempt`, and `a2.event.outcome = dead_lettered` is the attribute to
-alert on when a session [stalls for manual
+alert on when an event [needs manual
 resolution](#3-when-an-event-dead-letters). See the
 [API reference](/reference/api#a2otel) for the span catalogue.
 
 ## Running without a queue
 
-Skip `recovery`, and the only wakeups are a top-level append or explicit
-`server.drain()`. Reads never wake the session.
+If none of a contract's event types have handlers, skip `recovery`. Those
+events settle in their append transaction, so they create no drains, claims,
+queue messages, or recovery callbacks. The server is a durable event log for
+history, reducers, and live sync. That is a complete production configuration,
+not degraded recovery, because there is no reaction to recover.
+
+With handlers, skipping `recovery` means the only wakeups are a top-level
+append or explicit `server.drain()`. Reads never wake the session.
 
 That's a real configuration, not a broken one. Fine for internal tools
 and low-stakes apps where "heals on the next write" is acceptable. But
@@ -174,6 +208,6 @@ For production, configure recovery.
 | Piece               | Done when                                                            |
 | ------------------- | -------------------------------------------------------------------- |
 | Log                 | `log: postgres(...)` on every server                                  |
-| Recovery            | one shared `vercelQueues()`, route mounted, trigger in `vercel.json`  |
+| Recovery            | for servers with handlers: one shared `vercelQueues()`, route, and trigger |
 | Idempotent handlers | external side effects take `event.id` as an idempotency key           |
 | Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |

package/docs/guides/06-ai-agents.mdx

@@ -60,9 +60,14 @@ default. `model` also accepts any AI SDK `LanguageModel`, such as a provider
 model returned by `openai('gpt-5.6-terra')`, or an async resolver that chooses a
 model for each generation.
 
-`generation` accepts the remaining AI SDK `ToolLoopAgent` settings: sampling,
-token limits, stop conditions, provider options, step callbacks, and tool
-approval policy. Individual providers decide which settings they support.
+Each durable generation runs one AI SDK `streamText()` step. `generation`
+contains per-step settings such as sampling, token limits, provider options,
+and tool approval policy. A2 owns the stop condition, local tool execution,
+and continuation between steps. `maxSteps` limits one complete assistant
+response and defaults to 20. Individual providers decide which model settings
+they support. `generation` therefore excludes `stopWhen`, tool execution
+callbacks, tool callers, tool context, sandbox execution, and the tool approval
+secret. Model-step timeouts are supported; tool-execution timeouts are not.
 
 `experimental-a2/ai/server` is server-only. The isomorphic `experimental-a2/ai` entry point contains the
 contract, reducer, schemas, and pure inputs; it never imports a model provider
@@ -106,9 +111,10 @@ export async function POST(req: Request): Promise<Response> {
 }
 ```
 
-The route never calls the model directly. Appending
-`ai.generation.requested` wakes the built-in handler, which runs the AI SDK on
-the server and appends progress back to the same log.
+The route never calls the model directly. The browser appends user facts such
+as `ai.message.created`. Built-in server handlers schedule
+`ai.generation.requested`, run the AI SDK, and append progress back to the same
+log.
 
 ## Bind the reducer to React
 
@@ -182,13 +188,7 @@ export async function openAgent(
   message: UIMessage,
   router: { push(href: string): void },
 ): Promise<void> {
-  await assistantClient.session(sessionId).push(
-    {
-      type: 'ai.session.created',
-      payload: { metadata: {} },
-    },
-    ...inputs.message(message),
-  )
+  await assistantClient.session(sessionId).push(...inputs.message(message))
   router.push(`/agent/${sessionId}`)
 }
 ```
@@ -216,7 +216,7 @@ export function AgentClient() {
   const [draft, setDraft] = useState('')
   const [error, setError] = useState<string | null>(null)
 
-  const canSend = state.status === 'idle' || state.status === 'failed'
+  const canSend = state.status !== 'closed'
   const lastMessage = state.messages.at(-1)
   const lastText =
     lastMessage?.parts
@@ -289,16 +289,21 @@ export function AgentClient() {
 }
 ```
 
-There is no separate message state to reconcile. `push()` folds
-`ai.message.created` and `ai.generation.requested` locally before starting the
-request. The user message and generating state appear immediately. If the
-request fails, A2 removes both optimistic events; the component only restores
-the draft.
+There is no separate message state to reconcile. `push()` folds the
+`ai.message.created` fact locally before starting the request, so the user
+message appears immediately. If the request fails, A2 removes that optimistic
+event and the component restores the draft. The server owns the corresponding
+generation request.
 
 The form gives Enter its normal submit behavior. The thinking row is also
-derived from `AIState`: it appears with the Agent label as soon as the
-optimistic generation request folds, then the first visible assistant content
-replaces it. Empty stream-start messages never create a blank conversation row.
+derived from `AIState`: it appears with the Agent label when the server's
+generation request folds, then the first visible assistant content replaces
+it. Empty stream-start messages never create a blank conversation row.
+
+Users can send another message while a response is active. The message enters
+the durable log immediately, but its turn waits until the active assistant
+response, including every tool step and approval, reaches a terminal event.
+Queued messages keep log order.
 
 ## What happens after `push()`
 
@@ -306,26 +311,52 @@ One user interaction becomes a durable sequence:
 
 ```text
 browser  ai.message.created             optimistic, then durable
-browser  ai.generation.requested         optimistic, then durable
+server   ai.generation.requested         scheduled from durable facts
 server   ai.generation.started
 server   ai.generation.progress          batched UIMessageChunk[]
 server   ai.tool.called                  when present
-server   ai.tool.result                  when present
 server   ai.approval.requested           when present
-server   ai.generation.completed
+server   ai.tool.result                  after concurrent execution or denial
+server   ai.generation.completed         closes this model step
+server   ai.generation.requested         after all sibling tools are terminal
+         ...                             another one-step generation
 server   ai.message.completed
+server   ai.generation.requested         next queued user turn, when present
 ```
 
+Tool results and generation completion may arrive in either order. A fast
+automatic tool can finish while the model stream is still open. The join waits
+for both step closure and every required terminal result.
+
 The SSE connection delivers the server events to the same reducer. Progress
 stores every AI SDK chunk once. The reducer and the exported
 `deriveUIMessages()` apply those chunks synchronously to produce the current
 `UIMessage`; cumulative message snapshots are not duplicated in the log.
 
-`AIState` exposes `messages`, `status`, `activeGeneration`, `activeProjection`,
+`AIState` exposes `messages`, `status`, `activeGeneration`, `activeRequestId`,
+`activeResponseMessageId`, `activeProjection`, `responseGenerationIds`,
 `pendingApprovals`, `pendingInputs`, `tools`, `compaction`, per-generation
-`usage`, and the last generation `error`. `activeProjection` is the temporary
-indexed chunk/tool frontier used for exact interruption and becomes `null` at
-a terminal event.
+`usage`, and the last generation `error`.
+`activeProjection` is the temporary indexed chunk/tool frontier used for exact
+interruption and becomes `null` at a terminal event.
+
+`activeRequestId` identifies the server-authorized generation request. It
+prevents a delayed request or recovered attempt from taking ownership from the
+current response before its generation starts.
+
+`activeResponseMessageId` identifies that request's response before
+`activeGeneration` exists. It is `null` after the generation starts.
+
+`responseGenerationIds` keeps the latest generation owner for each response
+message. Late lifecycle events from a superseded generation stay in raw
+history but cannot alter the projected message, even after its replacement
+finishes.
+
+Generation requests share one durable lane, so model calls do not overlap.
+The queued-turn policy is the stronger ordering rule: a later user message is
+not scheduled until the current response's complete tool loop finishes. Lane
+FIFO alone would not prevent a newly appended user turn from overtaking a tool
+continuation that has not been appended yet.
 
 ## The built-in inputs
 
@@ -333,27 +364,32 @@ a terminal event.
 
 | Input | Events |
 | --- | --- |
-| `inputs.message(message)` | records a message and requests generation when its role is `user` |
-| `inputs.seed(message)` | records a message without requesting generation |
-| `inputs.approval(response)` | records an approval decision and requests continuation |
-| `inputs.input(response)` | records application input and requests continuation |
-| `inputs.requestInput(request)` | records an application-defined input request |
-| `inputs.retry(options)` | requests a fresh attempt after a failed partial response |
+| `inputs.message(message)` | records a message fact; the server schedules user turns |
+| `inputs.seed(message)` | records a trusted server message without scheduling a turn |
+| `inputs.approval(response)` | records an approval decision fact |
+| `inputs.input(response)` | records an application input response fact |
+| `inputs.requestInput(request)` | records a trusted server request for application input |
+| `inputs.retry(options)` | records `ai.retry.requested` for a failed response |
 | `inputs.interrupt(options)` | interrupts an active response |
 
 The builders hide stable event ids, so the same interaction is safe to resend.
-They return plain values accepted by both browser `push()` and server
-`append()`.
+Browser `push()` accepts user messages, approval and input responses,
+interruptions, and explicit retries. `inputs.seed()` and
+`inputs.requestInput()` are for trusted server appends. Browser inputs never
+append server scheduling, seeded non-user messages, or lifecycle events.
+Approval and input request/response payloads carry the active `generationId`;
+clients copy it from the pending request so a stale interaction cannot satisfy
+a later model step.
 
 `inputs` deliberately has no session lifecycle methods. The A2 log begins with
 the first append. Apps that use explicit `ai.session.created` or
-`ai.session.closed` lifecycle events push those ordinary contract events
+`ai.session.closed` lifecycle events append those trusted server facts
 directly.
 
 ## Add tools and approval
 
 Pass ordinary AI SDK tools to the server. Approval policy belongs in
-`generation`, beside the other `ToolLoopAgent` settings:
+`generation`, beside the other per-step settings:
 
 ```ts server/with-tools.ts
 import { tool } from 'ai'
@@ -405,6 +441,7 @@ export function ApprovalControls() {
           void push(
             ...inputs.approval({
               messageId: approval.messageId,
+              generationId: approval.generationId,
               approvalId: approval.approvalId,
               approved: true,
             }),
@@ -418,6 +455,7 @@ export function ApprovalControls() {
           void push(
             ...inputs.approval({
               messageId: approval.messageId,
+              generationId: approval.generationId,
               approvalId: approval.approvalId,
               approved: false,
               reason: 'Denied by the user',
@@ -432,9 +470,10 @@ export function ApprovalControls() {
 }
 ```
 
-`inputs.approval()` updates the approval part in the projected `UIMessage` and
-requests another model turn. The server then executes the approved tool or
-returns the denial to the model.
+`inputs.approval()` records only the decision and updates the approval part in
+the projected `UIMessage`. A built-in handler executes the approved tool or
+records a denied result. It never bypasses the same sibling join used by
+automatic tools.
 
 Tool activity follows the full AI SDK chunk lifecycle. Input validation errors,
 execution errors, denials, and preliminary and final outputs become durable
@@ -443,11 +482,36 @@ output completes it. Each result has its own event id, so a preliminary result
 cannot deduplicate the final one. Dynamic-tool, provider-executed, provider
 metadata, and tool metadata fields are preserved in the projection.
 
+Independent tool handlers run concurrently as soon as their durable inputs and
+authorization are ready. There is no fixed tool concurrency limit. A private
+coordinator reducer tracks generation closure, cancellation, calls, approvals,
+and terminal results for the active response. Its retained state is bounded;
+completed responses do not accumulate in the coordinator. Each join reads a
+durable reducer snapshot plus the log tail through `ctx.session.state()`. The snapshot
+is only a cache. Recovery can rebuild the same coordinator state from the event
+log after process death.
+
+A continuation needs the generation to close and every sibling tool to have a
+terminal success, error, or denied result. Racing join handlers call
+`ctx.session.append()` with the same deterministic continuation ID, so append
+idempotency resolves the race. A handler's single-owner terminal result is
+returned and committed atomically with that handler's completion. Preliminary
+streaming tool outputs use immediate appends. An approved provider-executed
+call can satisfy the join through its response. A provider tool that declares
+deferred-result support can wait for its provider result instead of a local
+executor. The authenticated provider callback appends that `ai.tool.result`
+through the trusted server session API. Browser `push()` rejects lifecycle
+events, including provider results.
+
 `inputs.input()` provides the same durable request/response shape for
 application-defined input. Its value stays in raw history and
 `state.pendingInputs`; resolve instructions dynamically or replace `generate`
 when the value should become model context.
 
+Approval and application-input request/response facts carry the active
+`generationId`. Echo that value from the pending request so a delayed UI action
+cannot authorize or resume a later model step.
+
 ## Interrupt and retry
 
 Interrupt the active response from the client:
@@ -489,10 +553,18 @@ keeps the partial response the user actually saw, and turns incomplete visible
 tools into `output-error`. Progress, completion, or failure from that generation
 cannot reactivate it after the interruption.
 
+`generationId` is optional only between `ai.generation.requested` and
+`ai.generation.started`, when no generation id exists yet. In that phase, use
+`state.activeResponseMessageId` as `messageId` and omit `generationId`. Once
+`activeGeneration` exists, copy both ids from it so a delayed interruption
+cannot stop a later generation.
+
 After a failed model call, `inputs.retry({ messageId, responseMessageId,
-retryId })` starts a fresh attempt. `retryId` identifies the user's action, so
-resending one retry is safe while a later retry remains distinct. Failed
-partial progress remains in raw history but is excluded from the new prompt.
+retryId })` records a retry request. The server schedules its fresh attempt.
+`retryId` identifies the user's action, so resending one retry is safe while a
+later retry remains distinct. Failed partial progress remains in raw history
+but is excluded from the new prompt. Later user messages remain queued while
+the failed response awaits an explicit retry or interruption.
 
 ## Append from the server
 
@@ -567,7 +639,10 @@ different server assembly:
 ```ts server/custom.ts
 import { z } from 'zod'
 import { agent } from 'experimental-a2/ai'
-import { createHandlers } from 'experimental-a2/ai/server'
+import {
+  createHandlers,
+  validateAgentPush,
+} from 'experimental-a2/ai/server'
 import { createServer } from 'experimental-a2/server'
 
 const supportAgent = agent({
@@ -584,6 +659,7 @@ const aiHandlers = createHandlers({
 
 export const customAssistantServer = createServer({
   contract: supportAgent.contract,
+  validatePush: validateAgentPush,
   handlers: {
     ...aiHandlers,
     'ticket.linked': async ({ event }) => {
@@ -596,16 +672,18 @@ export const customAssistantServer = createServer({
 
 Application events stay fully typed. The standard AI reducer ignores unknown
 events, so another reducer can project application state without forking the AI
-protocol.
+protocol. `validateAgentPush` preserves the same browser boundary as
+`createAgentServer()`: user facts may enter through a parsed push, while model
+scheduling, tool lifecycle, and trusted seed messages stay server-authored.
 
 ### Replace generation, not durability
 
-The default generator uses the AI SDK `ToolLoopAgent`. Replace only that
-model-facing step for fixtures, provider routing, or a different AI SDK
-assembly:
+The default generator uses AI SDK `streamText()` for one model step. Replace
+only that model-facing step for fixtures, provider routing, or a different AI
+SDK assembly:
 
 ```ts server/custom-generation.ts
-import { ToolLoopAgent, createAgentUIStream } from 'ai'
+import { convertToModelMessages, streamText } from 'ai'
 import { createAgentServer } from 'experimental-a2/ai/server'
 import { assistant } from '../assistant'
 
@@ -615,26 +693,20 @@ export const customGenerationServer = createAgentServer({
   generate: async ({
     messages,
     model,
-    tools,
     instructions,
-    generation,
-    generationId,
     responseMessageId,
     signal,
   }) => {
-    const sdkAgent = new ToolLoopAgent<never, typeof tools>({
-      ...generation,
-      id: generationId,
+    const result = streamText({
       model,
-      tools,
+      messages: await convertToModelMessages(messages),
+      abortSignal: signal,
       ...(instructions === undefined ? {} : { instructions }),
     })
 
-    return createAgentUIStream({
-      agent: sdkAgent,
-      uiMessages: messages,
+    return result.toUIMessageStream({
+      originalMessages: messages,
       generateMessageId: () => responseMessageId,
-      abortSignal: signal,
     })
   },
 })
@@ -642,17 +714,26 @@ export const customGenerationServer = createAgentServer({
 
 `generate` receives compacted messages, resolved model and instructions, tools,
 generation settings, durable request identity, current state and history, and
-the abort signal. It returns one `ReadableStream<UIMessageChunk>`. A2 still
-records progress, tool and approval events, completion, interruption, and
-failure.
+the abort signal. It returns exactly one model step as a
+`ReadableStream<UIMessageChunk>`. A tool-aware replacement sends definitions to
+the model without running local `execute` functions. A2 still owns durable
+progress, tool execution, approval, continuation, interruption, and failure.
 
 ## Delivery semantics
 
-Model calls and tools run inside an at-least-once A2 handler. Durable event ids
-make lifecycle appends effectively once, and A2 marks an incomplete attempt
-`superseded` before starting its replacement. Model providers and external tool
-side effects remain outside the log. Give side-effecting tools their own
-idempotency strategy, normally keyed by the AI SDK tool call id.
+Model steps and tools run inside at-least-once A2 handlers. The returned-event
+transaction makes each successful handler completion and its terminal events
+one atomic durable operation. Deterministic ids make scheduling and lifecycle
+appends effectively once, and A2 marks an incomplete model attempt
+`superseded` before starting its replacement.
+
+Provider calls and external tool side effects remain outside that transaction.
+A process can die after an external effect succeeds and before its handler
+completion commits, so recovery may run the call again. Give side-effecting
+tools their own idempotency strategy, normally keyed by the AI SDK tool call
+id. This is the same at-least-once boundary as every other A2 handler. A fast
+tool may also start before its model step later fails. The failure prevents a
+continuation, but it cannot roll back that external effect.
 
 Configure [production recovery](/guides/production) exactly as for any other A2
 server. Recovery wakes an interrupted generation after the original serverless

package/docs/guides/07-devtools.mdx

@@ -44,7 +44,7 @@ returning a `Response` supports a redirect or authentication challenge.
 ## Causal forest
 
 Every stored `cause` connects a child to the event index and handler attempt
-whose `ctx.append` first persisted it. The dashboard builds that forest
+whose `ctx.session.append` first persisted it. The dashboard builds that forest
 directly from the session log. It does not need a trace table or another write
 on the append path.
 
@@ -75,10 +75,13 @@ dashboard shows the first dispatch time as unknown instead of moving it to
 `createdAt` or `lastClaimedAt`.
 
 The bar is event lifetime, not handler execution time. A2 stores lifecycle
-summaries, not one span row for every attempt. Time spent waiting, running a
-handler, coordinating a lease, or waiting for recovery remains one honest
+summaries, not one span row for every attempt. Time spent waiting for a lane,
+running a handler, holding a claim, or waiting for recovery remains one honest
 interval.
 
+An event type without a handler is complete at append. Its bar has no waiting
+time or dispatch marker, and its attempt count stays at zero.
+
 Snapshots appear as their reducer name, event frontier, and last update time.
 The dashboard does not send cached snapshot state to the browser.
 

package/docs/guides/08-application-data.mdx

@@ -34,9 +34,9 @@ orders / order-43
 agents / run-abc
 ```
 
-The session is the boundary A2 orders, recovers, folds, and streams. Put events
-in the same session when they must be ordered or viewed together. Split work
-that should progress independently.
+The session is the boundary A2 logs, recovers, folds, and streams. Put events
+in the same session when they form one history or view. Handler execution is
+concurrent unless events share a lane.
 
 A contract is not a table. A session is not a table either. One contract
 usually serves many sessions, and one session may describe changes that touch
@@ -77,8 +77,7 @@ a cost: boards and search span many sessions and need another query model. If
 those collection views are the center of the product, let the database lead.
 
 Do not put an entire workspace in one session just to make cross-issue queries
-possible. Every event in one session is ordered together, and every client of
-that session follows the same growing log.
+possible. Every event joins the same growing log and every client follows it.
 
 ## Database writes from handlers
 
@@ -99,7 +98,7 @@ integration:
 
 - it is eventually consistent with the session logs;
 - writes must be idempotent;
-- A2 orders events within one session, not across sessions;
+- A2 assigns log order within one session, not across sessions;
 - A2 does not expose one API that scans and replays every session to rebuild
   the index.