narraeon 0.6.2 → 0.7.0

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

@@ -131,16 +131,64 @@ function assembleRetainedTrace(source, endpoint, selection) {
 export function restorePlayDocuments(files, context, events) {
     const documents = new FileNativePlayDocuments(files);
     try {
-        // Read authorizations are memory-only: a restored prefix always starts from
-        // its bootstrap, and stale write authority is caught by the commit's hash.
+        // Read authorizations are memory-only (ADR-0044). A restored prefix starts
+        // from its bootstrap, then replays the exact reads the retained transcript
+        // still shows the model, so it is not asked to read again what it has
+        // already seen. Stale write authority is caught by the commit's hash.
         const runs = playPromptRunsThroughEvents(context, events);
         documents.bindBootstrap(currentPlayPrompt({ ...context, promptRuns: runs }).bootstrap);
+        for (const read of completedReadsThroughEvents(context, events))
+            documents.replayRead(read.shortRef, read.locator);
     }
     catch (error) {
         throw new PlayCallChainError(`Call-chain document authorization could not be restored: ${error instanceof Error ? error.message : "invalid checkpoint"}。`);
     }
     return documents;
 }
+/**
+ * The exact document scopes successfully read by context_read within the
+ * selected event prefix, in event order. Tool results are keyed by exchange and
+ * call ID, and the exchange is the one of the nearest preceding assistant event.
+ */
+function completedReadsThroughEvents(context, events) {
+    const completed = new Map(context.completedTools.map((tool) => [tool.key, tool.result]));
+    const reads = [];
+    let exchange = 0;
+    for (const event of events) {
+        if (event.kind === "assistant") {
+            exchange = event.exchange;
+            continue;
+        }
+        if (event.kind !== "tool_result" || !event.ok)
+            continue;
+        const result = completed.get(`${exchange}:${event.callId}`);
+        const authorization = result?.readAuthorization;
+        if (!result?.ok || !isReplayableReadAuthorization(authorization))
+            continue;
+        reads.push({
+            shortRef: authorization.shortRef,
+            locator: structuredClone(authorization.locator),
+        });
+    }
+    return reads;
+}
+function isReplayableReadAuthorization(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const { shortRef, locator } = value;
+    if (typeof shortRef !== "string")
+        return false;
+    if (locator === null)
+        return true;
+    if (typeof locator !== "object" || locator === null)
+        return false;
+    const { yaml, markdown } = locator;
+    if (Array.isArray(yaml))
+        return yaml.every((segment) => typeof segment === "string" ||
+            (Number.isSafeInteger(segment) && Number(segment) >= 0));
+    return (Array.isArray(markdown) &&
+        markdown.every((segment) => typeof segment === "string"));
+}
 export function independentContextCopy(source) {
     const context = structuredClone(source);
     context.continuityContextId ??= source.chainId;

package/dist/node/runtime/prompt/FileNativePromptCompiler.js

@@ -5,7 +5,8 @@ import { hasLegacyHistoryTools } from "./FileNativeToolRegistry.js";
 import { effectiveFollowupDefinitions } from "../play/OrderedFollowups.js";
 import { legacyAuthorPrompts } from "../play/FileNativePlayPresetStore.js";
 import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-author-prompts.js";
-import { builtinPlayPrompts, orderedPromptScope, promptScopeApplies, } from "../../shared/ordered-play-prompts.js";
+import { builtinPlayPrompts, orderedPromptScope, orderedPromptTurnGuide, promptScopeApplies, } from "../../shared/ordered-play-prompts.js";
+import { turnGuideHeader, turnGuideText, } from "../../shared/turn-guide.js";
 import { parseOrderedPlayPrompts } from "../play/OrderedPlayPrompts.js";
 import { renderDocumentWritePosition } from "./WorldMaintenanceReport.js";
 import { parseDocument } from "yaml";
@@ -330,7 +331,7 @@ export class FileNativePromptCompiler {
         const worldFrame = readYamlRecord(worldFiles["control/frame.yaml"], "world frame");
         requireFormat(hostFrame, "narraeon.host-frame/v1", "host frame");
         requireFormat(worldFrame, "narraeon.world-frame/v1", "world frame");
-        const instructions = readWorldInstructions(worldFiles, worldFrame);
+        const instructions = readWorldInstructions(worldFiles, worldFrame).blocks;
         const { coverage, blocks: context, maintenance, } = this.playMaterials(effectiveInput);
         const hostRoles = compileHostRoles(effectiveInput.hostBinding.files, hostFrame, instructions, context, coverage, this.#locale);
         const blocks = {
@@ -511,6 +512,7 @@ export class FileNativePromptCompiler {
         };
         const playCatalog = builtinPlayPrompts(this.#locale);
         const gameplay = playGameplay(effective.world.documentSnapshot);
+        const turnGuideLines = [];
         for (const entry of parseOrderedPlayPrompts(binding.definition.playPrompts)) {
             // A scoped entry is absent from the request, not an empty message.
             if (!promptScopeApplies(orderedPromptScope(entry, playCatalog), gameplay))
@@ -519,10 +521,26 @@ export class FileNativePromptCompiler {
                 messageRole: entry.messageRole ?? "system",
                 promptId: entry.id,
             };
+            // The turn guide follows list order: each enabled entry's line, and
+            // the world frame's lines at the world placeholder.
+            if (entry.kind === "world")
+                turnGuideLines.push(...instructions.turnGuide);
+            else if (entry.enabled) {
+                const line = orderedPromptTurnGuide(entry, playCatalog);
+                if (line !== undefined)
+                    turnGuideLines.push({
+                        source: entry.kind === "builtin"
+                            ? `preset:builtin/${entry.builtin}`
+                            : `preset:prompt/${entry.id}`,
+                        text: line,
+                    });
+            }
+            if (entry.kind === "tail")
+                continue;
             if (entry.kind === "user" && !entry.body.trim())
                 continue;
             if (entry.kind === "world") {
-                append("author_instruction", instructions);
+                append("author_instruction", instructions.blocks);
                 append("world_context", [
                     ...materials.blocks,
                     {
@@ -550,7 +568,26 @@ export class FileNativePromptCompiler {
             append("player_input", [
                 { source: "player:input", markdown: effective.playerInput },
             ]);
-        scanRuntimeLeakage(logicalMessages);
+        const turnGuide = turnGuideLines.length === 0
+            ? undefined
+            : {
+                text: turnGuideText(this.#locale, turnGuideLines),
+                lines: turnGuideLines,
+            };
+        scanRuntimeLeakage([
+            ...logicalMessages,
+            ...(turnGuide === undefined
+                ? []
+                : [
+                    {
+                        role: "author_instruction",
+                        markdown: turnGuide.text,
+                        blocks: [
+                            { source: "runtime:turn-guide", markdown: turnGuide.text },
+                        ],
+                    },
+                ]),
+        ]);
         const tools = runtimeToolsForNames(runtimeToolNamesForGameplay(playGameplay(effective.world.documentSnapshot)), this.#locale);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(effective.modelBinding.provider);
@@ -569,6 +606,7 @@ export class FileNativePromptCompiler {
             ...(materials.maintenance === undefined
                 ? {}
                 : { maintenance: materials.maintenance }),
+            ...(turnGuide === undefined ? {} : { turnGuide }),
             budget: disabledPromptBudget(effective),
             cache: {
                 ...stableCacheBoundary(cacheStableText(logicalMessages, provider), tools, toolStrategy),
@@ -837,7 +875,7 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
                             : "World instructions expand here; frame-selected material is supplied as an initial tool result only for a fresh play context. Inspect actual content through the current authoring tools.",
                     },
                 ];
-            if (!entry.enabled)
+            if (entry.kind === "tail" || !entry.enabled)
                 return [];
             if (!promptScopeApplies(orderedPromptScope(entry, builtinPlayPrompts(locale)), gameplay))
                 return [];
@@ -856,6 +894,37 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
                 ];
         });
     const narrativeBlocks = ordered === undefined ? playNarrativeBlocks(binding) : [];
+    // The preset half of the turn guide: the world frame's lines are read from
+    // the package or world itself through the authoring tools.
+    const turnGuideLines = ordered === undefined
+        ? []
+        : parseOrderedPlayPrompts(ordered).flatMap((entry) => {
+            if (entry.kind === "world" || !entry.enabled)
+                return [];
+            if (!promptScopeApplies(orderedPromptScope(entry, builtinPlayPrompts(locale)), gameplay))
+                return [];
+            const line = orderedPromptTurnGuide(entry, builtinPlayPrompts(locale));
+            return line === undefined
+                ? []
+                : [
+                    `- ${line} （${entry.kind === "builtin" ? `preset:builtin/${entry.builtin}` : `preset:prompt/${entry.id}`}）`,
+                ];
+        });
+    const turnGuideBlocks = turnGuideLines.length === 0
+        ? []
+        : [
+            {
+                source: "play-preset:turn-guide",
+                markdown: [
+                    turnGuideHeader(locale),
+                    ...turnGuideLines,
+                    "",
+                    locale === "zh-CN"
+                        ? "世界 frame 的 instructions 可用 turnGuide 在世界占位处补充一到两行本世界特有、最容易丢的约束；不要复制上述跨世界规则。"
+                        : "The world frame's instructions may add one or two world-specific, easily lost constraints with turnGuide at the world placeholder; do not copy the cross-world lines above.",
+                ].join("\n"),
+            },
+        ];
     const heading = locale === "zh-CN"
         ? `# ${revision ? "继续游玩" : "创建后游玩"}语义边界（只读参考）`
         : `# ${revision ? "Continued" : "Post-creation"} play semantics (read-only reference)`;
@@ -880,6 +949,11 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
             : "Player-visible narrative semantics", locale === "zh-CN"
             ? "这些块只在未来游玩生成玩家可见正文时生效；不得把它们当作本轮 YAML 或 Markdown 设定正文的范文。"
             : "These blocks apply only when future play produces player-visible story. Do not use them as prose models for YAML or Markdown setting documents in this conversation.", narrativeBlocks),
+        settingImprovementReferenceGroup(locale === "zh-CN"
+            ? "本轮提示（每次发送的尾部）"
+            : "Turn guide (per-send suffix)", locale === "zh-CN"
+            ? "这些行在每次游玩发送时追加在玩家输入之后，由已启用块的尾部行按同一顺序拼成；它们是提醒，不是世界事实。"
+            : "These lines are appended after the player input on every play send, assembled from the enabled blocks' turn-guide lines in the same order. They are reminders, not world facts.", turnGuideBlocks),
     ].filter((group) => group !== null);
     return [
         heading,
@@ -958,6 +1032,21 @@ function promptPreview(input, playPreset, compilation, playCompilation) {
                 initialAppend: {
                     logical: { kind: "player", text: input.playerInput },
                     provider: { role: "user", content: input.playerInput },
+                    ...(compilation.turnGuide === undefined
+                        ? {}
+                        : {
+                            afterPlayer: {
+                                logical: {
+                                    kind: "runtime_notice",
+                                    notice: "turn_guide",
+                                    text: compilation.turnGuide.text,
+                                },
+                                provider: {
+                                    role: "user",
+                                    content: compilation.turnGuide.text,
+                                },
+                            },
+                        }),
                 },
             }
             : {}),
@@ -1761,18 +1850,40 @@ function isPathPrefix(prefix, path) {
     return (prefix.length <= path.length &&
         prefix.every((segment, index) => segment === path[index]));
 }
+/**
+ * A world instruction is `{ markdown }`, `{ markdown, turnGuide }` or a bare
+ * `{ turnGuide }`: the block joins the prefix and the line joins the turn
+ * guide at the world placeholder's position.
+ */
 function readWorldInstructions(files, frame) {
     if (!Array.isArray(frame.instructions))
         throw new PromptCompilationError("world_frame_invalid", "world frame.instructions must be an array");
-    return frame.instructions.map((entry) => {
-        if (!isRecord(entry) || typeof entry.markdown !== "string")
-            throw new PromptCompilationError("world_frame_invalid", "A world instruction must reference a Markdown block");
-        const path = `control/${entry.markdown}`;
-        return {
-            source: `world:${path}`,
-            markdown: readMarkdown(files, path, "world prompt block"),
-        };
+    const result = { blocks: [], turnGuide: [] };
+    frame.instructions.forEach((entry, index) => {
+        const valid = isRecord(entry) &&
+            Object.keys(entry).every((key) => key === "markdown" || key === "turnGuide") &&
+            (entry.markdown === undefined || typeof entry.markdown === "string") &&
+            (entry.turnGuide === undefined ||
+                (typeof entry.turnGuide === "string" &&
+                    !/[\r\n]/u.test(entry.turnGuide))) &&
+            (entry.markdown !== undefined || entry.turnGuide !== undefined);
+        if (!valid)
+            throw new PromptCompilationError("world_frame_invalid", "A world instruction must reference a Markdown block, carry a turn-guide line, or both");
+        if (typeof entry.markdown === "string") {
+            const path = `control/${entry.markdown}`;
+            result.blocks.push({
+                source: `world:${path}`,
+                markdown: readMarkdown(files, path, "world prompt block"),
+            });
+        }
+        const line = typeof entry.turnGuide === "string" ? entry.turnGuide.trim() : "";
+        if (line)
+            result.turnGuide.push({
+                source: `world:control/frame.yaml#instructions[${index}]`,
+                text: line,
+            });
     });
+    return result;
 }
 function compileHostRoles(files, frame, worldInstructions, worldContext, coverage, locale) {
     if (!isRecord(frame.roles))

package/dist/node/runtime/prompt/FileNativeToolRegistry.js

@@ -1,4 +1,3 @@
-import { historyUseGuidance } from "../../shared/history-use-guidance.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { resolutionCheckToolForScheme, resolutionToolDefinition, resolutionToolNames, } from "../play/TabletopResolution.js";
 /**
@@ -125,7 +124,7 @@ function createToolDefinitions(locale) {
             }, ["parent"]),
         },
         history_list: {
-            description: descriptions.history_list + " " + historyUseGuidance(locale),
+            description: descriptions.history_list,
             inputSchema: object({
                 before: string,
                 after: string,
@@ -134,7 +133,7 @@ function createToolDefinitions(locale) {
             }, []),
         },
         history_search: {
-            description: descriptions.history_search + " " + historyUseGuidance(locale),
+            description: descriptions.history_search,
             inputSchema: object({
                 queries: {
                     type: "array",
@@ -152,7 +151,7 @@ function createToolDefinitions(locale) {
             }, []),
         },
         history_read: {
-            description: descriptions.history_read + " " + historyUseGuidance(locale),
+            description: descriptions.history_read,
             inputSchema: object({
                 latest: { type: "integer", minimum: 1, maximum: 21 },
                 ref: string,
@@ -272,7 +271,7 @@ function resolutionDefinitions(locale) {
 }
 const toolDescriptions = {
     en: {
-        world_checkpoint: "Register a gap between events: the previous event has naturally settled at this turn's stopping point, or the scene has actually changed, suggesting that the player start a fresh context here. Arguments must be an empty object. Registration takes effect only after the subsequent nonempty tool-free final prose successfully commits, and includes that prose. A fresh context replays only committed player inputs and final narratives after this boundary, so save still-needed outcomes before registration. Consolidation and maintenance do not require this tool. Do not advance the story to register a checkpoint; registration neither switches context nor ends an in-world event. Further tool calls may follow registration; Runtime does not verify semantic completeness.",
+        world_checkpoint: "Register a gap between events and suggest that the player start a fresh context here. Arguments must be an empty object. The effect and replay scope are defined by the tools-and-settlement rules; when to register is defined by the checkpoint policy. Consolidation and maintenance do not require this tool; do not advance the story to register a checkpoint.",
         state_list: "List document and state directory handles known to Runtime. parent must be @dir-/ for the state root or an @dir-* handle from the initial directory index or an earlier state_list result; no preliminary listing is needed for an already supplied handle. Catalog directories declared by the frozen world frame remain listed and usable when empty. A cursor is valid only for the same state snapshot, parent, and limit. Pass returned document handles to context_read. This tool never lists committed history.",
         history_list: "Browse committed history on the current timeline. Omit anchors for the latest page; use only before or after with a Runtime ref (including refs in injected history) for the immediately adjacent page, excluding the anchor. Every page is oldest to newest. limit defaults to 20 (1–100 messages). Previews are only the first 120 Unicode code points. Use independent earlierCursor/laterCursor with {cursor} alone; no first-query parameters on continuation. Cursors bind world, tool, query and immutable ordered history. After history_changed rerun the query. Opening messages are queryable. Read full originals with history_read; positions are snapshot locations, not identities or turns.",
         history_search: "Search committed originals on the current timeline with queries: 1–5 nonempty literal strings (max 256 code points each); no query alias or semantic filters. match defaults to any, or all within one message. NFKC normalization always applies; caseSensitive defaults to false (locale-und case folding), normalized duplicate queries collapse. order defaults to newest_first, or oldest_first. limit defaults to 10 (1–50 matching messages). Optional after/before refs exclude timeline boundaries independently of order; after must precede before. Each result has at most 3 partial original fragments, query occurrence counts and complete-original length. Read a hit and nearby context with history_read. Continue with {cursor} alone; history_changed requires a new query.",
@@ -286,7 +285,7 @@ const toolDescriptions = {
         artifact_clear: "Clear the projection of an artifact that this follow-up declared in advance and explicitly allows to be cleared. The call cannot choose a channel, key, or any other output contract.",
     },
     "zh-CN": {
-        world_checkpoint: "登记事件间隙：上一事件已在本轮停笔位置自然告一段落，或场景已实际转换，建议玩家从这里开始全新上下文。参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文只补入边界之后的已提交玩家原文与最终叙事，因此登记前应已保存后续仍需要的结果。整理与归并不需要调用本工具。不要为了登记而推进剧情；登记不切换上下文，也不结束世界内事件。登记后仍可继续工具调用；Runtime 不认证语义完整。",
+        world_checkpoint: "登记事件间隙，向玩家建议从这里开始全新上下文。参数为空对象。生效条件与补入范围见“工具与响应结算”；何时登记见检查点政策。整理与归并不需要调用本工具；不要为了登记而推进剧情。",
         state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时使用初始目录索引或 state_list 返回的 @dir-*；已有句柄无需再次列目录确认。冻结世界 frame 声明的 catalog 目录即使为空，也会继续列出并可用。cursor 只对同一状态快照、parent 和 limit 有效。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
         history_list: "浏览当前时间线已提交历史。无锚点时取最新一页；before 或 after 只能选一个，取锚点紧邻前／后的一页且不含锚点。页内始终由旧到新。limit 默认20，整数1–100。预览仅含前120个Unicode码点；完整原文用history_read。earlierCursor／laterCursor独立翻页，续页只传{cursor}，不可混用首次参数。游标绑定世界、工具、查询和有序历史快照；history_changed须重新查询。开场白可查询。提示词注入中的ref可直接使用，无需再次列举；位置不是身份或回合数。",
         history_search: "搜索当前时间线已提交原文。queries必填：1–5个非空字面词，每词最多256个Unicode码点，不接受query别名或语义筛选。match默认any，all限于同一消息。始终NFKC规范化，caseSensitive默认false（locale-und大小写折叠），规范化重复词合并。order默认newest_first，可选oldest_first；limit默认10，整数1–50条命中消息。after／before始终按时间线先后排除边界，after必须早于before，与结果排序无关。每项最多3个部分原文片段、逐词命中次数及完整原文长度；可用history_read读取前后文。续页只传{cursor}；history_changed须重新查询。",

package/dist/node/runtime/prompt/PromptCompilationCodec.js

@@ -139,6 +139,17 @@ function validArtifactPayloadContract(value) {
     return (isRecord(value.properties) &&
         Object.values(value.properties).every(validArtifactPayloadContract));
 }
+function validTurnGuide(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["text", "lines"]) &&
+        typeof value.text === "string" &&
+        Array.isArray(value.lines) &&
+        value.lines.length > 0 &&
+        value.lines.every((line) => isRecord(line) &&
+            hasExactKeys(line, ["source", "text"]) &&
+            typeof line.source === "string" &&
+            typeof line.text === "string"));
+}
 export function validPromptCompilation(value) {
     return (isRecord(value) &&
         hasExactKeys(value, [
@@ -150,9 +161,10 @@ export function validPromptCompilation(value) {
             "coverage",
             "budget",
             "cache",
-        ], ["maintenance"]) &&
+        ], ["maintenance", "turnGuide"]) &&
         (value.maintenance === undefined ||
             isWorldPromptMaintenance(value.maintenance)) &&
+        (value.turnGuide === undefined || validTurnGuide(value.turnGuide)) &&
         validLogicalMessages(value.logicalMessages) &&
         validPromptProvider(value.provider) &&
         validPromptTools(value.tools) &&

package/dist/node/runtime/setting/FileNativeSettingImprovementStore.js

@@ -516,7 +516,8 @@ function validModelItemShape(value, storedToolChanges) {
         return (hasExactKeys(value, ["kind", "notice", "text"]) &&
             (value.notice === "checkpoint_rounds" ||
                 value.notice === "continuation" ||
-                value.notice === "tool_step") &&
+                value.notice === "tool_step" ||
+                value.notice === "turn_guide") &&
             typeof value.text === "string");
     if (value.kind === "prompt_delta")
         return (hasExactKeys(value, ["kind", "logicalMessages"]) &&
@@ -721,17 +722,21 @@ function validDiagnosticBinding(value) {
         (value.playPresetRevision === undefined ||
             typeof value.playPresetRevision === "string"));
 }
+function validNoticeAppend(value) {
+    return (value === undefined ||
+        (isRecord(value) &&
+            hasExactKeys(value, ["logical", "provider"]) &&
+            validLegacyModelItem(value.logical) &&
+            isRecord(value.provider) &&
+            hasExactKeys(value.provider, ["role", "content"]) &&
+            value.provider.role === "user" &&
+            typeof value.provider.content === "string"));
+}
 function validInitialAppend(value) {
     return (isRecord(value) &&
-        hasExactKeys(value, ["logical", "provider"], ["beforePlayer"]) &&
-        (value.beforePlayer === undefined ||
-            (isRecord(value.beforePlayer) &&
-                hasExactKeys(value.beforePlayer, ["logical", "provider"]) &&
-                validLegacyModelItem(value.beforePlayer.logical) &&
-                isRecord(value.beforePlayer.provider) &&
-                hasExactKeys(value.beforePlayer.provider, ["role", "content"]) &&
-                value.beforePlayer.provider.role === "user" &&
-                typeof value.beforePlayer.provider.content === "string")) &&
+        hasExactKeys(value, ["logical", "provider"], ["beforePlayer", "afterPlayer"]) &&
+        validNoticeAppend(value.beforePlayer) &&
+        validNoticeAppend(value.afterPlayer) &&
         isRecord(value.logical) &&
         hasExactKeys(value.logical, ["kind", "text"]) &&
         value.logical.kind === "player" &&

package/dist/node/runtime/setting/SettingAuthoringTransaction.js

@@ -103,7 +103,7 @@ export function settingImprovementRuntimeContract(locale, gameplay) {
 
 ## 游玩怎样读取并使用设定
 
-- control/frame.yaml 的 instructions 把世界专属提示块作为作者指令；context 只按声明顺序执行确定性材料选择。
+- control/frame.yaml 的 instructions 把世界专属提示块作为作者指令；每项可带 turnGuide（单行），或只含 turnGuide：这些行成为每次游玩发送追加在玩家输入之后的本轮提示中的世界尾部行，只放本世界特有且最容易丢的约束，一到两行，不复制跨世界规则。context 只按声明顺序执行确定性材料选择。
 - 可在 frame.maintenance.documents 中用 @短引用声明正文建议 UTF-8 字节数；slot 可声明唯一稳定 id 和 advisoryBytes。超限只提示，不截断或拒绝写入。frame.maintenance.clock 可明确绑定 {document: "@ref", locator: {yaml: [时间]}}；只记录该次写入时的标量或 Markdown 文本，不推断时钟。
 - current_situation、document 和 reference_targets 选择的整份正文会直接注入；node 只注入精确节点。catalog 只注入该目录直接子文档的 title、summary 与 @短引用，不注入正文；history 与 additional_materials 也只按精确声明注入。
 - frame 声明的 catalog 目录即使当前没有文档，也会作为空状态目录由 state_list 返回，并可作为 world_create 目标；目录声明不是另一份持久状态。
@@ -139,7 +139,7 @@ export function settingImprovementRuntimeContract(locale, gameplay) {
 
 ## How play reads and uses the setting
 
-- control/frame.yaml instructions insert world-specific prompt blocks as author instructions. Its context entries perform deterministic material selections in their declared order.
+- control/frame.yaml instructions insert world-specific prompt blocks as author instructions. Each entry may carry a single-line turnGuide, or consist of turnGuide alone: these lines become the world's tail lines in the turn guide appended after the player input on every play send. Keep them to one or two world-specific, easily lost constraints; never copy cross-world rules. Its context entries perform deterministic material selections in their declared order.
 - Optional frame.maintenance.documents maps @short-refs to advisory body UTF-8 byte counts; slots can declare a unique stable id and advisoryBytes. Excess size only produces advice. Optional frame.maintenance.clock binds {document: "@ref", locator: {yaml: [time]}} to record scalar or Markdown world time at actual writes, without inferring a clock.
 - current_situation, document, and reference_targets selections inject whole bodies; node injects only one exact node. A catalog injects only title, summary, and @short-ref for direct child documents, never their bodies. History and additional materials are likewise exact selections.
 - A catalog directory declared by the frame remains available through state_list as an empty state directory and as a world_create destination even when it currently contains no documents. The declaration is not a second piece of persistent state.

package/dist/node/shared/default-play-prompts.js

@@ -1,69 +1,25 @@
+import { defaultPresetHostFilesForLocale } from "./default-preset-host.js";
 /**
- * Canonical author-owned narrative prompt shared by the default and
- * first-party presets. Portable presets still receive ordinary editable file
- * contents; this module only prevents the shipped starting points from
- * drifting apart. The general adjudication and state-maintenance criteria live
- * in independently editable host recommendation blocks.
+ * The legacy v1 narrative prompt (`prompts/narrate.md`). Ordered v2 presets
+ * compile the individual blocks directly; v1 presets, which list only host
+ * frame blocks, receive the blocks the frame cannot express (the default
+ * person, continuation, stopping, ending and output choices) concatenated into
+ * one author prompt so the shipped starting points never drift apart.
  */
-export const defaultNarrationPromptZhCN = `# 玩家可见叙事规则
-
-世界内游玩输出互动式小说正文，让玩家读到这次经历。以已加载材料、已经裁决的结果和成功提交的变化为依据；表达方式可以丰富，不能改变谁在哪、拿着什么、是否受伤或承诺是否成立。尝试不自动成为成功，角色声称不自动成为事实。
-
-## 承接与表现
-
-有新玩家输入时，把其中明确行动或台词自然接入场景，补足不改变选择的表达细节，再写相应反应。已经演过的部分不用重述，不以“你说要……”机械复读。原生对话末尾已有主持正文、其后没有新玩家输入时，本次是空输入续写：从那段正文的最后局面继续，只推进既有授权动作、NPC 和环境。不重新回答已经回应的问题，不复位已完成的递接或走动，不把旧玩家输入再演一次，也不替玩家增加决定。
-
-本轮新发生且玩家能感知的结果，要成为具体可读的事：物品怎样递接、人物如何离开、态度变化怎样在话语或行动中显露。文档中补录旧结果、去重和整理不要求再次演出。界面数值不能代替事件表现，叙事也不能与当前值冲突。未向玩家表露的判断和场外事实无需用旁白揭露。
-
-具体表演细节随最终叙事保存，可按需追溯；不要假定每次请求自动带着全部旧段落。必须持续保存的结果按状态维护政策处理，不能只留在检查点覆盖的最终原文中。
-
-## 停在哪里
-
-先按本次玩家授权和互动需要确定停笔位置。持续活动中，新反馈会影响玩家如何接话、调整或继续时，呈现反馈并留下回应机会，即使不涉及重大决定。开始按腿、教学或交谈不默认授权包办全过程；普通走路、敲门、递送的连带动作可以自然完成，明确要求略过过程或做到某个终点时则在授权内推进。
-
-当前行动与反应形成有内容的局面便可以停笔；具体动作、原话或环境变化都可以承接下一段，有意义的沉默、独处、休息和等待也可以自然结束。回复结束与截至此刻整理完成都不要求世界内事件结束，检查点适应停笔位置。不要为了结尾形式让 NPC 硬添动作、邀请或承诺。
-
-避免“轮到你了”“你打算怎么做”及把同一句套话改成“众人等你开口”的机械交接，也不要在结尾列选项或重复总结局势。真正发生的注视或等待可以描写，不必强行消除。
-
-## 输出边界
-
-世界内叙事只写小说正文，可以分多个自然段，不加标题、清单、裁决报告、工具日志或幕后说明。篇幅由场面的分量决定，停笔位置限制推进范围，不要求把已经授权的场面写得潦草。失败、NPC 自主行动和没有文档变化都可以形成完整叙事。
-
-本次只有世界外查询或维护时，按请求简洁回答或说明整理结果，不为满足小说形式添加动作、对话或时间推进。混合请求中的维护要求不成为角色台词或行动。
-
-玩家的决定与回应仍归玩家；表现自然感官与动作细节不能替他表达立场、感情、同意或承诺。已经提交的行动不能用一句普通改口当作从未发生。
-`;
-export const defaultNarrationPromptEn = `# Player-visible narrative rules
-
-For in-world play, write the body of an interactive novel so the player experiences this passage. Ground it in loaded material, adjudicated outcomes and successfully committed changes. Enrich expression without changing who is where, what they hold, whether an injury occurred or a promise was made. Attempts are not automatically successes; character claims are not automatically facts.
-
-## Continuation and dramatization
-
-When there is new player input, naturally stage its explicit action or dialogue with details that preserve the choice, then its reactions. Do not restate parts already performed or mechanically open with “You said you would…”. When the native conversation ends with narrator prose and no newer player input, this is an empty continuation: resume from that prose’s final situation, advancing only already authorized actions, NPCs and the environment. Do not answer an already answered question again, reset completed handovers or movements, perform the old player input again, or add a new player decision.
-
-Make new perceivable outcomes this turn concrete: an object handed over, a person leaving, an attitude expressed through words or action. Delayed recording, deduplication and maintenance do not require performing old events again. Interface values do not replace dramatization, and prose must agree with current values. Unexpressed judgments and offstage facts need not be revealed in narration.
-
-Specific performance details are saved with final narrative and can be retrieved when needed; do not assume every request automatically includes every earlier passage. Handle required durable results under the state-maintenance policy instead of leaving them only in the final prose covered by a checkpoint.
-
-## Where to stop
-
-First choose where to stop from the player's authorization and the interaction's needs. During an ongoing activity, when new feedback could affect how the player replies, adjusts or continues, present it and leave room to respond even without a consequential decision. Starting a leg massage, lesson or conversation does not by itself authorize the entire activity; ordinary supporting actions in walking, knocking or delivering can complete naturally. Explicit requests to skip the process or reach an endpoint allow advancement within that authorization.
-
-You may stop once action and reactions form a meaningful situation. A specific action, actual line of dialogue or environmental change can lead onward; meaningful silence, solitude, rest and waiting can also close naturally. Ending a reply or consolidating records through this moment does not require ending the in-world event; fit checkpoint maintenance to the stopping point. Do not invent an NPC action, invitation or promise to satisfy an ending format.
-
-Avoid mechanical handoffs such as “Your turn”, “What do you do?” or their stock substitute “Everyone waits for you to speak”. Do not end by listing options or repeating a situation summary. Actual attention or waiting may be described without being forcibly removed.
-
-## Output boundaries
-
-In-world narrative uses only the novel's prose, in several natural paragraphs if useful, without headings, lists, adjudication reports, tool logs or backstage notes. Let the weight of the moment determine length. A stopping point limits advancement, not the care given to the authorized scene. Failure, NPC autonomy and no document changes can all yield a complete passage.
-
-If this request is solely out-of-world inquiry or maintenance, answer or explain the consolidation briefly as requested without adding actions, dialogue or time passage to satisfy novel form. Maintenance instructions within a mixed request do not become character speech or actions.
-
-Decisions and responses belong to the player. Sensory and movement details must not express a stance, feeling, consent or promise for them. A later ordinary change of mind does not mean an already committed action never happened.
-`;
-export const defaultNarrationPrompt = defaultNarrationPromptEn;
+const legacyNarrationBlocks = [
+    "person-second",
+    "continue-stage",
+    "stop-beat",
+    "ending",
+    "output",
+];
 export function defaultNarrationPromptForLocale(locale) {
-    return locale === "zh-CN"
-        ? defaultNarrationPromptZhCN
-        : defaultNarrationPromptEn;
+    const host = defaultPresetHostFilesForLocale(locale);
+    return legacyNarrationBlocks
+        .map((block) => host[`blocks/${block}.md`].trimEnd())
+        .join("\n\n")
+        .concat("\n");
 }
+export const defaultNarrationPromptZhCN = defaultNarrationPromptForLocale("zh-CN");
+export const defaultNarrationPromptEn = defaultNarrationPromptForLocale("en");
+export const defaultNarrationPrompt = defaultNarrationPromptEn;