narraeon 0.7.4 → 0.7.6

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

@@ -1,19 +1,22 @@
 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";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
+import { renderToolAliasNote, resolveToolName, } from "../prompt/ToolNameAlias.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
 import { cloneSharingPromptRuns, currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, promptRunStrings, sharePromptRun, } from "./PlayPromptRun.js";
 import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash, randomBytes } from "node:crypto";
+import { isTurnGuideLine } from "../../shared/ordered-play-prompts.js";
+import { turnGuideWithTurnNote } from "../../shared/turn-guide.js";
 import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, turnGuideNotice, } from "./PlayContinuity.js";
 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 +85,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 +94,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));
@@ -98,6 +106,7 @@ export class PlayCallChain {
         validateIdentity(input.chainId, "call-chain ID");
         validateIdentity(input.exchangeId, "exchange ID");
         validatePlayerText(input.playerText);
+        validTurnNote(input.turnNote);
         assertModelHostBinding(input.modelBinding, input.modelHost);
         // Only a resubmission to the current context needs that context loaded.
         await this.#worlds.ensureCurrentStorage(input.worldId);
@@ -115,32 +124,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 +148,15 @@ 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,
+            ...turnNoteField(validTurnNote(input.turnNote)),
             transcript: [],
             events: [],
             completedTools: [],
@@ -178,7 +168,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 +185,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));
     }
@@ -219,6 +248,9 @@ export class PlayCallChain {
                 return this.#dispatch(session, input.modelHost, structuredClone(session.lastRequest), session.lastRequestAttempt + 1, signal, input.observer);
             }
             await this.#refreshPrompt(session, input);
+            // Each dispatch carries exactly the request the client sent with it; a
+            // continuation without one must not inherit the previous turn's line.
+            setTurnNote(session, validTurnNote(input.turnNote));
             session.exchange += 1;
             const last = session.transcript.at(-1);
             if (last?.kind === "assistant" &&
@@ -227,7 +259,7 @@ export class PlayCallChain {
                 session.narrativeOrigin = await this.#captureOrigin(session);
                 session.transcript.push(continuationNotice(this.#compiler.locale));
             }
-            return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange), 1, signal, input.observer);
+            return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange, this.#compiler.locale), 1, signal, input.observer);
         }
         if (duplicatePlayerExchange(session, input.exchangeId, input.playerText, "append"))
             return projectView(session);
@@ -236,6 +268,7 @@ export class PlayCallChain {
                 ? "The call chain has an incomplete model response; clear the input and append a continuation, or use a fresh context."
                 : "The call chain was interrupted; use a fresh context.");
         await this.#refreshPrompt(session, input);
+        setTurnNote(session, validTurnNote(input.turnNote));
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "append", input.modelHost, signal, input.observer);
     }
     async #refreshPrompt(session, input) {
