narraeon 0.7.0 → 0.7.2

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

@@ -6,7 +6,7 @@ import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
-import { currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
+import { cloneSharingPromptRuns, currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, promptRunStrings, sharePromptRun, } from "./PlayPromptRun.js";
 import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash, randomBytes } from "node:crypto";
 import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, turnGuideNotice, } from "./PlayContinuity.js";
@@ -52,6 +52,12 @@ function isPlayerRevisionIntent(value) {
         (record.continuation === "continue_context" ||
             typeof record.freshContext === "object"));
 }
+/**
+ * Play sessions kept in memory at once, one per most recently used world. An
+ * idle session beyond this is released and reloaded from disk on next use,
+ * which behaves like a process restart (ADR-0044). Not a user setting.
+ */
+const residentWorldLimit = 3;
 export { PlayCallChainError } from "./PlayCallChainError.js";
 /**
  * The production play loop: one durable logical context, no Runtime-authored
@@ -74,6 +80,8 @@ export class PlayCallChain {
     #activeInvocations = new Map();
     /** Resolves when the matching invocation has left the active table. */
     #invocationSettled = new Map();
+    /** Worlds whose release is queued in their WorldQueue slot. */
+    #releasing = new Set();
     constructor(worlds, compiler = new FileNativePromptCompiler(), artifacts, failureLog, changed = () => {
         /* No observers attached. */
     }) {
@@ -91,7 +99,12 @@ export class PlayCallChain {
         validateIdentity(input.exchangeId, "exchange ID");
         validatePlayerText(input.playerText);
         assertModelHostBinding(input.modelBinding, input.modelHost);
-        const existing = await this.#readPersisted(input.worldId);
+        // Only a resubmission to the current context needs that context loaded.
+        await this.#worlds.ensureCurrentStorage(input.worldId);
+        const outline = await this.#worlds.playTimeline.readTimelineOutline(input.worldId);
+        const existing = outline?.chainIds.at(-1) === input.chainId
+            ? await this.#readPersisted(input.worldId)
+            : null;
         if (existing?.chainId === input.chainId) {
             const duplicate = duplicatePlayerExchange(existing, input.exchangeId, input.playerText, "fresh");
             if (duplicate)
@@ -136,9 +149,8 @@ export class PlayCallChain {
             continuityContextId: input.chainId,
             worldId: input.worldId,
             previousContexts: [],
-            previousChainId: existing?.chainId ?? null,
-            timelineGeneration: existing?.timelineGeneration ??
-                this.#worlds.playTimeline.newGeneration(),
+            previousChainId: outline?.chainIds.at(-1) ?? null,
+            timelineGeneration: outline?.generation ?? this.#worlds.playTimeline.newGeneration(),
             baselineHead: binding.parentHead,
             baselineHistoryLength: Object.keys(binding.history).length,
             parentHead: binding.parentHead,
@@ -178,8 +190,7 @@ export class PlayCallChain {
         };
         if (activeId !== undefined)
             this.#active.delete(activeId);
-        this.#active.set(session.chainId, session);
-        this.#worldChains.set(session.worldId, session.chainId);
+        this.#registerResident(session);
         await this.#persist(session);
         await this.#worlds.completeArchiveFreshContext(session.worldId);
         return this.#submitPlayer(session, input.exchangeId, input.playerText, "fresh", input.modelHost, signal, input.observer);
@@ -257,7 +268,8 @@ export class PlayCallChain {
         session.history = historyEntries(binding.history, binding.historyBackgrounds);
         session.narrativeCheckpoint = binding.narrativeCheckpoint;
         session.nextMaterials = structuredClone(binding.additionalMaterials);
-        (session.promptRuns ??= []).push({
+        const previousRun = session.promptRuns?.at(-1);
+        (session.promptRuns ??= []).push(sharePromptRun({
             schemaVersion: 1,
             firstEventId: session.nextEventId,
             head: binding.parentHead,
@@ -272,7 +284,7 @@ export class PlayCallChain {
             followups: structuredClone(compilation.followups ?? []),
             playPresetScriptsEnabled: playPreset.scriptsEnabled,
             presetFiles: structuredClone(playPreset.files),
-        });
+        }, promptRunStrings(previousRun)));
         await this.#persist(session);
     }
     cancel(input) {
@@ -322,6 +334,7 @@ export class PlayCallChain {
         this.#worlds.freezeControl(input.worldId, controlUseId);
         this.#activeInvocations.set(input.chainId, invocation);
         this.#invocationSettled.set(input.chainId, settled);
+        this.#touchWorld(input.worldId);
         this.changed(input.worldId);
         try {
             await this.#worlds.assertWorldRevisionUnlocked(input.worldId);
@@ -330,6 +343,7 @@ export class PlayCallChain {
         finally {
             if (this.#activeInvocations.get(input.chainId) === invocation)
                 this.#activeInvocations.delete(input.chainId);
+            this.#enforceResidentLimit();
             this.#worlds.releaseControl(input.worldId, controlUseId);
             this.changed(input.worldId);
             this.#invocationSettled.delete(input.chainId);
@@ -375,6 +389,10 @@ export class PlayCallChain {
             // running. Presentation failure never cancels or changes play Authority.
         }
     }
+    /** Worlds whose play session is held in memory, least recently used first. */
+    residentWorldIds() {
+        return [...this.#worldChains.keys()];
+    }
     async inspectWorld(worldId) {
         const session = await this.#worldSession(worldId);
         return session === null ? null : this.#projectActiveView(session);
@@ -394,6 +412,16 @@ export class PlayCallChain {
             : event);
         return view;
     }
+    /** The live context's frozen binding and transcript, without reloading it. */
+    async currentContinuation(worldId) {
+        const session = await this.#worldSession(worldId);
+        return session === null
+            ? null
+            : {
+                modelBinding: session.modelBinding,
+                transcript: structuredClone(session.transcript),
+            };
+    }
     async #worldSession(worldId) {
         return this.#loadWorldSession(worldId);
     }
@@ -406,9 +434,13 @@ export class PlayCallChain {
         const activeId = this.#worldChains.get(worldId);
         const active = activeId === undefined ? undefined : this.#active.get(activeId);
         if (active !== undefined) {
+            this.#touchWorld(worldId);
             if (this.#activeInvocations.get(active.chainId)?.worldId !== active.worldId)
                 await this.#reconcileSessionAdvance(active);
-            return active;
+            // Released while reconciling: load the current session, not this copy.
+            if (this.#active.get(active.chainId) === active)
+                return active;
+            return this.#loadWorldSession(worldId);
         }
         const pending = this.#hydrating.get(worldId);
         if (pending !== undefined)
@@ -438,8 +470,7 @@ export class PlayCallChain {
         // forgetWorld ran during hydration; do not resurrect the old session.
         if (this.#hydrating.get(worldId)?.token !== token)
             return null;
-        this.#active.set(hydrated.chainId, hydrated);
-        this.#worldChains.set(worldId, hydrated.chainId);
+        this.#registerResident(hydrated);
         await this.#reconcileSessionAdvance(hydrated, advance);
         return hydrated;
     }
@@ -566,10 +597,10 @@ export class PlayCallChain {
         const existing = await this.#readPersisted(input.targetWorldId);
         if (existing !== null)
             return projectView(existing);
-        const source = await this.#readPersisted(input.sourceWorldId);
-        if (source === null)
-            return null;
+        await this.#worlds.ensureCurrentStorage(input.sourceWorldId);
         const sourceContexts = await this.#worlds.playTimeline.readAllContexts(input.sourceWorldId);
+        if (sourceContexts.length === 0)
+            return null;
         const selectedContextIndex = sourceContexts.findIndex(({ events }) => eventsThroughHead(events, input.sourceHead) !== null);
         if (selectedContextIndex < 0)
             return null;
@@ -586,10 +617,10 @@ export class PlayCallChain {
         });
     }
     async stageForkToDerivedWorld(input) {
-        const source = await this.#readPersisted(input.sourceWorldId);
-        if (source === null)
-            return null;
+        await this.#worlds.ensureCurrentStorage(input.sourceWorldId);
         const sourceContexts = await this.#worlds.playTimeline.readAllContexts(input.sourceWorldId);
+        if (sourceContexts.length === 0)
+            return null;
         const selectedContextIndex = input.retainCompleteTimeline
             ? sourceContexts.length - 1
             : sourceContexts.findIndex(({ events }) => eventsThroughHead(events, input.sourceHead) !== null);
@@ -631,10 +662,32 @@ export class PlayCallChain {
         if (active?.status === "running")
             throw new PlayCallChainError("A model request is still running; wait for it to return before revising committed history.");
         await this.#recoverPlayerRevision(input.worldId);
-        const source = await this.#readPersisted(input.worldId);
-        if (source === null)
-            throw new PlayCallChainError("The current world has no model call chain to revise.");
+        // The plan's fully loaded contexts are out of scope once it returns, so
+        // completion does not hold a second copy of a long timeline.
+        const plan = await this.#planPlayerRevision(input);
+        if (plan.kind === "applied") {
+            const current = await this.#readPersisted(input.worldId);
+            if (current === null)
+                throw new PlayCallChainError("The current world has no model call chain to revise.");
+            return {
+                outcome: "revised",
+                worldId: input.worldId,
+                playCallChain: projectView(current),
+            };
+        }
+        await this.#worlds.writePlayerRevisionIntent(input.worldId, plan.intent);
+        const revised = await this.#completePlayerRevision(plan.intent);
+        return {
+            outcome: "revised",
+            worldId: input.worldId,
+            playCallChain: projectView(revised),
+        };
+    }
+    async #planPlayerRevision(input) {
+        await this.#worlds.ensureCurrentStorage(input.worldId);
         const contexts = await this.#worlds.playTimeline.readAllContexts(input.worldId);
+        if (contexts.length === 0)
+            throw new PlayCallChainError("The current world has no model call chain to revise.");
         // A replacement exchange that already reached the timeline is a repeat of
         // the same request: answer with the current view and do not redo it.
         const applied = contexts
@@ -645,11 +698,7 @@ export class PlayCallChain {
         if (applied !== undefined) {
             if (applied.kind === "player" && applied.text !== input.replacementText)
                 throw new PlayCallChainError("The same replacement exchange ID is already bound to different player text.");
-            return {
-                outcome: "revised",
-                worldId: input.worldId,
-                playCallChain: projectView(source),
-            };
+            return { kind: "applied" };
         }
         const contextIndex = contexts.findIndex(({ chainId }) => chainId === input.chainId);
         if (contextIndex < 0)
@@ -682,13 +731,7 @@ export class PlayCallChain {
                 ? { freshContext: structuredClone(input.freshContext) }
                 : {}),
         };
-        await this.#worlds.writePlayerRevisionIntent(input.worldId, intent);
-        const revised = await this.#completePlayerRevision(intent);
-        return {
-            outcome: "revised",
-            worldId: input.worldId,
-            playCallChain: projectView(revised),
-        };
+        return { kind: "intent", intent };
     }
     /** Complete an interrupted revision recorded by a previous process. */
     async #recoverPlayerRevision(worldId) {
@@ -714,16 +757,25 @@ export class PlayCallChain {
     async #completePlayerRevisionQueued(intent) {
         const worldId = intent.worldId;
         const resultChainId = revisionChainId(intent.chainId, intent.operationId, worldId, intent.continuation);
-        const current = await this.#readPersisted(worldId);
-        if (current?.chainId === resultChainId) {
+        await this.#worlds.ensureCurrentStorage(worldId);
+        // Only the edited context is loaded in full; a long timeline's prompt runs
+        // would otherwise be held several times over.
+        const outline = await this.#worlds.playTimeline.readTimelineOutline(worldId);
+        if (outline?.chainIds.at(-1) === resultChainId) {
+            const current = await this.#readPersisted(worldId);
+            if (current === null)
+                throw new PlayCallChainError("The revised model context could not be read.");
             await this.#discardRevisedContexts(intent, resultChainId);
             await this.#worlds.clearPlayerRevisionIntent(worldId);
             return current;
         }
-        const contexts = await this.#worlds.playTimeline.readAllContexts(worldId);
-        const sourceIndex = contexts.findIndex(({ chainId }) => chainId === intent.chainId);
-        const sourceContext = contexts[sourceIndex];
-        if (sourceContext === undefined)
+        const sourceIndex = outline?.chainIds.findIndex((chainId) => chainId === intent.chainId) ??
+            -1;
+        const sourceContext = sourceIndex < 0
+            ? undefined
+            : (await this.#worlds.playTimeline.readContext(worldId, intent.chainId))
+                ?.value;
+        if (outline === null || sourceContext === undefined)
             throw new PlayCallChainError("The model context to revise does not exist.");
         const eventIndex = sourceContext.events.findIndex(({ id }) => id === intent.eventId);
         if (eventIndex < 0)
@@ -740,8 +792,8 @@ export class PlayCallChain {
         ]);
         if (binding.parentHead !== head)
             throw new PlayCallChainError("The player revision was committed, but current-world materialization has not reached the new endpoint.");
-        const timelineGeneration = revisionTimelineGeneration(current?.timelineGeneration ?? "none", intent.operationId, worldId, intent.continuation);
-        const previousChainId = sourceIndex === 0 ? null : contexts[sourceIndex - 1].chainId;
+        const timelineGeneration = revisionTimelineGeneration(outline.generation, intent.operationId, worldId, intent.continuation);
+        const previousChainId = sourceIndex === 0 ? null : outline.chainIds[sourceIndex - 1];
         const traceRetention = preparePlayerRevisionTrace(sourceContext, eventIndex);
         let revised;
         if (intent.continuation === "fresh_context") {
@@ -782,7 +834,7 @@ export class PlayCallChain {
                 updatedAt: Date.now(),
             };
         }
-        await this.#worlds.playTimeline.persist(structuredClone(revised));
+        await this.#worlds.playTimeline.persist(revised);
         if (intent.continuation === "fresh_context")
             await this.#worlds.completeArchiveFreshContext(worldId);
         await this.#discardRevisedContexts(intent, resultChainId);
@@ -1009,9 +1061,6 @@ export class PlayCallChain {
                     targetWorldRoot: input.targetWorldRoot,
                     source: context,
                     target: previousContext,
-                    ...(input.retainCompleteTimeline
-                        ? { retainCompleteContext: true }
-                        : {}),
                 });
             previousChainId = chainId;
         }
@@ -1031,16 +1080,13 @@ export class PlayCallChain {
             updatedAt: now,
         };
         if (input.targetWorldRoot === undefined)
-            await this.#worlds.playTimeline.persist(structuredClone(derived));
+            await this.#worlds.playTimeline.persist(cloneSharingPromptRuns(derived));
         else
             await this.#worlds.playTimeline.cloneContextPrefixToStaging({
                 sourceWorldId: input.sourceWorldId,
                 targetWorldRoot: input.targetWorldRoot,
                 source: sourceContext,
-                target: structuredClone(derived),
-                ...(input.retainCompleteTimeline
-                    ? { retainCompleteContext: true }
-                    : {}),
+                target: cloneSharingPromptRuns(derived),
             });
         return projectView(derived);
     }
@@ -1878,7 +1924,8 @@ export class PlayCallChain {
             if (active.worldId !== worldId)
                 throw new PlayCallChainError("The call chain does not belong to this world.");
             await this.#reconcileSessionAdvance(active);
-            return active;
+            if (this.#active.get(chainId) === active)
+                return active;
         }
         const session = await this.#loadWorldSession(worldId);
         if (session?.chainId !== chainId)
@@ -1908,7 +1955,7 @@ export class PlayCallChain {
         const documents = restorePlayDocuments(binding.files, persisted, persisted.events);
         await this.#bindDocumentMaintenance(documents, persisted.worldId, binding.parentHead);
         return {
-            ...structuredClone(persisted),
+            ...cloneSharingPromptRuns(persisted),
             nextMaterials: structuredClone(binding.additionalMaterials),
             documents,
             history: historyEntries(binding.history, binding.historyBackgrounds),
@@ -1982,9 +2029,80 @@ export class PlayCallChain {
         if (loaded === null)
             return null;
         this.#loadedCursors.set(loaded.value.chainId, loaded.cursor);
-        return structuredClone(loaded.value);
+        // A fresh read shares nothing, so it needs no defensive copy.
+        return loaded.value;
+    }
+    /** Makes a session the live one for its world, then trims idle worlds. */
+    #registerResident(session) {
+        this.#active.set(session.chainId, session);
+        this.#worldChains.delete(session.worldId);
+        this.#worldChains.set(session.worldId, session.chainId);
+        this.#enforceResidentLimit();
+    }
+    #touchWorld(worldId) {
+        const chainId = this.#worldChains.get(worldId);
+        if (chainId === undefined)
+            return;
+        this.#worldChains.delete(worldId);
+        this.#worldChains.set(worldId, chainId);
+    }
+    /**
+     * Schedules release of least recently used idle worlds until at most
+     * residentWorldLimit remain. The most recently used world is never a
+     * candidate. A busy or queued world is skipped, and a later call trims it
+     * once it has gone idle.
+     */
+    #enforceResidentLimit() {
+        const worldIds = [...this.#worldChains.keys()];
+        let excess = worldIds.length - residentWorldLimit - this.#releasing.size;
+        for (const worldId of worldIds.slice(0, -1)) {
+            if (excess <= 0)
+                return;
+            if (this.#releasing.has(worldId))
+                continue;
+            if (this.#worlds.operations.pendingWorldOperations(worldId) > 0 ||
+                !this.#isIdle(worldId))
+                continue;
+            excess -= 1;
+            this.#releasing.add(worldId);
+            void this.#worlds.operations.withWorldAuthorityLock(worldId, () => {
+                this.#releaseIfIdle(worldId);
+                return Promise.resolve();
+            });
+        }
+    }
+    /**
+     * Runs in the world's queue slot, so no world operation can hold this
+     * session while it is released. An operation queued after the release was
+     * scheduled is counted, and the release waits for a later call.
+     */
+    #releaseIfIdle(worldId) {
+        this.#releasing.delete(worldId);
+        if (this.#worlds.operations.pendingWorldOperations(worldId) > 1 ||
+            !this.#isIdle(worldId))
+            return;
+        const chainId = this.#worldChains.get(worldId);
+        if (chainId === undefined)
+            return;
+        this.#active.delete(chainId);
+        this.#worldChains.delete(worldId);
+        this.#loadedCursors.delete(chainId);
+    }
+    /** No call, hydration, or running request holds this world's session. */
+    #isIdle(worldId) {
+        const chainId = this.#worldChains.get(worldId);
+        const session = chainId === undefined ? undefined : this.#active.get(chainId);
+        if (session === undefined || session.status === "running")
+            return false;
+        if (this.#hydrating.has(worldId))
+            return false;
+        return ![...this.#activeInvocations.values()].some((invocation) => invocation.worldId === worldId);
     }
     async #persist(session) {
+        // Only the live session may write. A copy released from memory would fork
+        // the world's session; readers that hold one reload on their next step.
+        if (this.#active.get(session.chainId) !== session)
+            throw new PlayCallChainError("The play context was released from memory; reload it before writing.");
         touch(session);
         session.completedTools = [...session.completedToolMap.values()].map((item) => structuredClone(item));
         const { documents: _documents, history: _history, completedToolMap: _completedToolMap, persistenceCursor: _persistenceCursor, ...persisted } = session;
@@ -1992,7 +2110,7 @@ export class PlayCallChain {
         void _history;
         void _completedToolMap;
         void _persistenceCursor;
-        session.persistenceCursor = await this.#worlds.playTimeline.persist(structuredClone(persisted), session.persistenceCursor);
+        session.persistenceCursor = await this.#worlds.playTimeline.persist(cloneSharingPromptRuns(persisted), session.persistenceCursor);
     }
 }
 /**

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

@@ -8,12 +8,74 @@ export function recordedPlayPrompt(source) {
     return (source.promptRuns?.findLast((run) => run.firstEventId <= lastEvent) ??
         source);
 }
+/** Shared runs are frozen, so the returned runs are the context's own. */
 export function playPromptRunsThroughEvents(context, events) {
     const lastEvent = events.at(-1)?.id ?? 0;
     const runs = (context.promptRuns ?? []).filter(({ firstEventId }) => firstEventId <= lastEvent);
-    return structuredClone([
-        ...new Map(runs.map((run) => [run.firstEventId, run])).values(),
-    ]);
+    return [...new Map(runs.map((run) => [run.firstEventId, run])).values()];
+}
+/** Strings shorter than this are not worth a pool entry. */
+const sharedStringLength = 128;
+/**
+ * Make a freshly built or decoded run share the pool's equal strings, then
+ * freeze it: contexts and their copies hold the same run instead of a clone.
+ */
+export function sharePromptRun(run, strings) {
+    return deepFreeze(internStrings(run, strings));
+}
+/** A pool seeded with an already shared run's strings. */
+export function promptRunStrings(run) {
+    const strings = new Map();
+    if (run !== undefined)
+        collectStrings(run, strings);
+    return strings;
+}
+/**
+ * Deep-copy a context or session while sharing its frozen prompt runs, the
+ * only part of it that is large.
+ */
+export function cloneSharingPromptRuns(value) {
+    const { promptRuns, ...rest } = value;
+    const copy = structuredClone(rest);
+    if (promptRuns !== undefined)
+        copy.promptRuns = [...promptRuns];
+    return copy;
+}
+function internStrings(value, strings) {
+    if (typeof value === "string")
+        return intern(value, strings);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const record = value;
+    for (const key of Object.keys(record))
+        record[key] = internStrings(record[key], strings);
+    return value;
+}
+function intern(value, strings) {
+    if (value.length < sharedStringLength)
+        return value;
+    const shared = strings.get(value);
+    if (shared !== undefined)
+        return shared;
+    strings.set(value, value);
+    return value;
+}
+function collectStrings(value, strings) {
+    if (typeof value === "string") {
+        intern(value, strings);
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    for (const item of Object.values(value))
+        collectStrings(item, strings);
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const item of Object.values(value))
+        deepFreeze(item);
+    return Object.freeze(value);
 }
 export function assertPlayPromptRun(value) {
     if (typeof value !== "object" || value === null)
@@ -58,6 +120,98 @@ export function encodePlayPromptRun(run) {
         digest: createHash("sha256").update(JSON.stringify(run)).digest("hex"),
     };
 }
+export function promptRunCompiled(source) {
+    return {
+        playPreset: source.playPreset,
+        bootstrap: source.bootstrap,
+        tools: source.tools,
+        followups: source.followups,
+        playPresetScriptsEnabled: source.playPresetScriptsEnabled,
+        presetFiles: source.presetFiles,
+    };
+}
+/**
+ * The compiled prompt a context base holds. A base written without its follow-up,
+ * script or file fields cannot be a basis, so runs are then stored in full.
+ */
+export function contextPromptBasis(source) {
+    if (source.followups === undefined ||
+        source.playPresetScriptsEnabled === undefined ||
+        source.presetFiles === undefined)
+        return null;
+    return promptRunCompiled(source);
+}
+/** Sorted-key JSON, so equal prompts digest equally whatever their key order. */
+export function compiledPromptDigest(compiled) {
+    return createHash("sha256")
+        .update(JSON.stringify(promptRunCompiled(compiled), (_key, value) => typeof value === "object" && value !== null && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0))
+        : value))
+        .digest("hex");
+}
+/** A compiled prompt shared into a pool and frozen, as the runs built on it are. */
+export function sharePromptCompiled(compiled, strings) {
+    return deepFreeze(internStrings(structuredClone(promptRunCompiled(compiled)), strings));
+}
+/** Full record, unless the compiled prompt repeats the basis. */
+export function encodePlayPromptRunRecord(run, basis) {
+    if (basis !== null &&
+        compiledPromptDigest(run) === compiledPromptDigest(basis.compiled))
+        return {
+            kind: "play_prompt_run_reference",
+            schemaVersion: 1,
+            firstEventId: run.firstEventId,
+            head: run.head,
+            exchange: run.exchange,
+            basisRun: basis.index,
+            digest: compiledPromptDigest(basis.compiled),
+        };
+    return encodePlayPromptRun(run);
+}
+export function isPlayPromptRunReference(value) {
+    return isRecordValue(value) && value.kind === "play_prompt_run_reference";
+}
+/**
+ * Rebuild a referenced run from the basis it names. The caller resolves the
+ * basis number from runs it has already read; the run shares its frozen parts.
+ */
+export function promptRunFromReference(record, basisOf) {
+    if (!isRecordValue(record) ||
+        !exactKeys(record, [
+            "kind",
+            "schemaVersion",
+            "firstEventId",
+            "head",
+            "exchange",
+            "basisRun",
+            "digest",
+        ]) ||
+        record.schemaVersion !== 1 ||
+        !Number.isSafeInteger(record.firstEventId) ||
+        Number(record.firstEventId) < 1 ||
+        !Number.isSafeInteger(record.exchange) ||
+        Number(record.exchange) < 1 ||
+        typeof record.head !== "string" ||
+        !Number.isSafeInteger(record.basisRun) ||
+        Number(record.basisRun) < 0 ||
+        typeof record.digest !== "string")
+        throw new Error("Invalid play prompt run reference");
+    const basis = basisOf(Number(record.basisRun));
+    if (basis === null)
+        throw new Error("Play prompt run reference has no earlier basis");
+    if (compiledPromptDigest(basis) !== record.digest)
+        throw new Error("Play prompt run reference does not match its basis");
+    return Object.freeze({
+        schemaVersion: 1,
+        firstEventId: Number(record.firstEventId),
+        head: record.head,
+        exchange: Number(record.exchange),
+        ...promptRunCompiled(basis),
+    });
+}
+function isRecordValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export function decodePlayPromptRun(value) {
     if (typeof value !== "object" || value === null)
         throw new Error("Invalid play prompt run record");

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

@@ -1,6 +1,6 @@
 import { captureNarrativeOrigin } from "../history/HistoryBackground.js";
 import { FileNativePlayDocuments } from "./PlayDocumentTools.js";
-import { currentPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
+import { cloneSharingPromptRuns, currentPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
 import { isPlayerRoundMarker, playerInputAppend } from "./PlayContinuity.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 /**
@@ -190,7 +190,7 @@ function isReplayableReadAuthorization(value) {
         markdown.every((segment) => typeof segment === "string"));
 }
 export function independentContextCopy(source) {
-    const context = structuredClone(source);
+    const context = cloneSharingPromptRuns(source);
     context.continuityContextId ??= source.chainId;
     delete context.derivedFrom;
     delete context.branchedBeforePlayer;

package/dist/node/runtime/world/FileNativeWorldStorageMigrator.js

@@ -1,3 +1,4 @@
+import { FileNativePlayTimelineStore } from "../play/FileNativePlayTimelineStore.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -19,8 +20,10 @@ export class UnsupportedLegacyStorageError extends Error {
  */
 export class FileNativeWorldStorageMigrator {
     #worldsRoot;
+    #playTimeline;
     constructor(dataRoot) {
         this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
+        this.#playTimeline = new FileNativePlayTimelineStore(dataRoot);
     }
     async migrate(worldId) {
         assertIdentity(worldId, "World ID");
@@ -35,12 +38,14 @@ export class FileNativeWorldStorageMigrator {
                 join(runtimeRoot, ".authority-v3-migration"),
             ])
                 await rm(residue, { recursive: true, force: true });
+            await this.#playTimeline.migrateLayout(worldId);
             const head = await ledger.readHead();
             return { outcome: "already_current", authorityCommits: head.sequence };
         }
         const authority = new LegacyAuthorityV3Reader(worldRoot);
         if (await authority.exists()) {
             const { commits } = await convertAuthorityV3ToLedger(worldRoot);
+            await this.#playTimeline.migrateLayout(worldId);
             return { outcome: "migrated", authorityCommits: commits };
         }
         throw new UnsupportedLegacyStorageError(worldId);