narraeon 0.7.7 → 0.7.9

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,7 +282,7 @@ 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.",
@@ -293,7 +292,7 @@ const toolDescriptionsEn = (tabletop) => ({
     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 自行完成存储封装。创建成功的文档视为已经完整读取。",
@@ -303,7 +302,7 @@ const toolDescriptionsZhCN = (tabletop) => ({
     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.",
@@ -313,7 +312,7 @@ const worldRevisionDescriptionsEn = (tabletop) => ({
     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 自行完成存储封装。创建成功的文档视为已经完整读取。",
@@ -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;
@@ -667,16 +668,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 +751,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 +768,7 @@ function renderPlayCoverage(coverage, surface, locale) {
             play_control: "游玩控制",
             unused_control: "未被 control/frame.yaml 启用",
             player_view: "玩家视图精确投影",
+            moved: "文档身份已延续到新路径",
             removed: `已从${surface.phrases["zh-CN"].tree}删除`,
         }
         : {
@@ -743,11 +781,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 +826,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 +840,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;
@@ -895,7 +938,7 @@ 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");
@@ -907,8 +950,6 @@ function worldRevisionCommand(snapshot, call, surface, locale) {
                 edits: [{ op: "set_metadata", title, summary, aliases }],
             };
         }
-        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"]))
@@ -1061,7 +1102,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")
@@ -1166,7 +1207,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 +1259,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 +1269,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 +1326,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 +1443,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 +1463,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 +1623,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 +1716,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;
+}