narraeon 0.7.10 → 0.8.1

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() {
@@ -661,6 +749,55 @@ export class FileNativePlayTimelineStore {
             indexValue.chainId !== chainId ||
             stateValue.chainId !== chainId)
             throw new Error("Play context durable identity is inconsistent");
+        // Older releases disallowed retry after a player cancellation. The tail
+        // cancellation and interrupted assistant prove this was a dispatch ending,
+        // not a settlement failure. Validate the frozen request before exposing it.
+        if (!indexValue.importedFromArchive &&
+            stateValue.status === "interrupted" &&
+            !stateValue.canRetry &&
+            stateValue.eventCount >= 2) {
+            try {
+                const [tail, previous] = await Promise.all([
+                    readJson(join(root, "events", numbered(stateValue.eventCount))),
+                    readJson(join(root, "events", numbered(stateValue.eventCount - 1))),
+                ]);
+                assertPlayEvent(tail);
+                assertPlayEvent(previous);
+                if (tail.kind === "cancellation" &&
+                    previous.kind === "assistant" &&
+                    previous.status === "interrupted") {
+                    const [base, continuation] = await Promise.all([
+                        readJson(join(root, "base.json")),
+                        readJson(join(root, "continuations", `${stateValue.continuationDigest}.json`)),
+                    ]);
+                    assertContextBase(base);
+                    assertContextContinuation(continuation);
+                    if (base.worldId === worldId &&
+                        base.chainId === chainId &&
+                        continuation.chainId === chainId &&
+                        continuation.lastRequestDigest !== null &&
+                        createHash("sha256")
+                            .update(JSON.stringify(continuation))
+                            .digest("hex") === stateValue.continuationDigest) {
+                        const request = await readJson(join(root, "requests", `${continuation.lastRequestDigest}.json`));
+                        const provider = request.modelConfig?.provider ?? base.modelBinding?.provider;
+                        if (provider !== undefined &&
+                            provider !== "google_interactions" &&
+                            Array.isArray(request.appended) &&
+                            // The legacy record carries no codec-validation receipt. Only
+                            // requests without native assistant fragments can be proven safe.
+                            request.appended.every((item) => item.kind !== "assistant") &&
+                            createHash("sha256")
+                                .update(JSON.stringify(request))
+                                .digest("hex") === continuation.lastRequestDigest)
+                            stateValue.canRetry = true;
+                    }
+                }
+            }
+            catch {
+                // Missing or damaged legacy evidence never grants retry or breaks metadata reads.
+            }
+        }
         // Old versions persisted a configuration preflight failure as a terminal
         // context failure. Recover only the disposition proven by its event prefix.
         // Archive contexts and genuine provider failures retain their restrictions.
@@ -900,7 +1037,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 +1110,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 +1218,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 +1342,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 +1379,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 });
 }
 /**

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

@@ -1,5 +1,7 @@
+import { builtinAuthorPrompts } from "../../shared/ordered-author-prompts.js";
+import { expandRetiredPrompts, customizePromptArrangement, resolvePromptArrangement, retiredBuiltinReplacements, } from "../../shared/prompt-arrangement.js";
 import { createHash } from "node:crypto";
-import { isMap, isSeq, parseDocument } from "yaml";
+import { isMap, parseDocument } from "yaml";
 import { builtinPlayPrompts, isPromptMessageRole, isTurnGuideLine, promptGroups, } from "../../shared/ordered-play-prompts.js";
 const promptName = /^[^\r\n\0]{1,160}$/u;
 /** The same strict permission gate is used by portable imports and structured saves. */
@@ -86,24 +88,22 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             ? retiredBuiltinReplacements[item.builtin]
             : undefined;
         if (retired !== undefined &&
-            exact(["id", "kind", "builtin", "enabled"]) &&
+            exact(["id", "kind", "builtin", "enabled"], ["turnGuide"]) &&
+            validTurnGuide &&
             typeof item.enabled === "boolean") {
-            const enabled = item.enabled;
-            return retired.flatMap(({ builtin, selected }) => {
-                if (builtins.has(builtin) || ids.has(builtin))
-                    return [];
-                builtins.add(builtin);
-                ids.add(builtin);
-                return [
-                    {
-                        id: builtin,
-                        kind: "builtin",
-                        builtin,
-                        enabled: selected === false ? false : enabled,
-                        ...messageRole,
-                    },
-                ];
-            });
+            if (builtins.has(item.builtin))
+                return fail();
+            builtins.add(item.builtin);
+            return [
+                {
+                    id: item.id,
+                    kind: "builtin",
+                    builtin: item.builtin,
+                    enabled: item.enabled,
+                    ...messageRole,
+                    ...turnGuide,
+                },
+            ];
         }
         const builtin = catalog.find((entry) => entry.id === item.builtin);
         if (item.kind !== "builtin" ||
@@ -128,10 +128,29 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             },
         ];
     });
