experimental-a2 0.14.1 → 0.16.0

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

@@ -20,9 +20,9 @@ AI_GATEWAY_API_KEY=your_api_key
 
 ## Define the agent
 
-`agent()` defines an isomorphic event contract and its standard `AIState`
-reducer. The same value types the server, server-rendered state, and optimistic
-client updates.
+`agent()` defines an isomorphic event contract, normalized `AIStoredState`,
+and its `AIState` view. The same reducer types server snapshots, hydration,
+and optimistic client updates.
 
 ```ts assistant.ts
 import { agent } from 'experimental-a2/ai'
@@ -399,7 +399,7 @@ stores every AI SDK chunk once. The reducer and the exported
 `UIMessage`; cumulative message snapshots are not duplicated in the log.
 
 `AIState` exposes `messages`, `status`, `activeGeneration`, `activeRequestId`,
-`activeResponseMessageId`, `activeProjection`, `responseGenerationIds`,
+`activeResponseMessageId`, `activeProjection`, `responseOwners`,
 `terminalRequestIds`, `terminalGenerations`, `pendingApprovals`,
 `pendingInputs`, `tools`, `compaction`, per-generation `usage`, and the last
 generation `error`.
@@ -417,11 +417,23 @@ 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
+`responseOwners` keeps the latest generation ID, request ID, and attempt 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.
 
+A2 generates fixed-length deterministic IDs in its reserved `a2.ai:` namespace
+for requests, generations, responses, and worker lifecycle events. Treat those
+IDs as opaque. An assistant response uses its first model-request event's ID. Generation requests carry
+`responseMessageId` explicitly; tool continuations also carry `sourceGenerationId`.
+Ownership comes from these fields and the generation's `requestId` and `attempt`,
+so ID strings never embed the preceding tool loop.
+
+Approval and application-input events carry both `requestId` and `generationId`.
+Copy both from the pending approval, pending input, or active generation when
+sending a response. `activeRequestReason` and `activeRequestSourceGenerationId`
+describe the current request independently from the message projection.
+
 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
@@ -442,7 +454,7 @@ continuation that has not been appended yet.
 | `inputs.retry(options)` | requests a fresh attempt for a failed response |
 | `inputs.stop({ turnId })` | ends the observed turn and advances |
 | `inputs.steer({ turnId, message })` | prioritizes input after the observed turn's current step finishes |
-| `inputs.queue.edit({ message, expectedRevision })` | edits a pending input |
+| `inputs.queue.edit({ message })` | edits a pending input |
 | `inputs.queue.move({ inputId, beforeId })` | reorders pending input; `null` means the end |
 | `inputs.queue.remove({ inputId })` | removes pending input from the inbox |
 | `inputs.queue.sendNow({ inputId, turnId })` | atomically prioritizes queued input and interrupts the observed turn |
@@ -610,6 +622,7 @@ export function ApprovalControls() {
         onClick={() =>
           void push(
             ...inputs.approval({
+              requestId: approval.requestId,
               messageId: approval.messageId,
               generationId: approval.generationId,
               approvalId: approval.approvalId,
@@ -624,6 +637,7 @@ export function ApprovalControls() {
         onClick={() =>
           void push(
             ...inputs.approval({
+              requestId: approval.requestId,
               messageId: approval.messageId,
               generationId: approval.generationId,
               approvalId: approval.approvalId,
@@ -738,12 +752,19 @@ 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.
+retryId })` records a retry request. The server reruns that failed model call.
+Earlier completed model steps and their tool results remain, including steps
+completed after the latest compaction. The committed summary also remains. For
+example, if a tool succeeds after compaction and the next model call fails, retry
+uses the summary and that tool's result.
 `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
+later retry remains distinct. The failed model call's uncommitted step remains in
+raw history but is excluded from the new prompt and response. Later user messages remain queued while
 the failed response awaits an explicit retry or interruption.
 
+Applications own conversation forks and edit-and-resend flows for previously
+admitted messages. A2's retry operation continues the current response.
+
 ## Append from the server
 
 Browser interactions should use `push()` for instant state. Server-originated
@@ -802,17 +823,17 @@ failure or use an explicit threshold in that case.
 The default threshold is 75% of the context window. A larger configured
 `generation.maxOutputTokens` lowers the threshold further to reserve that output
 allowance. This is an input-context policy, not a new output limit. Limits and
-metadata status are available in `state.modelMetadata`.
+metadata status are available through an explicit transcript reducer read.
 
 `compaction: { thresholdTokens: 80_000 }` overrides discovery with an explicit
 positive safe integer. `compaction: { instructions: 'Preserve exact IDs.' }`
 adds guidance to the built-in summary prompt while keeping the derived threshold.
 `compaction: false` disables both compaction and metadata lookup. The `compaction`
 option can also be a resolver receiving the same
-`{ event, state, session, signal }` context as `model` and `instructions`. It
+`{ event, messages, session, signal }` context as `model` and `instructions`. It
 returns `false`, automatic options, or a custom policy once per generation and
 can await `session.state(settingsReducer)` to read application settings.
-Use this to select a threshold from the checkpointed AI state.
+Use this to select a threshold from application settings at the prompt boundary.
 Changes after resolution apply to a later model step. Disabling compaction
 preserves summaries that were already recorded. Custom provider
 models and custom global SDK providers need an explicit threshold. A custom
@@ -849,7 +870,13 @@ the summary, its usage, and the exact event frontier it covers. Later model
 requests receive the summary plus everything produced after that frontier,
 including later tool steps in the same assistant message. Queued user messages
 remain queued. Compaction waits until earlier tool calls have terminal results.
-The raw log and `state.messages` remain available in full.
+The raw log and transcript from `agent.reducer` remain available in full.
+Server execution uses a separate model-context reducer and checkpoint. Successful
+compaction permanently replaces covered context. Callbacks receive their prompt
+messages and request information, not reducer state or execution internals.
+Application reducers remain explicit reads through `session.state(reducer)`.
+To read the full transcript, load `session.state(agent.reducer)` and pass its
+`state` to `agent.reducer.view()`. Client hooks continue to expose `AIState`.
 
 Custom `shouldCompact(context)` and `compact(context)` callbacks remain
 available for deterministic replacement messages or application-specific
@@ -873,16 +900,25 @@ export function CompactionStatus() {
 }
 ```
 
