experimental-a2 0.3.0 → 0.5.0

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

@@ -37,8 +37,8 @@ in the server module.
 
 ## Connect the model
 
-`createAgentServer()` adds the AI SDK runner and A2's ordinary storage,
-recovery, telemetry, and handler machinery:
+`createAgentServer()` adds the AI SDK runner and A2's ordinary store,
+scheduler, telemetry, and handler machinery:
 
 ```ts server/assistant.ts
 import { createAgentServer } from 'experimental-a2/ai/server'
@@ -63,52 +63,80 @@ model for each generation.
 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.
+and continuation between steps. Responses have no step limit by default. Set
+`maxSteps` to a positive integer to limit one complete assistant response.
+Individual providers decide which model settings they support. `generation`
+therefore excludes `stopWhen`, tool execution callbacks, tool callers, sandbox
+execution, and the tool approval secret. Everything else, including
+`toolsContext`, passes through to the AI SDK untouched. A local tool reads its
+durable execution context later, from the handler that runs it. Model-step
+timeouts are supported; tool-execution timeouts are not.
+
+### Store assistant metadata
+
+Extend the agent's `UIMessage` type to keep generation status and usage on the
+assistant message:
+
+```ts metadata-assistant.ts
+import type { LanguageModelUsage, UIMessage } from 'ai'
+import { agent } from 'experimental-a2/ai'
 
-`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
-or backend.
+export type MetadataAssistantMessage = UIMessage<{
+  status: 'writing' | 'complete'
+  usage?: LanguageModelUsage
+}>
 
-## Expose the event stream
+export const metadataAssistant = agent<MetadataAssistantMessage>({
+  name: 'metadata-assistant',
+})
+```
 
-One HTTP route gives the browser a read and write path. `GET` streams events;
-`POST` accepts optimistic pushes:
+Map the AI SDK's standard stream parts to that metadata type:
 
-```ts app/api/agent-events/route.ts
-import { A2Error } from 'experimental-a2'
-import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
-import { assistantServer } from '@/server/assistant'
+```ts server/metadata-assistant.ts
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { metadataAssistant } from '../metadata-assistant'
+
+export const metadataAssistantServer = createAgentServer({
+  agent: metadataAssistant,
+  model: 'openai/gpt-5.6-terra',
+  messageMetadata: ({ part }) => {
+    if (part.type === 'start') return { status: 'writing' as const }
+    if (part.type === 'finish') {
+      return { status: 'complete' as const, usage: part.totalUsage }
+    }
+    return undefined
+  },
+})
+```
 
-export async function GET(req: Request): Promise<Response> {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  const startAt = Number(searchParams.get('index')) || 0
+The default generator passes `messageMetadata` to the AI SDK's
+`toUIMessageStream()`. The callback receives the generation context and its
+current `TextStreamPart`. Its return type follows the metadata type in the
+agent's `UIMessage`. Metadata on standard `start` and `finish` chunks enters
+the event log with the rest of the stream. A2 shallow-merges those values onto
+the projected assistant message, so the example exposes `writing` immediately
+and keeps final token usage after completion. The callback is synchronous.
 
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
+`experimental-a2/ai/server` is server-only. The isomorphic
+`experimental-a2/ai` entry point contains the contract, reducer, schemas,
+`handlerContext()`, and pure inputs; it never imports a model provider or
+backend.
 
-  // here's where you'd do auth, or any other checks
+## Expose the event stream
 
-  return sseResponse(assistantServer.session(sessionId).stream({ startAt }))
-}
+One HTTP route gives the browser a read and write path. `GET` streams events;
+`POST` accepts optimistic pushes:
 
-export async function POST(req: Request): Promise<Response> {
-  try {
-    const { sessionId, events } = await parsePushBody(req)
+```ts app/api/agent-events/route.ts
+import { handle } from 'experimental-a2/http'
+import { assistantServer } from '@/server/assistant'
 
