narraeon 0.7.7 → 0.7.10

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { renderWorldMaintenanceReport } from "../prompt/WorldMaintenanceReport.js";
 import { listWorldDocuments as listQueryableWorldDocuments } from "../prompt/WorldMaintenanceReport.js";
@@ -98,7 +99,7 @@ export function settingImprovementRuntimeContract(locale, gameplay) {
 - 当前请求随附八个读写工具。不调用工具的完整响应会作为普通助手消息显示，并结束本次用户调用。含有工具调用的响应是内部工具步骤；收到全部工具结果后继续处理，最终用一个不调用工具的完整响应答复用户。
 - 工具写入直接修改内容包当前树。每个完整 Provider 工具响应中的调用按顺序执行，成功改动在该响应结算时原子发布，发布后立即成为内容包权威，无需另一步确认。
 - 每个写工具调用独立结算，并按本响应中的调用顺序读取之前已接受的结果。某个调用失败只在对应工具结果中返回精确原因，不回滚同一响应内其他成功调用，也不阻止后续调用。Runtime 在写调用结算后自动运行内容树检查和真实 Prompt Preview，并把检查结果附在最后一个成功写调用的结果中。
-- 修改既有文件前必须完整读取它。setting_list／setting_search 的 cursor，以及 setting_read 的读取授权，只属于产生它们的当前树 revision；任何其他对话或手动编辑改变当前树后，必须重新读取再写。setting_read 总是完整返回精确文件，不截断、不分页。工具只暴露逻辑路径，不暴露宿主路径。
+- 修改既有文件前必须完整读取它。setting_search 的 cursor，以及 setting_read 的读取授权，只属于产生它们的当前树 revision；任何其他对话或手动编辑改变当前树后，必须重新读取再写。setting_read 总是完整返回精确文件，不截断、不分页。工具只暴露逻辑路径，不暴露宿主路径。
 - world/ 下只写 .yaml 或 .md 世界文档；专用文件只允许 opening.md、control/frame.yaml、control/player-views.yaml${gameplayFileZh(tabletop)}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。人物、地点、规则与当前情境放在 world/，本世界特有的主持要求放在 control/。
 - opening.md 是玩家看见的第一页，不得替玩家决定行动、台词或内心。会继续约束首次行动的事实也必须写入自然承载它的世界文档。
 - 新建 world 文档使用 setting_create：ref 由你提供，并同时提供路径、标题、摘要、别名与不含技术头的正文。ref 必须是唯一的 2～32 位小写 ASCII 短句柄；Runtime 自行完成技术存储。既有文档选择值会在读取时自动投影为对应的 @ref；跨文档引用和 control 中的文档选择只使用 @ref。
@@ -134,7 +135,7 @@ export function settingImprovementRuntimeContract(locale, gameplay) {
 - The current request includes eight read/write tools. A complete response with no tool calls is shown as an ordinary assistant message and settles this user invocation. A response containing tool calls is an internal tool step; continue after all results and eventually answer with a complete tool-free response.
 - Tool writes directly modify the content package's current tree. Calls in one complete Provider tool response execute in order; its successful changes publish atomically when that response settles, immediately become authoritative, and require no second confirmation.
 - Every write tool call settles independently and sees earlier accepted calls in response order. A failure returns its precise cause only in that call's result, does not roll back successful siblings, and does not stop later calls. Runtime automatically runs content-tree checks and a real Prompt Preview after writes and appends that review to the last successful write result.
-- Read an existing file completely before changing it. Cursors from setting_list and setting_search, and read authorization from setting_read, belong only to the current-tree revision that produced them. setting_read always returns the complete exact file without truncation or pagination. Re-read after another conversation or a manual edit changes the current tree. Tools expose logical paths, never host paths.
+- Read an existing file completely before changing it. Cursors from setting_search, and read authorization from setting_read, belong only to the current-tree revision that produced them. setting_read always returns the complete exact file without truncation or pagination. Re-read after another conversation or a manual edit changes the current tree. Tools expose logical paths, never host paths.
 - World documents are .yaml or .md files under world/. Special writes are limited to opening.md, control/frame.yaml, control/player-views.yaml${gameplayFileEn(tabletop)}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. Put characters, places, rules, and the current situation under world/, and world-specific hosting guidance under control/.
 - opening.md is the first page shown to the player. Never decide the player's action, dialogue, or inner thoughts. Facts that constrain the first action must also live in the world document that naturally owns them.
 - Create a world document with setting_create. You provide its unique 2-to-32-character lowercase ASCII ref, path, title, summary, aliases, and body without a technical header; Runtime completes the technical storage. Existing document selectors are automatically projected to their @refs when read. Cross-document references and control selectors use only @refs.
@@ -191,8 +192,6 @@ export function authoringToolDefinitions(surface, locale, gameplay) {
                     type: "string",
                     pattern: `^${surface.root}(?:/[^\\\\]+)?$`,
                 },
-                limit,
-                cursor,
             }, []),
         },
         {
@@ -283,42 +282,42 @@ export function authoringToolDefinitions(surface, locale, gameplay) {
     ];
 }
 const toolDescriptionsEn = (tabletop) => ({
-    list: "List the world root or a world/ subdirectory from the content package's current tree. The root also lists opening and control files. A cursor is valid only for the same query and current-tree revision.",
+    list: "List the world root or a world/ subdirectory from the content package's current tree. The root also lists opening and control files. Each call returns the whole directory.",
     search: "Search literal source text in world documents in the content package's current tree. within may be world, a world/ directory or path, or @ref.",
     read: "Read a complete world document by world/ path or @ref, or read a complete opening/control file by exact path. Existing document selectors are projected to @refs. The result is never truncated or paginated.",
     create: "Create one world/ .yaml or .md document. Supply a unique lowercase ASCII ref, title, summary, aliases, and body without a technical header; Runtime completes the storage envelope. The created document is already fully read.",
-    write_file: `Replace a completely read world/ .yaml or .md document body while preserving its identity and metadata, or create/replace opening.md, control/frame.yaml, control/player-views.yaml, ${tabletop ? "control/blocks/*.md, or control/gameplay.json (only a tabletop resolution scheme may change)" : "or control/blocks/*.md"}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. To repair a damaged world document, also provide ref, title, summary, and aliases; Runtime preserves any recoverable storage identity. Create new world documents with setting_create.`,
-    patch: 'Update a completely read YAML world document without rewriting unrelated content. locator is a non-empty path whose segments are map keys or zero-based array indexes. Use add for a missing map key or array index, replace for an existing node, append for the end of an existing array, and remove for an existing map key or array item. When title, summary, or aliases are stale, update all three together with op "set_metadata". Rewrite Markdown bodies with setting_write_file.',
+    write_file: `Replace a completely read world/ .yaml or .md document body while preserving its identity and metadata, or create/replace opening.md, control/frame.yaml, control/player-views.yaml, ${tabletop ? "control/blocks/*.md, or control/gameplay.json (only a tabletop resolution scheme may change)" : "or control/blocks/*.md"}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. path may also be an @ref. On a valid document, title, summary, and aliases may be given in the same write to update metadata (any subset; omitted fields are kept), but ref never changes. To repair a damaged world document, provide ref, title, summary, and aliases together; Runtime preserves any recoverable storage identity. Create new world documents with setting_create.`,
+    patch: 'Update a completely read YAML world document without rewriting unrelated content. locator is a non-empty path whose segments are map keys or zero-based array indexes. Use add for a missing map key or array index, replace for an existing node, append for the end of an existing array, and remove for an existing map key or array item. To update title, summary, or aliases, use op "set_metadata" with only the fields that change; omitted fields are kept. Rewrite Markdown bodies with setting_write_file.',
     move: "Move a completely read world document to a new world/ .yaml or .md logical path while preserving its identity and contents.",
     delete: "Permanently delete a completely read world document from the content-package current tree. Runtime rejects deletion while currentSituation, a frame slot, a player-view selector, or another document's $ref still points to it, and reports every blocking location. Delete or redirect those references first.",
 });
 const toolDescriptionsZhCN = (tabletop) => ({
-    list: "列出内容包当前树的 world 根目录或 world/ 子目录；根目录同时列出 opening 和 control 专用文件。cursor 只对同一查询和当前树 revision 有效。",
+    list: "列出内容包当前树的 world 根目录或 world/ 子目录；根目录同时列出 opening 和 control 专用文件，每次整份返回。",
     search: "在内容包当前树的 world 文档中按原文字面搜索；within 可为 world、world/ 目录或路径或 @ref。",
     read: "按 world/ 路径或 @ref 完整读取世界文档，或按精确路径完整读取 opening/control；既有文档选择值自动投影为 @ref。结果不会截断或分页。",
     create: "创建一份 world/ 下的 .yaml 或 .md 文档；提供唯一的小写 ASCII ref、标题、摘要、别名和不含技术头的正文，Runtime 自行完成存储封装。创建成功的文档视为已经完整读取。",
-    write_file: `整份替换已完整读取的 world/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md${tabletop ? "、control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）" : ""}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 setting_create。`,
-    patch: '细粒度更新已完整读取的 YAML 世界文档，不重写无关内容。locator 是非空路径，每段可以是 map key 或从 0 开始的数组下标；add 新建 map key 或数组位置，replace 更新既有节点，append 追加既有数组，remove 删除既有 map key 或数组项。title、summary 或 aliases 过时时用 op "set_metadata" 整组更新三项。Markdown 正文用 setting_write_file 整份重写。',
+    write_file: `整份替换已完整读取的 world/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md${tabletop ? "、control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）" : ""}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。path 也可以是 @ref。有效文档可在同一次写入中提供 title、summary、aliases 的任意子集更新元信息，未提供的保持不变，但 ref 不能改。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 setting_create。`,
+    patch: '细粒度更新已完整读取的 YAML 世界文档，不重写无关内容。locator 是非空路径，每段可以是 map key 或从 0 开始的数组下标；add 新建 map key 或数组位置，replace 更新既有节点，append 追加既有数组，remove 删除既有 map key 或数组项。需要更新 title、summary 或 aliases 时用 op "set_metadata"，只提供要改变的字段，未提供的保持不变。Markdown 正文用 setting_write_file 整份重写。',
     move: "把已完整读取的世界文档移动到新的 world/ .yaml 或 .md 逻辑路径，并保留身份与内容。",
     delete: "从内容包当前树永久删除一份已完整读取的 world 文档。若 currentSituation、frame slot、player-view selector 或其他文档的 $ref 仍指向它，Runtime 会拒绝并返回全部精确阻挡位置；请先删除或改向这些引用。",
 });
 const worldRevisionDescriptionsEn = (tabletop) => ({
-    list: "List the state root or a state/ subdirectory from the world revision worktree. The root also lists control files. A cursor is valid only for the same query and worktree revision.",
+    list: "List the state root or a state/ subdirectory from the world revision worktree. The root also lists control files. Each call returns the whole directory.",
     search: "Search literal source text in world documents in the world revision worktree. within may be state, a state/ directory or path, or @ref.",
     read: "Read a complete world document by state/ path or @ref, or read a complete control file by exact path. Existing document selectors are projected to @refs. The result is never truncated or paginated.",
     create: "Create one state/ .yaml or .md document. Supply a unique lowercase ASCII ref, title, summary, aliases, and body without a technical header; Runtime completes the storage envelope. The created document is already fully read.",
-    write_file: `Replace a completely read state/ .yaml or .md document body while preserving its identity and metadata, or create/replace control/frame.yaml, control/player-views.yaml, ${tabletop ? "control/blocks/*.md, or control/gameplay.json (only a tabletop resolution scheme may change)" : "or control/blocks/*.md"}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. To repair a damaged world document, also provide ref, title, summary, and aliases; Runtime preserves any recoverable storage identity. Create new world documents with world_revision_create.`,
-    patch: 'Update a completely read YAML world document without rewriting unrelated content. locator is a non-empty path whose segments are map keys or zero-based array indexes. Use add for a missing map key or array index, replace for an existing node, append for the end of an existing array, and remove for an existing map key or array item. When title, summary, or aliases are stale, update all three together with op "set_metadata". Rewrite Markdown bodies with world_revision_write_file.',
+    write_file: `Replace a completely read state/ .yaml or .md document body while preserving its identity and metadata, or create/replace control/frame.yaml, control/player-views.yaml, ${tabletop ? "control/blocks/*.md, or control/gameplay.json (only a tabletop resolution scheme may change)" : "or control/blocks/*.md"}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. path may also be an @ref. On a valid document, title, summary, and aliases may be given in the same write to update metadata (any subset; omitted fields are kept), but ref never changes. To repair a damaged world document, provide ref, title, summary, and aliases together; Runtime preserves any recoverable storage identity. Create new world documents with world_revision_create.`,
+    patch: 'Update a completely read YAML world document without rewriting unrelated content. locator is a non-empty path whose segments are map keys or zero-based array indexes. Use add for a missing map key or array index, replace for an existing node, append for the end of an existing array, and remove for an existing map key or array item. To update title, summary, or aliases, use op "set_metadata" with only the fields that change; omitted fields are kept. Rewrite Markdown bodies with world_revision_write_file.',
     move: "Move a completely read world document to a new state/ .yaml or .md logical path while preserving its identity and contents.",
     delete: "Permanently delete a completely read world document from the world revision worktree. Runtime rejects deletion while currentSituation, a frame slot, a player-view selector, or another document's $ref still points to it, and reports every blocking location. Delete or redirect those references first.",
 });
 const worldRevisionDescriptionsZhCN = (tabletop) => ({
-    list: "列出世界修订工作树的 state 根目录或 state/ 子目录；根目录同时列出 control 文件。cursor 只对同一查询和工作树 revision 有效。",
+    list: "列出世界修订工作树的 state 根目录或 state/ 子目录；根目录同时列出 control 文件，每次整份返回。",
     search: "在世界修订工作树的 state 文档中按原文字面搜索；within 可为 state、state/ 目录或路径或 @ref。",
     read: "按 state/ 路径或 @ref 完整读取世界文档，或按精确路径完整读取 control 文件；既有文档选择值自动投影为 @ref。结果不会截断或分页。",
     create: "创建一份 state/ 下的 .yaml 或 .md 文档；提供唯一的小写 ASCII ref、标题、摘要、别名和不含技术头的正文，Runtime 自行完成存储封装。创建成功的文档视为已经完整读取。",
-    write_file: `整份替换已完整读取的 state/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 control/frame.yaml、control/player-views.yaml、control/blocks/*.md${tabletop ? "、control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）" : ""}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 world_revision_create。`,
-    patch: '细粒度更新已完整读取的 YAML 世界文档，不重写无关内容。locator 是非空路径，每段可以是 map key 或从 0 开始的数组下标；add 新建 map key 或数组位置，replace 更新既有节点，append 追加既有数组，remove 删除既有 map key 或数组项。title、summary 或 aliases 过时时用 op "set_metadata" 整组更新三项。Markdown 正文用 world_revision_write_file 整份重写。',
+    write_file: `整份替换已完整读取的 state/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 control/frame.yaml、control/player-views.yaml、control/blocks/*.md${tabletop ? "、control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）" : ""}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。path 也可以是 @ref。有效文档可在同一次写入中提供 title、summary、aliases 的任意子集更新元信息，未提供的保持不变，但 ref 不能改。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 world_revision_create。`,
+    patch: '细粒度更新已完整读取的 YAML 世界文档，不重写无关内容。locator 是非空路径，每段可以是 map key 或从 0 开始的数组下标；add 新建 map key 或数组位置，replace 更新既有节点，append 追加既有数组，remove 删除既有 map key 或数组项。需要更新 title、summary 或 aliases 时用 op "set_metadata"，只提供要改变的字段，未提供的保持不变。Markdown 正文用 world_revision_write_file 整份重写。',
     move: "把已完整读取的世界文档移动到新的 state/ .yaml 或 .md 逻辑路径，并保留身份与内容。",
     delete: "从世界修订工作树永久删除一份已完整读取的 world 文档。若 currentSituation、frame slot、player-view selector 或其他文档的 $ref 仍指向它，Runtime 会拒绝并返回全部精确阻挡位置；请先删除或改向这些引用。",
 });