-A failed or interrupted generation restores the prior compaction state. The
-synthetic summary request is not a user turn or an assistant reply in
+Successful compaction is a permanent boundary. Failure, interruption, retry, and
+worker recovery never restore the messages it replaced. Retry reruns the failed
+model step from the latest committed context and preserves earlier completed
+steps. A failed summary attempt leaves the previous committed context intact.
+The synthetic summary request is not a user turn or an assistant reply in
 `state.messages`.
 
+Compaction runs only when retained tool exchanges have final results and all
+A2-owned tool work has settled, including work from stopped or superseded turns.
+A2 checks a fresh coordinator checkpoint before starting a candidate compaction.
+This adds one state read on that path. Unresolved dead-lettered tool work keeps
+compaction deferred until repair and settlement or session closure.
+
 ## Extend the assembly
 
 The convenience API is ordinary A2 parts:
 
 - `events` and `createEvents()` export the built-in schemas.
-- `createReducer({ contract })` builds the standard `AIState` projection for a
+- `createReducer({ contract })` builds the normalized state and `AIState` view 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
@@ -979,20 +1015,56 @@ emit typed metadata chunks itself.
 
 ## Checkpoints and recovery reads
 
-Model steps read the AI reducer and coordinator at a fixed log boundary. Model,
-instruction, compaction, and custom-generation callbacks receive derived state.
+The AI reducer stores normalized `AIStoredState`. `session.state(agent.reducer)`
+returns that state and its log index, ready to pass to `SessionProvider` or client
+hydration. Client and React snapshots derive the familiar `AIState` view
+immediately, including streamed message parts and tool activity.
+
+For server-side inspection, use the reducer's view:
+
+```ts server/read-agent.ts
+import type { UIMessage } from 'ai'
+import { assistantServer } from './assistant'
+import { assistant } from '../assistant'
+
+export async function readMessages(sessionId: string): Promise<UIMessage[]> {
+  const snapshot = await assistantServer.session(sessionId).state(assistant.reducer)
+  return assistant.reducer.view(snapshot.state).messages
+}
+```
+
+Each snapshot stores repeated payloads once and keeps only the changes needed
+to restore the current generation's prompt and projection. The live view is cached while
+events fold; normalization does not run for every token. Reading or serializing
+the stored fields materializes the records. The log and displayed conversation
+retain their full content.
+
+Model steps read the model-context reducer and coordinator at a fixed log
+boundary. Model, instruction, compaction, and custom-generation callbacks
+receive prompt messages and request information without reducer state. Custom transcript folds and
+schemas apply only to the transcript; read application state explicitly with
+`session.state(yourReducer)` when a callback needs it.
 They do not receive a raw history array. Their `session.state(reducer)` reads
 application reducers at the captured prompt boundary by default; explicit
 `through` options follow the ordinary state-read contract. Compaction selection
 can be asynchronous when it needs a settings-state read.
 