+export const { GET, POST } = handle(assistantServer, {
+  before({ request, intent }) {
     // here's where you'd do auth, or any other checks
-
-    const appended = await assistantServer.session(sessionId).append(...events)
-    return Response.json(appended)
-  } catch (error) {
-    return errorResponse(error)
-  }
-}
+  },
+})
 ```
 
 The route never calls the model directly. The browser appends user facts such
@@ -153,16 +181,12 @@ export default async function AgentPage({
   const { sessionId } = await params
   const session = assistantServer.session(sessionId)
   const { state, index } = await session.state(assistant.reducer)
-  const initialEvents = (await session.history()).filter(
-    (event) => event.index <= index,
-  )
 
   return (
     <SessionProvider
       sessionId={sessionId}
       initialState={state}
       initialIndex={index}
-      initialEvents={initialEvents}
     >
       <AgentClient />
     </SessionProvider>
@@ -174,8 +198,8 @@ An empty session folds to the initial `AIState`. Its log is created lazily when
 the first message is pushed.
 
 Start the session from the previous route, but wait for its durable append
-before navigating. The destination server render then sees the message and its
-events in one complete response instead of racing the `POST`:
+before navigating. The destination server render then sees the message in its
+folded state instead of racing the `POST`:
 
 ```tsx app/agent/new-agent-session.tsx
 'use client'
