narraeon 0.7.10 → 0.8.0

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

@@ -1,15 +1,17 @@
+import { applicationPresetFilesForLocale } from "../../shared/application-preset-files.js";
 import { parseDisplayRegex, DisplayRegexError, } from "../../shared/display-regex.js";
 export { validatePlayPresetArtifactPayload } from "../../shared/artifact-payload-contract.js";
 import { defaultFollowupItems, } from "../../shared/ordered-followups.js";
 import { parseFollowupItems } from "./OrderedFollowups.js";
 import { builtinAuthorPrompts, defaultOrderedAuthorPrompts, } from "../../shared/ordered-author-prompts.js";
-import { parseOrderedPlayPrompts, migrateLegacyPlayPrompts, withCurrentPromptBuiltins, } from "./OrderedPlayPrompts.js";
-import { defaultOrderedPlayPrompts, } from "../../shared/ordered-play-prompts.js";
+import { parseOrderedPlayPrompts, parseReleasedOrderedPrompts, releasedPromptRequiredIdentities, parsePromptArrangement, migrateLegacyPlayPrompts, upgradeOrderedPromptFormat, } from "./OrderedPlayPrompts.js";
+import { builtinPlayPrompts, } from "../../shared/ordered-play-prompts.js";
+import { customizePromptArrangement, retiredBuiltinReplacements, } from "../../shared/prompt-arrangement.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { parseDocument, stringify, visit, isAlias } from "yaml";
+import { parseDocument, visit, isAlias } from "yaml";
 import { defaultPortableContentTreeLimits, portableContentTreePathKey, } from "../../protocol/contentTree.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { defaultNarrationPromptForLocale } from "../../shared/default-play-prompts.js";
@@ -95,27 +97,78 @@ export function isPlayPresetBinding(value) {
     const builtInDefault = value.id === "builtin-default" &&
         value.name === "default" &&
         value.revision === "builtin-default-v1" &&
-        value.scriptsEnabled === true &&
-        (isDeepStrictEqual(files, defaultPlayPresetFilesForLocale("en")) ||
-            isDeepStrictEqual(files, defaultPlayPresetFilesForLocale("zh-CN")) ||
-            isDeepStrictEqual(files, legacyDefaultPlayPresetFilesForLocale("en")) ||
-            isDeepStrictEqual(files, legacyDefaultPlayPresetFilesForLocale("zh-CN")));
+        value.scriptsEnabled === true;
+    // This internal sentinel predates content-hash revisions. Its original
+    // snapshot must validate on its own, never against today's seed template.
     return (parsed.kind === "valid" &&
-        isDeepStrictEqual(normalizedFrozenDefinition(value.definition), parsed.definition) &&
+        frozenDefinitionMatches(value.definition, parsed.definition, files) &&
         (builtInDefault || value.revision === revisionForPlayPresetFiles(files)));
 }
