narraeon 0.7.4 → 0.7.5

package/dist/node/runtime/play/PlayCallChain.js

@@ -1,5 +1,5 @@
 import { projectLegacyModelBindingFailure } from "./LegacyModelBindingFailure.js";
-import { classifyPlayFailure } from "./PlayFailure.js";
+import { dispatchFailureEnding, emptyResponseEnding, lastEndingCancelled, noContinuationEnding, PlayAdvanceLifecycle, settlementFailureEnding, } from "./PlayAdvanceLifecycle.js";
 import { isResolutionTool, resolutionMarkdown, resolutionToolNames, resolveTabletop, seededRandom, } from "./TabletopResolution.js";
 import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
 import { isDeepStrictEqual } from "node:util";
@@ -13,7 +13,7 @@ import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepN
 import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
-import { equalModelHostBinding, ModelHostBindingMismatchError, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
+import { equalModelHostBinding, ModelHostCancelledError, } from "../model/ModelHost.js";
 import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js";
 import { parsePlayPresetFiles, } from "./FileNativePlayPresetStore.js";
 import { runPlayFollowupRequests, } from "./PlayFollowupRequests.js";
@@ -82,6 +82,7 @@ export class PlayCallChain {
     #invocationSettled = new Map();
     /** Worlds whose release is queued in their WorldQueue slot. */
     #releasing = new Set();
+    #advances;
     constructor(worlds, compiler = new FileNativePromptCompiler(), artifacts, failureLog, changed = () => {
         /* No observers attached. */
     }) {
@@ -90,6 +91,10 @@ export class PlayCallChain {
         this.#compiler = compiler;
         this.#artifacts = artifacts;
         this.#failureLog = failureLog;
+        this.#advances = new PlayAdvanceLifecycle({
+            persist: (session) => this.#persist(session),
+            clearMarker: (advance) => this.#worlds.playAdvances.markSettled(advance),
+        });
     }
     async start(input) {
         return this.#runInvocation(input, (signal) => this.#start(input, signal));
@@ -115,32 +120,12 @@ export class PlayCallChain {
         if (active?.status === "running")
             throw new PlayCallChainError("A model request is still running for this world.");
         const binding = await this.#worlds.bindPlayCallChain(input.worldId);
-        const documents = new FileNativePlayDocuments(binding.files);
-        const documentMaintenance = await this.#bindDocumentMaintenance(documents, input.worldId, binding.parentHead);
-        const compilation = this.#compiler.compilePlayCallChain({
-            extensionControls: await this.#worlds.extensionControls(input.worldId, input.playPreset, this.#compiler.locale),
-            endpoint: {
-                id: `${input.worldId}:${binding.parentHead}`,
-                commit: binding.parentHead,
-            },
-            hostBinding: structuredClone(input.hostBinding),
-            world: {
-                controlFingerprint: fingerprintControl(binding.files),
-                documentSnapshot: documents.snapshot,
-                additionalMaterials: structuredClone(binding.additionalMaterials),
-                history: structuredClone(binding.history),
-                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
-                narrativeCheckpoint: binding.narrativeCheckpoint,
-                documentMaintenance,
-                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
-            },
-            playerInputPlacement: "append",
-            playerInput: input.playerText,
-            modelBinding: structuredClone(input.modelBinding),
-        }, input.playPreset);
-        const tools = structuredClone(compilation.toolUniverse);
-        const bootstrap = structuredClone(compilation.bootstrap);
-        documents.bindBootstrap(bootstrap);
+        const fresh = await this.#compileFreshContext(input.worldId, binding, {
+            hostBinding: input.hostBinding,
+            playPreset: input.playPreset,
+            modelBinding: input.modelBinding,
+            playerText: input.playerText,
+        });
         const now = Date.now();
         const session = {
             schemaVersion: 3,
@@ -159,14 +144,14 @@ export class PlayCallChain {
                 name: input.playPreset.name,
                 revision: input.playPreset.revision,
             },
-            followups: structuredClone(compilation.followups ?? []),
+            followups: fresh.followups,
             playPresetScriptsEnabled: input.playPreset.scriptsEnabled,
             presetFiles: structuredClone(input.playPreset.files),
             modelBinding: structuredClone(input.modelBinding),
             status: "ready",
             canRetry: false,
-            bootstrap,
-            tools: structuredClone(tools),
+            bootstrap: fresh.bootstrap,
+            tools: fresh.tools,
             transcript: [],
             events: [],
             completedTools: [],
@@ -178,7 +163,7 @@ export class PlayCallChain {
             lastRequestAttempt: 0,
             lastFailure: null,
             updatedAt: now,
-            documents,
+            documents: fresh.documents,
             history: historyEntries(binding.history, binding.historyBackgrounds),
             narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(),
@@ -195,6 +180,45 @@ export class PlayCallChain {
         await this.#worlds.completeArchiveFreshContext(session.worldId);
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "fresh", input.modelHost, signal, input.observer);
     }
+    /**
+     * Compiles a fresh context's input and binds its documents to the bootstrap.
+     * Starting a context and a player revision that begins one both come through
+     * here; they differ only in the world binding they read. A continuing context
+     * compiles against its frozen world context instead (`#refreshPrompt`).
+     */
+    async #compileFreshContext(worldId, binding, input) {
+        const documents = new FileNativePlayDocuments(binding.files);
+        const documentMaintenance = await this.#bindDocumentMaintenance(documents, worldId, binding.parentHead);
+        const compilation = this.#compiler.compilePlayCallChain({
+            extensionControls: await this.#worlds.extensionControls(worldId, input.playPreset, this.#compiler.locale),
+            endpoint: {
+                id: `${worldId}:${binding.parentHead}`,
+                commit: binding.parentHead,
+            },
+            hostBinding: structuredClone(input.hostBinding),
+            world: {
+                controlFingerprint: fingerprintControl(binding.files),
+                documentSnapshot: documents.snapshot,
+                additionalMaterials: structuredClone(binding.additionalMaterials),
+                history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
+                narrativeCheckpoint: binding.narrativeCheckpoint,
+                documentMaintenance,
+                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
+            },
+            playerInputPlacement: "append",
+            playerInput: input.playerText,
+            modelBinding: structuredClone(input.modelBinding),
+        }, input.playPreset);
+        const bootstrap = structuredClone(compilation.bootstrap);
+        documents.bindBootstrap(bootstrap);
+        return {
+            documents,
+            bootstrap,
+            tools: structuredClone(compilation.toolUniverse),
+            followups: structuredClone(compilation.followups ?? []),
+        };
+    }
     async append(input) {
         return this.#runInvocation(input, (signal) => this.#append(input, signal));
     }
