narraeon 0.5.5 → 0.5.7

package/dist/node/runtime/world/WorldActivity.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { FileNativeAuthorityV3 } from "./FileNativeAuthorityV3.js";
+import { fileNativeHistoryMessageIdFromProjectionPath } from "./FileNativeHistoryProjection.js";
+/** Read only the small head/cache on a hit; repair misses from the local projection. */
+export async function readWorldActivity(root, serializeRebuild = (rebuild) => rebuild()) {
+    const head = await currentHead(root);
+    const cached = await readCache(root);
+    if (cached?.head === head)
+        return cached;
+    return serializeRebuild(async () => {
+        const latestHead = await currentHead(root);
+        const latestCache = await readCache(root);
+        if (latestCache?.head === latestHead)
+            return latestCache;
+        const empty = {
+            schemaVersion: 1,
+            head: latestHead,
+            lastActivityAt: null,
+            excerpt: null,
+            playerTurns: 0,
+        };
+        // An accepted endpoint may still be awaiting recovery. Never label its old
+        // materialized history as a valid cache for the new endpoint.
+        const materialized = await readJson(join(root, "runtime/materialized-head.json"));
+        if (!isRecord(materialized) || materialized.head !== latestHead)
+            return empty;
+        const entries = await readdir(join(root, "history"), {
+            withFileTypes: true,
+        });
+        const messages = entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => ({
+            path: entry.name,
+            id: fileNativeHistoryMessageIdFromProjectionPath(entry.name),
+        }))
+            .filter((message) => message.id !== null)
+            .sort((left, right) => {
+            const a = left.path.split("-");
+            const b = right.path.split("-");
+            return Number(a[0]) - Number(b[0]) || Number(a[1]) - Number(b[1]);
+        });
+        const narrator = messages.findLast(({ id }) => id.endsWith(".narrator"));
+        const activity = {
+            ...empty,
+            excerpt: narrator === undefined
+                ? null
+                : excerpt(await readFile(join(root, "history", narrator.path), "utf8")),
+            playerTurns: messages.filter(({ id }) => id.endsWith(".player")).length,
+        };
+        await publishCache(root, activity);
+        return activity;
+    });
+}
+/** Best effort: activity is never part of accepting or recovering Authority. */
+export async function updateWorldActivity(root, head, history, lastActivityAt) {
+    const narrator = history.findLast(({ role }) => role === "narrator");
+    // Recovery cannot reconstruct a clock time, but can retain a matching cache.
+    const previous = lastActivityAt === null ? await readCache(root) : null;
+    await publishCache(root, {
+        schemaVersion: 1,
+        head,
+        lastActivityAt: lastActivityAt ??
+            (previous?.head === head ? previous.lastActivityAt : null),
+        excerpt: narrator === undefined ? null : excerpt(narrator.exactText),
+        playerTurns: history.filter(({ role }) => role === "player").length,
+    });
+}
+function excerpt(text) {
+    const singleLine = text.replace(/[\r\n\u2028\u2029]+/gu, " ").trim();
+    return singleLine === ""
+        ? null
+        : Array.from(singleLine).slice(0, 80).join("");
+}
+async function currentHead(root) {
+    try {
+        return (await new FileNativeAuthorityV3(root).readHead()).head;
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        // Listing a released layout must not trigger an Authority migration/replay.
+        const checkpoint = await readJson(join(root, "runtime/materialized-head.json"));
+        return isRecord(checkpoint) && typeof checkpoint.head === "string"
+            ? checkpoint.head
+            : "genesis";
+    }
+}
+async function readCache(root) {
+    const value = await readJson(join(root, "runtime/activity.json")).catch(() => null);
+    return isRecord(value) &&
+        Object.keys(value).length === 5 &&
+        value.schemaVersion === 1 &&
+        typeof value.head === "string" &&
+        /^(?:genesis|commit:[1-9][0-9]*)$/u.test(value.head) &&
+        (value.lastActivityAt === null ||
+            (typeof value.lastActivityAt === "number" &&
+                Number.isSafeInteger(value.lastActivityAt) &&
+                value.lastActivityAt >= 0 &&
+                Number.isFinite(new Date(value.lastActivityAt).valueOf()))) &&
+        (value.excerpt === null ||
+            (typeof value.excerpt === "string" &&
+                Array.from(value.excerpt).length <= 80 &&
+                !/[\r\n\u2028\u2029]/u.test(value.excerpt))) &&
+        typeof value.playerTurns === "number" &&
+        Number.isSafeInteger(value.playerTurns) &&
+        value.playerTurns >= 0
+        ? value
+        : null;
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isMissing(error) || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function publishCache(root, activity) {
+    const path = join(root, "runtime/activity.json");
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(activity)}\n`, {
+            mode: 0o600,
+        });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        console.warn("Could not write world activity cache", root, error);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/node/runtime/world/WorldYamlRendering.js

@@ -0,0 +1,28 @@
+import { stringify } from "yaml";
+/** Shared public YAML rendering; references keep their handle without expansion. */
+export function renderWorldYamlSource(value, options = {}) {
+    return stringify(publicValue(value), {
+        indent: 2,
+        lineWidth: 0,
+        ...options,
+    }).trimEnd();
+}
+function publicValue(value) {
+    if (Array.isArray(value))
+        return value.map(publicValue);
+    if (record(value)) {
+        if (Object.keys(value).length === 2 &&
+            typeof value.$ref === "string" &&
+            record(value.target) &&
+            typeof value.target.shortRef === "string")
+            return { $ref: `@${value.target.shortRef}` };
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, publicValue(child)]));
+    }
+    return value;
+}
+function record(value) {
+    return (value !== undefined &&
+        value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value));
+}

package/dist/node/server/createServer.js

@@ -6,6 +6,7 @@ import fastifyStatic from "@fastify/static";
 import Fastify, { LogController, } from "fastify";
 import { maxPortableContentArchiveBase64Characters } from "../protocol/contentTree.js";
 import { parseV1Envelope, V1ProtocolError, v1Protocol, } from "../protocol/v1.js";
+import { WorldArchiveError } from "../runtime/archive/WorldArchiveZip.js";
 const runtimeRequestBodyLimit = maxPortableContentArchiveBase64Characters + 64 * 1024;
 const playCallChainStreamContentType = "application/x-ndjson";
 class RuntimeLogController extends LogController {
@@ -81,6 +82,53 @@ export async function createServer(input) {
         done(null, payload);
     });
     registerConversationStream(server, input.runtime);
+    // Keep uploads as a backpressured stream with their own archive-size limit.
+    // Fastify's JSON parser and content-package body limit never buffer this route.
+    await server.register((archives, _options, done) => {
+        archives.addContentTypeParser("application/zip", (_request, payload, done) => done(null, payload));
+        archives.post("/api/runtime/v1/world-archives", async (request, reply) => {
+            try {
+                return await input.runtime.worldArchives.upload(request.body);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(error.code === "limit_exceeded" ? 413 : 400)
+                        .send({ error: { code: error.code, message: error.message } });
+                throw error;
+            }
+        });
+        archives.get("/api/runtime/v1/world-archives/:archiveId", async (request, reply) => {
+            try {
+                const archive = await input.runtime.worldArchives.download(request.params.archiveId);
+                reply.raw.once("finish", () => {
+                    void archive.cleanup().catch(() => undefined);
+                });
+                return reply
+                    .type("application/zip")
+                    .header("Content-Length", archive.metadata.bytes)
+                    .header("Content-Disposition", `attachment; filename="world.narraeon-world.zip"; filename*=UTF-8''${encodeURIComponent(archive.metadata.fileName)}`)
+                    .send(archive.stream);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(400)
+                        .send({ error: { code: error.code, message: error.message } });
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return reply.status(404).send({
+                        error: {
+                            code: "invalid_archive",
+                            message: "The archive download is unavailable",
+                        },
+                    });
+                throw error;
+            }
+        });
+        done();
+    });
     server.get("/health", () => ({
         status: "ok",
         protocol: "narraeon.runtime/v1",

package/dist/node/shared/default-preset-host.js

@@ -234,15 +234,20 @@ NPC 可以按性格、认知、处境和目标继续做事、与别人交谈、
 
 summary 是目录简介，用于识别文档和判断是否需要读取。只写简短的身份、主题或稳定线索，不复述具体状态和事件经过；具体事实放在正文。仅在识别信息改变时更新标题与简介。
 
-## 保存时机与整理检查点
+## 保存时机、整理与检查点
 
 先按玩家授权与互动需要确定本轮叙事范围和停笔位置，再保存该范围内的事实。保存进行中活动的实际进展、必要原话和待回应事项即可整理截至此刻的状态，不把尚未发生的完成结果提前写入。
 
 1. 玩家视图实际绑定的当前值改变，本轮终态叙事前写回。等待、赶路、休息或跨日后按世界粒度更新对应现值；绑定标记只说明界面读取范围。
-2. 需要保存但玩家原文和最终叙事没有记录的信息，当轮保存，包括重要场外进展、未表露的认知和隐蔽后果。工具中间文本不能替代持久记录。
-3. 其余可从玩家原文和最终叙事恢复的持续结果，允许事件收尾或合适的中间整理点归并。
+2. 当前情境已采用顶层 \`背景\` 时，时间、地点等定位值发生变化应在最终叙事提交前写回该节点，避免在其他情境字段维护同一现值的第二份。没有该字段的世界不必创建，未变化不必写入，仅维护记录不授权推进剧情。
+3. 需要保存但玩家原文和最终叙事没有记录的信息，当轮保存，包括重要场外进展、未表露的认知和隐蔽后果。工具中间文本不能替代持久记录。
+4. 其余可从玩家原文和最终叙事恢复的持续结果，允许事件收尾或合适的中间整理点归并。
 
-按已确定的叙事范围完成本轮必须保存的写入。只有本轮选择登记检查点时，才核对上次检查点后的交互和本轮范围内的结果，补齐必要记录，更新认知、进程、约定和界面值，结束实际已失效的待办并清理重复。整理可以停在活动中途；准备好该停笔位置的记录后登记检查点，再输出最终叙事。检查点覆盖该叙事，若其中又增加重要结果，继续工具调用补齐。正常回复无需登记检查点，登记回执也不是语义完整性认证。
+按已确定的叙事范围完成本轮必须保存的写入。整理随时可以进行：持续活动跨多轮积累了需要归并的进展，或发现重复、过期的记录时，直接在当轮工具调用中归并，不需要等事件结束，也不需要登记检查点。整理不等于检查点。只有零散即时变化时，按上述保存时机继续互动。
+
+world_checkpoint 只用于事件之间的间隙：上一事件已在本轮停笔位置自然告一段落，或场景已实际转换，接下来从全新上下文开始也不会丢失仍然重要的细节。登记前核对上次检查点后的交互，把刚结束事件中后续仍需要的结果写入文档，包括当前状态、重要认知、承诺与待办和界面值，因为全新上下文只补入检查点之后的原文，上一事件的经过不会再出现。持续活动中途、对方刚给出需要玩家回应的反馈，或仍有待玩家决定的事项时，不登记检查点。此前已写回的事实核对后沿用，无需重复写入。登记后输出最终叙事；若叙事又增加重要结果，继续工具调用补齐。登记回执不是语义完整性认证。
+
+检查点只标记已经出现的间隙，不是本轮要达成的目标。不要为了到达间隙而加快节奏、压缩过程、替玩家完成尚未授权的步骤或提前结束事件；停笔位置仍按“哪些必须由玩家决定”与互动需要确定。一个事件持续很多轮、跨越多次回复都是正常的，期间不需要登记检查点。
 
 ## 整理与连续性
 
@@ -489,15 +494,20 @@ Prefer natural owners for durable information. Create a separate document for in
 
 summary is a catalog description for identifying a document and deciding whether to read it. Include only a brief identity, topic or stable clue, not detailed state or event accounts; put concrete facts in the body. Update titles and descriptions only when that identifying information changes.
 
-## Save timing and consolidation checkpoints
+## Save timing, consolidation and checkpoints
 
 First choose this turn's narrative scope and stopping point from player authorization and interaction needs, then save facts within that scope. Recording actual progress in an ongoing activity, necessary exact wording and matters awaiting a response can complete maintenance through this moment without writing unrealized completion outcomes in advance.
 
 1. Write changed current values actually selected by player views before this turn's final narrative. After waiting, travel, rest or a day change, update those values at the world's granularity; binding annotations describe read locations only.
-2. Save needed information absent from player originals and final narrative during this turn, including important offstage progress, unexpressed knowledge and hidden consequences. Intermediate tool text is not a durable substitute.
-3. Other durable outcomes recoverable from player originals and final narrative may be consolidated at event closure or a suitable intermediate point.
+2. If the current situation already uses the exact top-level \`背景\` field, write changed time, location or other positioning values there before final narrative submission; avoid maintaining a second current copy elsewhere in that situation. Worlds without the field need not create it, unchanged values need no write, and record maintenance does not authorize story advancement.
+3. Save needed information absent from player originals and final narrative during this turn, including important offstage progress, unexpressed knowledge and hidden consequences. Intermediate tool text is not a durable substitute.
+4. Other durable outcomes recoverable from player originals and final narrative may be consolidated at event closure or a suitable intermediate point.
+
+Complete required writes within the chosen narrative scope. Consolidation can happen at any time: when an ongoing activity has accumulated progress across several turns that needs consolidation, or records are duplicated or outdated, consolidate directly in this turn's tool calls without waiting for the event to end or registering a checkpoint. Consolidation is not a checkpoint. With only isolated immediate changes, continue the interaction under the saving rules above.
+
+Use world_checkpoint only for gaps between events: the previous event has naturally settled at this turn's stopping point, or the scene has actually changed, and starting a fresh context next would not lose still-important details. Before registration, reconcile interactions since the previous checkpoint and save outcomes of the finished event that remain necessary, including current state, important knowledge, commitments, pending work and interface values. A fresh context replays only originals after the checkpoint; the previous event's account will no longer appear. Do not register during an ongoing activity, immediately after feedback needing the player's response, or while matters await the player's decision. Reuse already saved facts after checking them, without duplicate writes. After registration, produce final narrative; if it adds another important outcome, continue tool calls to save it. Registration is not certification of semantic completeness.
 
-Complete required writes within the chosen narrative scope. Only if you choose to register a checkpoint this turn, reconcile interactions since the previous checkpoint and outcomes within this turn's scope: fill necessary records, update knowledge, processes, commitments and interface values, close actually expired pending work and remove duplicates. Maintenance can stop during an activity; prepare records for that stopping point, register the checkpoint, then produce final narrative. The checkpoint covers that narrative; if it adds another important outcome, continue tool calls to save it. A normal reply needs no checkpoint, and registration is not certification of semantic completeness.
+A checkpoint marks a gap that has already appeared, not a goal for this turn. Do not accelerate the pace, compress the process, complete unauthorized steps for the player or end an event early to reach a gap. Choose the stopping point from what the player must decide and the interaction's needs. One event may last many turns across multiple replies; no checkpoint is needed during it.
 
 ## Maintenance and continuity
 

package/dist/node/shared/default-setting-improvement-prompt.js

@@ -27,6 +27,8 @@ export const defaultSettingImprovementPromptZhCN = `# 系统推荐的创作方
 
 这些区别适用于物品、伤病、地点、组织、交易、调查与人物关系，不要求固定目录、字段或数量。独立引用、自身状态或生命周期需要独立文档；小规模信息可集中在合适载体中。当前情境只承接眼前地点、在场者、进行中的事及待回应事项，不承担全部历史或未来分支。
 
+当前情境的受限 YAML 可选用精确顶层「背景」保存简短定位值，例如「背景: {时间: 青历三年六月初八，夜间, 地点: 南门客栈}」。Runtime 会将该节点的完整值随已提交叙事保存，用于解释旧原文的“明天”“这里”；缺失、null、空白字符串、空映射或空数组不采集，0 和 false 保留。字段内部不设固定 schema，在场名单、待办和长局面留在其他字段；采用后在背景中维护对应现值，避免同一时间地点的第二份现值。无需为未采用的既有内容创建或搬迁字段；运行中修订不会改写旧历史背景。
+
 summary 是目录简介：只写识别文档所需的简短身份、主题或稳定线索，不复述具体状态和事件经过。具体事实放在正文，仅在识别信息改变时更新标题与简介。
 
 ## 承载与发现一起安排
@@ -65,6 +67,8 @@ Keep important event accounts in one place, using independently referenceable ev
 
 These distinctions apply to objects, injuries, places, organizations, trades, investigations and personal relationships without fixed directories, fields or counts. Independent reference, evolving state or lifecycle tracking warrants a separate document; smaller records may share a suitable home. The current situation holds the immediate location, people present, ongoing matters and unanswered requests, not all history or future branches.
 
+Restricted YAML current situations may optionally use the exact top-level field 背景 for brief positioning values, for example \`背景: {时间: night on day eight, 地点: South Gate Inn}\`. Runtime saves the complete node with committed narrative to interpret old references to tomorrow or here; missing, null, blank strings and empty maps/lists are unrecorded, while 0 and false survive. Its contents have no fixed schema. Keep attendance, pending matters and long situations elsewhere; when adopted, maintain corresponding current values in this node without a second copy. Do not create or relocate fields in existing content merely to adopt this convention. Running-world revisions never rewrite saved historical backgrounds.
+
 summary is a catalog description: include only a brief identity, topic or stable clue needed to identify the document, not detailed state or event accounts. Concrete facts belong in the body. Update titles and descriptions only when identifying information changes.
 
 ## Arrange storage and discovery together

package/dist/node/shared/history-use-guidance.js

@@ -1,6 +1,6 @@
 /** Mechanical reading guidance shared by production prompts and tool help. */
 export function historyUseGuidance(locale, legacy = false) {
     return locale === "zh-CN"
-        ? `已有对话或注入原文足够接续时，不例行检索或重读。缺失信息会影响人物行为、重要承诺、因果或玩家选择时才检索${legacy ? "；仅使用本会话冻结的旧工具定义与参数定位及读取最近原文" : "；缺少最近上下文可直接 history_read {latest:4}"}。不记得原词时提出少量候选词，${legacy ? "用已声明旧历史搜索的单个 query 做字面搜索" : "用 history_search queries 的 any/all 字面搜索"}，命中后按需完整读前后文${legacy ? "" : "；all 限于同一消息"}。零命中不证明事件未发生，可改词、${legacy ? "扩大字面范围或读相邻上下文" : "放宽 all 为 any 或读相邻上下文"}。原文已足以判断时停止，不为穷尽分页而检索；重要矛盾可继续追查。玩家原文可能只是行动尝试、意图或主张，结果须结合后续叙事；主持原文也可能包含角色谎言、猜测、梦境或回忆，role=narrator 不证明事实已确认。过去持有不代表现在持有，明确当前世界修订优先于旧叙事。主持读到的信息不自动成为场内角色的知识。注入历史是已发生材料，不是本轮新请求，不能重复执行最后一条历史玩家行动。读取完整原文可能很大，参考原文长度并按需小步扩展；无需固定 list→search→read 流程。`
-        : `Do not routinely search or reread when conversation or injected originals already suffice. Retrieve only when missing details affect behavior, important promises, causality or player choices${legacy ? "; use only this session's frozen legacy tool definitions and arguments to locate and read recent originals" : "; missing recent context can be read directly with history_read {latest:4}"}. When exact wording is unknown, propose a few candidate terms and ${legacy ? "use the declared legacy literal search with a single query" : "use history_search queries with any/all"}, then read surrounding originals as needed${legacy ? "" : "; all applies within one message"}. Zero literal matches do not prove an event never happened: change terms, ${legacy ? "widen the literal scope or read nearby context" : "relax all to any or read nearby context"}. Stop once originals support the decision, without exhausting pages; important contradictions may warrant further investigation. Player originals may be attempts, intentions or claims; check subsequent narrative for outcomes. Narrator originals may contain character lies, guesses, dreams or memories; role=narrator does not confirm truth. Past possession is not current possession; explicit current world corrections take precedence. Host information does not automatically become in-scene character knowledge. Injected history is already committed material, not the current request; never repeat a final historical player action. Full originals can be large: use length information and expand in small windows. No fixed list→search→read ritual is required.`;
+        ? `已有对话或注入原文足够接续时，不例行检索或重读。缺失信息会影响人物行为、重要承诺、因果或玩家选择时才检索${legacy ? "；仅使用本会话冻结的旧工具定义与参数定位及读取最近原文" : "；缺少最近上下文可直接 history_read {latest:4}"}。不记得原词时提出少量候选词，${legacy ? "用已声明旧历史搜索的单个 query 做字面搜索" : "用 history_search queries 的 any/all 字面搜索"}，命中后按需完整读前后文${legacy ? "" : "；all 限于同一消息"}。零命中不证明事件未发生，可改词、${legacy ? "扩大字面范围或读相邻上下文" : "放宽 all 为 any 或读相邻上下文"}。原文已足以判断时停止，不为穷尽分页而检索；重要矛盾可继续追查。玩家原文可能只是行动尝试、意图或主张，结果须结合后续叙事；主持原文也可能包含角色谎言、猜测、梦境或回忆，role=narrator 不证明事实已确认。历史背景保存的是采集位置的情境，不是当前世界状态，也不认证整段每句话的发生时间；推进前后标记结合原文中的回忆、梦境和局部时间解释。背景在原文边界之外，搜索只匹配原文。过去持有不代表现在持有，明确当前世界修订优先于旧叙事。主持读到的信息不自动成为场内角色的知识。注入历史是已发生材料，不是本轮新请求，不能重复执行最后一条历史玩家行动。读取完整原文可能很大，参考原文长度并按需小步扩展；无需固定 list→search→read 流程。`
+        : `Do not routinely search or reread when conversation or injected originals already suffice. Retrieve only when missing details affect behavior, important promises, causality or player choices${legacy ? "; use only this session's frozen legacy tool definitions and arguments to locate and read recent originals" : "; missing recent context can be read directly with history_read {latest:4}"}. When exact wording is unknown, propose a few candidate terms and ${legacy ? "use the declared legacy literal search with a single query" : "use history_search queries with any/all"}, then read surrounding originals as needed${legacy ? "" : "; all applies within one message"}. Zero literal matches do not prove an event never happened: change terms, ${legacy ? "widen the literal scope or read nearby context" : "relax all to any or read nearby context"}. Stop once originals support the decision, without exhausting pages; important contradictions may warrant further investigation. Player originals may be attempts, intentions or claims; check subsequent narrative for outcomes. Narrator originals may contain character lies, guesses, dreams or memories; role=narrator does not confirm truth. Historical background records the captured situation, not current world state or the time of every sentence; interpret before/after annotations alongside memories, dreams and local times in the original. Background stays outside original-text boundaries and literal searches match only originals. Past possession is not current possession; explicit current world corrections take precedence. Host information does not automatically become in-scene character knowledge. Injected history is already committed material, not the current request; never repeat a final historical player action. Full originals can be large: use length information and expand in small windows. No fixed list→search→read ritual is required.`;
 }

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

@@ -22,7 +22,7 @@ export function builtinPlayPrompts(locale) {
 
 world_patch 的 YAML locator 可以包含 map key 和从零开始的数组下标；remove 删除一个精确位置。未提供的元数据保持原值。world_retire 从目录注入中退役文档，文档仍可读取、引用和恢复。工具响应的成功状态变化与后续最终叙事分别提交，后续失败不回滚已提交变化。成功写入回执表示当前值已改变；以真实回执的结算状态为准，模型文字不能提交世界。
 
-包含工具调用的响应属于中间步，其中的文字尚未展示或提交为最终叙事。收到全部工具结果后，根据回执在最终正文中呈现本轮尚未展示的内容，并与已提交状态一致；没有工具调用的非空正文结束本次循环并由 Runtime 提交。world_checkpoint 仅登记整理声明与历史重放边界，在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。正常回复无需检查点，登记不结束世界内事件，也不自动切换上下文，玩家自行选择。全新上下文补入边界后的已提交玩家原文与最终叙事，排除开场白、工具和推理。
+包含工具调用的响应属于中间步，其中的文字尚未展示或提交为最终叙事。收到全部工具结果后，根据回执在最终正文中呈现本轮尚未展示的内容，并与已提交状态一致；没有工具调用的非空正文结束本次循环并由 Runtime 提交。world_checkpoint 只在事件间隙登记，表示建议从此开始全新上下文，并作为历史重放边界；整理本身不需要登记。在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。登记不结束世界内事件，也不自动切换上下文，玩家自行选择。全新上下文补入边界后的已提交玩家原文与最终叙事，排除开场白、工具和推理。
 
 ${historyUseGuidance(locale)}`
                 : `# Tools and response settlement
@@ -31,7 +31,7 @@ Use only attached tools. Directories use @dir-* handles from the preload or tool
 
 YAML world_patch locators accept map keys and zero-based array indexes; remove deletes one exact location. Omitted metadata remains unchanged. world_retire removes a document from catalog injection while keeping it readable, referenceable and restorable. Successful tool-response state changes and later final narrative commit separately; later failure does not roll back committed changes. Successful write receipts change current values; the actual receipt determines settlement, not model prose.
 
-Responses containing tool calls are intermediate steps; their text has not yet been displayed or committed as final narrative. After all tool results, use the receipts to present this turn's still-unshown content in final prose consistent with committed state. A nonempty tool-free response ends this loop and Runtime commits it. world_checkpoint only registers a consolidation declaration and history-replay boundary; it takes effect after the subsequent nonempty tool-free final prose successfully commits, including that prose. Further tool calls may follow registration. Normal replies need no checkpoint; registration neither ends an in-world event nor switches context, which the player chooses. Fresh-context replay contains committed player originals and final narratives after the boundary, excluding the opening, tools and reasoning.
+Responses containing tool calls are intermediate steps; their text has not yet been displayed or committed as final narrative. After all tool results, use the receipts to present this turn's still-unshown content in final prose consistent with committed state. A nonempty tool-free response ends this loop and Runtime commits it. world_checkpoint registers only at gaps between events, suggesting a fresh context from that point and defining the history-replay boundary; consolidation itself does not require registration. It takes effect after the subsequent nonempty tool-free final prose successfully commits, including that prose. Further tool calls may follow registration. Registration neither ends an in-world event nor switches context, which the player chooses. Fresh-context replay contains committed player originals and final narratives after the boundary, excluding the opening, tools and reasoning.
 
 ${historyUseGuidance(locale)}`,
         },

