narraeon 0.4.0 → 0.5.0

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

@@ -1,6 +1,13 @@
+import { currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
+import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash } from "node:crypto";
-import { equalModelHostBinding, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, } from "../model/ModelHost.js";
+import { completedPlayerRounds, continuationNotice, isPlayerRoundMarker, playerInputAppend, toolStepNotice, } from "./PlayContinuity.js";
+import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
+import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
+import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
+import { equalModelHostBinding, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
 import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js";
+import { parsePlayPresetFiles, } from "./FileNativePlayPresetStore.js";
 import { runPlayFollowupRequests, } from "./PlayFollowupRequests.js";
 import { FileNativePlayDocuments, fingerprintControl, } from "./PlayDocumentTools.js";
 const callChainToolNames = new Set([
@@ -12,6 +19,8 @@ const callChainToolNames = new Set([
     "context_read",
     "world_patch",
     "world_create",
+    "world_retire",
+    "world_checkpoint",
 ]);
 const projectedEventTail = 40;
 export class PlayCallChainError extends Error {
@@ -28,6 +37,7 @@ export class PlayCallChainError extends Error {
  * response shape whose non-empty text can become committed narrative.
  */
 export class PlayCallChain {
+    changed;
     #worlds;
     #compiler;
     #artifacts;
@@ -36,7 +46,10 @@ export class PlayCallChain {
     #worldChains = new Map();
     #loadedCursors = new Map();
     #activeInvocations = new Map();
-    constructor(worlds, compiler = new FileNativePromptCompiler(), artifacts, failureLog) {
+    constructor(worlds, compiler = new FileNativePromptCompiler(), artifacts, failureLog, changed = () => {
+        /* No observers attached. */
+    }) {
+        this.changed = changed;
         this.#worlds = worlds;
         this.#compiler = compiler;
         this.#artifacts = artifacts;
@@ -62,7 +75,9 @@ export class PlayCallChain {
             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,
@@ -73,6 +88,9 @@ export class PlayCallChain {
                 documentSnapshot: documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                narrativeCheckpoint: binding.narrativeCheckpoint,
+                documentMaintenance,
+                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
             },
             playerInputPlacement: "append",
             playerInput: input.playerText,
@@ -86,6 +104,7 @@ export class PlayCallChain {
             schemaVersion: 3,
             kind: "play_call_chain",
             chainId: input.chainId,
+            continuityContextId: input.chainId,
             worldId: input.worldId,
             previousContexts: [],
             previousChainId: existing?.chainId ?? null,
@@ -101,6 +120,7 @@ export class PlayCallChain {
             },
             followups: structuredClone(compilation.followups ?? []),
             playPresetScriptsEnabled: input.playPreset.scriptsEnabled,
+            presetFiles: structuredClone(input.playPreset.files),
             modelBinding: structuredClone(input.modelBinding),
             status: "ready",
             canRetry: false,
@@ -125,6 +145,7 @@ export class PlayCallChain {
             updatedAt: now,
             documents,
             history: historyEntries(binding.history),
+            narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(),
             persistenceCursor: {
                 eventCount: 0,
@@ -153,10 +174,16 @@ export class PlayCallChain {
                 throw new PlayCallChainError("A model request is still running.");
             if (session.status === "interrupted") {
                 if (!session.canRetry || session.lastRequest === null)
-                    throw new PlayCallChainError("Call-chain processing failed, and there is no model context to continue.");
+                    throw new PlayCallChainError("The current model context cannot continue; use a fresh context.");
                 return this.#dispatch(session, input.modelHost, structuredClone(session.lastRequest), session.lastRequestAttempt + 1, signal, input.observer);
             }
+            await this.#refreshPrompt(session, input);
             session.exchange += 1;
+            const last = session.transcript.at(-1);
+            if (last?.kind === "assistant" &&
+                last.toolCalls.length === 0 &&
+                last.text.trim().length > 0)
+                session.transcript.push(continuationNotice(this.#compiler.locale));
             return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange), 1, signal, input.observer);
         }
         if (duplicatePlayerExchange(session, input.exchangeId, input.playerText, "append"))
@@ -165,8 +192,67 @@ export class PlayCallChain {
             throw new PlayCallChainError(session.canRetry
                 ? "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);
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "append", input.modelHost, signal, input.observer);
     }
+    async #refreshPrompt(session, input) {
+        if (input.resolvePrompt === undefined)
+            return;
+        const { hostBinding, playPreset } = await input.resolvePrompt();
+        const binding = await this.#worlds.bindPlayCallChain(input.worldId);
+        const baseline = await this.#worlds.bindPlayCallChainAt(input.worldId, session.baselineHead);
+        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, playPreset, this.#compiler.locale),
+            endpoint: {
+                id: `${input.worldId}:${binding.parentHead}`,
+                commit: binding.parentHead,
+            },
+            hostBinding,
+            world: {
+                controlFingerprint: fingerprintControl(binding.files),
+                documentSnapshot: documents.snapshot,
+                additionalMaterials: structuredClone(binding.additionalMaterials),
+                // Only pre-context history belongs in the prefix. Native conversation stays appended.
+                history: structuredClone(binding.history),
+                historyAlreadyAppended: Object.keys(binding.history).filter((key) => !(key in baseline.history)),
+                narrativeCheckpoint: baseline.narrativeCheckpoint,
+                documentMaintenance,
+                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
+            },
+            playerInputPlacement: "append",
+            playerInput: input.playerText,
+            modelBinding: input.modelHost.binding(),
+        }, playPreset);
+        documents.bindBootstrap(compilation.bootstrap, session.documents.authorizationCheckpoint());
+        session.documents = documents;
+        session.history = historyEntries(binding.history);
+        session.narrativeCheckpoint = binding.narrativeCheckpoint;
+        session.nextMaterials = structuredClone(binding.additionalMaterials);
+        (session.promptRuns ??= []).push({
+            schemaVersion: 1,
+            firstEventId: session.nextEventId,
+            head: binding.parentHead,
+            exchange: session.exchange + 1,
+            playPreset: {
+                id: playPreset.id,
+                name: playPreset.name,
+                revision: playPreset.revision,
+            },
+            bootstrap: structuredClone(compilation.bootstrap),
+            tools: structuredClone(compilation.toolUniverse),
+            followups: structuredClone(compilation.followups ?? []),
+            playPresetScriptsEnabled: playPreset.scriptsEnabled,
+            presetFiles: structuredClone(playPreset.files),
+        });
+        session.documentAuthorizationCheckpoints.push({
+            afterEventId: session.nextEventId,
+            authorization: documents.authorizationCheckpoint(),
+        });
+        await this.#persist(session);
+        crashAtPlayAdvanceEdge("after_prompt_run_prepared");
+    }
     cancel(input) {
         validateIdentity(input.worldId, "world ID");
         validateIdentity(input.chainId, "call-chain ID");
@@ -206,13 +292,19 @@ export class PlayCallChain {
             controller: new AbortController(),
             abortable: true,
         };
+        const controlUseId = operationId(input.chainId, `control-use:${input.exchangeId}`);
+        this.#worlds.freezeControl(input.worldId, controlUseId);
         this.#activeInvocations.set(input.chainId, invocation);
+        this.changed(input.worldId);
         try {
+            await this.#worlds.assertWorldRevisionUnlocked(input.worldId);
             return await run(invocation.controller.signal);
         }
         finally {
             if (this.#activeInvocations.get(input.chainId) === invocation)
                 this.#activeInvocations.delete(input.chainId);
+            this.#worlds.releaseControl(input.worldId, controlUseId);
+            this.changed(input.worldId);
         }
     }
     #observeInvocation(chainId, phase, increments = {}) {
@@ -226,6 +318,7 @@ export class PlayCallChain {
         active.toolChars += increments.toolChars ?? 0;
         active.toolCalls += increments.toolCalls ?? 0;
         active.dispatches += increments.dispatches ?? 0;
+        this.changed(active.worldId);
     }
     #setInvocationAbortable(chainId, abortable) {
         const active = this.#activeInvocations.get(chainId);
@@ -245,6 +338,7 @@ export class PlayCallChain {
     }
     #notifySnapshot(observer, session) {
         try {
+            this.changed(session.worldId);
             observer?.onSnapshot?.(this.#projectActiveView(session));
         }
         catch {
@@ -253,12 +347,31 @@ export class PlayCallChain {
         }
     }
     async inspectWorld(worldId) {
+        const session = await this.#worldSession(worldId);
+        return session === null ? null : this.#projectActiveView(session);
+    }
+    /** Browser observation never traverses old contexts. History and completed
+     * diagnostics remain behind the paged timeline/detail Interface. */
+    async observeWorld(worldId) {
+        const session = await this.#worldSession(worldId);
+        if (session === null)
+            return null;
+        const view = this.#projectActiveView({ ...session, previousContexts: [] });
+        const live = new Map(session.events
+            .slice(-projectedEventTail)
+            .map((event) => [event.id, event]));
+        view.events = view.events.map((event) => event.kind === "assistant" && event.status === "streaming"
+            ? structuredClone(live.get(event.id))
+            : event);
+        return view;
+    }
+    async #worldSession(worldId) {
         const activeId = this.#worldChains.get(worldId);
         const active = activeId === undefined ? undefined : this.#active.get(activeId);
         if (active !== undefined) {
             if (this.#activeInvocations.get(active.chainId)?.worldId !== active.worldId)
                 await this.#reconcileSessionAdvance(active);
-            return this.#projectActiveView(active);
+            return active;
         }
         const persisted = await this.#readPersisted(worldId);
         if (persisted === null)
@@ -270,7 +383,96 @@ export class PlayCallChain {
         await this.#reconcileSessionAdvance(session, advance);
         if (session.status === "running")
             await this.#interruptAbandonedDispatch(session);
-        return this.#projectActiveView(session);
+        return session;
+    }
+    async inspectReading(worldId, worldHead) {
+        const view = await this.inspectWorld(worldId);
+        if (view === null)
+            return null;
+        const session = this.#active.get(view.chainId);
+        if (session === undefined)
+            throw new PlayCallChainError("The current play context could not be inspected.");
+        const runs = playPromptRunsThroughEvents(session, session.events);
+        const latestRun = runs.at(-1);
+        const priorRun = runs.at(-2);
+        const previousContext = latestRun !== undefined || session.previousChainId === null
+            ? null
+            : await this.#worlds.playTimeline.readContext(worldId, session.previousChainId);
+        const previousContextRun = previousContext === null
+            ? undefined
+            : playPromptRunsThroughEvents(previousContext.value, previousContext.value.events).at(-1);
+        const previous = latestRun !== undefined
+            ? (priorRun ?? session)
+            : (previousContextRun ?? previousContext?.value ?? null);
+        const currentExchange = latestRun?.exchange ?? 1;
+        const previousExchange = priorRun?.exchange ?? previousContextRun?.exchange ?? 1;
+        const [currentEncoding, previousEncoding] = await Promise.all([
+            this.#worlds.playTimeline
+                .readInitialEncoding(worldId, session.chainId, currentExchange)
+                .catch(() => null),
+            previous === null
+                ? null
+                : this.#worlds.playTimeline
+                    .readInitialEncoding(worldId, latestRun !== undefined
+                    ? session.chainId
+                    : previousContext.value.chainId, previousExchange)
+                    .catch(() => null),
+        ]);
+        const usageAt = (events, exchange) => events.findLast((event) => event.kind === "assistant" &&
+            event.status === "completed" &&
+            event.exchange === exchange);
+        const currentResponse = usageAt(session.events, currentExchange);
+        const previousResponse = usageAt(previousContext?.value.events ?? session.events, previousExchange);
+        const prefixDiagnostics = comparePromptPrefixes(previous === null
+            ? null
+            : {
+                bootstrap: previous.bootstrap,
+                encoding: previousEncoding,
+                ...(previousResponse?.kind === "assistant" &&
+                    previousResponse.usage !== undefined
+                    ? { usage: previousResponse.usage }
+                    : {}),
+            }, {
+            bootstrap: recordedPlayPrompt(session).bootstrap,
+            encoding: currentEncoding,
+            ...(currentResponse?.kind === "assistant" &&
+                currentResponse.usage !== undefined
+                ? { usage: currentResponse.usage }
+                : {}),
+        });
+        return {
+            prefixDiagnostics,
+            promptHistory: [
+                {
+                    exchange: 1,
+                    head: session.baselineHead,
+                    playPreset: session.playPreset,
+                    bootstrap: session.bootstrap,
+                },
+                ...runs,
+            ].map(({ exchange, head, playPreset, bootstrap }) => ({
+                exchange,
+                head,
+                playPreset: structuredClone(playPreset),
+                bootstrap: {
+                    logicalMessages: structuredClone(bootstrap.logicalMessages),
+                    coverage: structuredClone(bootstrap.coverage),
+                },
+            })),
+            requestExchange: currentExchange,
+            requestHead: latestRun?.head ?? session.baselineHead,
+            chainId: session.chainId,
+            baselineHead: session.baselineHead,
+            parentHead: session.parentHead,
+            stale: session.parentHead !== worldHead,
+            playPreset: structuredClone(recordedPlayPrompt(session).playPreset),
+            updatedAt: session.updatedAt,
+            bootstrap: {
+                logicalMessages: structuredClone(recordedPlayPrompt(session).bootstrap.logicalMessages),
+                coverage: structuredClone(recordedPlayPrompt(session).bootstrap.coverage),
+            },
+            reads: projectContextReads(session),
+        };
     }
     async deriveWorld(input) {
         const result = await this.#worlds.deriveWorld({
@@ -358,14 +560,27 @@ export class PlayCallChain {
         if (source === null)
             throw new PlayCallChainError("The current world has no model call chain to revise.");
         const sourceContexts = await this.#worlds.playTimeline.readAllContexts(input.worldId);
-        const appliedEvent = sourceContexts
-            .flatMap(({ events }) => events)
-            .find((event) => event.kind === "player" &&
+        const appliedContext = sourceContexts.find(({ events }) => events.some((event) => event.kind === "player" &&
+            event.exchangeId === input.replacementExchangeId &&
+            event.committedHead !== undefined));
+        const appliedEvent = appliedContext?.events.find((event) => event.kind === "player" &&
             event.exchangeId === input.replacementExchangeId &&
             event.committedHead !== undefined);
         if (appliedEvent !== undefined) {
             if (appliedEvent.text !== input.replacementText)
                 throw new PlayCallChainError("The same replacement exchange ID is already bound to different player text.");
+            const requestedSource = await this.#worlds.playTimeline.readContext(input.worldId, input.chainId);
+            const requestedEventIndex = requestedSource?.value.events.findIndex(({ id }) => id === input.eventId);
+            const requestedEvent = requestedEventIndex === undefined || requestedEventIndex < 0
+                ? undefined
+                : requestedSource?.value.events[requestedEventIndex];
+            if (requestedSource === null ||
+                requestedEventIndex === undefined ||
+                requestedEventIndex < 0 ||
+                requestedEvent?.kind !== "player" ||
+                requestedEvent.committedHead === undefined)
+                throw new PlayCallChainError("The replacement exchange ID is already used by another commit.");
+            const requestedRestoresHead = playerRevisionRestoresHead(requestedSource.value, requestedEventIndex);
             const authority = await this.#worlds.readAuthorityHistory(input.worldId);
             const commit = authority.commits.find(({ head }) => head === appliedEvent.committedHead);
             const operation = await this.#worlds.getOperationOutcome(input.operationId);
@@ -373,7 +588,11 @@ export class PlayCallChain {
                 (operation.outcome !== "committed" &&
                     operation.outcome !== "committed_materialization_pending") ||
                 operation.worldId !== input.worldId ||
-                operation.head !== appliedEvent.committedHead)
+                operation.head !== appliedEvent.committedHead ||
+                commit.timelineRevision?.restoresHead !== requestedRestoresHead ||
+                commit.timelineRevision.replacesHead !== requestedEvent.committedHead ||
+                commit.timelineRevision.requestFingerprint !==
+                    playerRevisionRequestFingerprint(input, requestedEvent.committedHead, requestedRestoresHead))
                 throw new PlayCallChainError("The replacement exchange ID is already used by another commit.");
             return {
                 outcome: "revised",
@@ -406,23 +625,14 @@ export class PlayCallChain {
     async #applyPlayerRevision(input) {
         const request = input.request;
         const sourceContext = input.sourceContexts[input.selectedContextIndex];
-        let restoresHead = sourceContext.baselineHead;
-        for (const event of sourceContext.events.slice(0, input.selectedEventIndex))
-            if ((event.kind === "player" || event.kind === "assistant") &&
-                event.committedHead !== undefined)
-                restoresHead = event.committedHead;
-        const requestFingerprint = "sha256:" +
-            createHash("sha256")
-                .update(JSON.stringify({
-                schema: "narraeon.timeline-revision-request/v1",
-                chainId: request.chainId,
-                eventId: request.eventId,
-                selectedHead: input.selectedEvent.committedHead,
-                restoresHead,
-                replacementExchangeId: request.replacementExchangeId,
-                replacementText: request.replacementText,
-            }))
-                .digest("hex");
+        const restoresHead = playerRevisionRestoresHead(sourceContext, input.selectedEventIndex);
+        const freshPreparation = request.continuation === "fresh_context"
+            ? await this.#prepareFreshPlayerRevision(request, restoresHead)
+            : null;
+        const timelineGeneration = playerRevisionTimelineGeneration(input.source.timelineGeneration, request.operationId, request.worldId, request.continuation);
+        const requestFingerprint = playerRevisionRequestFingerprint(request, input.selectedEvent.committedHead, restoresHead);
+        const prefixEvents = structuredClone(sourceContext.events.slice(0, input.selectedEventIndex));
+        const transcript = transcriptThroughEvents(sourceContext.transcript, prefixEvents);
         const outcome = await this.#worlds.reviseTimeline({
             operationId: request.operationId,
             worldId: request.worldId,
@@ -432,9 +642,6 @@ export class PlayCallChain {
             replacementText: request.replacementText,
             requestFingerprint,
         });
-        const prefixEvents = structuredClone(sourceContext.events.slice(0, input.selectedEventIndex));
-        const transcript = transcriptThroughEvents(sourceContext.transcript, prefixEvents);
-        transcript.push({ kind: "player", text: request.replacementText });
         const events = [
             ...prefixEvents,
             {
@@ -452,22 +659,66 @@ export class PlayCallChain {
             this.#worlds.recoverEndpoint(request.worldId, restoresHead),
             this.#worlds.bindPlayCallChain(request.worldId),
         ]);
+        transcript.push(...playerInputAppend({
+            history: Object.fromEntries(selected.history.map(({ messageId, exactText }) => [
+                messageId,
+                exactText,
+            ])),
+            checkpoint: selected.narrativeCheckpoint,
+            text: request.replacementText,
+            locale: this.#compiler.locale,
+            checkpointAvailable: sourceContext.tools.some(({ name }) => name === "world_checkpoint"),
+        }));
         if (binding.parentHead !== outcome.head)
             throw new PlayCallChainError("The timeline revision was committed, but current-world materialization has not reached the new endpoint.");
+        if (request.continuation === "fresh_context") {
+            if (freshPreparation === null)
+                throw new PlayCallChainError("The fresh model context was not prepared before committing the timeline revision.");
+            const revised = await this.#buildFreshPlayerRevision({
+                request,
+                sourceContext,
+                sourceContexts: input.sourceContexts,
+                selectedContextIndex: input.selectedContextIndex,
+                prefixEvents,
+                baseline,
+                selected,
+                binding,
+                restoresHead,
+                outcomeHead: outcome.head,
+                timelineGeneration,
+                freshPreparation,
+            });
+            await this.#worlds.playTimeline.persist(structuredClone(revised));
+            const activeId = this.#worldChains.get(request.worldId);
+            if (activeId !== undefined)
+                this.#active.delete(activeId);
+            this.#active.delete(sourceContext.chainId);
+            this.#worldChains.delete(request.worldId);
+            return {
+                outcome: "revised",
+                worldId: request.worldId,
+                playCallChain: projectView(revised),
+            };
+        }
         const documents = restorePlayDocuments(binding.files, sourceContext, prefixEvents);
         const revised = {
+            continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
             schemaVersion: 3,
             kind: "play_call_chain",
-            chainId: derivedChainId(sourceContext.chainId, "timeline-revision:" + request.operationId, request.worldId),
+            chainId: playerRevisionChainId(sourceContext.chainId, request.operationId, request.worldId, request.continuation),
             worldId: request.worldId,
             previousContexts: [],
             previousChainId: input.selectedContextIndex === 0
                 ? null
                 : input.sourceContexts[input.selectedContextIndex - 1].chainId,
-            timelineGeneration: this.#worlds.playTimeline.newGeneration(),
+            timelineGeneration,
             baselineHead: sourceContext.baselineHead,
             baselineHistoryLength: sourceContext.baselineHistoryLength ?? baseline.history.length,
             parentHead: outcome.head,
+            promptRuns: playPromptRunsThroughEvents(sourceContext, events),
+            ...(sourceContext.presetFiles === undefined
+                ? {}
+                : { presetFiles: structuredClone(sourceContext.presetFiles) }),
             playPreset: structuredClone(sourceContext.playPreset),
             ...(sourceContext.followups === undefined
                 ? {}
@@ -513,6 +764,158 @@ export class PlayCallChain {
             playCallChain: projectView(revised),
         };
     }
+    async #prepareFreshPlayerRevision(request, restoresHead) {
+        const binding = await this.#worlds.bindPlayCallChainAt(request.worldId, restoresHead);
+        const documents = new FileNativePlayDocuments(binding.files);
+        const documentMaintenance = await this.#bindDocumentMaintenance(documents, request.worldId, binding.parentHead);
+        const compilation = this.#compiler.compilePlayCallChain({
+            extensionControls: await this.#worlds.extensionControls(request.worldId, request.freshContext.playPreset, this.#compiler.locale),
+            endpoint: {
+                id: `${request.worldId}:${binding.parentHead}`,
+                commit: binding.parentHead,
+            },
+            hostBinding: structuredClone(request.freshContext.hostBinding),
+            world: {
+                controlFingerprint: fingerprintControl(binding.files),
+                documentSnapshot: documents.snapshot,
+                additionalMaterials: structuredClone(binding.additionalMaterials),
+                history: structuredClone(binding.history),
+                narrativeCheckpoint: binding.narrativeCheckpoint,
+                documentMaintenance,
+                documentMaintenanceUnavailableReason: documents.maintenanceWarning,
+            },
+            playerInputPlacement: "append",
+            playerInput: request.replacementText,
+            modelBinding: structuredClone(request.freshContext.modelBinding),
+        }, request.freshContext.playPreset);
+        const bootstrap = structuredClone(compilation.bootstrap);
+        documents.bindBootstrap(bootstrap);
+        return {
+            binding,
+            bootstrap,
+            tools: structuredClone(compilation.toolUniverse),
+            followups: structuredClone(compilation.followups ?? []),
+            authorization: documents.authorizationCheckpoint(),
+        };
+    }
+    async #buildFreshPlayerRevision(input) {
+        const { request, sourceContext } = input;
+        let previousChainId = input.selectedContextIndex === 0
+            ? null
+            : input.sourceContexts[input.selectedContextIndex - 1].chainId;
+        if (input.prefixEvents.length > 0) {
+            const prefixTranscript = transcriptThroughEvents(sourceContext.transcript, input.prefixEvents);
+            const completedKeys = completedToolKeys(input.prefixEvents);
+            const documents = restorePlayDocuments(input.binding.files, sourceContext, input.prefixEvents);
+            const prefix = {
+                continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
+                schemaVersion: 3,
+                kind: "play_call_chain",
+                chainId: derivedChainId(sourceContext.chainId, "timeline-revision-prefix:" + request.operationId, request.worldId),
+                worldId: request.worldId,
+                previousContexts: [],
+                previousChainId,
+                timelineGeneration: input.timelineGeneration,
+                baselineHead: sourceContext.baselineHead,
+                baselineHistoryLength: sourceContext.baselineHistoryLength ?? input.baseline.history.length,
+                parentHead: input.restoresHead,
+                promptRuns: playPromptRunsThroughEvents(sourceContext, input.prefixEvents),
+                ...(sourceContext.presetFiles === undefined
+                    ? {}
+                    : { presetFiles: structuredClone(sourceContext.presetFiles) }),
+                playPreset: structuredClone(sourceContext.playPreset),
+                ...(sourceContext.followups === undefined
+                    ? {}
+                    : { followups: structuredClone(sourceContext.followups) }),
+                ...(sourceContext.playPresetScriptsEnabled === undefined
+                    ? {}
+                    : {
+                        playPresetScriptsEnabled: sourceContext.playPresetScriptsEnabled,
+                    }),
+                ...(sourceContext.modelBinding === undefined
+                    ? {}
+                    : { modelBinding: structuredClone(sourceContext.modelBinding) }),
+                status: "ready",
+                canRetry: false,
+                bootstrap: structuredClone(sourceContext.bootstrap),
+                tools: structuredClone(sourceContext.tools),
+                transcript: prefixTranscript,
+                events: structuredClone(input.prefixEvents),
+                completedTools: sourceContext.completedTools
+                    .filter(({ key }) => completedKeys.has(key))
+                    .map((item) => structuredClone(item)),
+                documentAuthorizationCheckpoints: authorizationCheckpointsThroughEvents(sourceContext, input.prefixEvents, documents.authorizationCheckpoint()),
+                changedDocuments: changedDocumentsAtHead(sourceContext.changedDocuments, input.baseline.state, input.selected.state),
+                nextMaterials: structuredClone(input.selected.additionalMaterials),
+                nextEventId: Math.max(0, ...input.prefixEvents.map(({ id }) => id)) + 1,
+                exchange: completedAssistantExchange(input.prefixEvents),
+                lastRequest: null,
+                lastRequestAttempt: 0,
+                lastFailure: null,
+                updatedAt: Date.now(),
+            };
+            await this.#worlds.playTimeline.persistDetached(structuredClone(prefix));
+            previousChainId = prefix.chainId;
+        }
+        const fresh = input.freshPreparation;
+        return {
+            schemaVersion: 3,
+            kind: "play_call_chain",
+            chainId: playerRevisionChainId(sourceContext.chainId, request.operationId, request.worldId, request.continuation),
+            worldId: request.worldId,
+            previousContexts: [],
+            previousChainId,
+            timelineGeneration: input.timelineGeneration,
+            baselineHead: input.restoresHead,
+            baselineHistoryLength: Object.keys(fresh.binding.history).length,
+            parentHead: input.outcomeHead,
+            playPreset: {
+                id: request.freshContext.playPreset.id,
+                name: request.freshContext.playPreset.name,
+                revision: request.freshContext.playPreset.revision,
+            },
+            followups: structuredClone(fresh.followups),
+            playPresetScriptsEnabled: request.freshContext.playPreset.scriptsEnabled,
+            presetFiles: structuredClone(request.freshContext.playPreset.files),
+            modelBinding: structuredClone(request.freshContext.modelBinding),
+            status: "ready",
+            canRetry: false,
+            bootstrap: structuredClone(fresh.bootstrap),
+            tools: structuredClone(fresh.tools),
+            transcript: playerInputAppend({
+                history: fresh.binding.history,
+                checkpoint: fresh.binding.narrativeCheckpoint,
+                text: request.replacementText,
+                locale: this.#compiler.locale,
+                checkpointAvailable: fresh.tools.some(({ name }) => name === "world_checkpoint"),
+            }),
+            events: [
+                {
+                    id: 1,
+                    kind: "player",
+                    exchangeId: request.replacementExchangeId,
+                    text: request.replacementText,
+                    context: "fresh",
+                    committedHead: input.outcomeHead,
+                },
+            ],
+            completedTools: [],
+            documentAuthorizationCheckpoints: [
+                {
+                    afterEventId: 0,
+                    authorization: structuredClone(fresh.authorization),
+                },
+            ],
+            changedDocuments: [],
+            nextMaterials: structuredClone(input.binding.additionalMaterials),
+            nextEventId: 2,
+            exchange: 0,
+            lastRequest: null,
+            lastRequestAttempt: 0,
+            lastFailure: null,
+            updatedAt: Date.now(),
+        };
+    }
     async #forkSelectionToDerivedWorld(input) {
         if (input.targetWorldRoot === undefined) {
             const existing = await this.#readPersisted(input.targetWorldId);
@@ -574,6 +977,7 @@ export class PlayCallChain {
             previousChainId = chainId;
         }
         const derived = {
+            continuityContextId: sourceContext.continuityContextId ?? sourceContext.chainId,
             schemaVersion: 3,
             kind: "play_call_chain",
             chainId: derivedChainId(sourceContext.chainId, input.branchIdentity, input.targetWorldId),
@@ -584,6 +988,10 @@ export class PlayCallChain {
             baselineHead: sourceContext.baselineHead,
             baselineHistoryLength: sourceContext.baselineHistoryLength ?? baseline.history.length,
             parentHead: input.sourceHead,
+            promptRuns: playPromptRunsThroughEvents(sourceContext, events),
+            ...(sourceContext.presetFiles === undefined
+                ? {}
+                : { presetFiles: structuredClone(sourceContext.presetFiles) }),
             playPreset: structuredClone(sourceContext.playPreset),
             ...(sourceContext.followups === undefined
                 ? {}
@@ -626,6 +1034,26 @@ export class PlayCallChain {
                 source: sourceContext,
                 target: structuredClone(derived),
             });
+        if (input.targetWorldRoot !== undefined) {
+            const retainedContexts = [
+                ...input.sourceContexts.slice(0, input.selectedContextIndex),
+                { ...sourceContext, events: input.sourceEvents },
+            ];
+            await this.#artifacts?.stageFork?.({
+                sourceWorldId: input.sourceWorldId,
+                targetWorldId: input.targetWorldId,
+                targetWorldRoot: input.targetWorldRoot,
+                timeline: retainedContexts.flatMap((context) => context.events.flatMap((event) => event.kind === "assistant" && event.committedHead !== undefined
+                    ? [
+                        {
+                            contextId: context.continuityContextId ?? context.chainId,
+                            eventId: event.id,
+                            head: event.committedHead,
+                        },
+                    ]
+                    : [])),
+            });
+        }
         return projectView(derived);
     }
     forgetWorld(worldId) {
@@ -645,7 +1073,13 @@ export class PlayCallChain {
         const exchange = session.exchange + 1;
         const nextRequest = createRequest(session, modelHost, exchange, [
             ...session.transcript,
-            { kind: "player", text: playerText },
+            ...playerInputAppend({
+                history: Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
+                checkpoint: session.narrativeCheckpoint,
+                text: playerText,
+                locale: this.#compiler.locale,
+                checkpointAvailable: currentPlayPrompt(session).tools.some(({ name }) => name === "world_checkpoint"),
+            }),
         ]);
         const operationKey = `player:${exchangeId}`;
         const playerOperationId = operationId(session.chainId, operationKey);
@@ -653,6 +1087,7 @@ export class PlayCallChain {
             schemaVersion: 1,
             kind: "play_advance",
             advanceKind: "player",
+            playContext: session.continuityContextId ?? session.chainId,
             worldId: session.worldId,
             chainId: session.chainId,
             advanceId: playerOperationId,
@@ -699,6 +1134,9 @@ export class PlayCallChain {
     }
     async #settlePlayerAdvance(session, advance) {
         const outcome = await this.#worlds.commitPlayStep({
+            ...(advance.playContext === undefined
+                ? {}
+                : { playContext: advance.playContext }),
             operationId: advance.operationId,
             worldId: session.worldId,
             parentHead: advance.parentHead,
@@ -725,7 +1163,7 @@ export class PlayCallChain {
             throw new PlayCallChainError("The recovered call-chain transcript is shorter than its player prefix.");
         session.transcript = [
             ...session.transcript.slice(0, advance.transcriptStart),
-            { kind: "player", text: advance.playerText },
+            ...structuredClone(advance.nextRequest.appended.slice(advance.transcriptStart)),
         ];
         session.nextEventId = advance.eventId + 1;
         session.parentHead = outcome.head;
@@ -741,7 +1179,7 @@ export class PlayCallChain {
         crashAtPlayAdvanceEdge("after_timeline_settled");
         await this.#worlds.playAdvances.markSettled(advance, outcome.head);
     }
-    #prepareResponseSettlement(session, advance, response) {
+    async #prepareResponseSettlement(session, advance, 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.");
@@ -775,7 +1213,7 @@ export class PlayCallChain {
         const trailingEvents = [];
         let nextEventId = advance.eventId + 1;
         for (const call of calls) {
-            const item = prepareTool(session, workingTools, advance.exchange, call);
+            const item = prepareTool(session, workingTools, advance.exchange, call, this.#compiler.locale);
             prepared.push(item);
             trailingEvents.push({
                 id: nextEventId++,
@@ -789,7 +1227,72 @@ 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.
+        const writes = [...workingTools.values()].filter(({ result }) => result.candidateWrite !== undefined);
+        let worldClock;
+        if (writes.length > 0) {
+            try {
+                // Author controls may change while an existing Provider context stays
+                // frozen. Predictions and clock capture use the controls active now.
+                const binding = await this.#worlds.bindPlayCallChain(session.worldId);
+                const snapshot = WorldDocumentStore.open({
+                    layout: "world_state",
+                    files: [
+                        ...session.documents.snapshot.files.filter(({ path }) => path.startsWith("state/")),
+                        ...Object.entries(binding.files)
+                            .filter(([path]) => path.startsWith("control/"))
+                            .map(([path, contents]) => ({ path, contents })),
+                    ],
+                });
+                worldClock = readDeclaredWorldClock(snapshot);
+                const { coverage, maintenance } = this.#compiler.inspectWorldMaterials({
+                    controlFingerprint: "receipt",
+                    documentSnapshot: snapshot,
+                    history: Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
+                    additionalMaterials: session.nextMaterials,
+                });
+                for (const { result } of writes) {
+                    const write = result.candidateWrite;
+                    write.freshContextCoverage = renderFreshContextCoverage(snapshot, coverage, write.shortRef, this.#compiler.locale);
+                    const previous = session.documents.committedSnapshot.query({
+                        kind: "read_document",
+                        document: { shortRef: write.shortRef },
+                    });
+                    const advice = renderWriteSizeAdvice(maintenance, write.shortRef, previous.kind === "read_document"
+                        ? Buffer.byteLength(previous.body, "utf8")
+                        : null, this.#compiler.locale);
+                    if (advice.length > 0)
+                        write.freshContextCoverage += `\n${advice}`;
+                }
+            }
+            catch (error) {
+                // A coverage prediction must never reject an otherwise valid write.
+                const reason = error instanceof Error ? error.message : "Material selection failed";
+                for (const { result } of writes)
+                    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 &&
+            session.events.some((event) => event.id >
+                Math.max(previousNarrative?.id ?? 0, previousPlayer?.id ?? 0) &&
+                event.kind === "tool_result" &&
+                event.name === "world_checkpoint" &&
+                event.ok);
+        const narrativeCheckpoint = checkpointRequested
+            ? {
+                contextId: session.chainId,
+                completedPlayerRounds: completedPlayerRounds({
+                    ...Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
+                    "message.pending.narrator": text,
+                }),
+            }
+            : undefined;
         const assistantItem = {
             kind: "assistant",
             text,
@@ -803,6 +1306,10 @@ export class PlayCallChain {
         };
         return {
             assistantEvent,
+            playContext: session.continuityContextId ?? session.chainId,
+            ...(worldClock === undefined || stateChanges.length === 0
+                ? {}
+                : { worldClock }),
             trailingEvents,
             transcriptStart: session.transcript.length,
             transcriptAppend: [
@@ -812,11 +1319,15 @@ export class PlayCallChain {
                     ? [assistantItem]
                     : []),
                 ...prepared.map(({ transcript }) => structuredClone(transcript)),
+                ...(calls.length > 0 && hasText
+                    ? [toolStepNotice(this.#compiler.locale)]
+                    : []),
             ],
             completedTools: [...workingTools.values()].map((item) => structuredClone(item)),
             authorizationCheckpoint: session.documents.authorizationCheckpoint(),
             stateChanges: structuredClone(stateChanges),
             visibleText,
+            ...(narrativeCheckpoint === undefined ? {} : { narrativeCheckpoint }),
         };
     }
     async #settleResponseAdvance(session, advance, prepared) {
@@ -838,6 +1349,12 @@ export class PlayCallChain {
         let committedHead;
         if (settlement.visibleText || settlement.stateChanges.length > 0) {
             const outcome = await this.#worlds.commitPlayStep({
+                ...(settlement.playContext === undefined
+                    ? {}
+                    : { playContext: settlement.playContext }),
+                ...(settlement.worldClock === undefined
+                    ? {}
+                    : { worldClock: settlement.worldClock }),
                 operationId: advance.operationId,
                 worldId: session.worldId,
                 parentHead: advance.parentHead,
@@ -851,9 +1368,20 @@ export class PlayCallChain {
                     : [],
                 nextMaterials: structuredClone(session.nextMaterials),
                 stateChanges: structuredClone(settlement.stateChanges),
+                ...(settlement.narrativeCheckpoint === undefined
+                    ? {}
+                    : { narrativeCheckpoint: settlement.narrativeCheckpoint }),
             });
             committedHead = outcome.head;
             settlement.assistantEvent.committedHead = outcome.head;
+            if (settlement.narrativeCheckpoint !== undefined) {
+                settlement.assistantEvent.checkpoint = true;
+                session.narrativeCheckpoint = {
+                    ...settlement.narrativeCheckpoint,
+                    head: outcome.head,
+                    historyMessageId: `message.${outcome.head.slice("commit:".length)}.1.narrator`,
+                };
+            }
             crashAtPlayAdvanceEdge("after_authority_accepted");
             appendCommittedHistory(session, outcome.head, outcome.historyAppend);
         }
@@ -901,6 +1429,8 @@ export class PlayCallChain {
             }
             mergeChangedDocuments(session, settlement.stateChanges);
         }
+        if (settlement.stateChanges.length > 0)
+            await this.#bindDocumentMaintenance(session.documents, session.worldId, session.parentHead);
         session.exchange = Math.max(session.exchange, advance.exchange);
         session.canRetry = false;
         session.lastFailure = null;
@@ -1007,6 +1537,16 @@ export class PlayCallChain {
             let response;
             try {
                 this.#observeInvocation(session.chainId, "waiting", { dispatches: 1 });
+                if (modelHost.previewRequest !== undefined &&
+                    (request.exchange === 1 ||
+                        request.exchange === session.promptRuns?.at(-1)?.exchange)) {
+                    try {
+                        await this.#worlds.playTimeline.recordInitialEncoding(session.worldId, session.chainId, modelHost.previewRequest(request), request.exchange);
+                    }
+                    catch {
+                        // Optional diagnostics never interrupt a model request or alter its cache key.
+                    }
+                }
                 response = await modelHost.exchange(request, {
                     signal,
                     onDelta: (delta) => {
@@ -1024,6 +1564,7 @@ export class PlayCallChain {
                         else if (delta.kind === "tool")
                             event.toolFragment = `${event.toolFragment ?? ""}${delta.text}`;
                         touch(session);
+                        this.changed(session.worldId);
                         notifyAssistantDelta(observer, {
                             eventId: event.id,
                             kind: delta.kind,
@@ -1056,7 +1597,8 @@ export class PlayCallChain {
                 });
                 session.status = "interrupted";
                 const requiresFreshContext = error instanceof ModelHostContinuationError ||
-                    error instanceof ModelHostOutcomeUnknownError;
+                    error instanceof ModelHostOutcomeUnknownError ||
+                    modelHostFailureRequiresFreshContext(error);
                 session.canRetry =
                     !requiresFreshContext && error instanceof ModelHostFailureError;
                 session.lastFailure = message;
@@ -1069,7 +1611,7 @@ export class PlayCallChain {
             try {
                 await this.#worlds.playAdvances.recordProviderCompleted(advance, durableResponse);
                 crashAtPlayAdvanceEdge("after_provider_completed");
-                const settlement = this.#prepareResponseSettlement(session, advance, durableResponse);
+                const settlement = await this.#prepareResponseSettlement(session, advance, durableResponse);
                 await this.#worlds.playAdvances.recordSettlementPrepared(advance, settlement);
                 crashAtPlayAdvanceEdge("after_settlement_prepared");
                 const failedTools = settlement.trailingEvents.filter((candidate) => candidate.kind === "tool_result" && !candidate.ok);
@@ -1123,7 +1665,7 @@ export class PlayCallChain {
                             message: "The play call chain recovered during a later model exchange and completed.",
                             details: { parentHead: session.parentHead },
                         });
-                    if ((session.followups?.length ?? 0) > 0) {
+                    if ((currentPlayPrompt(session).followups?.length ?? 0) > 0) {
                         // Follow-up artifacts are part of this player-visible invocation.
                         // Keep `running` ephemeral: the settled main response remains the
                         // durable recovery point if this Runtime process stops here.
@@ -1141,6 +1683,7 @@ export class PlayCallChain {
                             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);
@@ -1222,9 +1765,13 @@ export class PlayCallChain {
      * trace and the chain still returns to `ready`.
      */
     async #runFollowups(session, modelHost, signal, observer) {
-        const followups = session.followups ?? [];
+        const followups = currentPlayPrompt(session).followups ?? [];
         if (this.#artifacts === undefined || followups.length === 0)
             return;
+        const reply = session.events.findLast((event) => event.kind === "assistant" &&
+            event.committedHead === session.parentHead);
+        if (reply === undefined)
+            throw new PlayCallChainError("Follow-up reply is not committed");
         const observeFollowupDelta = (delta) => {
             this.#observeInvocation(session.chainId, "followup", {
                 ...(delta.kind === "reasoning"
@@ -1258,13 +1805,15 @@ export class PlayCallChain {
         try {
             await runPlayFollowupRequests({
                 artifacts: this.#artifacts,
+                controls: this.#worlds.extensionRequests,
+                presentations: frozenFollowupPresentations(session),
                 modelHost,
                 followups,
-                bootstrap: session.bootstrap,
+                bootstrap: currentPlayPrompt(session).bootstrap,
                 // Captured once: every followup is dispatched against this exact
                 // prefix, so none of them observes another one's prompt or output.
                 prefix: structuredClone(session.transcript),
-                toolStrategy: session.bootstrap.toolStrategy,
+                toolStrategy: currentPlayPrompt(session).bootstrap.toolStrategy,
                 context: {
                     // A follow-up produces no world endpoint of its own, so it starts and
                     // ends on the settled exchange's head. Reconciliation keeps panels
@@ -1272,9 +1821,15 @@ export class PlayCallChain {
                     worldId: session.worldId,
                     parentHead: session.parentHead,
                     operationId: followupOperationId(session),
-                    playPresetId: session.playPreset.id,
-                    playPresetRevision: session.playPreset.revision,
-                    playPresetScriptsEnabled: session.playPresetScriptsEnabled ?? true,
+                    attachment: {
+                        contextId: session.continuityContextId ?? session.chainId,
+                        eventId: reply.id,
+                        head: session.parentHead,
+                        runId: `${session.chainId}:send:${session.promptRuns?.at(-1)?.firstEventId ?? reply.id}`,
+                    },
+                    playPresetId: currentPlayPrompt(session).playPreset.id,
+                    playPresetRevision: currentPlayPrompt(session).playPreset.revision,
+                    playPresetScriptsEnabled: currentPlayPrompt(session).playPresetScriptsEnabled ?? true,
                 },
                 head: session.parentHead,
                 maxOutputTokens: modelHost.binding().maxOutputTokens,
@@ -1331,8 +1886,24 @@ export class PlayCallChain {
             throw new PlayCallChainError("The call-chain record differs from the current world endpoint; use a fresh context.");
         return session;
     }
+    async #bindDocumentMaintenance(documents, worldId, head) {
+        const inspection = await this.#worlds.inspectDocumentMaintenance(worldId, head);
+        if (inspection.documentMaintenanceUnavailableReason === undefined)
+            documents.bindMaintenance(inspection.documentMaintenance, this.#compiler.locale);
+        else
+            documents.bindMaintenanceUnavailable(inspection.documentMaintenanceUnavailableReason, this.#compiler.locale);
+        return inspection.documentMaintenance;
+    }
     async #hydrateSession(persisted, advance) {
-        const binding = await this.#worlds.bindPlayCallChain(persisted.worldId);
+        const currentBinding = await this.#worlds.bindPlayCallChain(persisted.worldId);
+        // A completed chain still describes its own immutable endpoint after a
+        // world revision. Restore its reads against that state, not the revised
+        // current tree. An unsettled advance keeps the existing crash-recovery
+        // path because Authority may already contain its prepared result.
+        const binding = currentBinding.parentHead !== persisted.parentHead &&
+            advance?.settled !== null
+            ? await this.#worlds.bindPlayCallChainAt(persisted.worldId, persisted.parentHead)
+            : currentBinding;
         let documents;
         try {
             documents = restorePlayDocuments(binding.files, persisted, persisted.events);
@@ -1344,12 +1915,14 @@ export class PlayCallChain {
             documents = new FileNativePlayDocuments(binding.files);
             documents.restoreAuthorizationCheckpoint(prepared.authorizationCheckpoint);
         }
+        await this.#bindDocumentMaintenance(documents, persisted.worldId, binding.parentHead);
         return {
             ...structuredClone(persisted),
             documentAuthorizationCheckpoints: persisted.documentAuthorizationCheckpoints?.map((checkpoint) => structuredClone(checkpoint)) ?? [],
             nextMaterials: structuredClone(binding.additionalMaterials),
             documents,
             history: historyEntries(binding.history),
+            narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(persisted.completedTools.map((item) => [
                 item.key,
                 structuredClone(item),
@@ -1378,7 +1951,7 @@ export class PlayCallChain {
         }
         let settlement = current.settlementPrepared?.settlement;
         if (settlement === undefined) {
-            settlement = this.#prepareResponseSettlement(session, current.base, current.providerCompleted.response);
+            settlement = await this.#prepareResponseSettlement(session, current.base, current.providerCompleted.response);
             await this.#worlds.playAdvances.recordSettlementPrepared(current.base, settlement);
         }
         await this.#settleResponseAdvance(session, current.base, settlement);
@@ -1442,11 +2015,11 @@ function createRequest(session, modelHost, exchange, appended = session.transcri
 }
 function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, appended = session.transcript) {
     return {
-        bootstrap: structuredClone(session.bootstrap),
-        tools: structuredClone(session.tools),
-        toolUniverse: structuredClone(session.tools),
-        allowedTools: session.tools.map(({ name }) => name),
-        toolStrategy: session.bootstrap.toolStrategy,
+        bootstrap: structuredClone(currentPlayPrompt(session).bootstrap),
+        tools: structuredClone(currentPlayPrompt(session).tools),
+        toolUniverse: structuredClone(currentPlayPrompt(session).tools),
+        allowedTools: currentPlayPrompt(session).tools.map(({ name }) => name),
+        toolStrategy: currentPlayPrompt(session).bootstrap.toolStrategy,
         appended: structuredClone([...appended]),
         requestId: "play_call_chain",
         operationId: session.chainId,
@@ -1467,9 +2040,12 @@ function finalizePreparedReceipts(settlement) {
         const candidateWrite = completed.result.candidateWrite;
         if (!completed.result.ok || candidateWrite === undefined)
             continue;
-        const markdown = candidateWrite.changed && committedWriteRefs.has(candidateWrite.shortRef)
+        const status = candidateWrite.changed && committedWriteRefs.has(candidateWrite.shortRef)
             ? `@${candidateWrite.shortRef} write succeeded`
             : `@${candidateWrite.shortRef} unchanged`;
+        const markdown = [status, candidateWrite.freshContextCoverage]
+            .filter(Boolean)
+            .join("\n");
         completed.result.markdown = markdown;
         delete completed.result.candidateWrite;
         const callId = completed.key.slice(completed.key.indexOf(":") + 1);
@@ -1503,7 +2079,7 @@ function appendCommittedHistory(session, head, messages) {
         session.history.push({ path, contents: message.exactText });
     }
 }
-function prepareTool(session, working, exchange, call) {
+function prepareTool(session, working, exchange, call, locale) {
     const key = `${exchange}:${call.id}`;
     const signature = JSON.stringify(call.arguments);
     const completed = working.get(key);
@@ -1521,7 +2097,7 @@ function prepareTool(session, working, exchange, call) {
                 };
     }
     else if (!callChainToolNames.has(call.name) ||
-        !session.tools.some(({ name }) => name === call.name)) {
+        !currentPlayPrompt(session).tools.some(({ name }) => name === call.name)) {
         result = {
             ok: false,
             failureKind: "protocol",
@@ -1530,7 +2106,24 @@ function prepareTool(session, working, exchange, call) {
     }
     else {
         try {
-            result = session.documents.execute(call, session.history);
+            result =
+                call.name === "world_checkpoint"
+                    ? typeof call.arguments === "object" &&
+                        call.arguments !== null &&
+                        !Array.isArray(call.arguments) &&
+                        Object.keys(call.arguments).length === 0
+                        ? {
+                            ok: true,
+                            markdown: locale === "zh-CN"
+                                ? "检查点已登记，将在本轮最终叙事提交后生效。玩家随后可以选择开启全新上下文。"
+                                : "Checkpoint registered. It becomes effective when this turn’s final narrative commits. The player can then choose a fresh context.",
+                        }
+                        : {
+                            ok: false,
+                            failureKind: "protocol",
+                            markdown: "world_checkpoint requires an empty argument object.",
+                        }
+                    : session.documents.execute(call, session.history);
         }
         catch (error) {
             result = {
@@ -1595,9 +2188,10 @@ function restorePlayDocuments(files, context, events) {
     const documents = new FileNativePlayDocuments(files);
     try {
         const checkpoint = documentAuthorizationThroughEvents(context, events);
-        if (checkpoint === undefined)
-            documents.bindBootstrap(context.bootstrap);
-        else
+        const runs = playPromptRunsThroughEvents(context, events);
+        if (checkpoint === undefined || runs.length > 0)
+            documents.bindBootstrap(currentPlayPrompt({ ...context, promptRuns: runs }).bootstrap);
+        if (checkpoint !== undefined)
             documents.restoreAuthorizationCheckpoint(checkpoint.authorization);
     }
     catch (error) {
@@ -1618,6 +2212,7 @@ function documentAuthorizationThroughEvents(context, events) {
 }
 function independentContextCopy(source) {
     const context = structuredClone(source);
+    context.continuityContextId ??= source.chainId;
     delete context.derivedFrom;
     delete context.branchedBeforePlayer;
     return context;
@@ -1644,7 +2239,7 @@ function projectContext(context) {
             ? {}
             : { baselineHistoryLength: context.baselineHistoryLength }),
         parentHead: context.parentHead,
-        playPreset: structuredClone(context.playPreset),
+        playPreset: structuredClone(recordedPlayPrompt(context).playPreset),
         status: context.status,
         canRetry: context.canRetry,
         events: context.events
@@ -1691,6 +2286,57 @@ function projectView(session) {
         previousContexts: (session.previousContexts ?? []).map((context) => projectContext(context)),
     };
 }
+function projectContextReads(session) {
+    const completed = new Map(session.completedTools.map((tool) => [tool.key, tool.result]));
+    let exchange = 0;
+    const calls = new Map();
+    const reads = [];
+    for (const event of session.events) {
+        if (event.kind === "assistant") {
+            exchange = event.exchange;
+            continue;
+        }
+        if (event.kind === "tool_call" && event.name === "context_read") {
+            const ref = isRecord(event.arguments) && typeof event.arguments.ref === "string"
+                ? event.arguments.ref
+                : "(invalid ref)";
+            calls.set(event.callId, {
+                key: `${exchange}:${event.callId}`,
+                ref,
+            });
+            continue;
+        }
+        if (event.kind !== "tool_result" || event.name !== "context_read")
+            continue;
+        const call = calls.get(event.callId);
+        if (call === undefined)
+            continue;
+        const result = completed.get(call.key);
+        reads.push({
+            eventId: event.id,
+            callId: event.callId,
+            ref: call.ref,
+            ok: event.ok,
+            complete: result === undefined ? null : completedContextReadIsComplete(result),
+            markdown: result?.markdown ?? null,
+            locator: result?.readAuthorization?.locator ?? null,
+        });
+    }
+    return reads;
+}
+function completedContextReadIsComplete(result) {
+    if (result.readAuthorization === undefined)
+        return /(?:^|\n)Complete: yes(?:\n|$)/u.test(result.markdown);
+    const legacyAuthorization = result.readAuthorization;
+    if (!isRecord(legacyAuthorization) || !isRecord(legacyAuthorization.page))
+        return true;
+    return (typeof legacyAuthorization.page.end === "number" &&
+        typeof legacyAuthorization.page.total === "number" &&
+        legacyAuthorization.page.end === legacyAuthorization.page.total);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function eventsThroughHead(events, head) {
     const selectedIndex = events.findIndex((event) => (event.kind === "player" || event.kind === "assistant") &&
         event.committedHead === head);
@@ -1708,6 +2354,11 @@ function transcriptThroughEvents(transcript, events) {
     let cursor = 0;
     for (const [index, event] of events.entries()) {
         if (event.kind === "player") {
+            const marker = transcript[cursor];
+            if (isPlayerRoundMarker(marker)) {
+                result.push(structuredClone(marker));
+                cursor += 1;
+            }
             const item = transcript[cursor];
             if (item?.kind !== "player" || item.text !== event.text)
                 throw new PlayCallChainError("Source call-chain events do not match the model transcript, so a fork cannot be created safely.");
@@ -1716,6 +2367,9 @@ function transcriptThroughEvents(transcript, events) {
             continue;
         }
         if (event.kind === "assistant" && event.status === "completed") {
+            const notice = transcript[cursor];
+            const hasContinuationNotice = notice?.kind === "runtime_notice" && notice.notice === "continuation";
+            const item = transcript[cursor + (hasContinuationNotice ? 1 : 0)];
             const hasToolCall = events
                 .slice(index + 1)
                 .find((candidate) => candidate.kind === "player" ||
@@ -1723,12 +2377,17 @@ function transcriptThroughEvents(transcript, events) {
                 candidate.kind === "tool_call");
             const recorded = event.text.trim().length > 0 ||
                 hasToolCall?.kind === "tool_call" ||
-                transcript[cursor]?.kind === "assistant";
+                item?.kind === "assistant";
             if (!recorded)
                 continue;
-            const item = transcript[cursor];
             if (item?.kind !== "assistant" || item.text !== event.text)
                 throw new PlayCallChainError("Source call-chain responses do not match the model transcript, so a fork cannot be created safely.");
+            // A continuation notice belongs to the generation it precedes, never
+            // to a fork ending at the previously completed narrative.
+            if (hasContinuationNotice) {
+                result.push(structuredClone(notice));
+                cursor += 1;
+            }
             result.push(structuredClone(item));
             cursor += 1;
             continue;
@@ -1739,6 +2398,13 @@ function transcriptThroughEvents(transcript, events) {
                 throw new PlayCallChainError("Source call-chain tool results do not match the model transcript, so a fork cannot be created safely.");
             result.push(structuredClone(item));
             cursor += 1;
+            // A tool-step notice follows the entire settled batch and remains part
+            // of its closure even when the selected endpoint stops at that batch.
+            const notice = transcript[cursor];
+            if (notice?.kind === "runtime_notice" && notice.notice === "tool_step") {
+                result.push(structuredClone(notice));
+                cursor += 1;
+            }
         }
     }
     return result;
@@ -1769,6 +2435,55 @@ function derivedChainId(sourceChainId, branchIdentity, targetWorldId) {
         .digest("hex")
         .slice(0, 40)}`;
 }
+function playerRevisionRestoresHead(source, selectedEventIndex) {
+    let restoresHead = source.baselineHead;
+    for (const event of source.events.slice(0, selectedEventIndex))
+        if ((event.kind === "player" || event.kind === "assistant") &&
+            event.committedHead !== undefined)
+            restoresHead = event.committedHead;
+    return restoresHead;
+}
+function playerRevisionRequestFingerprint(request, selectedHead, restoresHead) {
+    const base = {
+        schema: "narraeon.timeline-revision-request/v1",
+        chainId: request.chainId,
+        eventId: request.eventId,
+        selectedHead,
+        restoresHead,
+        replacementExchangeId: request.replacementExchangeId,
+        replacementText: request.replacementText,
+    };
+    // Keep the released continuation fingerprint byte-for-byte recoverable;
+    // the fresh strategy owns a new request shape with an explicit mode.
+    const value = request.continuation === "continue_context"
+        ? base
+        : {
+            ...base,
+            schema: "narraeon.timeline-revision-request/v2",
+            continuation: request.continuation,
+        };
+    return ("sha256:" + createHash("sha256").update(JSON.stringify(value)).digest("hex"));
+}
+function playerRevisionChainId(sourceChainId, operationId, worldId, continuation) {
+    return derivedChainId(sourceChainId, `${continuation === "fresh_context" ? "timeline-revision-fresh" : "timeline-revision"}:${operationId}`, worldId);
+}
+function playerRevisionTimelineGeneration(sourceGeneration, operationId, worldId, continuation) {
+    return `timeline:${createHash("sha256")
+        .update(JSON.stringify({
+        schema: "narraeon.player-revision-timeline-generation/v1",
+        sourceGeneration,
+        operationId,
+        worldId,
+        continuation,
+    }))
+        .digest("hex")
+        .slice(0, 40)}`;
+}
+function completedAssistantExchange(events) {
+    return Math.max(0, ...events
+        .filter((event) => event.kind === "assistant" && event.status === "completed")
+        .map(({ exchange }) => exchange));
+}
 function historyEntries(history) {
     return Object.entries(history).map(([path, contents]) => ({
         path,
@@ -1813,3 +2528,41 @@ function crashAtPlayAdvanceEdge(edge) {
         process.env.NARRAEON_INTERNAL_TEST_CRASH_AT_PLAY_ADVANCE_EDGE === edge)
         throw new Error(`Simulated process exit at play advance edge: ${edge}`);
 }
+function frozenFollowupPresentations(session) {
+    const files = session.promptRuns?.at(-1)?.presetFiles ?? session.presetFiles;
+    if (files === undefined)
+        return {};
+    const parsed = parsePlayPresetFiles(files);
+    if (parsed.kind === "invalid")
+        throw parsed.error;
+    const definition = parsed.definition;
+    return Object.fromEntries((currentPlayPrompt(session).followups ?? []).map((followup) => [
+        followup.id,
+        Object.fromEntries(followup.artifacts.flatMap((declaration) => {
+            const resources = followup.frozenResources;
+            const mount = resources?.mount ??
+                definition.mounts.find((item) => item.channel === declaration.channel)?.mount;
+            return mount === undefined
+                ? []
+                : [
+                    [
+                        declaration.name,
+                        {
+                            ...resources,
+                            declaration: structuredClone(declaration),
+                            files: resources?.files ??
+                                Object.fromEntries([
+                                    declaration.renderer,
+                                    declaration.regex,
+                                    ...(declaration.scripts ?? []),
+                                    ...(declaration.assets ?? []),
+                                ].flatMap((path) => path === undefined
+                                    ? []
+                                    : [[path, (resources?.files ?? files)[path]]])),
+                            mount,
+                        },
+                    ],
+                ];
+        })),
+    ]));
+}