+    const expanded = expandRetiredPrompts(entries);
     if (worlds !== (worldRequired ? 1 : 0) ||
-        catalog.some((item) => item.required && !builtins.has(item.id)))
+        catalog.some((item) => {
+            if (!item.required)
+                return false;
+            const entry = expanded.find((entry) => entry.kind === "builtin" && entry.builtin === item.id);
+            return (entry?.kind !== "builtin" ||
+                !entry.enabled ||
+                (entry.messageRole !== undefined && entry.messageRole !== "system"));
+        }))
         return fail();
-    return entries;
+    return expanded;
+}
+/** The required identities are part of each released list-format contract.
+ * New catalog requirements apply after conversion, never while validating old bytes. */
+export function releasedPromptRequiredIdentities(worldRequired) {
+    return worldRequired
+        ? ["play.mechanics"]
+        : ["author.mechanics", "author.target"];
+}
+export function parseReleasedOrderedPrompts(value, catalog = builtinPlayPrompts("en"), worldRequired = true) {
+    const required = releasedPromptRequiredIdentities(worldRequired);
+    return parseOrderedPlayPrompts(value, catalog.map((item) => ({ ...item, required: required.includes(item.id) })), worldRequired);
 }
 function orderedPresetDocument(files) {
     const source = files["preset.yaml"];
@@ -145,165 +164,104 @@ function orderedPresetDocument(files) {
         return undefined;
     return document;
 }
-/**
- * Insert the tabletop builtins that an ordered preset does not list yet.
- * play.tabletop goes just before the world placeholder and author.tabletop just
- * after author.guidance. Files that are not ordered v2 or do not parse come back
- * unchanged, and nothing else in them is rewritten. The same object is returned
- * when nothing needs inserting, so callers can detect a change by identity.
- */
-export function withTabletopPromptBuiltins(files) {
-    const document = orderedPresetDocument(files);
-    if (document === undefined)
-        return files;
-    let changed = false;
-    const playPrompts = document.get("playPrompts", true);
-    if (isSeq(playPrompts) && !hasEntry(playPrompts, "play.tabletop")) {
-        const world = playPrompts.items.findIndex((item) => entryField(item, "kind") === "world");
-        playPrompts.items.splice(world < 0 ? playPrompts.items.length : world, 0, document.createNode({
-            id: "play.tabletop",
-            kind: "builtin",
-            builtin: "play.tabletop",
-            enabled: true,
-        }));
-        changed = true;
-    }
-    const authorPrompts = document.get("authorPrompts", true);
-    if (isSeq(authorPrompts) && !hasEntry(authorPrompts, "author.tabletop")) {
-        const guidance = authorPrompts.items.findIndex((item) => entryField(item, "id") === "author.guidance");
-        authorPrompts.items.splice(guidance < 0 ? authorPrompts.items.length : guidance + 1, 0, document.createNode({
-            id: "author.tabletop",
-            kind: "builtin",
-            builtin: "author.tabletop",
-            enabled: true,
-        }));
-        changed = true;
-    }
-    return changed ? { ...files, "preset.yaml": document.toString() } : files;
-}
-/**
- * The retired composite builtins and the blocks that replaced each of them.
- * A stored entry for a retired builtin is replaced in place by its successors,
- * which inherit its enabled state and message role; the unselected members of
- * a choice group arrive disabled. User copies of the old text are not touched.
- */
-const retiredBuiltinReplacements = {
-    "play.style": [{ builtin: "play.prose" }, { builtin: "play.scene" }],
-    "play.adjudication": [
-        { builtin: "play.agency-default" },
-        { builtin: "play.agency-strict", selected: false },
-        { builtin: "play.agency-open", selected: false },
-        { builtin: "play.facts" },
-        { builtin: "play.npc" },
-    ],
-    "play.narrative": [
-        { builtin: "play.stop-beat" },
-        { builtin: "play.stop-scene", selected: false },
-        { builtin: "play.ending" },
-        { builtin: "play.output" },
-    ],
-    "play.state": [
-        { builtin: "play.save-timing" },
-        { builtin: "play.ownership" },
-        { builtin: "play.situation" },
-        { builtin: "play.checkpoint-policy" },
-    ],
-};
 export const retiredPlayBuiltins = Object.keys(retiredBuiltinReplacements);
-/**
- * Replace the retired composite builtins (style, adjudication, narrative and
- * state) with the single-rule blocks that succeeded them, each at the old
- * entry's position. Same identity contract as the other insertions.
- */
-export function withRestructuredPromptBuiltins(files) {
+/** One-time released v2 -> v3 encoding conversion, never a catalog migration. */
+export function upgradeOrderedPromptFormat(files) {
     const document = orderedPresetDocument(files);
-    if (document === undefined)
+    if (!document)
         return files;
-    const playPrompts = document.get("playPrompts", true);
-    if (!isSeq(playPrompts))
-        return files;
-    let changed = false;
-    for (const [retired, replacements] of Object.entries(retiredBuiltinReplacements)) {
-        const at = playPrompts.items.findIndex((item) => entryField(item, "kind") === "builtin" &&
-            entryField(item, "builtin") === retired);
-        if (at < 0)
-            continue;
-        const old = playPrompts.items[at];
-        const enabled = entryField(old, "enabled") === true;
-        const messageRole = entryField(old, "messageRole");
-        const successors = replacements
-            .filter(({ builtin }) => !hasEntry(playPrompts, builtin))
-            .map(({ builtin, selected }) => document.createNode({
-            id: builtin,
-            kind: "builtin",
-            builtin,
-            enabled: selected === false ? false : enabled,
-            ...(typeof messageRole === "string" ? { messageRole } : {}),
-        }));
-        playPrompts.items.splice(at, 1, ...successors);
-        changed = true;
+    try {
+        const source = document.toJS();
+        document.set("playPrompts", customizePromptArrangement(parseReleasedOrderedPrompts(source.playPrompts), builtinPlayPrompts("en")));
+        const author = document.get("authorPrompts");
+        if (author !== undefined)
+            document.set("authorPrompts", customizePromptArrangement(parseReleasedOrderedPrompts(source.authorPrompts, builtinAuthorPrompts("en"), false), builtinAuthorPrompts("en"), false));
+        document.set("format", "narraeon.play-preset/v3");
+        return { ...files, "preset.yaml": document.toString() };
     }
-    return changed ? { ...files, "preset.yaml": document.toString() } : files;
-}
-const alternativeGroups = () => {
-    const members = (group) => builtinPlayPrompts("en")
-        .filter((item) => item.group === group)
-        .map(({ id }) => id);
-    const order = promptGroups.map((group) => members(group));
-    // The default list runs mechanics, then the choice groups in `promptGroups`
-    // order, then the policy blocks: a missing group lands after the previous
-    // group (or mechanics), else ahead of the first later group or policy block.
-    return promptGroups.map((group, index) => ({
-        after: [...order.slice(0, index).flat().reverse(), "play.mechanics"],
-        before: [
-            ...order.slice(index + 1).flat(),
-            "play.prose",
-            "play.scene",
-            "play.ending",
-            "play.output",
-            "play.facts",
-            "play.tabletop",
-        ],
-        entries: groupPromptEntries(group),
-    }));
-};
-/**
- * Insert the choice-group builtins (person, continuation, agency, stopping)
- * that an ordered preset does not list yet. Same identity contract as the
- * tabletop insertion.
- */
-export function withAlternativePromptBuiltins(files) {
-    const document = orderedPresetDocument(files);
-    if (document === undefined)
-        return files;
-    const playPrompts = document.get("playPrompts", true);
-    if (!isSeq(playPrompts))
+    catch {
+        // Invalid drafts stay repairable, without dropping their original bytes.
         return files;
-    let changed = false;
-    for (const group of alternativeGroups()) {
-        if (group.entries.some((entry) => hasEntry(playPrompts, entry.id)))
-            continue;
-        const anchor = group.after
-            .map((id) => playPrompts.items.findIndex((item) => entryField(item, "id") === id))
-            .find((index) => index >= 0);
-        const fallback = playPrompts.items.findIndex((item) => {
-            const id = entryField(item, "id");
-            return ((typeof id === "string" && group.before.includes(id)) ||
-                entryField(item, "kind") === "world");
-        });
-        const at = anchor !== undefined
-            ? anchor + 1
-            : fallback >= 0
-                ? fallback
-                : playPrompts.items.length;
-        playPrompts.items.splice(at, 0, ...group.entries.map((entry) => document.createNode(entry)));
-        changed = true;
     }
-    return changed ? { ...files, "preset.yaml": document.toString() } : files;
 }
-/** Every builtin upgrade a stored or imported ordered preset must receive. */
-export function withCurrentPromptBuiltins(files) {
-    return withAlternativePromptBuiltins(withRestructuredPromptBuiltins(withTabletopPromptBuiltins(files)));
+/** Decode portable customizations through the same resolver used by every caller. */
+export function parsePromptArrangement(value, catalog = builtinPlayPrompts("en"), worldRequired = true) {
+    const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+    const fail = () => {
+        throw new Error("Invalid prompt customizations");
+    };
+    if (!record(value) ||
+        Object.keys(value).some((k) => !["entries", "overrides", "order", "groups"].includes(k)))
+        return fail();
+    if (value.entries !== undefined &&
+        (!Array.isArray(value.entries) ||
+            value.entries.length > 256 ||
+            value.entries.some((e) => !record(e) || e.kind === "builtin")))
+        return fail();
+    const entries = (value.entries ?? []);
+    const entryIds = new Set(entries.map((e) => e.id));
+    if (entryIds.size !== entries.length ||
+        entries.filter((e) => e.kind === "world").length > (worldRequired ? 1 : 0))
+        return fail();
+    if (value.overrides !== undefined) {
+        if (!Array.isArray(value.overrides) || value.overrides.length > 256)
+            return fail();
+        const seen = new Set();
+        const overrideIds = new Set();
+        for (const o of value.overrides) {
+            if (!record(o) ||
+                typeof o.builtin !== "string" ||
+                seen.has(o.builtin) ||
+                (!catalog.some((c) => c.id === o.builtin) &&
+                    !retiredBuiltinReplacements[o.builtin]) ||
+                Object.keys(o).some((k) => !["builtin", "id", "enabled", "messageRole", "turnGuide"].includes(k)) ||
+                (o.enabled !== undefined && typeof o.enabled !== "boolean") ||
+                (o.messageRole !== undefined && !isPromptMessageRole(o.messageRole)) ||
+                (o.turnGuide !== undefined &&
+                    (typeof o.turnGuide !== "string" || !isTurnGuideLine(o.turnGuide))) ||
+                (o.id !== undefined && typeof o.id !== "string"))
+                return fail();
+            if (typeof o.id === "string") {
+                if (entryIds.has(o.id) || overrideIds.has(o.id))
+                    return fail();
+                overrideIds.add(o.id);
+            }
+            seen.add(o.builtin);
+        }
+    }
+    if (value.order !== undefined &&
+        (!Array.isArray(value.order) ||
+            value.order.length > 512 ||
+            value.order.some((k) => typeof k !== "string") ||
+            new Set(value.order).size !== value.order.length))
+        return fail();
+    if (Array.isArray(value.order) &&
+        value.order.some((key) => {
+            if (typeof key !== "string")
+                return true;
+            if (key.startsWith("entry:"))
+                return (!entryIds.has(key.slice(6)) &&
+                    !(worldRequired && key === "entry:world"));
+            return (!key.startsWith("builtin:") ||
+                (!catalog.some((c) => c.id === key.slice(8)) &&
+                    !retiredBuiltinReplacements[key.slice(8)]));
+        }))
+        return fail();
+    if (value.groups !== undefined) {
+        if (!record(value.groups))
+            return fail();
+        for (const [group, ids] of Object.entries(value.groups)) {
+            if (!promptGroups.some((item) => item === group) ||
+                !Array.isArray(ids) ||
+                ids.some((id) => typeof id !== "string" ||
+                    !catalog.some((c) => (c.id === id ||
+                        retiredBuiltinReplacements[id]?.some((r) => r.builtin === c.id)) &&
+                        c.group === group)) ||
+                new Set(ids).size !== ids.length)
+                return fail();
+        }
+    }
+    return parseOrderedPlayPrompts(resolvePromptArrangement(value, catalog, worldRequired), catalog, worldRequired);
 }
 /** A choice group's entries: the first member enabled, the rest disabled. */
 function groupPromptEntries(group) {
@@ -316,12 +274,6 @@ function groupPromptEntries(group) {
         enabled: index === 0,
     }));
 }
-function hasEntry(sequence, id) {
-    return sequence.items.some((item) => entryField(item, "id") === id);
-}
-function entryField(item, key) {
-    return isMap(item) ? item.get(key) : undefined;
-}
 /** Recognized v1 content becomes user text, never a locked builtin inferred from a path. */
 export function migrateLegacyPlayPrompts(files, narrative, excludedPaths = []) {
     const document = parseDocument(files["frame.yaml"] ?? "", {
@@ -447,5 +399,14 @@ export function migrateLegacyPlayPrompts(files, narrative, excludedPaths = []) {
         builtin: "play.tabletop",
         enabled: true,
     });
+    const listed = new Set(entries.flatMap((entry) => entry.kind === "builtin" ? [entry.builtin] : []));
+    entries.splice(entries.findIndex((entry) => entry.kind === "builtin" && entry.builtin === "play.tabletop"), 0, ...builtinPlayPrompts("en")
+        .filter((item) => !listed.has(item.id))
+        .map((item) => ({
+        id: item.id,
+        kind: "builtin",
+        builtin: item.id,
+        enabled: false,
+    })));
     return entries;
 }