package/dist/node/shared/sample-packages/index.js

@@ -0,0 +1,10 @@
+import { rainyInnEnglish } from "./rainy-inn-en.js";
+import { rainyInnChinese } from "./rainy-inn-zh.js";
+/** Each caller receives an ordinary, independent content-tree seed. */
+export function sampleContentPackageForLocale(locale) {
+    const sample = locale === "zh-CN" ? rainyInnChinese : rainyInnEnglish;
+    return {
+        title: sample.title,
+        files: sample.files.map((file) => ({ ...file })),
+    };
+}

package/dist/node/shared/sample-packages/rainy-inn-en.js

@@ -0,0 +1,194 @@
+export const rainyInnEnglish = {
+    title: "A Letter at the Rain Lantern Inn",
+    files: [
+        {
+            path: "opening.md",
+            contents: `Rain patters from the inn's eaves. The little brass bell above you is still swaying, and the lobby smells of ginger tea. A lamp casts a warm circle across the wooden counter.
+
+Behind it, a woman in a green apron lifts an empty blue saucer, checks underneath, and sets it down again. “Well, it hasn't grown legs.”
+
+A guest in a grey cardigan looks up from the window table. “A pale blue envelope. It's for my sister, and I haven't sealed it yet.” Beside the counter, a young postal runner pauses with a damp ledger tucked against his chest.
+
+The woman offers you a dry towel. “Welcome in. We're having a small mystery with a letter. Would you mind lending us a fresh pair of eyes?” The counter, umbrella stand, and window table are all within the lamplight. She waits for your answer.
+`,
+        },
+        {
+            path: "world/current-situation.yaml",
+            contents: `$document:
+  id: situation.rainy-inn
+  ref: current-situation
+  title: An empty saucer in the lamplight
+  summary: A small search in the Rain Lantern Inn's lobby.
+  aliases: []
+背景:
+  Time: An autumn evening, nine o'clock, steady rain
+  Place: Rain Lantern Inn lobby, Brookbridge
+Present:
+  - $ref: character.nora
+  - $ref: character.evelyn
+  - $ref: character.kit
+In progress:
+  Letter search: Evelyn's pale blue envelope is no longer on the counter's blue saucer. Nobody has begun a methodical search of the lobby.
+Awaiting a response:
+  Speaker: { $ref: character.nora }
+  Invitation: Welcome in. We're having a small mystery with a letter. Would you mind lending us a fresh pair of eyes?
+Immediate circumstances:
+  - You have just arrived at the doorway. Nora's offered towel has not been taken.
+  - Kit holds the ledger and has paused wiping its damp corner.
+`,
+        },
+        {
+            path: "world/characters/nora.yaml",
+            contents: `$document:
+  id: character.nora
+  ref: nora
+  title: Nora
+  summary: The Rain Lantern's attentive innkeeper, quick to offer practical kindness.
+  aliases: []
+Appearance: Short hair, soft features, a dusting of flour on one cuff.
+Clothing: A cream shirt, forest-green apron, and soft indoor shoes.
+Temperament: Patient; looks for a remedy before laying blame.
+Relationships:
+  Evelyn:
+    Person: { $ref: character.evelyn }
+    View: A familiar guest whose plant stories brighten the lobby; hopes she can rest without worrying tonight.
+  Kit:
+    Person: { $ref: character.kit }
+    View: A neighbour's helpful son, sometimes distracted; willing to hear him out when something goes wrong.
+Knowledge:
+  Letter: Remembers putting Evelyn's envelope on the blue saucer, then leaving to make tea. Did not watch the counter after that.
+  Basis: { $ref: event.letter-entrusted }
+`,
+        },
+        {
+            path: "world/characters/evelyn.yaml",
+            contents: `$document:
+  id: character.evelyn
+  ref: evelyn
+  title: Evelyn
+  summary: A travelling botanical illustrator who shares discoveries in letters.
+  aliases: []
+Appearance: Round glasses and a faint smudge of graphite on her fingertips.
+Clothing: A grey cardigan and navy trousers; her brown rain cape hangs by the umbrellas.
+Temperament: Observant and deliberate; double-checks small details when worried.
+Relationships:
+  Nora:
+    Person: { $ref: character.nora }
+    View: A trusted innkeeper; the missing letter has not made her suspect deliberate concealment.
+  Kit:
+    Person: { $ref: character.kit }
+    View: Met him this evening; trusts his postal expertise but knows little about his habits.
+Important belongings:
+  Letter for her sister: An unsealed pale blue envelope containing a page of news and a hand-drawn leaf study, intended for tomorrow's post.
+Knowledge:
+  Letter: Knows she entrusted it to Nora and now sees an empty saucer; does not know where it went afterward.
+  Basis: { $ref: event.letter-entrusted }
+`,
+        },
+        {
+            path: "world/characters/kit.yaml",
+            contents: `$document:
+  id: character.kit
+  ref: kit
+  title: Kit
+  summary: Brookbridge's young postal runner, always willing to help a neighbour.
+  aliases: []
+Appearance: Rain-flattened hair and a small dimple when he smiles.
+Clothing: An unbuttoned blue raincoat, striped shirt, and canvas shoes with wet toes.
+Temperament: Eager and easily distracted; owns up to mistakes and tries to put them right.
+Relationships:
+  Nora:
+    Person: { $ref: character.nora }
+    View: A neighbour he has known since childhood; trusts her and wants to be useful.
+  Evelyn:
+    Person: { $ref: character.evelyn }
+    View: A new acquaintance with intriguing drawings; hopes to ask about the leaves she sketches.
+Knowledge:
+  Remembered action: Moved a pale blue envelope to make room for his wet ledger, slipping it inside the back cover. Assumed the envelope was empty.
+  Current understanding: Has not caught what Evelyn is looking for or connected her letter with the envelope he moved.
+Belongings:
+  Ledger: Held against his chest; a corner of the back cover is damp.
+`,
+        },
+        {
+            path: "world/locations/rain-lantern-inn.yaml",
+            contents: `$document:
+  id: location.rain-lantern-inn
+  ref: rain-lantern-inn
+  title: Rain Lantern Inn
+  summary: A small inn by Brookbridge's bridge, where neighbours shelter over tea.
+  aliases: []
+Lobby: A wooden counter faces the entrance, with a blue saucer and brass lamp on top. A small table stands by the window; the umbrellas rest beside the door.
+Daily life: Guests can rest over ginger tea; the innkeeper sometimes holds letters for familiar visitors until morning.
+`,
+        },
+        {
+            path: "world/events/letter-entrusted.yaml",
+            contents: `$document:
+  id: event.letter-entrusted
+  ref: letter-entrusted
+  title: A letter left for safekeeping
+  summary: Evelyn's earlier arrangement with Nora to keep a letter at the counter.
+  aliases: []
+When: About half an hour earlier this evening
+Account: Evelyn gave Nora an unsealed pale blue envelope, explaining that it held a letter and leaf drawing for her sister. Nora put it on the blue saucer while Evelyn watched.
+Words: Evelyn said, “I'll seal it in the morning. Could you keep it here until then?” Nora agreed.
+Source: Both Evelyn and Nora were at the counter.
+`,
+        },
+        {
+            path: "control/frame.yaml",
+            contents: `format: narraeon.world-frame/v1
+bindings:
+  currentSituation: "@current-situation"
+instructions:
+  - markdown: blocks/world.md
+context:
+  - slot: { kind: catalog, directory: characters, maxEntries: 3 }
+  - slot: { kind: catalog, directory: locations, maxEntries: 4 }
+  - slot: { kind: catalog, directory: events, maxEntries: 12 }
+  - slot: { kind: document, document: "@rain-lantern-inn" }
+  - slot:
+      kind: reference_targets
+      from:
+        document: "@current-situation"
+        locator: { yaml: [Present] }
+      maxEntries: 3
+  - slot: { kind: current_situation }
+  - slot: { kind: additional_materials }
+`,
+        },
+        {
+            path: "control/blocks/world.md",
+            contents: `<!-- opening.md is the visible opening; world/current-situation.yaml holds the background and pending response; characters/ holds each person's state, relationships, and knowledge; locations/ describes places; events/ records shared past events; frame.yaml selects play material; player-views.yaml selects status values. Adapt these files to write your own story. -->
+
+# Genre and boundaries
+
+Focus on small-town inn life, conversation, and gentle mysteries arising from objects, memories, and misunderstandings. Keep the tone warm and suitable for all ages, without violence, adult content, or life-threatening conspiracies. Sharing a letter's private contents is up to its writer and recipient.
+
+## Documents and where changes belong
+
+Keep relationships, opinions, and knowledge in each person's own world/characters/ document, without a shared truth or secret field. Record events that need shared reference in world/events/; link to the account rather than copying it into each character. Lasting changes to places belong in world/locations/. Keep the letter among its owner's important belongings until independent transfer tracking warrants a separate document.
+`,
+        },
+        {
+            path: "control/player-views.yaml",
+            contents: `format: narraeon.player-views/v1
+views:
+  - id: scene-status
+    title: Right now
+    items:
+      - id: time
+        label: Time
+        select:
+          document: "@current-situation"
+          locator: { yaml: [背景, Time] }
+      - id: place
+        label: Place
+        select:
+          document: "@current-situation"
+          locator: { yaml: [背景, Place] }
+`,
+        },
+    ],
+};