@@ -397,6 +396,7 @@ export class SettingAuthoringTransaction {
     #surface;
     #preview;
     #validateFiles;
+    #additionalToolNames;
     #snapshot;
     #reads;
     #review;
@@ -406,6 +406,7 @@ export class SettingAuthoringTransaction {
         this.#surface = input.surface ?? contentPackageAuthoringSurface;
         this.#preview = input.preview;
         this.#validateFiles = input.validateFiles ?? (() => undefined);
+        this.#additionalToolNames = input.additionalToolNames ?? [];
         this.#snapshot = WorldDocumentStore.open({
             layout: this.#surface.layout,
             files: cloneFiles(input.baseFiles),
@@ -436,7 +437,7 @@ export class SettingAuthoringTransaction {
         };
     }
     execute(calls) {
-        const normalized = calls.map((call) => normalizeCall(call, this.#surface, this.#locale));
+        const normalized = calls.map((call) => normalizeCall(call, this.#surface, this.#locale, this.#additionalToolNames));
         const results = [];
         const responseBase = this.files();
         let lastSuccessfulWrite = -1;
@@ -518,9 +519,7 @@ export class SettingAuthoringTransaction {
                     ? requiredSettingRef(call.arguments.ref, this.#locale)
                     : null;
                 const revised = snapshot.revise({
-                    commands: [
-                        worldRevisionCommand(snapshot, call, this.#surface, this.#locale),
-                    ],
+                    commands: worldRevisionCommands(snapshot, call, this.#surface, this.#locale),
                 });
                 if (!revised.ok)
                     throw new SettingAuthoringError(renderRevisionFailure(revised.diagnostics, this.#surface, this.#locale));
@@ -667,16 +666,51 @@ function buildSettingAuthoringPlayCoverage(snapshot, preview, diff, surface) {
     }
     return {
         totals,
-        changed: diff.map(({ path, after }) => {
-            const access = changedPathPlayAccess(path, after, accessByPath, enabledWorldInstructionPaths);
+        changed: diff.map(({ path, before, after }) => {
+            const movedTo = after === null
+                ? movedDocumentPath(before, path, snapshot, surface)
+                : null;
+            const access = movedTo !== null
+                ? "moved"
+                : changedPathPlayAccess(path, after, accessByPath, enabledWorldInstructionPaths);
             return {
                 path,
                 access,
                 detail: playAccessDetail(access, surface),
+                ...(movedTo === null ? {} : { movedTo }),
             };
         }),
     };
 }
+/**
+ * A deleted-looking world document whose identity survives at another path
+ * was moved, not removed: the old path is reported with its new location.
+ */
+function movedDocumentPath(before, path, snapshot, surface) {
+    if (before === null)
+        return null;
+    const previous = WorldDocumentStore.open({
+        layout: surface.layout,
+        files: [{ path, contents: before }],
+    });
+    if (previous.status !== "usable")
+        return null;
+    const identity = previous.query({
+        kind: "read_document",
+        document: { logicalPath: path },
+    });
+    if (identity.kind !== "read_document" || !identity.ok)
+        return null;
+    const current = snapshot.query({
+        kind: "read_document",
+        document: { documentId: identity.scope.document.documentId },
+    });
+    if (current.kind !== "read_document" || !current.ok)
+        return null;
+    return current.scope.document.logicalPath === path
+        ? null
+        : current.scope.document.logicalPath;
+}
 function changedPathPlayAccess(path, after, accessByPath, enabledWorldInstructionPaths) {
     if (after === null)
         return "removed";
@@ -715,6 +749,7 @@ function playAccessDetail(access, surface) {
         play_control: "compiled as immutable play-author control",
         unused_control: "not enabled by control/frame.yaml and unavailable to ordinary play AI",
         player_view: "projected through exact player-view selectors",
+        moved: "its document identity continues at the new path",
         removed: `removed from ${surface.phrases.en.bareTree}`,
     };
     return details[access];
@@ -731,6 +766,7 @@ function renderPlayCoverage(coverage, surface, locale) {
             play_control: "游玩控制",
             unused_control: "未被 control/frame.yaml 启用",
             player_view: "玩家视图精确投影",
+            moved: "文档身份已延续到新路径",
             removed: `已从${surface.phrases["zh-CN"].tree}删除`,
         }
         : {
@@ -743,11 +779,16 @@ function renderPlayCoverage(coverage, surface, locale) {
             play_control: "play-author control",
             unused_control: "not enabled by control/frame.yaml",
             player_view: "exact player-view projection",
+            moved: "identity continues at the new path",
             removed: `removed from ${surface.phrases.en.bareTree}`,
         };
     const maximumReportedChanges = 64;
     const reportedChanges = coverage.changed.slice(0, maximumReportedChanges);
-    const changed = reportedChanges.map(({ path, access }) => `- ${path} — ${labels[access]}`);
+    const changed = reportedChanges.map(({ path, access, movedTo }) => {
+        if (access === "moved" && movedTo !== undefined)
+            return localized(locale, `- ${path} — moved to ${movedTo}`, `- ${path} — 已移动到 ${movedTo}`);
+        return `- ${path} — ${labels[access]}`;
+    });
     const onDemand = coverage.changed.filter(({ access }) => access === "on_demand");
     const unusedControl = coverage.changed.filter(({ access }) => access === "unused_control");
     return [
@@ -783,7 +824,7 @@ class SettingAuthoringError extends Error {
         this.name = "SettingAuthoringError";
     }
 }
-function normalizeCall(call, surface, locale) {
+function normalizeCall(call, surface, locale, additionalToolNames) {
     const cloned = isRecord(call.arguments)
         ? structuredClone(call.arguments)
         : {};
@@ -797,7 +838,7 @@ function normalizeCall(call, surface, locale) {
             operation: null,
             arguments: cloned,
             coerced: [],
-            rejection: unknownToolMessage(call.name, provided, locale),
+            rejection: unknownToolMessage(call.name, [...provided, ...additionalToolNames], locale),
         };
     const name = resolved.name;
     const schema = definitions.find((definition) => definition.name === name)?.inputSchema;
@@ -842,7 +883,51 @@ function isWorldWriteCall(call, surface) {
         return true;
     return (call.operation === "write_file" &&
         typeof call.arguments.path === "string" &&
-        call.arguments.path.startsWith(`${surface.root}/`));
+        (call.arguments.path.startsWith(`${surface.root}/`) ||
+            call.arguments.path.startsWith("@")));
+}
+/**
+ * A world write may need two revision commands: the body write, then a
+ * metadata patch for any title, summary or aliases given on a valid document.
+ * Both target the same logical path, so they apply in one revision.
+ */
+function worldRevisionCommands(snapshot, call, surface, locale) {
+    if (call.operation !== "write_file")
+        return [worldRevisionCommand(snapshot, call, surface, locale)];
+    const logicalPath = writeFileLogicalPath(snapshot, requiredString(call.arguments.path, "path"), surface, locale);
+    const request = worldWriteRequest(snapshot, logicalPath, call.arguments, surface, locale);
+    const write = {
+        kind: "write",
+        logicalPath,
+        contents: request.contents,
+    };
+    if (request.metadata === null)
+        return [write];
+    return [
+        write,
+        {
+            kind: "patch",
+            document: { logicalPath },
+            edits: [{ op: "set_metadata", ...request.metadata }],
+        },
+    ];
+}
+/** Resolves `@ref` write targets to their logical path; paths are checked as before. */
+function writeFileLogicalPath(snapshot, path, surface, locale) {
+    if (!path.startsWith("@"))
+        return safeWorldDocumentPath(path, surface, locale);
+    const selector = documentSelector(path, surface);
+    if (selector === null)
+        throw new SettingAuthoringError(localized(locale, `${authoringToolName(surface, "write_file")}.path must be an @ref or ${surface.root}/ document path`, `${authoringToolName(surface, "write_file")}.path 必须是 @ref 或 ${surface.root}/ 文档路径`));
+    const resolved = snapshot.query({
+        kind: "read_document",
+        document: selector,
+    });
+    if (resolved.kind === "error")
+        throw new SettingAuthoringError(localized(locale, `Unknown document ${path}`, `未知文档 ${path}`));
+    if (resolved.kind !== "read_document")
+        throw new Error("Unexpected world-document write lookup result");
+    return resolved.document.logicalPath;
 }
 function worldRevisionCommand(snapshot, call, surface, locale) {
     if (call.operation === "create") {
@@ -874,16 +959,6 @@ function worldRevisionCommand(snapshot, call, surface, locale) {
             body,
         };
     }
-    if (call.operation === "write_file") {
-        const logicalPath = safeWorldDocumentPath(requiredString(call.arguments.path, "path"), surface, locale);
-        const contents = worldWriteContents(snapshot, logicalPath, call.arguments, surface, locale);
-        assertNoLiteralUnicodeEscapes(contents, locale);
-        return {
-            kind: "write",
-            logicalPath,
-            contents,
-        };
-    }
     if (call.operation === "move") {
         const toLogicalPath = safePath(requiredString(call.arguments.to, "to"), surface);
         if (!documentPathPattern(surface).test(toLogicalPath))
@@ -895,20 +970,15 @@ function worldRevisionCommand(snapshot, call, surface, locale) {
         };
     }
     if (call.operation === "patch") {
-        const op = requiredString(call.arguments.op, "op");
+        const op = requiredPatchOp(call.arguments, surface);
         if (op === "set_metadata") {
-            const title = requiredString(call.arguments.title, "title");
-            const summary = requiredString(call.arguments.summary, "summary");
-            const aliases = requiredAliases(call.arguments.aliases);
-            assertNoLiteralUnicodeEscapes({ title, summary, aliases }, locale);
+            const metadata = metadataFields(call.arguments, surface, locale);
             return {
                 kind: "patch",
                 document: revisionTarget(requiredString(call.arguments.document, "document"), surface),
-                edits: [{ op: "set_metadata", title, summary, aliases }],
+                edits: [{ op: "set_metadata", ...metadata }],
             };
         }
-        if (op !== "add" && op !== "replace" && op !== "append" && op !== "remove")
-            throw new SettingAuthoringError(`${authoringToolName(surface, "patch")}.op must be add, replace, append, remove, or set_metadata`);
         const locator = requiredYamlLocatorPath(call.arguments.locator, "locator");
         if (op === "remove") {
             if (!hasOnly(call.arguments, ["document", "op", "locator"]))
@@ -951,29 +1021,59 @@ function safeWorldDocumentPath(path, surface, locale) {
         throw new SettingAuthoringError(localized(locale, `World files must be .yaml or .md documents below ${surface.root}/`, `world 文件必须是 ${surface.root}/ 下的 .yaml 或 .md 文档`));
     return logicalPath;
 }
-function worldWriteContents(snapshot, logicalPath, args, surface, locale) {
+/**
+ * Title, summary and aliases are public index metadata that AI may update on a
+ * valid document. Only the ones given are read, and at least one must be given.
+ */
+function metadataFields(args, surface, locale) {
+    const fields = {};
+    if (args.title !== undefined)
+        fields.title = requiredString(args.title, "title");
+    if (args.summary !== undefined)
+        fields.summary = requiredString(args.summary, "summary");
+    if (args.aliases !== undefined)
+        fields.aliases = requiredAliases(args.aliases);
+    if (Object.keys(fields).length === 0)
+        throw new SettingAuthoringError(localized(locale, `${authoringToolName(surface, "patch")} set_metadata needs at least one of title, summary, or aliases`, `${authoringToolName(surface, "patch")} set_metadata 至少需要 title、summary 或 aliases 之一`));
+    assertNoLiteralUnicodeEscapes(fields, locale);
+    return fields;
+}
+function worldWriteRequest(snapshot, logicalPath, args, surface, locale) {
     if (!hasOnly(args, ["path", "contents", "ref", "title", "summary", "aliases"]))
         throw new SettingAuthoringError(`${authoringToolName(surface, "write_file")} accepts only its declared arguments`);
     const body = requiredString(args.contents, "contents");
-    const metadataKeys = ["ref", "title", "summary", "aliases"];
-    const provided = metadataKeys.filter((key) => args[key] !== undefined);
     const existingFile = snapshot.files.some(({ path }) => path === logicalPath);
     const existingDocument = listQueryableWorldDocuments(snapshot).some(({ logicalPath: existingPath }) => existingPath === logicalPath);
+    const metadataGiven = ["title", "summary", "aliases"].some((key) => args[key] !== undefined);
+    if (existingDocument) {
+        if (args.ref !== undefined)
+            throw new SettingAuthoringError(localized(locale, `ref is the stable identity of a valid document and cannot change; omit ref, and use title, summary, or aliases to update its metadata`, `有效文档的 ref 是稳定身份，写入不能改变；请省略 ref，需要更新时只用 title、summary 或 aliases`));
+        return {
+            contents: body,
+            metadata: metadataGiven ? metadataFields(args, surface, locale) : null,
+        };
+    }
+    if (!existingFile) {
+        if (!metadataGiven && containsTechnicalDocumentHeader(logicalPath, body))
+            return { contents: body, metadata: null };
+        throw new SettingAuthoringError(localized(locale, `Create a new world document with ${authoringToolName(surface, "create")}`, `新建世界文档请使用 ${authoringToolName(surface, "create")}`));
+    }
+    return {
+        contents: worldRepairContents(snapshot, logicalPath, args, body, surface, locale),
+        metadata: null,
+    };
+}
+/** Damaged documents keep their body only with a complete ref, title, summary and aliases set. */
+function worldRepairContents(snapshot, logicalPath, args, body, surface, locale) {
+    const metadataKeys = ["ref", "title", "summary", "aliases"];
+    const provided = metadataKeys.filter((key) => args[key] !== undefined);
     if (provided.length === 0) {
-        if (!existingFile && !containsTechnicalDocumentHeader(logicalPath, body))
-            throw new SettingAuthoringError(localized(locale, `Create a new world document with ${authoringToolName(surface, "create")}`, `新建世界文档请使用 ${authoringToolName(surface, "create")}`));
-        if (existingFile &&
-            !existingDocument &&
-            !containsTechnicalDocumentHeader(logicalPath, body))
+        if (!containsTechnicalDocumentHeader(logicalPath, body))
             throw new SettingAuthoringError(localized(locale, "Repair a damaged document by providing ref, title, summary, and aliases with its body", "修复损坏文档时，请在正文之外同时提供 ref、title、summary 和 aliases"));
         return body;
     }
     if (provided.length !== metadataKeys.length)
         throw new SettingAuthoringError(localized(locale, "Repair metadata must provide ref, title, summary, and aliases together", "修复元信息时必须同时提供 ref、title、summary 和 aliases"));
-    if (!existingFile)
-        throw new SettingAuthoringError(localized(locale, `Create a new world document with ${authoringToolName(surface, "create")}`, `新建世界文档请使用 ${authoringToolName(surface, "create")}`));
-    if (existingDocument)
-        throw new SettingAuthoringError(localized(locale, `Repair metadata is only for a damaged document; update valid metadata with ${authoringToolName(surface, "patch")} set_metadata`, `修复元信息只用于损坏文档；有效文档请用 ${authoringToolName(surface, "patch")} set_metadata 更新元信息`));
     const ref = requiredSettingRef(args.ref, locale);
     const title = requiredString(args.title, "title");
     const summary = requiredString(args.summary, "summary");
@@ -1061,7 +1161,7 @@ function deleteWorldDocument(snapshot, call, reads, surface, locale) {
         markdown: localized(locale, `# Current-tree deletion accepted\n\nDeleted @${target.shortRef} · ${target.logicalPath}. No currentSituation binding, frame slot, player-view selector, or cross-document $ref points to it.`, `# 当前树删除已接受\n\n已删除 @${target.shortRef} · ${target.logicalPath}。没有 currentSituation、frame slot、player-view selector 或跨文档 $ref 指向它。`),
     };
 }
-function settingDocumentDeletionBlockers(snapshot, target) {
+export function settingDocumentDeletionBlockers(snapshot, target) {
     const blockers = [];
     for (const document of listQueryableWorldDocuments(snapshot)) {
         if (document.documentId === target.documentId || document.codec !== "yaml")
@@ -1134,13 +1234,13 @@ function deletionLocator(locator) {
         : `markdown:${JSON.stringify(locator.markdown)}`;
 }
 function writeOpaque(snapshot, call, reads, surface, locale) {
-    if (!hasOnly(call.arguments, ["path", "contents"]))
-        throw new SettingAuthoringError("Special-file writes accept only path and contents");
     const path = safePath(requiredString(call.arguments.path, "path"), surface);
     if (!writableOpaquePath(path, surface))
         throw new SettingAuthoringError(surface.opening
             ? localized(locale, "Special-file writes accept only opening.md, control/frame.yaml, control/player-views.yaml, control/blocks/*.md, or control/gameplay.json", "专用文件只允许写入 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md 或 control/gameplay.json")
             : localized(locale, "Special-file writes accept only control/frame.yaml, control/player-views.yaml, control/blocks/*.md, or control/gameplay.json", "专用文件只允许写入 control/frame.yaml、control/player-views.yaml、control/blocks/*.md 或 control/gameplay.json"));
+    if (!hasOnly(call.arguments, ["path", "contents"]))
+        throw new SettingAuthoringError("Special-file writes accept only path and contents");
     const authoredContents = requiredString(call.arguments.contents, "contents");
     assertNoLiteralUnicodeEscapes(authoredContents, locale);
     const contents = projectOpaqueDocumentIds(snapshot, path, authoredContents);
@@ -1166,7 +1266,7 @@ function writeOpaque(snapshot, call, reads, surface, locale) {
     return {
         snapshot: revised,
         markdown: [
-            localized(locale, `# Current-tree write accepted\n\n${existing === undefined ? "Created" : "Updated"} ${path} in ${surface.phrases.en.tree}. This file is already fully read; do not read it again unless a later decision needs Runtime's exact serialization.`, `# 当前树写入已接受\n\n已在${surface.phrases["zh-CN"].tree}中${existing === undefined ? "创建" : "更新"} ${path}。该文件已视为完整读取；除非后续判断依赖 Runtime 的精确序列化结果，否则不要再次读取。`),
+            localized(locale, `# Current-tree write accepted\n\n${existing === undefined ? "Created" : "Updated"} ${path} in ${surface.phrases.en.tree}.`, `# 当前树写入已接受\n\n已在${surface.phrases["zh-CN"].tree}中${existing === undefined ? "创建" : "更新"} ${path}。`),
             ...(gameplay === null
                 ? []
                 : [
@@ -1218,8 +1318,6 @@ function renderWorldWriteSuccess(changes, locale) {
                     return `- ${localized(locale, "Updated", "更新")} @${change.shortRef} · ${change.after.logicalPath}`;
                 return `- ${localized(locale, "Moved", "移动")} @${change.shortRef} · ${change.before.logicalPath} → ${change.after.logicalPath}`;
             })),
-        "",
-        localized(locale, "This call was accepted independently. Every created or changed document above is already fully read; do not read it again unless a later decision needs Runtime's exact serialization.", "本调用已独立接受。上方新建或修改的文档均视为已经完整读取；除非后续判断依赖 Runtime 的精确序列化结果，否则不要再次读取。"),
     ].join("\n");
 }
 function renderRevisionFailure(diagnostics, surface, locale) {
@@ -1230,41 +1328,43 @@ function renderRevisionFailure(diagnostics, surface, locale) {
 function listDocuments(snapshot, args, surface, locale) {
     const tool = authoringToolName(surface, "list");
     const root = surface.root;
+    // Frozen sessions may still send obsolete limit/cursor; directories are
+    // always listed in full, so those keys are accepted and ignored.
     if (!hasOnly(args, ["directory", "limit", "cursor"]))
-        return failure(`${tool} accepts only directory, limit, and cursor`, locale);
+        return failure(`${tool} accepts only directory`, locale);
     const directory = args.directory ?? root;
-    const limit = args.limit ?? 100;
     if (typeof directory !== "string" ||
-        (directory !== root && !directory.startsWith(`${root}/`)) ||
-        typeof limit !== "number" ||
-        !Number.isInteger(limit) ||
-        limit < 1 ||
-        limit > 100 ||
-        !validCursor(args.cursor))
-        return failure(`Invalid ${tool} directory, limit, or cursor`, locale);
+        (directory !== root && !directory.startsWith(`${root}/`)))
+        return failure(`Invalid ${tool} directory`, locale);
     const relative = directory === root ? "" : directory.slice(root.length + 1);
-    const result = snapshot.query({
-        kind: "catalog",
-        directory: relative,
-        limit,
-        ...(args.cursor === undefined ? {} : { cursor: args.cursor }),
-    });
-    if (result.kind === "error")
-        return renderQueryFailure(result, surface, locale);
-    if (result.kind !== "catalog")
-        throw new Error("Unexpected catalog result");
-    const entries = result.entries.map((entry) => {
-        if (entry.kind === "directory")
-            return `- [dir] ${entry.logicalPath}/`;
-        if (entry.document === undefined)
-            return `- [damaged] ${entry.logicalPath} · ${entry.diagnostics.map(({ code }) => code).join(", ")}`;
-        return `- @${entry.document.shortRef} · ${entry.document.title} · ${entry.logicalPath}`;
-    });
-    if (relative === "" && result.page.start === 0)
+    const entries = [];
+    let cursor = null;
+    do {
+        const result = snapshot.query({
+            kind: "catalog",
+            directory: relative,
+            limit: 100,
+            ...(cursor === null ? {} : { cursor }),
+        });
+        if (result.kind === "error")
+            return renderQueryFailure(result, surface, locale);
+        if (result.kind !== "catalog")
+            throw new Error("Unexpected catalog result");
+        entries.push(...result.entries.map(catalogEntryLine));
+        cursor = result.page.nextCursor;
+    } while (cursor !== null);
+    if (relative === "")
         entries.unshift(...snapshot.files
             .filter(({ path }) => !path.startsWith(`${root}/`))
             .map(({ path, encoding }) => encoding === undefined ? `- [special] ${path}` : `- [binary] ${path}`));
-    return success(`# ${localized(locale, surface.phrases.en.directoryHeading, surface.phrases["zh-CN"].directoryHeading)}\n\n${entries.join("\n") || localized(locale, "(empty)", "（空）")}\n\n${pageFooter(result.page, locale)}`);
+    return success(`# ${localized(locale, surface.phrases.en.directoryHeading, surface.phrases["zh-CN"].directoryHeading)}\n\n${entries.join("\n") || localized(locale, "(empty)", "（空）")}\n\nComplete: yes`);
+}
+function catalogEntryLine(entry) {
+    if (entry.kind === "directory")
+        return `- [dir] ${entry.logicalPath}/`;
+    if (entry.document === undefined)
+        return `- [damaged] ${entry.logicalPath} · ${entry.diagnostics.map(({ code }) => code).join(", ")}`;
+    return `- @${entry.document.shortRef} · ${entry.document.title} · ${entry.logicalPath}`;
 }
 function searchDocuments(snapshot, args, surface, locale) {
     const tool = authoringToolName(surface, "search");
@@ -1285,20 +1385,90 @@ function searchDocuments(snapshot, args, surface, locale) {
     const within = searchScope(args.within, surface);
     if (within === invalidScope)
         return failure(`Invalid ${tool} within scope`, locale);
-    const result = snapshot.query({
-        kind: "literal_search",
+    const matches = [];
+    let storeCursor = null;
+    let snapshotId;
+    do {
+        const result = snapshot.query({
+            kind: "literal_search",
+            query,
+            caseSensitive: args.caseSensitive === true,
+            ...(within === undefined ? {} : { within }),
+            limit: 100,
+            ...(storeCursor === null ? {} : { cursor: storeCursor }),
+        });
+        if (result.kind === "error")
+            return renderQueryFailure(result, surface, locale);
+        if (result.kind !== "literal_search")
+            throw new Error("Unexpected literal search result");
+        matches.push(...result.matches);
+        snapshotId = result.snapshotId;
+        storeCursor = result.page.nextCursor;
+    } while (storeCursor !== null);
+    // Pages count whole document lines so one line never spans two pages.
+    const groups = groupMatchesByLine(matches);
+    const scope = createHash("sha256")
+        .update(JSON.stringify({
         query,
         caseSensitive: args.caseSensitive === true,
-        ...(within === undefined ? {} : { within }),
+        within: within ?? null,
         limit,
-        ...(args.cursor === undefined ? {} : { cursor: args.cursor }),
-    });
-    if (result.kind === "error")
-        return renderQueryFailure(result, surface, locale);
-    if (result.kind !== "literal_search")
-        throw new Error("Unexpected literal search result");
-    const lines = result.matches.map(({ document, referenceProjection, range }) => `- @${document.shortRef} · ${document.logicalPath} · ${range.start.line}:${range.start.column}\n  ${JSON.stringify(referenceProjection.excerpt)}`);
-    return success(`# ${localized(locale, "Literal setting search", "设定字面搜索")}\n\n${lines.join("\n") || localized(locale, "Zero literal matches do not prove the fact is absent.", "0 个字面命中不证明设定中不存在该事实。")}\n\n${pageFooter(result.page, locale)}`);
+        snapshotId,
+    }))
+        .digest("base64url")
+        .slice(0, 22);
+    const offset = args.cursor === undefined ? 0 : decodeLineCursor(args.cursor, scope);
+    if (offset === null || offset > groups.length)
+        return failure(`Invalid ${tool} cursor`, locale);
+    const page = groups.slice(offset, offset + limit);
+    const end = offset + page.length;
+    const complete = end >= groups.length;
+    const lines = page.map(({ shortRef, line, columns, excerpt }) => `- @${shortRef} · ${line}:${columns.join(",")}\n  ${JSON.stringify(excerpt)}`);
+    return success(`# ${localized(locale, "Literal setting search", "设定字面搜索")}\n\n${lines.join("\n") || localized(locale, "Zero literal matches do not prove the fact is absent.", "0 个字面命中不证明设定中不存在该事实。")}\n\n${pageFooter({
+        start: offset,
+        end,
+        total: groups.length,
+        complete,
+        nextCursor: complete ? null : encodeLineCursor(scope, end),
+    }, locale)}`);
+}
+function encodeLineCursor(scope, offset) {
+    return Buffer.from(JSON.stringify({ scope, offset })).toString("base64url");
+}
+/** Returns the grouped-line offset, or null when the cursor is not for this scope. */
+function decodeLineCursor(cursor, scope) {
+    if (typeof cursor !== "string")
+        return null;
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!isRecord(decoded) || decoded.scope !== scope)
+            return null;
+        return typeof decoded.offset === "number" &&
+            Number.isInteger(decoded.offset) &&
+            decoded.offset >= 0
+            ? decoded.offset
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Hits on one line share a single entry; document order is preserved. */
+function groupMatchesByLine(matches) {
+    const groups = [];
+    for (const { document: { shortRef }, range: { start }, referenceProjection: { excerpt }, } of matches) {
+        const group = groups.at(-1);
+        if (group?.shortRef === shortRef && group.line === start.line)
+            group.columns.push(start.column);
+        else
+            groups.push({
+                shortRef,
+                line: start.line,
+                columns: [start.column],
+                excerpt,
+            });
+    }
+    return groups;
 }
 const invalidScope = Symbol("invalid-scope");
 function searchScope(value, surface) {
@@ -1332,7 +1502,7 @@ function readDocument(snapshot, args, reads, surface, locale) {
             return failure("Special files require one complete text read", locale);
         reads.opaquePaths.add(path);
         const projected = projectOpaqueDocumentIds(snapshot, path, opaque.contents);
-        return success(`# ${localized(locale, "Special-file source", "专用文件原文")} ${path}\n\n${projected}\n\n---\nComplete: yes`);
+        return success(`# ${localized(locale, "Special-file source", "专用文件原文")} ${path}\n\n${projected}`);
     }
     const selector = documentSelector(path, surface);
     if (selector === null)
@@ -1352,7 +1522,7 @@ function readDocument(snapshot, args, reads, surface, locale) {
     if (result.kind !== "read_document")
         throw new Error("Unexpected read result");
     reads.worldDocumentIds.add(result.document.documentId);
-    return success(`# ${localized(locale, "Exact read", "精确读取")} @${result.document.shortRef}\n\ntitle: ${result.document.title}\nsummary: ${result.document.summary}\ncodec: ${result.document.codec}\nlogicalPath: ${result.document.logicalPath}\n[body]\n${result.body.trimEnd()}\n[/body]\n\n---\nComplete: yes`);
+    return success(`# ${localized(locale, "Exact read", "精确读取")} @${result.document.shortRef}\n\ntitle: ${result.document.title}\nsummary: ${result.document.summary}\ncodec: ${result.document.codec}\nlogicalPath: ${result.document.logicalPath}\n[body]\n${result.body.trimEnd()}\n[/body]`);
 }
 function repairableDamagedWorldRead(snapshot, path, surface, result) {
     if (!path.startsWith(`${surface.root}/`) ||
@@ -1512,6 +1682,22 @@ function safePath(path, surface) {
         throw new SettingAuthoringError(`Unsafe ${surface.phrases.en.slug} path: ${path}`);
     return path;
 }
+const patchOps = [
+    "add",
+    "replace",
+    "append",
+    "remove",
+    "set_metadata",
+];
+function isPatchOp(value) {
+    return patchOps.includes(value);
+}
+function requiredPatchOp(args, surface) {
+    const op = args.op;
+    if (isPatchOp(op))
+        return op;
+    throw new SettingAuthoringError(`${authoringToolName(surface, "patch")} document ${JSON.stringify(args.document)} received op ${JSON.stringify(op)}; valid ops: ${patchOps.join(", ")}`);
+}
 function requiredString(value, name) {
     if (typeof value !== "string" || value.length === 0)
         throw new SettingAuthoringError(`${name} must be a non-empty string`);
@@ -1589,3 +1775,140 @@ function sortFiles(files) {
 function localized(locale, english, chinese) {
     return locale === "zh-CN" ? chinese : english;
 }
+/**
+ * Builds the complete-read preload for one bootstrap. Every document body goes
+ * through the same read path the model's read tool uses, so the text matches it
+ * byte for byte and the read authority is exactly what that path would grant.
+ */
+export function buildAuthoringPreload(input) {
+    const { snapshot, surface, locale, sourcePrefix } = input;
+    const reads = {
+        snapshotId: snapshot.id,
+        worldDocumentIds: new Set(),
+        damagedWorldPaths: new Set(),
+        opaquePaths: new Set(),
+    };
+    const blocks = [
+        {
+            source: `${sourcePrefix}/directory`,
+            markdown: preloadDirectory(snapshot, surface, locale),
+        },
+    ];
+    const controlPaths = snapshot.files
+        .map(({ path }) => path)
+        .filter(isPreloadControlPath)
+        .sort((left, right) => controlRank(left) - controlRank(right) || left.localeCompare(right));
+    for (const path of controlPaths) {
+        const result = readDocument(snapshot, { path }, reads, surface, locale);
+        if (result.ok)
+            blocks.push({
+                source: `${sourcePrefix}/${path}`,
+                markdown: result.markdown,
+            });
+    }
+    const seen = new Set();
+    for (const { shortRef, slot } of input.injected) {
+        if (seen.has(shortRef))
+            continue;
+        seen.add(shortRef);
+        const document = snapshot.query({
+            kind: "read_document",
+            document: { shortRef },
+            referenceProjection: "short_ref",
+        });
+        if (document.kind !== "read_document")
+            continue;
+        const result = readDocument(snapshot, { path: `@${shortRef}` }, reads, surface, locale);
+        if (!result.ok)
+            continue;
+        blocks.push({
+            source: `${sourcePrefix}/${document.document.logicalPath}`,
+            markdown: `${localized(locale, `Injected by slot ${slot}`, `由槽位 ${slot} 注入`)}\n\n${result.markdown}`,
+        });
+    }
+    if (input.injectedUnavailable !== undefined)
+        blocks.push({
+            source: `${sourcePrefix}/injected-unavailable`,
+            markdown: localized(locale, `# Injected documents unavailable\n\nThe play preview could not be built (${input.injectedUnavailable}), so documents injected by the world frame are not preloaded. Read them before writing.`, `# 注入文档不可用\n\n游玩预览无法生成（${input.injectedUnavailable}），因此未预载世界框架注入的文档。写入前请先读取它们。`),
+        });
+    blocks.push({
+        source: `${sourcePrefix}/runtime`,
+        markdown: localized(locale, `# Runtime preload note\n\nThe documents above are a snapshot of the worktree at revision ${input.revision}, taken when this request was sent.`, `# Runtime 预载说明\n\n以上内容是本次请求发出时工作树 revision ${input.revision} 的快照。`),
+    });
+    return {
+        blocks,
+        record: {
+            revision: input.revision,
+            worldDocumentIds: [...reads.worldDocumentIds].sort(),
+            opaquePaths: [...reads.opaquePaths].sort(),
+        },
+    };
+}
+/** Merges a preload's read authority into the authorization of the same revision. */
+export function authoringPreloadAuthorization(current, preload) {
+    const same = current?.revision === preload.revision;
+    return {
+        revision: preload.revision,
+        readWorldDocumentIds: sortedUnion(same ? current.readWorldDocumentIds : [], preload.worldDocumentIds),
+        readableDamagedWorldPaths: same
+            ? [...current.readableDamagedWorldPaths]
+            : [],
+        readOpaquePaths: sortedUnion(same ? current.readOpaquePaths : [], preload.opaquePaths),
+    };
+}
+function sortedUnion(left, right) {
+    return [...new Set([...left, ...right])].sort();
+}
+const preloadControlFiles = [
+    "control/frame.yaml",
+    "control/player-views.yaml",
+    "control/gameplay.json",
+    "control/followups.yaml",
+];
+function isPreloadControlPath(path) {
+    return (preloadControlFiles.includes(path) ||
+        /^control\/blocks\/[^/]+\.md$/u.test(path));
+}
+function controlRank(path) {
+    const index = preloadControlFiles.indexOf(path);
+    return index === -1 ? preloadControlFiles.length : index;
+}
+function preloadDirectory(snapshot, surface, locale) {
+    const entries = snapshot.files
+        .filter(({ path }) => !path.startsWith(`${surface.root}/`))
+        .map(({ path, encoding }) => encoding === undefined ? `- [special] ${path}` : `- [binary] ${path}`);
+    entries.push(...preloadCatalogLines(snapshot, surface.root, ""));
+    return `# ${localized(locale, surface.phrases.en.directoryHeading, surface.phrases["zh-CN"].directoryHeading)}\n\n${entries.join("\n") || localized(locale, "(empty)", "（空）")}\n\nComplete: yes`;
+}
+/**
+ * Depth-first walk of one directory: documents are listed in place, and each
+ * subdirectory is expanded. A subdirectory yields a `[dir]` line only when it
+ * holds nothing, since every non-empty listing produces at least one line.
+ */
+function preloadCatalogLines(snapshot, root, directory) {
+    const lines = [];
+    let cursor = null;
+    do {
+        const result = snapshot.query({
+            kind: "catalog",
+            directory,
+            limit: 100,
+            ...(cursor === null ? {} : { cursor }),
+        });
+        if (result.kind === "error")
+            throw new Error("The authoring directory could not be listed");
+        if (result.kind !== "catalog")
+            throw new Error("Unexpected catalog result");
+        for (const entry of result.entries) {
+            if (entry.kind === "document") {
+                lines.push(catalogEntryLine(entry));
+                continue;
+            }
+            const child = entry.logicalPath.slice(`${root}/`.length);
+            const childLines = preloadCatalogLines(snapshot, root, child);
+            lines.push(...(childLines.length === 0 ? [catalogEntryLine(entry)] : childLines));
+        }
+        cursor = result.page.nextCursor;
+    } while (cursor !== null);
+    return lines;
+}