-Ordinary generation uses checkpointed state. A recovered attempt reads from its
-saved prompt boundary to the captured current boundary, excluding abandoned
-attempts. Tools recovering in a fresh process reconstruct their original prompt
-from that checkpoint and the owning generation's start and compaction events.
-Compacted context uses its checkpoint and subsequent events. These AI history
-reads always have explicit lower and upper bounds. A2 core can rebuild a missing
-or invalid reducer snapshot from the log.
+Ordinary generation uses the model-context checkpoint without reading the
+transcript or replaying history to apply an existing compaction. The context
+checkpoint has its own identity and fold. Recovery and explicit retry discard
+only the unfinished model step. Completed compactions remain committed, so these
+paths never reconstruct pre-compaction prompts or retain rollback copies.
+
+Tools recovering in a fresh process read context at their tool-admission index.
+The saved generation projection restores their original prompt, preserving the
+committed summary and excluding later arrivals. No separate history read is
+needed. A2 core can rebuild a missing or invalid reducer snapshot from the log.
+
+Compaction immediately releases covered message and tool content from model
+context. Execution retains the active turn, queued inputs, unsettled tool work
+IDs, and token calibration. Model metadata is cached per distinct model.
+Historical input uniqueness comes from core event deduplication. The full
+transcript remains available independently.
 
 Streaming progress updates the current message incrementally. Snapshots preserve
 open text and reasoning parts and partial tool inputs. Indexed progress remains
@@ -1037,9 +1109,23 @@ agent session when adopting it. Existing event logs remain readable; finish
 pending work with the runtime that created it before upgrading.
 
 `inputs.message(message)` places a message in the durable inbox. The controller
-admits one input at a time, freezes its revision, and adds it to `state.messages`.
+admits one input at a time, freezes its content, and adds it to `state.messages`.
 Pending inputs appear in `state.inbox.items`; they do not enter the model prompt.
-Each item has an `id`, `revision`, `message`, and `generate` flag.
+Each item has an `id`, `message`, and `generate` flag.
+
+New-input commands from `inputs.message()`, `inputs.seed()`, and `inputs.steer()`
+use the message ID as their event ID. Those IDs must match on hand-written
+commands too. Caller IDs cannot start with the reserved `a2.ai:` prefix. IDs must
+be unique within the store; include contract/session scope when deriving them
+with `idempotentId()`.
+
+An identical submission replays its original event without creating more work,
+even after removal or compaction. Reusing the ID with different content, a
+different command action, or another session rejects at append with
+`PARTIAL_DUPLICATE_BATCH`. Use `queue.edit()` to change a pending input and a fresh
+message ID to create another input. Edit, move, remove, and other commands have
+their own event IDs. The controller stores no historical input-ID registry.
+
 
 `state.active` identifies the logical turn, its frozen `input`, and its `phase`.
 The turn ID stays the same across model steps, tools, and a pause. Stop ends that
