narraeon 0.6.2 → 0.7.0

package/dist/node/runtime/V1Runtime.js

@@ -462,6 +462,9 @@ export class V1Runtime {
                                     kind: "player",
                                     text: preview.initialAppend.logical.text,
                                 },
+                                ...(preview.initialAppend.afterPlayer === undefined
+                                    ? []
+                                    : [preview.initialAppend.afterPlayer.logical]),
                             ],
                         requestId: "play_call_chain",
                         operationId: "prompt-preview",

package/dist/node/runtime/content/FileNativeContentTree.js

@@ -368,13 +368,21 @@ function validateFrameMarkdownFiles(frame, files, issues) {
         ? frame.instructions
         : [];
     for (const entry of instructions) {
-        if (!isRecord(entry) ||
-            Object.keys(entry).length !== 1 ||
-            typeof entry.markdown !== "string" ||
-            entry.markdown.startsWith("/") ||
-            entry.markdown.includes("..") ||
-            !files.has(`control/${entry.markdown}`)) {
-            issue(issues, "invalid_world_frame", "control/frame.yaml", "A Markdown block referenced by the world frame is missing or escapes the control directory");
+        // An instruction references a Markdown block, carries one turn-guide
+        // line for the per-send suffix, or both.
+        const keysValid = isRecord(entry) &&
+            Object.keys(entry).every((key) => key === "markdown" || key === "turnGuide") &&
+            (entry.markdown !== undefined || entry.turnGuide !== undefined) &&
+            (entry.turnGuide === undefined ||
+                (typeof entry.turnGuide === "string" &&
+                    !/[\r\n]/u.test(entry.turnGuide)));
+        if (!keysValid ||
+            (entry.markdown !== undefined &&
+                (typeof entry.markdown !== "string" ||
+                    entry.markdown.startsWith("/") ||
+                    entry.markdown.includes("..") ||
+                    !files.has(`control/${entry.markdown}`)))) {
+            issue(issues, "invalid_world_frame", "control/frame.yaml", "A world instruction must reference an existing Markdown block inside the control directory or carry a single-line turn-guide entry");
         }
     }
 }

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

@@ -3,7 +3,7 @@ export { validatePlayPresetArtifactPayload } from "../../shared/artifact-payload
 import { defaultFollowupItems, } from "../../shared/ordered-followups.js";
 import { parseFollowupItems } from "./OrderedFollowups.js";
 import { builtinAuthorPrompts, defaultOrderedAuthorPrompts, } from "../../shared/ordered-author-prompts.js";
-import { parseOrderedPlayPrompts, migrateLegacyPlayPrompts, withTabletopPromptBuiltins, } from "./OrderedPlayPrompts.js";
+import { parseOrderedPlayPrompts, migrateLegacyPlayPrompts, withCurrentPromptBuiltins, } from "./OrderedPlayPrompts.js";
 import { defaultOrderedPlayPrompts, } from "../../shared/ordered-play-prompts.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
@@ -101,9 +101,27 @@ export function isPlayPresetBinding(value) {
             isDeepStrictEqual(files, legacyDefaultPlayPresetFilesForLocale("en")) ||
             isDeepStrictEqual(files, legacyDefaultPlayPresetFilesForLocale("zh-CN")));
     return (parsed.kind === "valid" &&
-        isDeepStrictEqual(value.definition, parsed.definition) &&
+        isDeepStrictEqual(normalizedFrozenDefinition(value.definition), parsed.definition) &&
         (builtInDefault || value.revision === revisionForPlayPresetFiles(files)));
 }