+/** A frozen v3 binding validates against the catalog identities it captured.
+ * Newly shipped defaults belong to new sends, never to a saved request. */
+function frozenDefinitionMatches(snapshot, current, files) {
+    if (current.format !== "narraeon.play-preset/v3")
+        return isDeepStrictEqual(normalizedFrozenDefinition(snapshot), current);
+    try {
+        const source = readYaml(files, "preset.yaml", "preset.yaml");
+        const expected = { ...current };
+        const normalizedSnapshot = { ...snapshot };
+        for (const key of ["playPrompts", "authorPrompts"]) {
+            if (source[key] === undefined && snapshot[key] === undefined)
+                continue;
+            const author = key === "authorPrompts";
+            const catalog = author
+                ? builtinAuthorPrompts("en")
+                : builtinPlayPrompts("en");
+            const raw = snapshot[key];
+            if (!Array.isArray(raw))
+                return false;
+            const identities = new Set(raw.flatMap((e) => isRecord(e) && e.kind === "builtin" && typeof e.builtin === "string"
+                ? (retiredBuiltinReplacements[e.builtin]?.map((r) => r.builtin) ?? [
+                    e.builtin,
+                ])
+                : []));
+            // v3's original mandatory identities are part of its validation contract.
+            // Later required additions are mandatory only for newly compiled requests.
+            const requiredAtRelease = releasedPromptRequiredIdentities(!author);
+            const capturedCatalog = catalog.filter((c) => identities.has(c.id) || requiredAtRelease.includes(c.id));
+            const captured = parseOrderedPlayPrompts(raw, capturedCatalog, !author);
+            const frozenCatalog = captured.flatMap((entry) => {
+                if (entry.kind !== "builtin")
+                    return [];
+                const item = capturedCatalog.find((item) => item.id === entry.builtin);
+                return item === undefined
+                    ? []
+                    : [{ ...item, defaultEnabled: entry.enabled }];
+            });
+            if (!isDeepStrictEqual(captured, parsePromptArrangement(source[key], frozenCatalog, !author)))
+                return false;
+            expected[key] = captured;
+            normalizedSnapshot[key] = captured;
+        }
+        return isDeepStrictEqual(normalizedSnapshot, expected);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * A frozen definition captured before a builtin was retired still lists the
- * old entry; reading its ordered list through the parser yields the same
- * successors the files now parse to, so the binding stays consistent.
+ * old entry; reading both ordered lists through their respective parsers yields
+ * the same successors as the files, so the binding stays consistent.
  */
 function normalizedFrozenDefinition(definition) {
-    if (!Array.isArray(definition.playPrompts))
-        return definition;
     try {
         return {
             ...definition,
-            playPrompts: parseOrderedPlayPrompts(definition.playPrompts),
+            ...(Array.isArray(definition.playPrompts)
+                ? { playPrompts: parseReleasedOrderedPrompts(definition.playPrompts) }
+                : {}),
+            ...(Array.isArray(definition.authorPrompts)
+                ? {
+                    authorPrompts: parseReleasedOrderedPrompts(definition.authorPrompts, builtinAuthorPrompts("en"), false),
+                }
+                : {}),
         };
     }
     catch {
@@ -151,14 +204,7 @@ followups: []
     };
 }
 export function defaultPlayPresetFilesForLocale(locale) {
-    const files = legacyDefaultPlayPresetFilesForLocale(locale);
-    const preset = parseDocument(files["preset.yaml"]);
-    preset.set("format", "narraeon.play-preset/v2");
-    preset.set("playPrompts", defaultOrderedPlayPrompts());
-    preset.set("authorPrompts", defaultOrderedAuthorPrompts());
-    preset.set("mergeConsecutiveMessages", false);
-    files["preset.yaml"] = stringify(preset.toJS());
-    return files;
+    return applicationPresetFilesForLocale(locale);
 }
 export const defaultPlayPresetFiles = defaultPlayPresetFilesForLocale(defaultAppLocale);
 /**
@@ -230,8 +276,8 @@ export class FileNativePlayPresetStore {
             const document = await this.#read();
             const migrated = this.#markLegacyBuiltinDefault(document);
             const synchronized = this.#synchronizeBuiltinDefault(document);
-            const tabletop = this.#migrateTabletopPromptBuiltins(document);
-            if (migrated || synchronized || tabletop)
+            const customizations = this.#migratePromptCustomizations(document);
+            if (migrated || synchronized || customizations)
                 await this.#write(document);
         });
     }
@@ -291,10 +337,18 @@ export class FileNativePlayPresetStore {
             const stored = findStored(document, input.presetId);
             delete stored.builtinDefault;
             let files = cloneFiles(input.files);
+            const previous = parsePlayPresetFiles(stored.revisions[stored.currentRevision]);
             if (input.structure !== undefined) {
-                files = applyPlayPresetStructuredEditor(input.files, parsePlayPresetStructuredEditor(input.structure));
+                const structure = parsePlayPresetStructuredEditor(input.structure);
+                if (previous.kind === "valid") {
+                    for (const key of ["playPrompts", "authorPrompts"]) {
+                        if (structure[key] === undefined)
+                            continue;
+                        assertReadonlyPromptsRetained(previous.definition[key] ?? [], structure[key]);
+                    }
+                }
+                files = applyPlayPresetStructuredEditor(input.files, structure);
             }
-            const previous = parsePlayPresetFiles(stored.revisions[stored.currentRevision]);
             if (previous.kind === "valid" &&
                 previous.definition.followupItems !== undefined) {
                 const candidate = readYaml(files, "call-chain.yaml", "call-chain.yaml");
@@ -305,31 +359,23 @@ export class FileNativePlayPresetStore {
             if (previous.kind === "valid" &&
                 previous.definition.playPrompts !== undefined) {
                 const candidate = readYaml(files, "preset.yaml", "preset.yaml");
-                if (candidate.format !== "narraeon.play-preset/v2")
+                if (candidate.format !== "narraeon.play-preset/v2" &&
+                    candidate.format !== "narraeon.play-preset/v3")
                     throw new FileNativePlayPresetError("readonly_prompt_removed", "Ordered presets cannot downgrade to v1");
-                const candidates = parseOrderedPlayPrompts(candidate.playPrompts);
-                for (const entry of previous.definition.playPrompts.filter((entry) => entry.kind === "builtin" || entry.kind === "world")) {
-                    const retained = candidates.find((item) => item.id === entry.id);
-                    if (retained?.kind !== entry.kind ||
-                        (entry.kind === "builtin" &&
-                            retained.kind === "builtin" &&
-                            retained.builtin !== entry.builtin))
-                        throw new FileNativePlayPresetError("readonly_prompt_removed", "System prompts and the world placeholder cannot be deleted or replaced; disable optional prompts or clone them instead");
-                }
+                const candidates = candidate.format === "narraeon.play-preset/v3"
+                    ? parsePromptArrangement(candidate.playPrompts)
+                    : parseOrderedPlayPrompts(candidate.playPrompts);
+                assertReadonlyPromptsRetained(previous.definition.playPrompts, candidates);
             }
             if (previous.kind === "valid" &&
                 previous.definition.authorPrompts !== undefined) {
                 const candidate = readYaml(files, "preset.yaml", "preset.yaml");
-                const entries = parseOrderedAuthorPrompts(candidate.authorPrompts);
-                for (const entry of previous.definition.authorPrompts) {
-                    if (entry.kind !== "builtin")
-                        continue;
-                    const retained = entries.find((item) => item.id === entry.id);
-                    if (retained?.kind !== "builtin" ||
-                        retained.builtin !== entry.builtin)
-                        throw new FileNativePlayPresetError("readonly_prompt_removed", "Authoring system prompts cannot be deleted or replaced; disable or clone optional prompts");
-                }
+                const entries = candidate.format === "narraeon.play-preset/v3"
+                    ? parsePromptArrangement(candidate.authorPrompts, builtinAuthorPrompts("en"), false)
+                    : parseOrderedAuthorPrompts(candidate.authorPrompts);
+                assertReadonlyPromptsRetained(previous.definition.authorPrompts, entries);
             }
+            files = upgradeValidOrderedPromptFormat(files, this.#limits);
             const revision = revisionForFiles(files, this.#limits);
             stored.name = normalizeName(input.name);
             stored.revisions[revision] = cloneFiles(files);
@@ -472,14 +518,16 @@ export class FileNativePlayPresetStore {
     }
     /** Portable export deliberately contains no id, revision, world, operation or provider state. */
     async exportPortable(id) {
-        const binding = await this.bindRevision(id);
-        return Object.keys(binding.files)
+        await this.#tail;
+        const stored = findStored(await this.#read(), id);
+        const files = stored.revisions[stored.currentRevision];
+        return Object.keys(files)
             .sort()
-            .map((path) => ({ path, contents: binding.files[path] }));
+            .map((path) => ({ path, contents: files[path] }));
     }
     async importPortable(input) {
         // A released preset gains the current builtins at import, as at upgrade.
-        const files = withCurrentPromptBuiltins(toFileMap(input.files, this.#limits));
+        const files = upgradeOrderedPromptFormat(toFileMap(input.files, this.#limits));
         const parsed = parsePlayPresetFiles(files, this.#limits);
         if (parsed.kind === "invalid")
             throw parsed.error;
@@ -537,7 +585,7 @@ export class FileNativePlayPresetStore {
             return document;
         }
         try {
-            // Validation hashes and parses every stored revision, so a library
+            // Validation checks the structure and hash of every stored revision, so a library
             // whose bytes were already validated is served from that result. Each
             // caller gets its own copy because callers edit what they read.
             if (this.#validated !== undefined && raw === this.#validated.raw)
@@ -597,19 +645,17 @@ export class FileNativePlayPresetStore {
         return true;
     }
     /**
-     * One-time upgrade for ordered presets saved before the tabletop or
-     * continuation builtins existed. An affected revision is replaced by a new revision that inserts
-     * them; the old revision stays for frozen requests. A pending draft gets the
-     * same insertion, because a draft that kept the old list would fail the
-     * builtin-retention rule on save. The library is one atomically written file,
-     * so an interrupted upgrade leaves the released bytes and reruns cleanly.
+     * Convert released ordered lists to sparse customizations exactly once.
+     * Original revisions remain immutable. Current and valid draft endpoints
+     * advance together in one atomic library replacement; invalid drafts retain
+     * their original bytes for repair. Catalog evolution never changes v3 files.
      */
-    #migrateTabletopPromptBuiltins(document) {
+    #migratePromptCustomizations(document) {
         let changed = false;
         for (const stored of document.presets) {
             const current = stored.revisions[stored.currentRevision];
             if (current !== undefined) {
-                const migrated = withCurrentPromptBuiltins(current);
+                const migrated = upgradeValidOrderedPromptFormat(current, this.#limits);
                 if (migrated !== current) {
                     const revision = revisionForFiles(migrated, this.#limits);
                     stored.revisions[revision] = cloneFiles(migrated);
@@ -621,7 +667,7 @@ export class FileNativePlayPresetStore {
                 ? undefined
                 : stored.revisions[stored.draftRevision];
             if (draft !== undefined) {
-                const migrated = withCurrentPromptBuiltins(draft);
+                const migrated = upgradeValidOrderedPromptFormat(draft, this.#limits);
                 if (migrated !== draft) {
                     const revision = revisionForFiles(migrated, this.#limits);
                     stored.revisions[revision] = cloneFiles(migrated);
@@ -653,7 +699,7 @@ export class FileNativePlayPresetStore {
     }
     #stored(id, rawName, rawFiles) {
         const name = normalizeName(rawName);
-        const files = cloneFiles(rawFiles);
+        const files = cloneFiles(upgradeValidOrderedPromptFormat(rawFiles, this.#limits));
         const revision = revisionForFiles(files, this.#limits);
         return {
             id,
@@ -784,7 +830,7 @@ export function toPlayPresetStructuredEditor(definition) {
  * public structure and never bypasses the normal codec.
  */
 export function applyPlayPresetStructuredEditor(files, input) {
-    const next = cloneFiles(files);
+    const next = cloneFiles(upgradeOrderedPromptFormat(files));
     const presetSource = next["preset.yaml"];
     const callChainSource = next[input.callChainPath];
     if (presetSource === undefined || callChainSource === undefined)
@@ -805,10 +851,10 @@ export function applyPlayPresetStructuredEditor(files, input) {
     if (input.mergeConsecutiveMessages !== undefined)
         preset.set("mergeConsecutiveMessages", parseMessageMerging(input.mergeConsecutiveMessages));
     if (input.authorPrompts !== undefined)
-        preset.set("authorPrompts", parseOrderedAuthorPrompts(input.authorPrompts));
+        preset.set("authorPrompts", customizePromptArrangement(parseOrderedAuthorPrompts(input.authorPrompts), builtinAuthorPrompts("en"), false));
     if (input.playPrompts !== undefined) {
-        preset.set("format", "narraeon.play-preset/v2");
-        preset.set("playPrompts", parseOrderedPlayPrompts(input.playPrompts));
+        preset.set("format", "narraeon.play-preset/v3");
+        preset.set("playPrompts", customizePromptArrangement(parseOrderedPlayPrompts(input.playPrompts), builtinPlayPrompts("en")));
     }
     preset.set("callChain", input.callChainPath);
     if (input.settingImprovementPrompt === undefined)
@@ -965,7 +1011,8 @@ export function parsePlayPresetFiles(files, limits = {}) {
         if (callChainPath !== "call-chain.yaml")
             invalid("call_chain_path_invalid", "Entry callChain must be call-chain.yaml", "preset.yaml");
         if (preset.format !== "narraeon.play-preset/v1" &&
-            preset.format !== "narraeon.play-preset/v2")
+            preset.format !== "narraeon.play-preset/v2" &&
+            preset.format !== "narraeon.play-preset/v3")
             invalid("preset_format_invalid", "preset.yaml format must be narraeon.play-preset/v1", "preset.yaml");
         if (preset.format === "narraeon.play-preset/v1" &&
             (preset.playPrompts !== undefined ||
@@ -1009,12 +1056,21 @@ export function parsePlayPresetFiles(files, limits = {}) {
                     : {
                         mergeConsecutiveMessages: parseMessageMerging(preset.mergeConsecutiveMessages),
                     }),
-                ...(preset.format === "narraeon.play-preset/v2"
-                    ? { playPrompts: parseOrderedPlayPrompts(preset.playPrompts) }
+                ...(preset.format === "narraeon.play-preset/v2" ||
+                    preset.format === "narraeon.play-preset/v3"
+                    ? {
+                        playPrompts: preset.format === "narraeon.play-preset/v3"
+                            ? parsePromptArrangement(preset.playPrompts)
+                            : parseReleasedOrderedPrompts(preset.playPrompts),
+                    }
                     : {}),
                 ...(preset.authorPrompts === undefined
                     ? {}
-                    : { authorPrompts: parseOrderedAuthorPrompts(preset.authorPrompts) }),
+                    : {
+                        authorPrompts: preset.format === "narraeon.play-preset/v3"
+                            ? parsePromptArrangement(preset.authorPrompts, builtinAuthorPrompts("en"), false)
+                            : parseReleasedOrderedPrompts(preset.authorPrompts, builtinAuthorPrompts("en"), false),
+                    }),
                 name: name.trim(),
                 callChainPath,
                 ...(settingImprovementPrompt === undefined
@@ -1819,6 +1875,13 @@ function toFileMap(input, limits) {
     validateFileTree(files, limits);
     return files;
 }
+function upgradeValidOrderedPromptFormat(files, limits) {
+    const upgraded = upgradeOrderedPromptFormat(files);
+    return upgraded !== files &&
+        validatePlayPresetFiles(upgraded, limits).status === "valid"
+        ? upgraded
+        : files;
+}
 function parseStoredDocument(value, limits = defaultLimits) {
     if (!isRecord(value) ||
         !hasExactKeys(value, ["schemaVersion", "currentPresetId", "presets"]) ||
@@ -1875,14 +1938,6 @@ function parseStoredDocument(value, limits = defaultLimits) {
             }
             if (expectedRevision !== revision)
                 throw new FileNativePlayPresetError("store_invalid", "Play-preset revision content hash does not match");
-            // A revision saved by an earlier release may still name builtins that
-            // the catalog has since replaced; it counts as current-format when the
-            // load-time migration makes it so, and its bytes stay as written.
-            if (revision !== raw.draftRevision &&
-                validatePlayPresetFiles(clone, limits).status !== "valid" &&
-                validatePlayPresetFiles(withCurrentPromptBuiltins(clone), limits)
-                    .status !== "valid")
-                throw new FileNativePlayPresetError("store_invalid", "Play-preset revision does not match the current format");
             revisions[revision] = clone;
         }
         if (revisions[raw.currentRevision] === undefined)
@@ -1919,6 +1974,18 @@ function findStored(document, id) {
         throw new FileNativePlayPresetError("not_found", "Requested play preset was not found");
     return preset;
 }
+function assertReadonlyPromptsRetained(previous, candidate) {
+    for (const entry of previous) {
+        if (entry.kind !== "builtin" && entry.kind !== "world")
+            continue;
+        const retained = candidate.find((item) => item.id === entry.id);
+        if (retained?.kind !== entry.kind ||
+            (entry.kind === "builtin" &&
+                retained.kind === "builtin" &&
+                retained.builtin !== entry.builtin))
+            throw new FileNativePlayPresetError("readonly_prompt_removed", "System prompts and the world placeholder cannot be deleted or replaced; disable optional prompts or clone them instead");
+    }
+}
 function normalizeName(raw) {
     const name = raw.trim();
     if (!namePattern.test(name) || name.includes(String.fromCharCode(0)))
@@ -1959,13 +2026,18 @@ export function legacyAuthorPrompts(definition) {
     const entries = defaultOrderedAuthorPrompts();
     const path = definition.settingImprovementPrompt?.path;
     if (path !== undefined)
-        entries[1] = {
+        entries.splice(1, 1, {
+            id: "author.guidance",
+            kind: "builtin",
+            builtin: "author.guidance",
+            enabled: false,
+        }, {
             id: "legacy-author",
             kind: "user",
             name: "Authoring",
             body: definition.files[path],
             enabled: true,
-        };
+        });
     return entries;
 }
 function parseMessageMerging(value) {

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

@@ -1,4 +1,6 @@
 import { isResolutionReceipt } from "../../protocol/resolution.js";
+import { isSafeGoogleWireRequest } from "../model/GoogleRequestPreview.js";
+import { readGoogleHops, writeGoogleHop } from "../model/GoogleHopJournal.js";
 import { legacyModelBindingFailure, projectLegacyModelBindingFailure, } from "./LegacyModelBindingFailure.js";
 import { isPlayFailureKind, } from "../../protocol/playFailure.js";
 import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
@@ -43,11 +45,7 @@ export class FileNativePlayTimelineStore {
         const transcriptCount = prefixLength(input.source.transcript, input.target.transcript);
         const eventCount = prefixLength(input.source.events, input.target.events);
         const completedToolCount = prefixLength(input.source.completedTools, input.target.completedTools);
-        for (const exchange of (await recordedEncodingExchanges(sourceRoot)).slice(0, 2)) {
-            const encoding = await this.readInitialEncoding(input.sourceWorldId, input.source.chainId, exchange).catch(() => null);
-            if (encoding !== null)
-                await publishImmutableJson(join(targetRoot, encodingFileName(exchange)), encoding);
-        }
+        await this.#copyRetainedEncodings(input.sourceWorldId, input.source.chainId, targetRoot, input.target);
         await Promise.all([
             cloneNumberedPrefix({
                 sourceRoot,
@@ -346,18 +344,96 @@ export class FileNativePlayTimelineStore {
         await pruneEncodings(root);
     }
     async readInitialEncoding(worldId, chainId, exchange = 1) {
-        const value = await readOptionalJson(join(this.#contextRoot(worldId, chainId), encodingFileName(exchange)));
+        const root = this.#contextRoot(worldId, chainId);
+        if (!(await retainedEncodingExchanges(root)).includes(exchange))
+            return null;
+        const value = await readOptionalJson(join(root, encodingFileName(exchange)));
         if (value === null)
             return null;
+        if (isRecord(value) &&
+            value.provider === "google_interactions" &&
+            !isSafeGoogleWireRequest(value))
+            return null;
         if (!isRecord(value) ||
             value.method !== "POST" ||
-            !["chat_completions", "openai_responses", "anthropic_messages"].includes(String(value.provider)) ||
+            ![
+                "chat_completions",
+                "openai_responses",
+                "anthropic_messages",
+                "google_interactions",
+            ].includes(String(value.provider)) ||
             !isRecord(value.body) ||
             typeof value.endpointPath !== "string" ||
             !Array.isArray(value.headerNames) ||
             !value.headerNames.every((name) => typeof name === "string"))
             throw new Error("Initial request encoding has an invalid shape");
-        return value;
+        const wire = value;
+        return wire.provider === "google_interactions"
+            ? readGoogleHops(join(root, "google-hops", String(exchange)), "main", wire)
+            : wire;
+    }
+    async recordGoogleHop(worldId, chainId, runExchange, hop, followupId) {
+        const root = this.#contextRoot(worldId, chainId);
+        await writeGoogleHop(join(root, "google-hops", String(runExchange)), followupId === undefined ? "main" : `followup:${followupId}`, hop, async () => (await retainedEncodingExchanges(root)).includes(runExchange));
+    }
+    async copyRetainedEncodings(worldId, sourceChainId, target) {
+        await this.#copyRetainedEncodings(worldId, sourceChainId, this.#contextRoot(worldId, target.chainId), target);
+    }
+    async #copyRetainedEncodings(worldId, sourceChainId, targetRoot, target) {
+        const sourceRoot = this.#contextRoot(worldId, sourceChainId);
+        const retainedResponses = new Set(target.events.flatMap((event) => event.kind === "assistant"
+            ? [`${event.exchange}:${event.attempt}`]
+            : []));
+        const targetFollowups = new Map(target.events.flatMap((event) => event.kind === "followup" && event.requestPreviewExchange !== undefined
+            ? [
+                [
+                    followupEncodingFileName(event.requestPreviewExchange, event.followupId),
+                    event.followupId,
+                ],
+            ]
+            : []));
+        for (const exchange of (await retainedEncodingExchanges(sourceRoot)).filter((value) => value <= target.exchange)) {
+            const encoding = await this.readInitialEncoding(worldId, sourceChainId, exchange).catch(() => null);
+            if (encoding === null)
+                continue;
+            if (encoding.googleHops !== undefined)
+                encoding.googleHops = encoding.googleHops.filter((hop) => retainedResponses.has(`${hop.exchange}:${hop.attempt}`));
+            await publishImmutableJson(join(targetRoot, encodingFileName(exchange)), encoding);
+            for (const name of await followupEncodingNames(sourceRoot, exchange)) {
+                const followupId = targetFollowups.get(name);
+                if (followupId === undefined)
+                    continue;
+                try {
+                    const value = await this.readFollowupEncoding(worldId, sourceChainId, exchange, followupId);
+                    if (safeFollowupEncoding(value))
+                        await publishImmutableJson(join(targetRoot, name), value);
+                }
+                catch {
+                    // A single optional diagnostic must not prevent other evidence or a fork.
+                }
+            }
+        }
+    }
+    async recordFollowupEncoding(worldId, chainId, exchange, requestId, encoding) {
+        const root = this.#contextRoot(worldId, chainId);
+        // The main encoding owns the bounded run slot; never create an orphan slot.
+        if (!(await retainedEncodingExchanges(root)).includes(exchange) ||
+            !safeFollowupEncoding(encoding))
+            return false;
+        await publishImmutableJson(join(root, followupEncodingFileName(exchange, requestId)), encoding);
+        await pruneEncodings(root);
+        return true;
+    }
+    async readFollowupEncoding(worldId, chainId, exchange, requestId) {
+        const root = this.#contextRoot(worldId, chainId);
+        if (!(await retainedEncodingExchanges(root)).includes(exchange))
+            return null;
+        const value = await readOptionalJson(join(root, followupEncodingFileName(exchange, requestId)));
+        if (value === null)
+            return null;
+        if (!safeFollowupEncoding(value))
+            throw new Error("Follow-up request encoding has an invalid shape");
+        return readGoogleHops(join(root, "google-hops", String(exchange)), `followup:${requestId}`, value);
     }
     async readAllContexts(worldId) {
         const current = await this.readCurrent(worldId);
@@ -538,6 +614,18 @@ export class FileNativePlayTimelineStore {
         assertPlayEvent(event);
         if (event.id !== eventId)
             throw new Error("Play timeline event identity is inconsistent");
+        if (event.kind === "followup") {
+            const wireRequest = event.requestPreviewExchange === undefined ||
+                event.requestPreviewStatus === undefined
+                ? null
+                : await this.readFollowupEncoding(worldId, chainId, event.requestPreviewExchange, event.followupId).catch(() => null);
+            return {
+                ...event,
+                requestPreview: wireRequest === null || event.requestPreviewStatus === undefined
+                    ? { status: "unavailable" }
+                    : { status: event.requestPreviewStatus, wireRequest },
+            };
+        }
         return projectLegacyModelBindingFailure(event);
     }
     newGeneration() {
@@ -900,7 +988,8 @@ function validModelHostBinding(value) {
     return (isRecord(value) &&
         (value.provider === "chat_completions" ||
             value.provider === "openai_responses" ||
-            value.provider === "anthropic_messages") &&
+            value.provider === "anthropic_messages" ||
+            value.provider === "google_interactions") &&
         typeof value.endpointFingerprint === "string" &&
         value.endpointFingerprint.length > 0 &&
         typeof value.modelId === "string" &&
@@ -972,6 +1061,13 @@ function assertPlayEvent(value) {
             typeof value.text !== "string" ||
             !validOptionalString(value.reasoning) ||
             !validOptionalUsage(value.usage) ||
+            (value.requestPreviewExchange !== undefined &&
+                (!Number.isSafeInteger(value.requestPreviewExchange) ||
+                    Number(value.requestPreviewExchange) < 1)) ||
+            (value.requestPreviewStatus !== undefined &&
+                value.requestPreviewStatus !== "attempted" &&
+                value.requestPreviewStatus !== "completed" &&
+                value.requestPreviewStatus !== "cancelled") ||
             !Array.isArray(value.toolCalls) ||
             !value.toolCalls.every(validFollowupToolCall) ||
             !validOptionalString(value.failure))
@@ -1073,6 +1169,11 @@ function validOptionalUsage(value) {
 function validFullUsage(value) {
     if (!isRecord(value) || !isRecord(value.provenance))
         return false;
+    if (value.providerRaw !== undefined && !isRecord(value.providerRaw))
+        return false;
+    if (value.accounting !== undefined &&
+        value.accounting !== "google_interactions")
+        return false;
     const provenance = value.provenance;
     const fields = [
         "inputTokens",
@@ -1192,6 +1293,31 @@ function encodingFileName(exchange) {
         ? "initial-request-encoding.json"
         : `request-encoding-${exchange}.json`;
 }
+function followupEncodingFileName(exchange, requestId) {
+    return `followup-encoding-${exchange}-${createHash("sha256").update(requestId).digest("hex")}.json`;
+}
+function safeFollowupEncoding(value) {
+    if (!isSafeGoogleWireRequest(value) ||
+        value.headerNames.length !== 3 ||
+        value.headerNames[0] !== "Accept" ||
+        value.headerNames[1] !== "x-goog-api-key" ||
+        value.headerNames[2] !== "Content-Type" ||
+        !isRecord(value.body) ||
+        !Array.isArray(value.body.input))
+        return false;
+    // Provider function calls must have been redacted; only the Runtime's
+    // explicitly marked bootstrap call can remain in the projected input.
+    return value.body.input.every((item) => !isRecord(item) ||
+        item.type !== "function_call" ||
+        (item.name === "runtime_load_context" &&
+            isRecord(item.arguments) &&
+            Object.keys(item.arguments).length === 0));
+}
+async function followupEncodingNames(root, exchange) {
+    const prefix = `followup-encoding-${exchange}-`;
+    return (await readDirectoryNames(root)).filter((name) => name.startsWith(prefix) &&
+        /^[a-f0-9]{64}\.json$/u.test(name.slice(prefix.length)));
+}
 /** The exchanges with a recorded encoding in a context, latest first. */
 async function recordedEncodingExchanges(contextRoot) {
     return (await readDirectoryNames(contextRoot))
@@ -1204,12 +1330,26 @@ async function recordedEncodingExchanges(contextRoot) {
         .filter((exchange) => exchange !== null)
         .sort((left, right) => right - left);
 }
+async function retainedEncodingExchanges(contextRoot) {
+    return (await recordedEncodingExchanges(contextRoot)).slice(0, 2);
+}
 /**
  * Keep the encodings of the two latest exchanges, the pair the AI-reading
  * diagnostics compare. A context without runs is read at exchange 1.
  */
 async function pruneEncodings(contextRoot) {
-    for (const exchange of (await recordedEncodingExchanges(contextRoot)).slice(2))
+    const exchanges = await recordedEncodingExchanges(contextRoot);
+    const retained = new Set(exchanges.slice(0, 2));
+    const hopRoot = join(contextRoot, "google-hops");
+    for (const name of await readDirectoryNames(hopRoot))
+        if (/^[1-9]\d*$/u.test(name) && !retained.has(Number(name)))
+            await rm(join(hopRoot, name), { recursive: true, force: true });
+    for (const name of await readDirectoryNames(contextRoot)) {
+        const match = /^followup-encoding-([1-9][0-9]*)-[a-f0-9]{64}\.json$/u.exec(name);
+        if (match !== null && !retained.has(Number(match[1])))
+            await rm(join(contextRoot, name), { force: true });
+    }
+    for (const exchange of exchanges.slice(2))
         await rm(join(contextRoot, encodingFileName(exchange)), { force: true });
 }
 /**