@@ -1049,8 +1135,8 @@ turn and admits the next queued input when admission is running.
 import { inputs, type AIState } from 'experimental-a2/ai'
 import type { UIMessage } from 'ai'
 
-export function editPending(message: UIMessage, expectedRevision: number) {
-  return inputs.queue.edit({ message, expectedRevision })
+export function editPending(message: UIMessage) {
+  return inputs.queue.edit({ message })
 }
 
 export function movePending(inputId: string, beforeId: string | null) {
@@ -1083,13 +1169,15 @@ export const resume = () => inputs.resume()
 Pass these arrays to `push(...events)` from `useSession()`, or to a server
 session's `append(...events)`. `beforeId: null` moves an item to the end.
 Removal only applies to pending input. It preserves the immutable log and keeps
-the input identity reserved, so replay cannot recreate a removed prompt.
-Removing an admitted input returns `already-active`; removing an absent or
-already removed input returns `not-found`.
+its original submission event, so replay cannot recreate a removed prompt.
+Removing an input that is no longer pending returns `not-pending`, whether it was
+admitted, removed, or never queued.
 
-An edit that loses to admission returns `already-active`. Concurrent edits use
-`expectedRevision`; an outdated revision returns `revision-conflict`. A Stop
-aimed at a completed turn returns `stale-turn`.
+Edits to pending input use last-write-wins in session log order. Clients can send
+another edit before an earlier one is confirmed. Editing preserves the message's
+identity and role; changing its role returns `role-mismatch`. An edit that loses
+to admission returns `not-pending`. A Stop aimed at a completed turn returns
+`stale-turn`.
 
 Steer validates the new input and places it ahead of the inbox in one decision.
 If the observed turn is still active, it finishes its current model response and
@@ -1109,7 +1197,7 @@ Steering preserves the admission gate: steering while paused does not resume
 execution. Duplicate input identities and closed sessions still reject the command.
 
 Send now uses the selected queued message's existing identity and latest
-accepted revision. It validates the selected input and the observed `turnId`,
+accepted content. It validates the selected input and the observed `turnId`,
 then moves the input first for the same handoff after the current step. Use
 `turnId: null` when no turn is active. If that expectation is stale, the command
 returns `stale-turn` without changing the queue.
@@ -1117,8 +1205,8 @@ returns `stale-turn` without changing the queue.
 Send now preserves pause just like steering. A paused queue keeps the selected
 input first until Resume. It accepts user-role inputs, including passive user
 input, which it marks for generation. Non-user context returns `not-user-input`;
-a conflicting response identity returns `duplicate-input`. Unsaved editor text
-is separate from the accepted queue revision; save it before sending.
+reserved internal IDs are rejected before append. Unsaved editor text
+is separate from the accepted queue content; save it before sending.
 
 A queued item's optional `afterStepOf` records the observed turn for steering.
 A matching active turn hands off after its current step.
@@ -1175,12 +1263,15 @@ Server `session.state(reducer)`, reducer folds, checkpoints, and model prompts
 contain confirmed messages and inbox entries, with `starting: false`. The client
 applies pending intent and displays accepted steering only when returning its
 state, after folding events.
-A custom reducer that calls `reduceAIState()` or nests `agent.reducer.fold()`
-uses that confirmed fold; it does not inherit the built-in reducer's client display.
+A custom reducer can keep normalized AI state by nesting `agent.reducer.fold()`
+and derive its view with `agent.reducer.view()`. It does not inherit the built-in
+optimistic client display. `reduceAIState()` remains a pure transition over the
+confirmed `AIState` view for applications that project raw event histories.
 `state.pendingQueueCommands` tracks unresolved queue commands incrementally, so
-the client does not scan raw history. Revisions remain server-confirmed; keep
-repeat editing and Send now disabled while an edit for that item awaits its
-receipt. Moving and removing an item do not require a revision.
+the client does not scan raw history. Pending edits apply in order, so the latest
+local edit stays visible while earlier commands are confirmed. Editing and Send
+now can remain available while an edit awaits its receipt. Close an editor as
+soon as its save is pushed; retain the draft if the push fails.
 
 ### Persistence and application are separate
 

package/docs/reference/01-api.mdx

@@ -63,6 +63,31 @@ The shared base for A2 failures, discriminated by `code`. The session
 client exposes its `A2ClientError` subclass. See
 [Errors](/reference/errors).
 
+### `idempotentId(...parts)`
+
+`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
+from an ordered tuple of strings. It runs on the server and in the browser.
+
+```ts shared/request-id.ts
+import { idempotentId } from 'experimental-a2'
+
+export const id = await idempotentId('orders', 'shop-7', 'request-42')
+```
+
+Pass the result as an event's `id` when retries should converge on the same
+event. The same tuple produces the same ID across runtimes and A2 versions.
+String boundaries, order, and case matter; strings are not normalized.
+Empty strings and an empty tuple are valid inputs.
+
+Every argument has the same role. A prefix such as `'orders'` is a namespace
+by convention. Include enough context to distinguish operations across
+contracts and sessions, since event IDs are globally unique within a store.
+
+The helper performs no I/O. A2 preserves explicit IDs and keeps its automatic
+ID generation unchanged. Changing an existing application's ID recipe changes
+retry identity, so retries of previously committed requests need to retain
+their original IDs.
+
 ## `experimental-a2/server`
 
 ### `handler(entry)`
@@ -736,6 +761,13 @@ eligible retained checkpoint. A root historical read never creates retention
 or writes a stale checkpoint behind the latest snapshot; it folds from the log
 when no eligible checkpoint exists.
 
+Operational snapshot-read failures preserve existing A2 errors; other errors
+become `STORE_UNAVAILABLE` with the original error as the cause. They do not retry through individual
+reads or raw history. Cache misses and `stateSchema` rejection still rebuild
+from the log. Snapshot write-back remains background work; failures are reported
+through `a2.snapshot` telemetry or the default console sink, without failing the
+completed read or attaching snapshot contents.
+
 ### `session.stream(options?)`
 
 ```ts
@@ -1073,20 +1105,24 @@ Pure typed inputs for `append()` and `push()`:
 | `inputs.retry(options)` | retries a failed response |
 | `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances when admission is open |
 | `inputs.steer({ turnId, message, lastSeenIndex? })` | puts the new input first for a handoff after the observed turn's current step |
-| `inputs.queue.edit({ message, expectedRevision })` | changes a pending input; its ID stays fixed |
+| `inputs.queue.edit({ message })` | changes a pending input; its ID stays fixed |
 | `inputs.queue.move({ inputId, beforeId })` | moves pending input before an ID; `null` means the end |
-| `inputs.queue.remove({ inputId })` | removes pending input; its identity stays reserved |
+| `inputs.queue.remove({ inputId })` | removes pending input; its submission stays in the log |
 | `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input for a handoff after the current step; preserves pause |
 | `inputs.pause({ when: 'now' \| 'after-turn' })` | pauses execution now or inbox admission after the turn |
 | `inputs.resume()` | resumes retained work, then inbox admission |
 | `inputs.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
 | `inputs.interrupt(options)` | interrupts a specific generation/request owner |
 
+Edits are last-write-wins in session log order and preserve the pending message's
+identity and role. They require no revision or confirmation before another edit.
+Admission freezes the message; subsequent edits return `not-pending`.
+
 All builders emit `ai.control.requested`. Persistence and application are
 separate: `ai.control.decided` returns `{ commandId, outcome, reason? }` through
 the existing stream. Outcomes are `applied` or `rejected`. Rejection reasons
-include `already-active`, `revision-conflict`, `stale-turn`, `not-found`,
-`duplicate-input`, `not-user-input`, and `closed`. `state.receipt` holds the latest user receipt.
+include `not-pending`, `role-mismatch`, `stale-turn`, `not-found`,
+`not-user-input`, and `closed`. `state.receipt` holds the latest user receipt.
 
 Steering validates and prioritizes new input even if the observed turn has
 finished. A matching active turn finishes its current model response and tool
@@ -1097,15 +1133,14 @@ or waits first behind a different active turn. The priority change is atomic;
 the later handoff and new work are committed atomically at the step boundary.
 Steer and Send now do not use `lastSeenIndex` to cut output.
 
-Queue removal leaves the log intact and retains the removed identity's reservation.
-Send now preserves the queued input ID and latest accepted revision. It requires
+Queue removal leaves the original submission in the log, so replay does not recreate the input.
+Send now preserves the queued input ID and latest accepted content. It requires
 an observed `turnId` (or null for idle), preserves pause, and only accepts
-user-role input. It promotes passive user input to generation after reserving its
-response ID. Missing targets, stale turns, and identity collisions reject before
-any queue change.
+user-role input. It promotes passive user input to generation. Missing targets
+and stale turns reject before any queue change.
 
 `state.inbox` contains `paused` and ordered `items`. Each item contains
-`{ id, revision, message, generate, afterStepOf? }`. The optional turn ID
+`{ id, message, generate, afterStepOf? }`. The optional turn ID
 `afterStepOf` records the observed steering turn while that item remains queued;
 a matching active turn hands off after its current step.
 Removal cancels it and admission consumes it. `state.active` is null or contains
@@ -1117,7 +1152,12 @@ execution version. Tools without terminal outcomes can retry; their stable
 
 `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. Message, approval, input, and retry builders use stable interaction IDs.
+when an application uses them. Message, seed, and steering builders set the event ID to the input message ID.
+The two IDs must match for all new-input commands. Caller command/input IDs must
+be nonempty and cannot use the reserved `a2.ai:` prefix. Identical events replay;
+conflicting ID reuse rejects before append under core deduplication rules. IDs
+are unique across the store, including different contracts and sessions.
+Approval, input-response, and retry builders use stable interaction IDs.
 Other commands use IDs assigned by `push()` or `append()`; transport retries
 preserve those IDs. Browser
 ingress accepts user messages, approval and input responses, interruptions,
@@ -1138,12 +1178,25 @@ field. Model output is generation progress rather than another
 new turn.
 
 Approval and input request/response payloads require the active
-`generationId`. Clients copy it from the pending request, which prevents a
+`requestId` and `generationId`. Clients copy both 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`.
+Retry reruns the failed model call while retaining earlier completed model steps,
+their tool results, and committed compactions, including steps completed after
+the latest compaction.
+The failed model call's uncommitted step is removed from the active prompt and
+response. Conversation forks and edit-and-resend flows for admitted messages are
+application-owned.
+
+A2-generated requests, generations, assistant responses, worker jobs, reports,
+and lifecycle events have fixed-length deterministic IDs in the reserved
+`a2.ai:` namespace. An assistant message's ID equals its initial model-request
+event ID. Control state keeps no lifetime input/response-ID registry. IDs are opaque;
+ownership is carried by event fields. `ai.generation.requested` requires
+`responseMessageId`; a tool continuation also requires `sourceGenerationId`.
 
 `ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
 continuation before another model step starts.
@@ -1192,11 +1245,12 @@ inbox. This display survives receipt and hydration, including while paused.
 They remain pending server inputs until admission and do not enter the model
 prompt early. Multiple steering inputs follow inbox admission order.
 
-`state.active`, model execution, and revision numbers stay confirmed.
+`state.active` and model execution stay confirmed.
 Server reads and reducer folds retain confirmed messages and inbox entries;
 `state.starting` is false there. Custom reducers that call `reduceAIState()` or
-nest the AI fold do not inherit the client display behavior. Disable repeat editing and Send now while an
-edit for that input is present in `state.pendingQueueCommands`.
+nest the AI fold do not inherit the client display behavior. Repeat editing and
+Send now remain available while earlier edits are pending. Later local edits
+stay visible through earlier commands' acknowledgments and receipts.
 
 The pending-command ledger survives request echo and retires on the matching
 `ai.control.decided` receipt or session close. Failed pushes roll back through
@@ -1206,15 +1260,32 @@ read raw history.
 ### `createReducer(options)`
 
 ```ts
-createReducer({ contract, name? }): Reducer<AIState>
+createReducer({ contract, name?, fold?, stateSchema? }): AIStoredReducer
 ```
 
-Builds the standard AI projection for a compatible contract. `AIState`
+Builds a normalized AI reducer for a compatible contract. Its `initialState`,
+`fold`, and server `session.state(reducer)` use `AIStoredState`. Client and
+React snapshots expose the inferred `AIState` view automatically.
+
+`reducer.view(storedState)` derives confirmed `AIState` for server code.
+`reducer.fromView(state)` converts a confirmed view into stored state, including
+when migrating an application-owned hydration value. Keep the stored state and
+its log index together when hydrating; do not fold already-seen history twice.
+`fold` can customize the confirmed `AIState` transition, and `stateSchema`
+validates that view after restoration. Both apply only to the transcript.
+Model context has its own built-in fold and schema. Changed custom fold semantics
+still require a new `name`.
+
+Stored state is versioned, serializable data. Shared payload records and
+inverse changes replace repeated tool values and complete recovery copies.
+The reducer caches its live view and builds the records when the stored fields
+are read or serialized. Treat state and views as immutable. No event or tool
+payload is truncated. `AIState`
 contains `inbox`, `active`, `starting`, the latest command `receipt`, session lifecycle,
 messages, generation status, pending approvals
 and input, tool activity, compaction, usage, the last error, and
-`activeRequestId`, `activeResponseMessageId`,
-`responseGenerationIds: Record<string, string>`, and terminal request and
+`activeRequestId`, `activeRequestReason`, `activeRequestSourceGenerationId`, `activeResponseMessageId`,
+`responseOwners: Record<string, { generationId: string; requestId: string; attempt: number }>`, and terminal request and
 generation ownership fences.
 `activeRequestId` is the server-authorized generation request and fences
 delayed requests before their generation starts. `activeResponseMessageId`
@@ -1223,7 +1294,7 @@ identifies the requested response until `activeGeneration` exists.
 active, after a generation step completes while its response waits on tool,
 approval, or input barriers, while paused, and after a generation fails while it awaits retry
 or interruption. Response completion, interruption, supersession, retry, or a
-later generation clears or replaces it. `responseGenerationIds` keeps the
+later generation clears or replaces it. `responseOwners` keeps the
 latest generation owner for each response message, so late events from a
 superseded owner cannot alter the projection. `terminalRequestIds` and
 `terminalGenerations` preserve accepted completion, failure, interruption,
@@ -1242,7 +1313,7 @@ Checkpoint size and serialization cost still grow with retained progress.
 Tool-input deltas update `input-streaming` parts with best-effort partial JSON
 for display. The state stays `input-streaming` until a completed input arrives;
 partial parsing does not authorize execution or change interruption handling.
-Extension events are ignored. The default reducer name is `a2.ai.state.v17`.
+Extension events are ignored. The default reducer name is `a2.ai.state.v21:records-v2`.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
@@ -1345,6 +1416,16 @@ The resolver runs once per generation and returns a valid policy or `false`.
 It can await application reducers through `context.session.state(reducer)`, whose
 default boundary is the captured prompt frontier. Model, instruction, compaction,
 metadata, and custom-generation contexts expose state access and omit raw history.
+Callbacks receive prompt messages and request identity, without `state` or
+`execution` arguments. Model and instruction resolvers receive
+`{ event, messages, session, signal }`. Compaction and generation callbacks also
+receive `modelMessages`, including committed summaries. Custom transcript folds
+and schemas apply only to the transcript. `agent.reducer` and `createReducer()`
+continue to expose the full
+transcript view. To read it explicitly, load
+`context.session.state(agent.reducer)` and pass its `state` to
+`agent.reducer.view()`. The stored state also remains suitable for client
+hydration.
 Static options are validated at construction; resolved options are validated
 before that generation starts. Each session uses its own resolved value. `thresholdTokens` is an
 optional positive safe integer. `instructions` adds to A2's internal summary
@@ -1365,10 +1446,20 @@ compaction configuration. Provider-executed tools, structured output, and forced
 tool choices skip implicit compaction and reject explicit automatic policies.
 Custom policies remain available for these configurations.
 
-The input estimate includes messages, tools, and instructions, and uses prior
-reported input usage to anchor later growth where applicable. It is not a provider
-tokenizer. Completed generations record `inputTokenEstimate` beside usage. The
-built-in summary adds one model request and preserves the request prefix for
+The raw input estimate uses serialized bytes of messages, tools, and instructions,
+excluding provider options on messages and content parts. These options still reach
+the model unchanged. It is not a provider tokenizer. A preceding same-model
+completion anchors later growth to reported input usage, correcting both overestimates
+and underestimates. A smaller prompt, retry, compaction, or model change stops
+that calibration.
+
+Completed generations record the raw `inputTokenEstimate` beside usage.
+Automatic `ai.compaction.requested` events also record the pre-compaction
+`inputTokenEstimate`, the calibrated `inputTokens` used for the decision, and
+`thresholdTokens`. Custom-policy requests omit these diagnostics. They add no
+model calls or database round trips.
+
+The built-in summary adds one model request and preserves the request prefix for
 caching. It does not invoke application generation callbacks, transforms, or tool
 hooks. Both custom policy callbacks and `generate` receive `modelMessages`, the
 model-ready prompt including summaries, alongside typed UI `messages`.
@@ -1376,7 +1467,14 @@ model-ready prompt including summaries, alongside typed UI `messages`.
 Built-in summaries remain separate from application-typed messages. Render
 `state.compaction?.status === 'running'` as current activity, and the durable
 `ai.compaction.*` events as historical timeline markers. The conversation in
-`state.messages` remains intact. `progress` controls durable batching with
+`state.messages` from the transcript reducer remains intact. Model execution
+uses a separate context checkpoint; existing compactions do not require a
+transcript read. Successful compaction is permanent, including across failure,
+interruption, retry, and recovery. Retry reruns the failed step from the latest
+committed context. Compaction defers while tool exchanges or A2-owned tool work
+remain unsettled, checked with one fresh coordinator state read on each candidate.
+Unresolved dead-lettered tool work also defers compaction until repair and
+settlement or session closure. `progress` controls durable batching with
 `maxChunks` and `maxDelayMs`.
 
 This entry point is server-only and resolves to a throwing browser stub.
@@ -1519,7 +1617,7 @@ each handler → the events those handlers append.
 
 ### The span catalogue
 
-Four spans, all carrying `a2.contract` and `a2.session_id`:
+Five spans, all carrying `a2.contract` and `a2.session_id`:
 
 | Span        | Wraps                                                  |
 | ----------- | ------------------------------------------------------ |
@@ -1527,6 +1625,7 @@ Four spans, all carrying `a2.contract` and `a2.session_id`:
 | `a2.drain`  | one drain pass over a session's backlog                |
 | `a2.event`  | one claimed dispatch of one event                      |
 | `a2.state`  | one `state()` read: snapshot-plus-tail load + fold      |
+| `a2.snapshot` | one background batch of checkpoint writes            |
 
 Attributes arrive in two waves: **at start** (passed to `span()`) and
 **mid-span** (via `handle.setAttribute`; outcomes and counts aren't
@@ -1554,6 +1653,9 @@ alert on are all mid-span.
 | `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              |
+| `a2.snapshot.reducer` | `a2.snapshot` | start | the reducer's name                                  |
+| `a2.snapshot.index`   | `a2.snapshot` | start | greatest checkpoint index in the write batch       |
+| `a2.snapshot.count`   | `a2.snapshot` | start | number of checkpoints in the write batch           |
 
 Drain outcomes: `settled` means nothing actionable is left; `busy` means live
 per-event claims remain; `stalled` means a caught failure needs a later retry.