narraeon 0.7.10 → 0.8.1

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) {