@@ -194,8 +218,8 @@ export async function openAgent(
 ```
 
 The draft clears immediately while the append is in flight and can be restored
-if it fails. Once navigation begins, SSR already has a durable frontier and
-event history. When the destination provider mounts, it resolves the same live
+if it fails. Once navigation begins, SSR already has folded state at a durable
+frontier. When the destination provider mounts, it resolves the same live
 session and reconciles that server render without replacing the object. Idle
 session objects expire after five minutes by default; configure `gcTime` on
 `createClient` when a different lifetime fits the app.
@@ -305,9 +329,34 @@ 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.
 
+Pass `{ generate: false }` when a user message should update the conversation
+without starting a model turn:
+
+```ts app/agent/passive-message.ts
+import type { UIMessage } from 'ai'
+import { inputs } from 'experimental-a2/ai'
+import { assistantClient } from './session'
+
+export async function recordPassiveMessage(
+  sessionId: string,
+  message: UIMessage,
+): Promise<void> {
+  await assistantClient
+    .session(sessionId)
+    .push(...inputs.message(message, { generate: false }))
+}
+```
+
+The passive user message still appears in `AIState.messages`. A later user
+message with the default generation behavior includes passive user messages
+before it in model context. Passive user messages after that trigger remain
+outside its prompt and wait for the next generating message. This ordering
+supports ambient agents without letting new background context leak into an
+already queued turn.
+
 ## What happens after `push()`
 
-One user interaction becomes a durable sequence:
+One generating user interaction becomes a durable sequence:
 
 ```text
 browser  ai.message.created             optimistic, then durable
@@ -335,10 +384,15 @@ stores every AI SDK chunk once. The reducer and the exported
 
 `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.
+`terminalRequestIds`, `terminalGenerations`, `pendingApprovals`,
+`pendingInputs`, `tools`, `compaction`, per-generation `usage`, and the last
+generation `error`.
+`activeProjection` is the temporary indexed generation frontier used for exact
+interruption. It remains available after a generation step completes while the
+response waits on tool, approval, or input barriers, and after a generation
+fails while it awaits retry or interruption. It clears when the response
+completes, is interrupted or superseded, a retry begins, or a later generation
+replaces it.
 
 `activeRequestId` identifies the server-authorized generation request. It
 prevents a delayed request or recovered attempt from taking ownership from the
@@ -364,8 +418,8 @@ continuation that has not been appended yet.
 
 | Input | Events |
 | --- | --- |
-| `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.message(message, { generate? })` | records a message fact; `false` keeps context without scheduling |
+| `inputs.seed(message)` | records `generate: false`; non-user roles require a trusted append |
 | `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 |
@@ -373,10 +427,15 @@ continuation that has not been appended yet.
 | `inputs.interrupt(options)` | interrupts an active response |
 
 The builders hide stable event ids, so the same interaction is safe to resend.
+Generation scheduling considers only user-role `ai.message.created` facts.
+Assistant and system message facts remain context regardless of the `generate`
+field, and model output is recorded as generation progress rather than a new
+message fact, so an assistant reply cannot recursively schedule another turn.
 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.
+interruptions, and explicit retries. `inputs.requestInput()` and non-user
+messages built with `inputs.seed()` 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.
@@ -388,8 +447,9 @@ directly.
 
 ## Add tools and approval
 
-Pass ordinary AI SDK tools to the server. Approval policy belongs in
-`generation`, beside the other per-step settings:
+Tools are ordinary AI SDK `tool()` definitions. A2 passes them through to
+the AI SDK without interpreting or restricting them. Approval policy
+belongs in `generation`, beside the other per-step settings:
 
 ```ts server/with-tools.ts
 import { tool } from 'ai'
@@ -421,6 +481,90 @@ export const assistantServerWithTools = createAgentServer({
 })
 ```
 
+The AI SDK infers the tool input and output from its schemas and
+`execute`. A2 additionally runs each local `execute` inside an ambient
+scope carrying the current durable handler attempt. Read it with
+`handlerContext(agent)` from `experimental-a2/ai`: it returns the same
+typed context bag an event handler receives, with `event`, `attempt`,
+`session`, and `signal`. Automatic tools see an `ai.tool.called` event.
+Approved tools see the `ai.approval.responded` event that authorized
+them. Narrow `ctx.event.type` if you need fields specific to either
+event. The agent argument carries the types; A2 verifies it against the
+server executing the tool and throws when a tool written for one agent
+runs under another, or when `handlerContext()` is called outside a tool
+execution. The scope survives awaited helpers and async iteration, so
+any code below `execute` can read it.
+
+`generation.toolApproval` is evaluated during the model step, before A2 has a
+durable tool handler. Static policies such as the example above are simplest.
+An input-dependent policy may be a function that returns `user-approval` or
+`approved` from the validated tool input. Approval predicates are
+re-evaluated on recovery for the same durable tool call, so they must be
+deterministic over the tool input; an impure predicate can fork one
+durable call's flow. Model-phase options such as `toolsContext` and
+per-tool `contextSchema` are yours and pass through to the AI SDK
+untouched. Any model-phase hook that receives tool definitions sees
+them without local `execute` functions. The durable A2 context is
+ambient only inside `execute`.
+
+The agent argument supplies types, not infrastructure. The context's
+`session` belongs to the server executing the tool, so its `schedule()`
+method uses that server's scheduler. For example, this tool schedules a
+reminder as a new user message:
+
+```ts server/set-reminder.ts
+import { tool } from 'ai'
+import { handlerContext, inputs } from 'experimental-a2/ai'
+import { z } from 'zod'
+import { assistant } from '../assistant'
+
+export const setReminder = tool({
+  description: 'Set a reminder for yourself',
+  inputSchema: z.object({
+    delaySeconds: z.number().int().min(1).max(6 * 24 * 60 * 60),
+    reminder: z.string(),
+  }),
+  execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
+    const ctx = handlerContext(assistant)
+    await ctx.session.schedule(
+      `reminder:${toolCallId}`,
+      { delay: `${delaySeconds}s` },
+      ...inputs.message({
+        id: `reminder:${ctx.event.id}`,
+        role: 'user',
+        parts: [{ type: 'text', text: `Reminder: ${reminder}` }],
+      }),
+    )
+
+    return { scheduled: true, delaySeconds }
+  },
+})
+```
+
+Add `setReminder` to the server's `tools` and configure a
+[scheduler](/guides/production).
+The numeric schema lets the model choose any whole-second delay in the
+provider's supported range instead of selecting from a fixed application enum.
+The example uses A2's six-day Vercel Queues limit. The seventh retention day is
+reserved for delivery and retries. Adjust the maximum to match your scheduler
+and plan.
+The schedule name uses `toolCallId`, and the message id uses the durable
+triggering event id. A retry therefore converges on the same timer and message,
+even if a provider reuses tool-call ids in a later generation. When the timer
+arrives, `inputs.message()` records an ordinary `ai.message.created` fact. The
+queued-turn policy starts a fresh response after the active response completes
+or is interrupted. A failed response must be retried or interrupted first.
+If the scheduler send fails ambiguously or transiently, A2 retries the same
+durable tool handler so that identity and target time stay fixed. Deterministic
+adapter rejections are terminal tool errors. A missing scheduler is also a
+normal tool error, so configure one before exposing the tool.
+
+A tool that never reads `handlerContext()` is just an AI SDK tool;
+nothing else changes. To test a context-reading tool directly, wrap the
+call with `runWithHandlerContext(ctx, fn)` from
+`experimental-a2/ai/server`: inside `fn`, `handlerContext()` returns
+`ctx` for any agent.
+
 The AI SDK emits an approval request instead of executing the tool. A2 records
 it as `ai.approval.requested`, and the reducer adds it to
 `state.pendingApprovals`. Respond from the same optimistic client path:
@@ -524,16 +668,38 @@ import { useSession } from '../session'
 export function StopButton() {
   const { state, push, index } = useSession()
   const active = state.activeGeneration
+  const requested =
+    state.activeRequestId && state.activeResponseMessageId
+      ? {
+          messageId: state.activeResponseMessageId,
+          requestId: state.activeRequestId,
+        }
+      : null
+  const waiting =
+    state.pendingApprovals[0] ??
+    state.pendingInputs[0] ??
+    state.tools.find((tool) => tool.status === 'running')
+  const target = active
+    ? {
+        messageId: active.responseMessageId,
+        generationId: active.generationId,
+      }
+    : requested ??
+      (waiting
+        ? {
+            messageId: waiting.messageId,
+            generationId: waiting.generationId,
+          }
+        : null)
 
-  if (!active) return null
+  if (!target) return null
 
   return (
     <button
       onClick={() =>
         void push(
           ...inputs.interrupt({
-            messageId: active.responseMessageId,
-            generationId: active.generationId,
+            ...target,
             reason: 'Stopped by the user',
             lastSeenIndex: index,
           }),
@@ -548,16 +714,23 @@ export function StopButton() {
 
 The optimistic event updates the UI immediately and reaches A2's cancellation
 channel. `lastSeenIndex` is the exact confirmed log frontier visible when the
-user clicked. The reducer rewinds chunk and tool projections to that frontier,
-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.
+user clicked. The reducer rewinds the indexed generation projection to that
+frontier, keeps the partial response the user actually saw, and turns
+incomplete visible tools into `output-error`. An accepted interruption
+terminally fences that request or generation. Later generation, tool, approval,
+input, and compaction events remain in raw history but cannot reactivate it or
+alter the projection.
+Completed tool results at or before the visible frontier remain completed.
+
+Between `ai.generation.requested` and `ai.generation.started`, copy
+`activeRequestId` as `requestId` and `activeResponseMessageId` as `messageId`.
+Once `activeGeneration` exists, send its `generationId` and
+`responseMessageId` instead. A request-owned interruption remains valid if
+that same request starts before the append commits. Every interruption has
+exactly one of `requestId` or `generationId`, so a delayed action cannot stop
+later work that reuses the response message. After a generation completes,
+copy the owner from a pending approval, pending input, or running tool while
+the response is still waiting.
 
 After a failed model call, `inputs.retry({ messageId, responseMessageId,
 retryId })` records a retry request. The server schedules its fresh attempt.
@@ -630,6 +803,8 @@ The convenience API is ordinary A2 parts:
 - `createReducer({ contract })` builds the standard `AIState` projection for a
   compatible contract.
 - `agent()` combines the built-in protocol, application events, and reducer.
+- `tool()` binds an AI SDK function-tool definition to an agent's typed A2
+  handler context.
 - `createHandlers({ agent, ... })` returns the AI handler table.
 - `createAgentServer()` combines those handlers with `createServer()`.
 
@@ -674,7 +849,7 @@ Application events stay fully typed. The standard AI reducer ignores unknown
 events, so another reducer can project application state without forking the AI
 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.
+scheduling, tool lifecycle, and seeded non-user messages stay server-authored.
 
 ### Replace generation, not durability
 
@@ -718,6 +893,9 @@ 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.
+`messageMetadata` applies only to the default generator. A custom `generate`
+function owns its metadata and can pass a callback to `toUIMessageStream()` or
+emit typed metadata chunks itself.
 
 ## Delivery semantics
 
@@ -735,6 +913,6 @@ 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
-invocation disappears.
+Configure a [production scheduler](/guides/production) exactly as for any other A2
+server. It recovers an incomplete generation attempt after the original
+serverless invocation disappears.

package/docs/guides/07-devtools.mdx

@@ -1,6 +1,6 @@
 ---
 title: Devtools
-description: Mount one read-only handler to inspect sessions, event lifecycles, failures, and snapshots from the durable log.
+description: Mount one authenticated, read-only handler to inspect and export durable sessions from the browser, CLI, or a test.
 ---
 
 ## Mount the dashboard
@@ -16,8 +16,9 @@ import { billingServer, ordersServer } from '@/server'
 const devtools = createDevtools({
   servers: [ordersServer, billingServer],
   authorize: async (_request) => {
-    // Return true after your auth or any other checks.
-    return process.env.NODE_ENV !== 'production'
+    // your authentication and authorization check:
+    // return await canInspectA2(_request)
+    return process.env.NODE_ENV === 'development'
   },
 })
 
@@ -36,10 +37,132 @@ then takes over navigation and live updates.
 The selected contract and session stay in the URL. Refreshing preserves the
 view, links open the same session, and browser back and forward navigation work.
 
-Omit `authorize` for the same development-only behavior shown above. An
-unguarded handler returns 404 in production. In a deployed dashboard, provide
-your application's access check. Returning `false` hides the route with a 404;
-returning a `Response` supports a redirect or authentication challenge.
+The mounted route is the policy boundary for the complete Devtools surface.
+`authorize` runs before the browser application, JSON inspection endpoints,
+live stream, capture export, and CLI requests. A2 does not maintain a second
+credential store. Use your application's authentication and authorization at
+this route, and give Devtools the same protection as the durable data it reads.
+
+Omit `authorize` only for local development. An unguarded handler is available
+when `NODE_ENV` is exactly `development`. It returns 404 when the value is
+anything else, including unset. In a deployed dashboard, provide your
+application's access check. Only a literal `true` grants access. Returning
+`false` hides the route with a 404. Returning a `Response` supports a redirect
+or authentication challenge.
+
+## Inspect from the CLI
+
+The `a2 devtools` CLI reads the same mounted route. Set its URL once, then list
+contracts and sessions or inspect one session:
+
+```bash terminal
+export A2_DEVTOOLS_URL='https://example.com/api/a2/devtools'
+export A2_DEVTOOLS_TOKEN="$DEVTOOLS_BEARER_TOKEN"
+
+a2 devtools contracts
+a2 devtools sessions --contract orders --limit 50
+a2 devtools show --contract orders --session order-42
+a2 devtools show --contract orders --session order-42 --format json
+```
+
+`A2_DEVTOOLS_TOKEN` becomes an `Authorization: Bearer` header. For a different
+environment variable, pass `--bearer-env DEVTOOLS_TOKEN`. Custom headers use
+`--header-env HEADER=ENV`, which is repeatable. The CLI accepts credential
+values only through environment variables. It rejects literal token and header
+flags, credentials embedded in `--url`, and URLs with query strings. Requests
+do not follow redirects, so an authentication redirect cannot forward those
+headers to another origin.
+
+Human-readable output is the default. `--format json` emits one JSON value and
+`--format ndjson` emits one record per line. Session listing also accepts
+`--cursor` for the next page. `--url` overrides `A2_DEVTOOLS_URL`.
+
+## Export and check a capture
+
+Export writes one exact `.a2log` capture. `check` verifies a live capture and
+can assert operational conditions. `verify` checks a saved file without a
+server URL or credentials:
+
+```bash terminal
+a2 devtools export \
+  --contract orders \
+  --session order-42 \
+  --output artifacts/order-42.a2log
+
+a2 devtools check \
+  --contract orders \
+  --session order-42 \
+  --settled \
+  --no-dead-letters \
+  --no-caught-failures \
+  --max-redispatches 0
+
+a2 devtools verify artifacts/order-42.a2log
+```
+
+An export contains a versioned manifest, every durable event in log order,
+snapshot metadata, and a footer with counts and a SHA-256 digest. Event records
+retain payloads, causal edges, lanes, dispatch attempts, failures, claims, and
+completion metadata. Snapshot state is not included. The CLI checks the digest
+and structure before writing the capture. It refuses to replace an existing
+file unless you pass `--force`, and creates capture files with owner-only
+permissions (`0600`).
+
+The CLI and browser read large sessions in bounded pages. The first page
+freezes a finite event frontier, so messages appended during the download do
+not extend it. Export includes every event through that frontier. If a store or
+provider returns a gap or ends early, the read fails instead of producing a
+partial capture with a valid footer.
+
+The capture is canonical UTF-8 NDJSON. If a durable payload contains a value
+that JSON would coerce or omit, export fails instead of signing a changed
+representation. Keep event payloads JSON-compatible when they need to be
+portable.
+
+Capture verification and failed `check` assertions exit with status 2. Usage,
+network, and filesystem errors exit with status 1. The live commands support
+the same human, JSON, and NDJSON output modes, which makes `check` useful in CI.
+
+An exact capture is sensitive production data. It can contain user payloads,
+AI prompts and tool results, provider metadata, usage, and failure messages
+when those values exist in the event log. Route authorization controls who can
+download a capture. It does not redact or encrypt the downloaded file. Store,
+share, and expire `.a2log` files under the same policy as the source log.
+
+## Replay reducer state offline
+
+`experimental-a2/testing` loads a capture in Node.js, verifies it against the
+current contract, and folds its events through a reducer:
+
+```ts test/replay-order.ts
+import { loadCapture, replayCapture } from 'experimental-a2/testing'
+import { orders } from '@/contracts'
+import { ordersReducer } from '@/reducer'
+
+export async function replayOrder(path: string) {
+  const loaded = await loadCapture(path, orders)
+
+  const afterFirstEvent = replayCapture(loaded, ordersReducer, {
+    throughIndex: 1,
+  })
+  const current = replayCapture(loaded, ordersReducer)
+
+  return { afterFirstEvent, current }
+}
+```
+
+`loadCapture()` verifies the capture digest and identity, validates every event
+type and payload through the current contract schemas, and revives the public
+`createdAt` timestamp as `Date`. The loaded value also keeps `rawEvents` with
+the exact wire payloads and operational metadata.
+
+`throughIndex` is inclusive. Pass `0` to return the reducer's initial state at
+index 0. Replay always folds immutable events. Captured snapshots contain
+metadata only and are not used as reducer state.
+
+This is pure reducer replay. It does not construct a server, run handlers,
+invoke a model or tool, or repeat an external side effect. Test handler or model
+behavior with a fresh log and explicit test doubles instead.
 
 ## Causal forest
 
@@ -76,7 +199,7 @@ dashboard shows the first dispatch time as unknown instead of moving it to
 
 The bar is event lifetime, not handler execution time. A2 stores lifecycle
 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
+running a handler, holding a claim, or waiting for the scheduler remains one honest
 interval.
 
 An event type without a handler is complete at append. Its bar has no waiting
@@ -96,9 +219,11 @@ While work is pending, the handler checks processing metadata quickly. It
 backs off after the session settles and emits heartbeats for intermediaries.
 Only sessions someone is viewing have a live inspection loop.
 
-## Custom logs
+## Custom stores
 
 The memory, SQLite, Postgres, and Redis adapters provide the optional read-only
-inspection interface. A custom `A2Log` can implement `inspect.listSessions`
-and `inspect.listSnapshots` to appear in the dashboard. Logs without inspection
-continue to work normally; their devtools endpoint returns 501.
+inspection interface. A custom `A2Store` can implement `inspect.listSessions`
+and `inspect.listSnapshots` to appear in the dashboard. Add
+`inspect.readEvents` for bounded storage-native event pages. Without it, A2
+reads the complete session for each page and slices it in memory. Stores without
+inspection continue to work normally; their devtools endpoint returns 501.

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

@@ -49,7 +49,7 @@ projects, issue lists, labels, permissions, search, joins, pagination, and
 reporting. Use its transactions for constraints that must hold across several
 rows before a request returns.
 
-The Postgres adapter in `experimental-a2/log-postgres` stores A2's own logs. It does not
+The Postgres adapter in `experimental-a2/store-postgres` stores A2's own event logs. It does not
 watch your application tables, turn their changes into events, or combine an
 A2 append with your SQL transaction. The A2 log and your tables may share one
 Postgres database, but they remain separate data models and transaction