@@ -896,35 +920,17 @@ export class PlayCallChain {
     }
     async #prepareFreshPlayerRevision(worldId, freshContext, restoresHead, replacementText) {
         const binding = await this.#worlds.bindPlayCallChainAt(worldId, restoresHead);
-        const documents = new FileNativePlayDocuments(binding.files);
-        const documentMaintenance = await this.#bindDocumentMaintenance(documents, worldId, binding.parentHead);
-        const compilation = this.#compiler.compilePlayCallChain({
-            extensionControls: await this.#worlds.extensionControls(worldId, freshContext.playPreset, this.#compiler.locale),
-            endpoint: {
-                id: `${worldId}:${binding.parentHead}`,
-                commit: binding.parentHead,
-            },
-            hostBinding: structuredClone(freshContext.hostBinding),
-            world: {
-                controlFingerprint: fingerprintControl(binding.files),
-                documentSnapshot: documents.snapshot,
-                additionalMaterials: structuredClone(binding.additionalMaterials),
-                history: structuredClone(binding.history),
-                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
-                narrativeCheckpoint: binding.narrativeCheckpoint,
-                documentMaintenance,
-                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
-            },
-            playerInputPlacement: "append",
-            playerInput: replacementText,
-            modelBinding: structuredClone(freshContext.modelBinding),
-        }, freshContext.playPreset);
-        documents.bindBootstrap(compilation.bootstrap);
+        const fresh = await this.#compileFreshContext(worldId, binding, {
+            hostBinding: freshContext.hostBinding,
+            playPreset: freshContext.playPreset,
+            modelBinding: freshContext.modelBinding,
+            playerText: replacementText,
+        });
         return {
             binding,
-            bootstrap: structuredClone(compilation.bootstrap),
-            tools: structuredClone(compilation.toolUniverse),
-            followups: structuredClone(compilation.followups ?? []),
+            bootstrap: fresh.bootstrap,
+            tools: fresh.tools,
+            followups: fresh.followups,
         };
     }
     async #buildFreshPlayerRevision(input) {