+/**
+ * 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.
+ */
+function normalizedFrozenDefinition(definition) {
+    if (!Array.isArray(definition.playPrompts))
+        return definition;
+    try {
+        return {
+            ...definition,
+            playPrompts: parseOrderedPlayPrompts(definition.playPrompts),
+        };
+    }
+    catch {
+        return definition;
+    }
+}
 export class FileNativePlayPresetError extends Error {
     code;
     constructor(code, message) {
@@ -290,7 +308,7 @@ export class FileNativePlayPresetStore {
                 if (candidate.format !== "narraeon.play-preset/v2")
                     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 !== "user")) {
+                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" &&
@@ -364,6 +382,9 @@ export class FileNativePlayPresetStore {
         const files = stored.revisions[selectedRevision];
         if (files === undefined)
             throw new FileNativePlayPresetError("revision_not_found", "The requested play-preset revision was not found");
+        // A frozen revision may still name a retired composite builtin; the
+        // ordered-prompt parser reads it as the blocks that replaced it, so old
+        // requests keep a readable preset while the stored bytes stay as written.
         const parsed = parsePlayPresetFiles(files, this.#limits);
         if (parsed.kind === "invalid")
             throw new FileNativePlayPresetError(parsed.error.code, parsed.error.message);
@@ -457,8 +478,8 @@ export class FileNativePlayPresetStore {
             .map((path) => ({ path, contents: binding.files[path] }));
     }
     async importPortable(input) {
-        // A released preset gains the tabletop builtins at import, as at upgrade.
-        const files = withTabletopPromptBuiltins(toFileMap(input.files, this.#limits));
+        // A released preset gains the current builtins at import, as at upgrade.
+        const files = withCurrentPromptBuiltins(toFileMap(input.files, this.#limits));
         const parsed = parsePlayPresetFiles(files, this.#limits);
         if (parsed.kind === "invalid")
             throw parsed.error;
@@ -502,6 +523,7 @@ export class FileNativePlayPresetStore {
      * surface to fix it from. The damaged file is preserved under a new name
      * instead, so nothing is lost and the workspace can still open.
      */
+    #validated;
     async #read() {
         let raw;
         try {
@@ -515,7 +537,14 @@ export class FileNativePlayPresetStore {
             return document;
         }
         try {
-            return parseStoredDocument(JSON.parse(raw), this.#limits);
+            // Validation hashes and parses 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)
+                return structuredClone(this.#validated.document);
+            const document = parseStoredDocument(JSON.parse(raw), this.#limits);
+            this.#validated = { raw, document: structuredClone(document) };
+            return document;
         }
         catch (error) {
             const quarantined = await this.#quarantine();
@@ -568,8 +597,8 @@ export class FileNativePlayPresetStore {
         return true;
     }
     /**
-     * One-time upgrade for ordered presets saved before the tabletop builtins
-     * existed. An affected revision is replaced by a new revision that inserts
+     * 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,
@@ -580,7 +609,7 @@ export class FileNativePlayPresetStore {
         for (const stored of document.presets) {
             const current = stored.revisions[stored.currentRevision];
             if (current !== undefined) {
-                const migrated = withTabletopPromptBuiltins(current);
+                const migrated = withCurrentPromptBuiltins(current);
                 if (migrated !== current) {
                     const revision = revisionForFiles(migrated, this.#limits);
                     stored.revisions[revision] = cloneFiles(migrated);
@@ -592,7 +621,7 @@ export class FileNativePlayPresetStore {
                 ? undefined
                 : stored.revisions[stored.draftRevision];
             if (draft !== undefined) {
-                const migrated = withTabletopPromptBuiltins(draft);
+                const migrated = withCurrentPromptBuiltins(draft);
                 if (migrated !== draft) {
                     const revision = revisionForFiles(migrated, this.#limits);
                     stored.revisions[revision] = cloneFiles(migrated);
@@ -1846,8 +1875,13 @@ 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(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;
         }

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

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
 import { isMap, isSeq, parseDocument } from "yaml";
-import { builtinPlayPrompts, isPromptMessageRole, } from "../../shared/ordered-play-prompts.js";
+import { builtinPlayPrompts, isPromptMessageRole, promptGroups, } from "../../shared/ordered-play-prompts.js";
+/** One turn-guide line: no line breaks, bounded length; empty clears a builtin default. */
+const turnGuideLine = /^[^\r\n\0]{0,1000}$/u;
+const promptName = /^[^\r\n\0]{1,160}$/u;
 /** The same strict permission gate is used by portable imports and structured saves. */
 export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"), worldRequired = true) {
     const fail = () => {
@@ -11,7 +14,7 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
     const ids = new Set();
     const builtins = new Set();
     let worlds = 0;
-    const entries = value.map((raw) => {
+    const entries = value.flatMap((raw) => {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return fail();
         const item = raw;
@@ -29,53 +32,122 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             key === "messageRole" ||
             key === "id" ||
             key === "kind") && keys.every((key) => Object.hasOwn(item, key));
+        const validTurnGuide = item.turnGuide === undefined ||
+            (typeof item.turnGuide === "string" &&
+                turnGuideLine.test(item.turnGuide));
+        const turnGuide = typeof item.turnGuide === "string" ? { turnGuide: item.turnGuide } : {};
         if (item.kind === "world" && exact(["id", "kind"])) {
             worlds++;
-            return { id: item.id, kind: "world", ...messageRole };
+            return [{ id: item.id, kind: "world", ...messageRole }];
         }
+        if (item.kind === "tail" &&
+            exact(["id", "kind", "name", "enabled", "body"]) &&
+            item.messageRole === undefined &&
+            typeof item.name === "string" &&
+            item.name.trim().length > 0 &&
+            promptName.test(item.name) &&
+            typeof item.body === "string" &&
+            turnGuideLine.test(item.body) &&
+            typeof item.enabled === "boolean")
+            return [
+                {
+                    id: item.id,
+                    kind: "tail",
+                    name: item.name,
+                    enabled: item.enabled,
+                    body: item.body,
+                },
+            ];
         if (item.kind === "user" &&
-            exact(["id", "kind", "name", "enabled", "body"], ["gameplay"]) &&
+            exact(["id", "kind", "name", "enabled", "body"], ["gameplay", "turnGuide"]) &&
             typeof item.name === "string" &&
             item.name.trim().length > 0 &&
-            /^[^\r\n\0]{1,160}$/u.test(item.name) &&
+            promptName.test(item.name) &&
             typeof item.body === "string" &&
             typeof item.enabled === "boolean" &&
+            validTurnGuide &&
             (item.gameplay === undefined || item.gameplay === "tabletop"))
-            return {
-                id: item.id,
-                kind: "user",
-                name: item.name,
-                enabled: item.enabled,
-                body: item.body,
-                ...messageRole,
-                ...(item.gameplay === "tabletop"
-                    ? { gameplay: "tabletop" }
-                    : {}),
-            };
+            return [
+                {
+                    id: item.id,
+                    kind: "user",
+                    name: item.name,
+                    enabled: item.enabled,
+                    body: item.body,
+                    ...messageRole,
+                    ...(item.gameplay === "tabletop"
+                        ? { gameplay: "tabletop" }
+                        : {}),
+                    ...turnGuide,
+                },
+            ];
+        // A frozen list (an old preset revision, or the preset a stored author
+        // session captured) may still name a retired composite builtin. It reads
+        // as the single-rule blocks that replaced it, exactly as the stored
+        // library migrates it, so old bindings keep parsing and compiling.
+        const retired = item.kind === "builtin" && typeof item.builtin === "string"
+            ? retiredBuiltinReplacements[item.builtin]
+            : undefined;
+        if (retired !== undefined &&
+            exact(["id", "kind", "builtin", "enabled"]) &&
+            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,
+                    },
+                ];
+            });
+        }
         const builtin = catalog.find((entry) => entry.id === item.builtin);
         if (item.kind !== "builtin" ||
-            !exact(["id", "kind", "builtin", "enabled"]) ||
+            !exact(["id", "kind", "builtin", "enabled"], ["turnGuide"]) ||
             !builtin ||
             builtins.has(builtin.id) ||
             typeof item.enabled !== "boolean" ||
+            !validTurnGuide ||
             (builtin.required &&
                 (!item.enabled ||
                     (item.messageRole !== undefined && item.messageRole !== "system"))))
             return fail();
         builtins.add(builtin.id);
-        return {
-            id: item.id,
-            kind: "builtin",
-            builtin: builtin.id,
-            enabled: item.enabled,
-            ...messageRole,
-        };
+        return [
+            {
+                id: item.id,
+                kind: "builtin",
+                builtin: builtin.id,
+                enabled: item.enabled,
+                ...messageRole,
+                ...turnGuide,
+            },
+        ];
     });
     if (worlds !== (worldRequired ? 1 : 0) ||
         catalog.some((item) => item.required && !builtins.has(item.id)))
         return fail();
     return entries;
 }
+function orderedPresetDocument(files) {
+    const source = files["preset.yaml"];
+    if (source === undefined)
+        return undefined;
+    const document = parseDocument(source, { uniqueKeys: true });
+    if (document.errors.length > 0 ||
+        document.warnings.length > 0 ||
+        !isMap(document.contents) ||
+        document.get("format") !== "narraeon.play-preset/v2")
+        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
@@ -84,14 +156,8 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
  * when nothing needs inserting, so callers can detect a change by identity.
  */
 export function withTabletopPromptBuiltins(files) {
-    const source = files["preset.yaml"];
-    if (source === undefined)
-        return files;
-    const document = parseDocument(source, { uniqueKeys: true });
-    if (document.errors.length > 0 ||
-        document.warnings.length > 0 ||
-        !isMap(document.contents) ||
-        document.get("format") !== "narraeon.play-preset/v2")
+    const document = orderedPresetDocument(files);
+    if (document === undefined)
         return files;
     let changed = false;
     const playPrompts = document.get("playPrompts", true);
@@ -118,6 +184,141 @@ export function withTabletopPromptBuiltins(files) {
     }
     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) {
+    const document = orderedPresetDocument(files);
+    if (document === undefined)
+        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;
+    }
+    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))
+        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)));
+}
+/** A choice group's entries: the first member enabled, the rest disabled. */
+function groupPromptEntries(group) {
+    return builtinPlayPrompts("en")
+        .filter((item) => item.group === group)
+        .map(({ id }, index) => ({
+        id,
+        kind: "builtin",
+        builtin: id,
+        enabled: index === 0,
+    }));
+}
 function hasEntry(sequence, id) {
     return sequence.items.some((item) => entryField(item, "id") === id);
 }
@@ -239,9 +440,11 @@ export function migrateLegacyPlayPrompts(files, narrative, excludedPaths = []) {
         if ((path.startsWith("blocks/") || path.startsWith("prompts/")) &&
             path.endsWith(".md"))
             add(path, false);
-    // The tabletop builtin joins converted presets just before the world placeholder.
+    // Converted presets gain the choice-group builtins and then the tabletop
+    // builtin just before the world placeholder. The legacy block copies keep
+    // their own wording as user text; the current builtins arrive beside them.
     const worldIndex = entries.findIndex((entry) => entry.kind === "world");
-    entries.splice(worldIndex, 0, {
+    entries.splice(worldIndex, 0, ...promptGroups.flatMap((group) => groupPromptEntries(group)), {
         id: "play.tabletop",
         kind: "builtin",
         builtin: "play.tabletop",

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

@@ -9,7 +9,7 @@ import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, ind
 import { currentPlayPrompt, recordedPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
 import { comparePromptPrefixes } from "../prompt/WorldPromptDiagnostics.js";
 import { createHash, randomBytes } from "node:crypto";
-import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, } from "./PlayContinuity.js";
+import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, turnGuideNotice, } from "./PlayContinuity.js";
 import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
@@ -1181,7 +1181,7 @@ export class PlayCallChain {
             throw new PlayCallChainError("The recovered call-chain transcript is shorter than its player prefix.");
         session.transcript = [
             ...session.transcript.slice(0, advance.transcriptStart),
-            ...structuredClone(advance.nextRequest.appended.slice(advance.transcriptStart)),
+            ...structuredClone(transcriptAppendOf(advance.nextRequest).slice(advance.transcriptStart)),
         ];
         session.nextEventId = advance.eventId + 1;
         session.parentHead = outcome.head;
@@ -2008,13 +2008,19 @@ function createRequest(session, modelHost, exchange, appended = session.transcri
     return modelHost.freezeRequest?.(request) ?? request;
 }
 function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, appended = session.transcript) {
+    // The turn guide is a request-level suffix: it follows whatever this
+    // dispatch appends and is never part of the transcript it is built on.
+    const turnGuide = currentPlayPrompt(session).bootstrap.turnGuide;
     return {
         bootstrap: structuredClone(currentPlayPrompt(session).bootstrap),
         tools: structuredClone(currentPlayPrompt(session).tools),
         toolUniverse: structuredClone(currentPlayPrompt(session).tools),
         allowedTools: currentPlayPrompt(session).tools.map(({ name }) => name),
         toolStrategy: currentPlayPrompt(session).bootstrap.toolStrategy,
-        appended: structuredClone([...appended]),
+        appended: structuredClone([
+            ...appended,
+            ...(turnGuide === undefined ? [] : [turnGuideNotice(turnGuide.text)]),
+        ]),
         requestId: "play_call_chain",
         operationId: session.chainId,
         requestAttempt: 1,
@@ -2022,6 +2028,17 @@ function createRequestWithMaxOutputTokens(session, maxOutputTokens, exchange, ap
         maxOutputTokens,
     };
 }
+/**
+ * The items a frozen request contributes to the transcript: everything it
+ * appended except the request-level turn-guide suffix, which is re-attached to
+ * every dispatch and never stored.
+ */
+function transcriptAppendOf(request) {
+    const last = request.appended.at(-1);
+    return last?.kind === "runtime_notice" && last.notice === "turn_guide"
+        ? request.appended.slice(0, -1)
+        : request.appended;
+}
 function durableModelResponse(response) {
     const { diagnostics: _diagnostics, ...durable } = response;
     void _diagnostics;

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

@@ -37,10 +37,18 @@ export function continuationNotice(locale) {
         kind: "runtime_notice",
         notice: "continuation",
         text: locale === "zh-CN"
-            ? "[Runtime 续写提示]\n本次发送没有追加新的玩家原文。已有的最终主持正文已展示并提交为历史；本次响应接在其后，不重新提交旧正文。回复提交不表示世界内活动已经结束。"
-            : "[Runtime continuation]\nThis send adds no new player input. Existing final narrator prose has been displayed and committed as history; this response follows it without resubmitting it. A committed reply does not mean an in-world activity has ended.",
+            ? "[Runtime 续写提示]\n本次发送没有追加新的玩家原文。已有的最终主持正文已展示并提交为历史；本次响应接在其后，从那段正文的最后局面继续，只推进既有的动作、NPC 和环境：不重新回答已经回应的问题，不复位已完成的递接或走动，不把旧玩家输入再演一次，不替玩家增加决定，也不代玩家接受邀请或作出承诺。回复提交不表示世界内活动已经结束。"
+            : "[Runtime continuation]\nThis send adds no new player input. Existing final narrator prose has been displayed and committed as history; this response follows it, resuming from that prose's final situation and advancing only existing actions, NPCs and the environment: do not answer an already answered question again, reset a completed handover or movement, perform the old player input again, add a decision for the player, or accept an invitation or make a promise on their behalf. A committed reply does not mean an in-world activity has ended.",
     };
 }
+/**
+ * The per-send turn guide. It is request-level: appended after the current
+ * transcript on every dispatch and never stored in the transcript, so the next
+ * dispatch appends a fresh copy at the new end.
+ */
+export function turnGuideNotice(text) {
+    return { kind: "runtime_notice", notice: "turn_guide", text };
+}
 export function toolStepNotice(locale) {
     return {
         kind: "runtime_notice",

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

@@ -66,6 +66,15 @@ export class FileNativePlayDocuments {
         // Creation capabilities come from this prefix, not past directory slots.
         this.#declaredDirectories = declaredStateDirectories(bootstrap);
     }
+    /**
+     * Re-grant one exact read the model already completed in a retained
+     * transcript. The scope is resolved against the current snapshot again, so a
+     * document or node that no longer exists grants nothing. Returns whether the
+     * scope resolved.
+     */
+    replayRead(shortRef, locator) {
+        return authorizeResolvedRead(this.#reads, this.#candidate.snapshot, shortRef, locator);
+    }
     execute(call, history, options = {}) {
         let historyQuery;
         const query = () => (historyQuery ??= new HistoryQuery(options.historyScope ?? "local-document-context", historyInputs(history)));
@@ -156,26 +165,31 @@ function bootstrapAuthorizations(bootstrap, snapshot) {
     for (const { status, complete, readAuthorization } of bootstrap.coverage) {
         if (status !== "resolved" || !complete || readAuthorization === undefined)
             continue;
-        if (readAuthorization.locator === null) {
-            const resolved = snapshot.query({
-                kind: "read_document",
-                document: { shortRef: readAuthorization.shortRef },
-            });
-            if (resolved.kind === "read_document" && resolved.ok)
-                authorizeRead(result, snapshot.id, resolved.document.shortRef, null);
-        }
-        else {
-            const selected = snapshot.query({
-                kind: "select_node",
-                document: { shortRef: readAuthorization.shortRef },
-                locator: readAuthorization.locator,
-            });
-            if (selected.kind === "select_node" && selected.ok)
-                authorizeRead(result, snapshot.id, selected.document.shortRef, selected.node.locator);
-        }
+        authorizeResolvedRead(result, snapshot, readAuthorization.shortRef, readAuthorization.locator);
     }
     return result;
 }
+function authorizeResolvedRead(authorizations, snapshot, shortRef, locator) {
+    if (locator === null) {
+        const resolved = snapshot.query({
+            kind: "read_document",
+            document: { shortRef },
+        });
+        if (resolved.kind !== "read_document" || !resolved.ok)
+            return false;
+        authorizeRead(authorizations, snapshot.id, resolved.document.shortRef, null);
+        return true;
+    }
+    const selected = snapshot.query({
+        kind: "select_node",
+        document: { shortRef },
+        locator,
+    });
+    if (selected.kind !== "select_node" || !selected.ok)
+        return false;
+    authorizeRead(authorizations, snapshot.id, selected.document.shortRef, selected.node.locator);
+    return true;
+}
 function declaredStateDirectories(bootstrap) {
     // Catalog coverage is the durable compiler projection shared by current
     // state_list contexts and legacy context_list contexts.