@@ -722,6 +755,7 @@ export class PlayCallChain {
             eventId: input.eventId,
             replacementExchangeId: input.replacementExchangeId,
             replacementText: input.replacementText,
+            ...turnNoteField(validTurnNote(input.turnNote)),
             continuation: input.continuation,
             restoresHead: playerRevisionRestoresHead(sourceContext, eventIndex),
             discardChainIds: contexts
@@ -830,6 +864,7 @@ export class PlayCallChain {
                 previousContexts: [],
                 previousChainId,
                 timelineGeneration,
+                ...turnNoteField(intent.turnNote),
                 parentHead: head,
                 updatedAt: Date.now(),
             };
@@ -896,35 +931,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) {
@@ -968,6 +985,7 @@ export class PlayCallChain {
                 revision: input.freshContext.playPreset.revision,
             },
             followups: structuredClone(fresh.followups),
+            ...turnNoteField(input.intent.turnNote),
             playPresetScriptsEnabled: input.freshContext.playPreset.scriptsEnabled,
             presetFiles: structuredClone(input.freshContext.playPreset.files),
             modelBinding: structuredClone(input.freshContext.modelBinding),
@@ -1135,10 +1153,7 @@ export class PlayCallChain {
             throw new PlayCallChainError("The call chain is waiting for the model to return.");
         session.narrativeOrigin = await this.#captureOrigin(session);
         const exchange = session.exchange + 1;
-        const nextRequest = createRequest(session, modelHost, exchange, [
-            ...session.transcript,
-            ...playerInputAppend(playerText),
-        ]);
+        const nextRequest = createRequest(session, modelHost, exchange, this.#compiler.locale, [...session.transcript, ...playerInputAppend(playerText)]);
         const operationKey = `player:${exchangeId}`;
         const playerOperationId = operationId(session.chainId, operationKey);
         const advance = {
@@ -1166,23 +1181,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 +1224,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 +1236,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 +1266,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 = [];
@@ -1282,7 +1285,11 @@ export class PlayCallChain {
         let nextEventId = advance.eventId + 1;
         // Fresh in-memory seed per settlement. It is never persisted: a crashed
         // exchange is retried by the player and re-rolls (ADR-0044).
-        const resolutionSeed = calls.some(({ name }) => isResolutionTool(name))
+        const providedToolNames = currentPlayPrompt(session).tools.map(({ name }) => name);
+        const resolutionSeed = calls.some(({ name }) => {
+            const resolved = resolveToolName(name, providedToolNames);
+            return resolved.kind !== "rejected" && isResolutionTool(resolved.name);
+        })
             ? randomBytes(32).toString("hex")
             : undefined;
         for (const call of calls) {
@@ -1293,6 +1300,9 @@ export class PlayCallChain {
                 kind: "tool_call",
                 callId: call.id,
                 name: call.name,
+                ...(item.event.executedName === undefined
+                    ? {}
+                    : { executedName: item.event.executedName }),
                 arguments: structuredClone(call.arguments),
                 replayed: item.replayed,
             });
@@ -1300,8 +1310,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,16 +1356,15 @@ 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" &&
-                event.name === "world_checkpoint" &&
+                (event.executedName ?? event.name) === "world_checkpoint" &&
                 event.ok);
         const narrativeCheckpoint = checkpointRequested
             ? {
@@ -1369,177 +1378,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);
+            const nextRequest = createRequestWithMaxOutputTokens(session, session.lastRequest?.maxOutputTokens ?? 1, session.exchange, this.#compiler.locale);
             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 +1516,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 +1601,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 +1647,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 +1655,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 +1851,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)
@@ -2121,14 +1958,16 @@ export class PlayCallChain {
 function followupOperationId(session) {
     return `${session.chainId}:followup:${session.parentHead}`;
 }
-function createRequest(session, modelHost, exchange, appended = session.transcript) {
-    const request = createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, appended);
+function createRequest(session, modelHost, exchange, locale, appended = session.transcript) {
+    const request = createRequestWithMaxOutputTokens(session, modelHost.binding().maxOutputTokens, exchange, locale, appended);
     return modelHost.freezeRequest?.(request) ?? request;
 }
-function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, appended = session.transcript) {
+function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, locale, appended = session.transcript) {
     // The turn guide is a request-level suffix: it follows whatever this
-    // dispatch appends and is never part of the transcript it is built on.
-    const turnGuide = currentPlayPrompt(session).bootstrap.turnGuide;
+    // dispatch appends and is never part of the transcript it is built on. The
+    // player's one-turn request joins the suffix here, not in the bootstrap, so
+    // the bootstrap snapshot stays shared by every dispatch of the turn.
+    const turnGuide = turnGuideWithTurnNote(locale, currentPlayPrompt(session).bootstrap.turnGuide, session.turnNote);
     return {
         bootstrap: structuredClone(currentPlayPrompt(session).bootstrap),
         tools: structuredClone(currentPlayPrompt(session).tools),
@@ -2162,7 +2001,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) {
@@ -2218,13 +2061,17 @@ function appendCommittedHistory(session, head, messages) {
 function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
     const key = `${exchange}:${call.id}`;
     const signature = JSON.stringify(call.arguments);
+    const provided = currentPlayPrompt(session).tools.map(({ name }) => name);
+    const resolved = resolveToolName(call.name, provided);
+    // The executed name, not the model's spelling, decides replay identity.
+    const executedName = resolved.kind === "rejected" ? call.name : resolved.name;
     const completed = working.get(key);
     let result;
     let replayed = false;
     if (completed !== undefined) {
         replayed = true;
         result =
-            completed.name === call.name && completed.signature === signature
+            completed.name === executedName && completed.signature === signature
                 ? structuredClone(completed.result)
                 : {
                     ok: false,
@@ -2232,19 +2079,19 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                     markdown: "# Runtime tool rejected\n\nThe same tool-call ID is already bound to another tool name or argument set.",
                 };
     }
-    else if (!callChainToolNames.has(call.name) ||
-        !currentPlayPrompt(session).tools.some(({ name }) => name === call.name)) {
+    else if (resolved.kind === "rejected" ||
+        !callChainToolNames.has(executedName)) {
         result = {
             ok: false,
             failureKind: "protocol",
-            markdown: `# Runtime tool rejected\n\nThe current call chain does not provide ${call.name}.`,
+            markdown: `# Runtime tool rejected\n\nThe current call chain does not provide ${call.name}. Available tools: ${provided.join(", ")}.`,
         };
     }
     else {
         try {
-            result = isResolutionTool(call.name)
-                ? resolutionToolResult(call.name, call.arguments, resolutionSeed, key, locale)
-                : call.name === "world_checkpoint"
+            result = isResolutionTool(executedName)
+                ? resolutionToolResult(executedName, call.arguments, resolutionSeed, key, locale)
+                : executedName === "world_checkpoint"
                     ? typeof call.arguments === "object" &&
                         call.arguments !== null &&
                         !Array.isArray(call.arguments) &&
@@ -2260,7 +2107,7 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                             failureKind: "protocol",
                             markdown: "world_checkpoint requires an empty argument object.",
                         }
-                    : session.documents.execute(call, session.history, {
+                    : session.documents.execute({ ...call, name: executedName }, session.history, {
                         historyScope: session.worldId,
                         locale,
                         legacyHistoryTools: hasLegacyHistoryTools(currentPlayPrompt(session).tools),
@@ -2273,9 +2120,14 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
                 markdown: `# Runtime tool failed\n\n${error instanceof Error ? error.message : "Tool execution failed."}`,
             };
         }
+        if (resolved.kind === "alias")
+            result = {
+                ...result,
+                markdown: `${result.markdown}\n\n${renderToolAliasNote(call.name, executedName, locale)}`,
+            };
         working.set(key, {
             key,
-            name: call.name,
+            name: executedName,
             signature,
             result: structuredClone(result),
         });
@@ -2285,6 +2137,7 @@ function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
         kind: "tool_result",
         callId: call.id,
         name: call.name,
+        ...(executedName === call.name ? {} : { executedName }),
         ok: result.ok,
         markdown: result.markdown,
         ...(result.resolution === undefined
@@ -2402,6 +2255,7 @@ function projectView(session) {
         ...projectContext(session),
         worldId: session.worldId,
         previousContexts: (session.previousContexts ?? []).map((context) => projectContext(context)),
+        ...(lastEndingCancelled(session) ? { lastCancelled: true } : {}),
     };
 }
 function projectContextReads(session) {
@@ -2414,7 +2268,8 @@ function projectContextReads(session) {
             exchange = event.exchange;
             continue;
         }
-        if (event.kind === "tool_call" && event.name === "context_read") {
+        if (event.kind === "tool_call" &&
+            (event.executedName ?? event.name) === "context_read") {
             const ref = isRecord(event.arguments) && typeof event.arguments.ref === "string"
                 ? event.arguments.ref
                 : "(invalid ref)";
@@ -2424,7 +2279,8 @@ function projectContextReads(session) {
             });
             continue;
         }
-        if (event.kind !== "tool_result" || event.name !== "context_read")
+        if (event.kind !== "tool_result" ||
+            (event.executedName ?? event.name) !== "context_read")
             continue;
         const call = calls.get(event.callId);
         if (call === undefined)
@@ -2528,6 +2384,28 @@ function validatePlayerText(value) {
     if (value.trim().length === 0)
         throw new PlayCallChainError("Player text must not be empty.");
 }
+/**
+ * The player's one-turn request: one line, bounded like a turn-guide line.
+ * Blank input means no request. Length beyond the soft limit is only warned
+ * about by the client and Prompt Preview, never rejected here.
+ */
+function validTurnNote(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isTurnGuideLine(value))
+        throw new PlayCallChainError("The turn request must be a single line of at most 1000 characters.");
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function setTurnNote(session, turnNote) {
+    if (turnNote === undefined)
+        delete session.turnNote;
+    else
+        session.turnNote = turnNote;
+}
+function turnNoteField(turnNote) {
+    return turnNote === undefined ? {} : { turnNote };
+}
 function touch(session) {
     session.updatedAt = Date.now();
 }