@@ -1166,23 +1172,9 @@ export class PlayCallChain {
             await this.#settlePlayerAdvance(session, advance);
         }
         catch (error) {
-            const message = error instanceof Error
-                ? error.message
-                : "Failed to write the original player text.";
-            const failureKind = classifyPlayFailure(error, false);
-            session.events.push({
-                id: session.nextEventId++,
-                kind: "failure",
-                message,
-                failureKind,
-            });
-            session.status = "interrupted";
-            session.canRetry = false;
-            session.lastFailure = message;
-            session.lastFailureKind = failureKind;
-            await this.#persist(session);
-            await this.#worlds.playAdvances.markSettled(advance);
-            throw new PlayCallChainError(message);
+            const ending = settlementFailureEnding(error, "Failed to write the original player text.");
+            await this.#advances.end(session, ending, advance);
+            throw new PlayCallChainError(ending.message);
         }
         return this.#dispatch(session, modelHost, structuredClone(nextRequest), 1, signal, observer);
     }
@@ -1223,8 +1215,6 @@ export class PlayCallChain {
             ...session.events.filter(({ id }) => id < advance.eventId),
             playerEvent,
         ];
-        if (session.transcript.length < advance.transcriptStart)
-            throw new PlayCallChainError("The recovered call-chain transcript is shorter than its player prefix.");
         session.transcript = [
             ...session.transcript.slice(0, advance.transcriptStart),
             ...structuredClone(transcriptAppendOf(advance.nextRequest).slice(advance.transcriptStart)),
@@ -1237,24 +1227,28 @@ export class PlayCallChain {
         else
             session.narrativeOrigin = structuredClone(advance.narrativeOrigin);
         session.exchange = advance.exchange;
-        session.lastRequest = structuredClone(advance.nextRequest);
-        session.lastRequestAttempt = 0;
-        session.status = "interrupted";
-        session.canRetry = true;
-        session.lastFailure =
-            "The player message is committed; the frozen model request is ready to continue.";
-        session.lastFailureKind = "retryable";
-        await this.#persist(session);
-        await this.#worlds.playAdvances.markSettled(advance);
+        await this.#advances.end(session, {
+            kind: "resumable",
+            reason: "player_committed",
+            request: advance.nextRequest,
+        }, advance);
     }
-    async #prepareResponseSettlement(session, advance, response) {
+    /**
+     * Settles one complete model response in this process. The tool batch, the
+     * narrative and state commit, and the transcript and event tail advance
+     * together. Nothing is kept for a replay: a process that stops before this
+     * returns is recovered as an interrupted exchange (ADR-0044).
+     */
+    async #settleResponse(session, advance, response) {
+        const durable = durableModelResponse(response);
         const existing = session.events.find(({ id }) => id === advance.eventId);
         if (existing?.kind !== "assistant")
             throw new PlayCallChainError("The durable Provider result no longer matches its assistant event.");
-        const calls = response.toolCalls ?? [];
-        const text = response.text ?? existing.text;
+        const calls = durable.toolCalls ?? [];
+        const text = durable.text ?? existing.text;
         const hasText = text.trim().length > 0;
         const responseKind = calls.length > 0 ? "tool_step" : hasText ? "narrative" : "empty";
+        const narrative = responseKind === "narrative";
         const assistantEvent = {
             id: advance.eventId,
             kind: "assistant",
@@ -1263,18 +1257,18 @@ export class PlayCallChain {
             responseKind,
             exchange: advance.exchange,
             attempt: advance.attempt,
-            ...(response.reasoningContent === undefined
+            ...(durable.reasoningContent === undefined
                 ? existing.reasoning === undefined
                     ? {}
                     : { reasoning: existing.reasoning }
-                : { reasoning: response.reasoningContent }),
-            ...(response.usage === undefined
+                : { reasoning: durable.reasoningContent }),
+            ...(durable.usage === undefined
                 ? {}
-                : { usage: structuredClone(response.usage) }),
-            ...(response.stopReason === undefined
+                : { usage: structuredClone(durable.usage) }),
+            ...(durable.stopReason === undefined
                 ? {}
-                : { stopReason: response.stopReason }),
-            continuation: response.providerState === undefined ? "unavailable" : "available",
+                : { stopReason: durable.stopReason }),
+            continuation: durable.providerState === undefined ? "unavailable" : "available",
         };
         const workingTools = new Map(session.completedToolMap);
         const prepared = [];
@@ -1300,8 +1294,8 @@ export class PlayCallChain {
             trailingEvents.push(structuredClone(item.event));
         }
         const stateChanges = session.documents.stateChanges();
-        // Resolve once after the entire tool batch. Store the prediction with the
-        // prepared fact so crash recovery publishes exactly the same receipt.
+        // Resolve once after the entire tool batch, so every write result reports
+        // the prediction that the commit below makes true.
         const writes = [...workingTools.values()].filter(({ result }) => result.candidateWrite !== undefined);
         let worldClock;
         if (writes.length > 0) {
@@ -1346,12 +1340,11 @@ export class PlayCallChain {
                     result.candidateWrite.freshContextCoverage = `${this.#compiler.locale === "zh-CN" ? "暂时无法判定下次注入；写入结果不受影响。原因" : "Fresh-context coverage unavailable; the write result is unaffected. Reason"}: ${reason}`;
             }
         }
-        const visibleText = responseKind === "narrative";
         const previousNarrative = session.events.findLast((event) => event.kind === "assistant" &&
             event.committedHead !== undefined &&
             event.responseKind === "narrative");
         const previousPlayer = session.events.findLast((event) => event.kind === "player");
-        const checkpointRequested = visibleText &&
+        const checkpointRequested = narrative &&
             session.events.some((event) => event.id >
                 Math.max(previousNarrative?.id ?? 0, previousPlayer?.id ?? 0) &&
                 event.kind === "tool_result" &&
@@ -1369,177 +1362,135 @@ export class PlayCallChain {
         const assistantItem = {
             kind: "assistant",
             text,
-            ...(response.reasoningContent === undefined
+            ...(durable.reasoningContent === undefined
                 ? {}
-                : { reasoningContent: response.reasoningContent }),
-            ...(response.providerState === undefined
+                : { reasoningContent: durable.reasoningContent }),
+            ...(durable.providerState === undefined
                 ? {}
-                : { providerState: response.providerState }),
+                : { providerState: durable.providerState }),
             toolCalls: structuredClone(calls),
         };
-        const background = visibleText
+        const background = narrative
             ? narrativeBackground(advance.narrativeOrigin, session.documents.snapshot)
             : undefined;
-        return {
-            ...(background === undefined ? {} : { background }),
-            assistantEvent,
-            playContext: session.continuityContextId ?? session.chainId,
-            ...(worldClock === undefined || stateChanges.length === 0
-                ? {}
-                : { worldClock }),
-            trailingEvents,
-            transcriptStart: session.transcript.length,
-            transcriptAppend: [
-                ...(calls.length > 0 ||
-                    visibleText ||
-                    response.providerState !== undefined
-                    ? [assistantItem]
-                    : []),
-                ...prepared.map(({ transcript }) => structuredClone(transcript)),
-                ...(calls.length > 0 && hasText
-                    ? [toolStepNotice(this.#compiler.locale)]
-                    : []),
-            ],
-            completedTools: [...workingTools.values()].map((item) => structuredClone(item)),
-            stateChanges: structuredClone(stateChanges),
-            visibleText,
-            ...(narrativeCheckpoint === undefined ? {} : { narrativeCheckpoint }),
-        };
-    }
-    async #settleResponseAdvance(session, advance, prepared) {
-        const settlement = structuredClone(prepared);
-        const hasToolCalls = settlement.trailingEvents.some(({ kind }) => kind === "tool_call");
-        // A legacy prepared fact has no responseKind. Its visibleText decision is
-        // already part of an immutable recovery operation and must be replayed as
-        // recorded; every newly prepared fact is checked against the current rule.
-        if (settlement.assistantEvent.responseKind !== undefined) {
-            const expectedResponseKind = hasToolCalls
-                ? "tool_step"
-                : settlement.assistantEvent.text.trim().length > 0
-                    ? "narrative"
-                    : "empty";
-            if (settlement.assistantEvent.responseKind !== expectedResponseKind ||
-                settlement.visibleText !== (expectedResponseKind === "narrative"))
-                throw new PlayCallChainError("The prepared response settlement has an inconsistent narrative classification.");
-        }
+        const transcriptStart = session.transcript.length;
+        const transcriptAppend = [
+            ...(calls.length > 0 || narrative || durable.providerState !== undefined
+                ? [assistantItem]
+                : []),
+            ...prepared.map(({ transcript }) => structuredClone(transcript)),
+            ...(calls.length > 0 && hasText
+                ? [toolStepNotice(this.#compiler.locale)]
+                : []),
+        ];
+        const completedTools = [...workingTools.values()].map((item) => structuredClone(item));
+        const failedTools = trailingEvents.filter((candidate) => candidate.kind === "tool_result" && !candidate.ok);
+        if (failedTools.length > 0 && response.diagnostics !== undefined)
+            await this.#failureLog?.recordFailure({
+                exchange: response.diagnostics,
+                failures: [
+                    {
+                        kind: "tool_execution",
+                        message: "A Runtime tool call from the model was rejected.",
+                        details: {
+                            calls: failedTools.map((result) => ({
+                                id: result.callId,
+                                name: result.name,
+                                ok: result.ok,
+                                markdown: result.markdown,
+                                replayed: result.replayed,
+                            })),
+                        },
+                    },
+                ],
+            });
         let committedHead;
-        if (settlement.visibleText || settlement.stateChanges.length > 0) {
+        if (narrative || stateChanges.length > 0) {
             const outcome = await this.#worlds.commitPlayStep({
-                ...(settlement.playContext === undefined
+                playContext: session.continuityContextId ?? session.chainId,
+                ...(worldClock === undefined || stateChanges.length === 0
                     ? {}
-                    : { playContext: settlement.playContext }),
-                ...(settlement.worldClock === undefined
-                    ? {}
-                    : { worldClock: settlement.worldClock }),
+                    : { worldClock }),
                 operationId: advance.operationId,
                 worldId: session.worldId,
                 parentHead: advance.parentHead,
-                historyAppend: settlement.visibleText
+                historyAppend: narrative
                     ? [
                         {
                             role: "narrator",
-                            exactText: settlement.assistantEvent.text,
-                            ...(settlement.background === undefined
-                                ? {}
-                                : { background: settlement.background }),
+                            exactText: text,
+                            ...(background === undefined ? {} : { background }),
                         },
                     ]
                     : [],
                 nextMaterials: structuredClone(session.nextMaterials),
-                stateChanges: structuredClone(settlement.stateChanges),
-                ...(settlement.narrativeCheckpoint === undefined
-                    ? {}
-                    : { narrativeCheckpoint: settlement.narrativeCheckpoint }),
+                stateChanges: structuredClone(stateChanges),
+                ...(narrativeCheckpoint === undefined ? {} : { narrativeCheckpoint }),
             });
             committedHead = outcome.head;
-            settlement.assistantEvent.committedHead = outcome.head;
-            if (settlement.narrativeCheckpoint !== undefined) {
-                settlement.assistantEvent.checkpoint = true;
+            assistantEvent.committedHead = outcome.head;
+            if (narrativeCheckpoint !== undefined) {
+                assistantEvent.checkpoint = true;
                 session.narrativeCheckpoint = {
-                    ...settlement.narrativeCheckpoint,
+                    ...narrativeCheckpoint,
                     head: outcome.head,
                     historyMessageId: `message.${outcome.head.slice("commit:".length)}.1.narrator`,
                 };
             }
             appendCommittedHistory(session, outcome.head, outcome.historyAppend);
         }
-        finalizePreparedReceipts(settlement);
+        finalizeWriteReceipts({
+            stateChanges,
+            completedTools,
+            trailingEvents,
+            transcriptAppend,
+        });
         session.events = [
             ...session.events.filter(({ id }) => id < advance.eventId),
-            structuredClone(settlement.assistantEvent),
-            ...structuredClone(settlement.trailingEvents),
+            structuredClone(assistantEvent),
+            ...structuredClone(trailingEvents),
         ];
         session.nextEventId =
-            Math.max(advance.eventId, ...settlement.trailingEvents.map(({ id }) => id)) + 1;
-        if (session.transcript.length < settlement.transcriptStart)
-            throw new PlayCallChainError("The recovered call-chain transcript is shorter than its settlement prefix.");
+            Math.max(advance.eventId, ...trailingEvents.map(({ id }) => id)) + 1;
         session.transcript = [
-            ...session.transcript.slice(0, settlement.transcriptStart),
-            ...structuredClone(settlement.transcriptAppend),
+            ...session.transcript.slice(0, transcriptStart),
+            ...structuredClone(transcriptAppend),
         ];
-        session.completedTools = structuredClone(settlement.completedTools);
-        session.completedToolMap = new Map(settlement.completedTools.map((item) => [
-            item.key,
-            structuredClone(item),
-        ]));
+        session.completedTools = structuredClone(completedTools);
+        session.completedToolMap = new Map(completedTools.map((item) => [item.key, structuredClone(item)]));
         if (committedHead !== undefined)
             session.parentHead = committedHead;
-        if (settlement.stateChanges.length > 0) {
+        if (stateChanges.length > 0) {
             session.documents.acceptCommittedState();
-            mergeChangedDocuments(session, settlement.stateChanges);
-        }
-        if (settlement.stateChanges.length > 0)
+            mergeChangedDocuments(session, stateChanges);
             await this.#bindDocumentMaintenance(session.documents, session.worldId, session.parentHead);
+        }
+        const hasToolCalls = calls.length > 0;
         session.exchange = Math.max(session.exchange, advance.exchange);
-        session.canRetry = false;
-        session.lastFailure = null;
-        delete session.lastFailureKind;
-        let result;
-        if (settlement.assistantEvent.continuation !== "available") {
-            const message = "The complete model response has no provider-native continuation payload; use a fresh context.";
-            session.events.push({
-                id: session.nextEventId++,
-                kind: "failure",
-                message,
-                failureKind: "context_unavailable",
-            });
-            session.status = "interrupted";
-            session.lastFailure = message;
-            session.lastFailureKind = "context_unavailable";
-            result = { kind: "terminal", status: "interrupted" };
+        // The chain has been `running` since its dispatch began, so its failure
+        // fields are already clear; the ending below replaces them.
+        if (assistantEvent.continuation !== "available") {
+            await this.#advances.end(session, noContinuationEnding(), advance);
+            return { kind: "terminal", status: "interrupted", narrative };
         }
-        else if (hasToolCalls) {
+        if (hasToolCalls) {
             session.exchange += 1;
             const nextRequest = createRequestWithMaxOutputTokens(session, session.lastRequest?.maxOutputTokens ?? 1, session.exchange);
             if (session.lastRequest?.modelConfig !== undefined)
                 nextRequest.modelConfig = structuredClone(session.lastRequest.modelConfig);
-            session.lastRequest = structuredClone(nextRequest);
-            session.lastRequestAttempt = 0;
-            session.status = "interrupted";
-            session.canRetry = true;
-            session.lastFailure =
-                "The completed tool response is settled; its frozen continuation request is ready.";
-            session.lastFailureKind = "retryable";
-            result = { kind: "continue", nextRequest };
+            await this.#advances.end(session, {
+                kind: "resumable",
+                reason: "tool_step_settled",
+                request: nextRequest,
+            }, advance);
+            return { kind: "continue", nextRequest };
         }
-        else {
-            session.status = settlement.visibleText ? "ready" : "interrupted";
-            if (!settlement.visibleText) {
-                const message = "The model returned neither text nor a complete tool call.";
-                session.events.push({
-                    id: session.nextEventId++,
-                    kind: "failure",
-                    message,
-                    failureKind: "other",
-                });
-                session.lastFailure = message;
-                session.lastFailureKind = "other";
-            }
-            result = { kind: "terminal", status: session.status };
+        if (!narrative) {
+            await this.#advances.end(session, emptyResponseEnding(), advance);
+            return { kind: "terminal", status: "interrupted", narrative };
         }
-        await this.#persist(session);
-        await this.#worlds.playAdvances.markSettled(advance);
-        return result;
+        await this.#advances.end(session, { kind: "ready" }, advance);
+        return { kind: "terminal", status: "ready", narrative };
     }
     async #dispatch(session, modelHost, firstRequest, firstAttempt, signal, observer) {
         let request = modelHost.freezeRequest?.(firstRequest) ?? structuredClone(firstRequest);
@@ -1549,12 +1500,7 @@ export class PlayCallChain {
             if (signal.aborted)
                 return this.#cancelBeforeProviderDispatch(session, request, attempt, observer);
             this.#observeInvocation(session.chainId, "waiting");
-            session.status = "running";
-            session.canRetry = false;
-            session.lastFailure = null;
-            delete session.lastFailureKind;
-            session.lastRequest = structuredClone(request);
-            session.lastRequestAttempt = attempt;
+            this.#advances.beginDispatch(session, request, attempt);
             const responseExchange = request.exchange ?? session.exchange;
             const event = {
                 id: session.nextEventId++,
@@ -1639,66 +1585,13 @@ export class PlayCallChain {
                     await this.#failureLog?.recordExchangeIfActive(response.diagnostics);
             }
             catch (error) {
-                event.status = "interrupted";
-                const message = error instanceof Error
-                    ? error.message
-                    : "The model request was interrupted.";
-                session.status = "interrupted";
-                const requiresFreshContext = error instanceof ModelHostBindingMismatchError ||
-                    error instanceof ModelHostContinuationError ||
-                    error instanceof ModelHostOutcomeUnknownError ||
-                    modelHostFailureRequiresFreshContext(error);
-                session.canRetry =
-                    !requiresFreshContext && error instanceof ModelHostFailureError;
-                session.lastFailure = message;
-                if (error instanceof ModelHostCancelledError) {
-                    delete session.lastFailureKind;
-                    session.events.push({
-                        id: session.nextEventId++,
-                        kind: "cancellation",
-                        message,
-                    });
-                }
-                else {
-                    session.lastFailureKind = classifyPlayFailure(error, session.canRetry);
-                    session.events.push({
-                        id: session.nextEventId++,
-                        kind: "failure",
-                        message,
-                        failureKind: session.lastFailureKind,
-                    });
-                }
-                await this.#persist(session);
-                await this.#worlds.playAdvances.markSettled(advance);
-                this.#notifySnapshot(observer, session);
+                await this.#advances.end(session, dispatchFailureEnding(error, event.id), advance, () => this.#notifySnapshot(observer, session));
                 return projectView(session);
             }
-            const durableResponse = durableModelResponse(response);
             try {
-                const settlement = await this.#prepareResponseSettlement(session, advance, durableResponse);
-                const failedTools = settlement.trailingEvents.filter((candidate) => candidate.kind === "tool_result" && !candidate.ok);
-                if (failedTools.length > 0 && response.diagnostics !== undefined)
-                    await this.#failureLog?.recordFailure({
-                        exchange: response.diagnostics,
-                        failures: [
-                            {
-                                kind: "tool_execution",
-                                message: "A Runtime tool call from the model was rejected.",
-                                details: {
-                                    calls: failedTools.map((result) => ({
-                                        id: result.callId,
-                                        name: result.name,
-                                        ok: result.ok,
-                                        markdown: result.markdown,
-                                        replayed: result.replayed,
-                                    })),
-                                },
-                            },
-                        ],
-                    });
-                const settled = await this.#settleResponseAdvance(session, advance, settlement);
+                const settled = await this.#settleResponse(session, advance, response);
                 if (settled.kind === "terminal") {
-                    if (!settlement.visibleText) {
+                    if (!settled.narrative) {
                         const message = "The model returned neither text nor a complete tool call.";
                         if (response.diagnostics !== undefined)
                             await this.#failureLog?.recordFailure({
@@ -1738,18 +1631,7 @@ export class PlayCallChain {
                     }
                     await this.#runFollowups(session, modelHost, signal, observer);
                     this.#setInvocationAbortable(session.chainId, false);
-                    if (signal.aborted) {
-                        session.events.push({
-                            id: session.nextEventId++,
-                            kind: "cancellation",
-                            message: "The player cancelled the remaining follow-up generation after the narrative was committed.",
-                        });
-                        touch(session);
-                        this.changed(session.worldId);
-                    }
-                    session.status = "ready";
-                    await this.#persist(session);
-                    this.#notifySnapshot(observer, session);
+                    await this.#advances.end(session, { kind: "ready", followupsCancelled: signal.aborted }, null, () => this.#notifySnapshot(observer, session));
                     return projectView(session);
                 }
                 this.#notifySnapshot(observer, session);
@@ -1757,58 +1639,29 @@ export class PlayCallChain {
                 attempt = 1;
             }
             catch (error) {
-                const message = error instanceof Error
-                    ? error.message
-                    : "Call-chain processing failed.";
+                const ending = settlementFailureEnding(error, "Call-chain processing failed.");
                 if (response.diagnostics !== undefined)
                     await this.#failureLog?.recordFailure({
                         exchange: response.diagnostics,
                         failures: [
                             {
                                 kind: "runtime_post_processing",
-                                message,
+                                message: ending.message,
                             },
                         ],
                     });
-                const failureKind = classifyPlayFailure(error, false);
-                session.events.push({
-                    id: session.nextEventId++,
-                    kind: "failure",
-                    message,
-                    failureKind,
-                });
-                session.status = "interrupted";
-                session.canRetry = false;
-                session.lastFailure = message;
-                session.lastFailureKind = failureKind;
-                await this.#persist(session);
-                this.#notifySnapshot(observer, session);
+                await this.#advances.end(session, ending, advance, () => this.#notifySnapshot(observer, session));
                 return projectView(session);
             }
         }
     }
     async #cancelBeforeProviderDispatch(session, request, attempt, observer, advance) {
-        if (advance !== undefined) {
-            const streaming = session.events.find((event) => event.kind === "assistant" && event.id === advance.eventId);
-            if (streaming !== undefined)
-                streaming.status = "interrupted";
-        }
-        const message = "The player cancelled before the next Provider dispatch; the frozen request can be resumed without replaying a completed model result.";
-        session.events.push({
-            id: session.nextEventId++,
-            kind: "cancellation",
-            message,
-        });
-        session.status = "interrupted";
-        session.canRetry = true;
-        session.lastRequest = structuredClone(request);
-        session.lastRequestAttempt = Math.max(0, attempt - 1);
-        session.lastFailure = message;
-        delete session.lastFailureKind;
-        await this.#persist(session);
-        if (advance !== undefined)
-            await this.#worlds.playAdvances.markSettled(advance);
-        this.#notifySnapshot(observer, session);
+        await this.#advances.end(session, {
+            kind: "cancelled_before_dispatch",
+            request,
+            attempt,
+            ...(advance === undefined ? {} : { streamingEventId: advance.eventId }),
+        }, advance ?? null, () => this.#notifySnapshot(observer, session));
         return projectView(session);
     }
     /**
@@ -1982,42 +1835,10 @@ export class PlayCallChain {
             : loaded;
         if (advance === null && session.status !== "running")
             return;
-        await this.#interruptAbandonedDispatch(session, advance);
-        if (advance !== null)
-            await this.#worlds.playAdvances.markSettled(advance);
-    }
-    async #interruptAbandonedDispatch(session, advance) {
+        // Authority already moved past the persisted parent head: the world cannot
+        // be replayed onto that head, so the recovery requires a fresh context.
         const headMoved = (await this.#worlds.currentHead(session.worldId)) !== session.parentHead;
-        const playerPhase = advance?.advanceKind === "player";
-        const streaming = playerPhase
-            ? undefined
-            : session.events.findLast((event) => event.kind === "assistant" &&
-                event.status === "streaming" &&
-                (advance === null || event.id === advance.eventId));
-        if (streaming !== undefined)
-            streaming.status = "interrupted";
-        // Authority already moved past the persisted parent head: the world
-        // cannot be replayed onto that head, so a fresh context is required.
-        const canRetry = !headMoved && !playerPhase && session.lastRequest !== null;
-        const message = headMoved
-            ? "The service stopped after the world was updated; use a fresh context."
-            : playerPhase
-                ? "The service stopped while saving the player message; use a fresh context."
-                : canRetry
-                    ? "The service stopped while the model request was in progress; retry to call the model again."
-                    : "The service stopped before preparing a model request; use a fresh context.";
-        const failureKind = canRetry ? "retryable" : "other";
-        session.events.push({
-            id: session.nextEventId++,
-            kind: "failure",
-            message,
-            failureKind,
-        });
-        session.status = "interrupted";
-        session.canRetry = canRetry;
-        session.lastFailure = message;
-        session.lastFailureKind = failureKind;
-        await this.#persist(session);
+        await this.#advances.recoverAbandoned(session, advance, headMoved);
     }
     async #assertCurrentHead(session) {
         if ((await this.#worlds.currentHead(session.worldId)) !== session.parentHead)
@@ -2162,7 +1983,11 @@ function durableModelResponse(response) {
     void _diagnostics;
     return structuredClone(durable);
 }
-function finalizePreparedReceipts(settlement) {
+/**
+ * Copies each committed write's receipt into the tool results that report it,
+ * then drops the candidate write. Receipts state what the commit made true.
+ */
+function finalizeWriteReceipts(settlement) {
     const committedWriteRefs = new Set(settlement.stateChanges.map(({ stableShortRef }) => stableShortRef));
     const markdownByCall = new Map();
     for (const completed of settlement.completedTools) {
@@ -2402,6 +2227,7 @@ function projectView(session) {
         ...projectContext(session),
         worldId: session.worldId,
         previousContexts: (session.previousContexts ?? []).map((context) => projectContext(context)),
+        ...(lastEndingCancelled(session) ? { lastCancelled: true } : {}),
     };
 }
 function projectContextReads(session) {