narraeon 0.7.7 → 0.7.10

package/dist/node/runtime/world-revision/WorldRevisionSession.js

@@ -5,9 +5,11 @@ import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringReq
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { equalModelHostBinding } from "../model/ModelHost.js";
 import { settingImprovementPromptForBinding, } from "../play/FileNativePlayPresetStore.js";
+import { authoringPreloadAuthorization, buildAuthoringPreload, worldRevisionAuthoringSurface, } from "../setting/SettingAuthoringTransaction.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
 import { WorldRevisionAuthoringTransaction, worldRevisionRuntimeContract, worldRevisionToolDefinitions, } from "./WorldRevisionAuthoringTransaction.js";
 import { WorldRevisionWorkspaceError } from "./WorldRevisionWorkspace.js";
+import { historyEntries } from "../history/HistoryTools.js";
 /** Conversation orchestration over the shared locked revision worktree. */
 export class WorldRevisionSession {
     #store;
@@ -197,7 +199,7 @@ export class WorldRevisionSession {
             const host = await this.#bindExistingModelHost(session.modelBinding);
             if (!equalModelHostBinding(session.modelBinding, host.binding()))
                 throw new Error("No saved model connection matches this world-revision conversation");
-            const { playPreset, bootstrap } = await this.#compileCurrent(input.worldId, session.modelBinding);
+            const { playPreset, bootstrap, preload } = await this.#compileCurrent(input.worldId, session.modelBinding);
             session.schemaVersion = 2;
             session.requests ??= [];
             session.requests.push({
@@ -205,7 +207,12 @@ export class WorldRevisionSession {
                 modelItemStart: session.modelItems.length,
                 bootstrap,
                 playPreset: structuredClone(playPreset),
+                ...(preload === null
+                    ? {}
+                    : { preload: structuredClone(preload.record) }),
             });
+            if (preload !== null)
+                session.authorization = authoringPreloadAuthorization(session.authorization, preload.record);
             appendAuthoringUserMessage(session, message, requestId);
             await this.#store.saveSession(session);
             return {
@@ -262,6 +269,9 @@ export class WorldRevisionSession {
         const playPreset = await this.#bindPlayPreset();
         const locale = this.#locale();
         const gameplay = await this.#worlds.gameplay(worldId);
+        const preload = epoch === null
+            ? null
+            : await this.#preload(epoch, modelBinding, playPreset, locale);
         const bootstrap = this.#compiler.compileWorldRevision({
             ...(epoch === null
                 ? {}
@@ -273,8 +283,54 @@ export class WorldRevisionSession {
             playPreset,
             modelBinding: modelBinding,
             tools: worldRevisionToolDefinitions(locale, gameplay),
+            ...(preload === null ? {} : { preload: preload.blocks }),
+        });
+        return { bootstrap, playPreset, preload };
+    }
+    /**
+     * Preloads the control documents and the documents the world frame injects.
+     * A preview that cannot be built degrades to the directory and control files.
+     */
+    async #preload(epoch, modelBinding, playPreset, locale) {
+        const [binding, maintenance] = await Promise.all([
+            this.#worlds.bindWorldRevision({
+                worldId: epoch.worldId,
+                epochId: epoch.epochId,
+            }),
+            this.#worlds.inspectDocumentMaintenance(epoch.worldId, epoch.baseHead),
+        ]);
+        const snapshot = WorldDocumentStore.open({
+            layout: "world_state",
+            files: epoch.files,
+        });
+        let injected = [];
+        let injectedUnavailable;
+        try {
+            const preview = this.#preview({
+                snapshot,
+                modelBinding,
+                playPreset,
+                binding,
+                epoch,
+                maintenance,
+            });
+            injected = preview.compilation.coverage.flatMap(({ slot, status, readAuthorization }) => status === "resolved" && readAuthorization !== undefined
+                ? [{ shortRef: readAuthorization.shortRef, slot }]
+                : []);
+        }
+        catch (error) {
+            injectedUnavailable =
+                error instanceof Error ? error.message : "unknown preview failure";
+        }
+        return buildAuthoringPreload({
+            snapshot,
+            surface: worldRevisionAuthoringSurface,
+            locale,
+            revision: epoch.revision,
+            sourcePrefix: "world-revision:preload",
+            injected,
+            ...(injectedUnavailable === undefined ? {} : { injectedUnavailable }),
         });
-        return { bootstrap, playPreset };
     }
     async cancel(sessionId) {
         const running = this.#conversation.cancel(sessionId);
@@ -408,6 +464,10 @@ export class WorldRevisionSession {
         return new WorldRevisionAuthoringTransaction({
             baseFiles: epoch.files,
             immutableBaseFiles: epoch.baseFiles,
+            history: {
+                scope: epoch.worldId,
+                entries: historyEntries(binding.history, binding.historyBackgrounds),
+            },
             locale: session.locale,
             revision: epoch.revision,
             authorization: session.authorization,
@@ -565,8 +625,8 @@ export class WorldRevisionSession {
 }
 function retargetSession(session, epoch, locale) {
     const markdown = locale === "zh-CN"
-        ? `# 新的世界修订 epoch\n\n上一轮修订已经应用或放弃。当前工作树是 ${epoch.epochId}，从世界端点 ${epoch.baseHead} 重新建立。此前全部 list/search cursor 和 read 写授权已失效；修改前必须重新读取。`
-        : `# New world-revision epoch\n\nThe previous revision was applied or discarded. Worktree ${epoch.epochId} was rebuilt from world endpoint ${epoch.baseHead}. Every prior list/search cursor and read authorization is invalid; re-read before writing.`;
+        ? `# 新的世界修订 epoch\n\n上一轮修订已经应用或放弃。当前工作树是 ${epoch.epochId}，从世界端点 ${epoch.baseHead} 重新建立。此前全部 search cursor 和 read 写授权已失效；修改前必须重新读取。`
+        : `# New world-revision epoch\n\nThe previous revision was applied or discarded. Worktree ${epoch.epochId} was rebuilt from world endpoint ${epoch.baseHead}. Every prior search cursor and read authorization is invalid; re-read before writing.`;
     session.modelItems.push({
         kind: "prompt_delta",
         logicalMessages: [

package/dist/node/runtime/world-revision/WorldRevisionWorkspace.js

@@ -353,18 +353,21 @@ function assertExpectedRevision(epoch, expected) {
         throw new WorldRevisionWorkspaceError("The world-revision worktree changed; refresh it before writing");
 }
 function stateChanges(baseFiles, files) {
-    const base = new Map(baseFiles
-        .filter(({ path }) => path.startsWith("state/"))
-        .map((file) => [file.path, file]));
+    const baseStateFiles = baseFiles.filter(({ path }) => path.startsWith("state/"));
+    const base = new Map(baseStateFiles.map((file) => [file.path, file]));
+    const candidateStateFiles = files.filter(({ path }) => path.startsWith("state/"));
     const snapshot = WorldDocumentStore.open({
         layout: "world_state",
-        files: files.filter(({ path }) => path.startsWith("state/")),
+        files: candidateStateFiles,
     });
     if (snapshot.status !== "usable")
         throw new WorldRevisionWorkspaceError("Only a usable world-state snapshot can be applied");
-    return files
-        .filter(({ path }) => path.startsWith("state/"))
-        .flatMap((file) => {
+    const baseSnapshot = WorldDocumentStore.open({
+        layout: "world_state",
+        files: baseStateFiles,
+    });
+    const candidatePaths = new Set(candidateStateFiles.map(({ path }) => path));
+    const changes = candidateStateFiles.flatMap((file) => {
         const previous = base.get(file.path);
         if (previous?.contents === file.contents)
             return [];
@@ -375,10 +378,6 @@ function stateChanges(baseFiles, files) {
         if (result.kind !== "read_document" || !result.ok)
             throw new WorldRevisionWorkspaceError(`Cannot resolve changed world document: ${file.path}`);
         if (previous !== undefined) {
-            const baseSnapshot = WorldDocumentStore.open({
-                layout: "world_state",
-                files: baseFiles.filter(({ path }) => path.startsWith("state/")),
-            });
             const before = baseSnapshot.query({
                 kind: "read_document",
                 document: { logicalPath: file.path },
@@ -401,6 +400,28 @@ function stateChanges(baseFiles, files) {
             },
         ];
     });
+    // A base document whose path is gone was deleted or moved away; a move's new path is a create above.
+    const removals = baseStateFiles
+        .filter(({ path }) => !candidatePaths.has(path))
+        .map((file) => {
+        const before = baseSnapshot.query({
+            kind: "read_document",
+            document: { logicalPath: file.path },
+        });
+        if (before.kind !== "read_document" || !before.ok)
+            throw new WorldRevisionWorkspaceError(`Cannot resolve removed world document: ${file.path}`);
+        return {
+            kind: "delete",
+            documentId: before.document.documentId,
+            stableShortRef: before.document.shortRef,
+            relativePath: file.path.slice("state/".length),
+            codec: before.document.codec,
+            expectedPreviousHash: sha256(file.contents),
+            nextHash: null,
+            canonicalNextBytes: null,
+        };
+    });
+    return [...changes, ...removals];
 }
 function controlFiles(files) {
     return files

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

@@ -7,17 +7,22 @@
  * mechanical setting-improvement boundary.
  */
 export const defaultSettingImprovementPromptPath = "prompts/setting-improvement.md";
+/** Content-package-only paragraphs; a running-world revision omits them. */
+const contentPackageWorldStartZhCN = "内容包设定完善定义开场结束处的世界起点，可以包含已有历史、当前状态、持续过程和各人的认知。简单起点足以开玩，普通未定义内容可在游玩中生长；不预写未来必然发生的经历或强制剧情阶段。";
+const contentPackageOpeningZhCN = "仅在内容包分支检查 opening.md：写玩家当时可感知的具体局面，保留尚待回答的请求与必要原话，不替玩家决定行动、台词或内心。独处、安静和等待也可形成开场。开场与文档停在同一时点，将约束首次行动的结果写给自然所有者，无需复制整篇叙事。";
+const contentPackageWorldStartEn = "Content-package setting improvement defines the world where the opening ends, including established history, current state, ongoing processes and individual knowledge. A simple starting point can be playable and ordinary undefined content can grow during play. Do not prewrite inevitable future experiences or mandatory plot stages.";
+const contentPackageOpeningEn = "Inspect opening.md only in the content-package branch. Show a concrete situation the player can perceive, retaining unanswered requests and consequential wording without choosing player action, speech or inner thoughts. Solitude, quiet and waiting can also open a story. Documents and opening stop at the same moment; give outcomes constraining the first action to natural owners without copying the whole narrative.";
 export const defaultSettingImprovementPromptZhCN = `# 系统推荐的创作方法
 
 以当前编辑目标、已有内容和用户目标为起点。讨论时说明必要判断，落实时定向修改；用户要求审查或重组时，相关结构与重复表达也在范围内。不为填满结构制造内容，无需修改也是合法结果。
 
 ## 编辑目标与世界起点
 
-内容包设定完善定义开场结束处的世界起点，可以包含已有历史、当前状态、持续过程和各人的认知。简单起点足以开玩，普通未定义内容可在游玩中生长；不预写未来必然发生的经历或强制剧情阶段。
+${contentPackageWorldStartZhCN}
 
-运行中世界修订维护当前已经演变的世界，按用户要求调整并保留未受影响的事实、经历与认知，不退回初始取值。此分支不读取或修改 opening.md。明确修订不是世界内事件，不需虚构行动解释它。
+运行中世界修订维护当前已经演变的世界，按用户要求调整并保留未受影响的事实、经历与认知，不退回初始取值。明确修订不是世界内事件，不需虚构行动解释它。
 
-涉及结构、材料发现或更新位置时，先列出编辑目标根目录，完整读取 control/frame.yaml、启用的世界提示块、绑定的当前情境及受影响文档。实际操作遵守本轮工具边界。
+涉及结构、材料发现或更新位置时，以本请求 bootstrap 已提供的目录、控制文档与注入文档为起点；未提供而受影响的文档再用工具读取。实际操作遵守本轮工具边界。
 
 ## 世界信息怎样组织
 
@@ -41,7 +46,7 @@ world/ 或 state/ 承载虚构事实，control/ 安排本世界的取材、规
 
 ## 开场与整理
 
-仅在内容包分支检查 opening.md：写玩家当时可感知的具体局面，保留尚待回答的请求与必要原话，不替玩家决定行动、台词或内心。独处、安静和等待也可形成开场。开场与文档停在同一时点，将约束首次行动的结果写给自然所有者，无需复制整篇叙事。
+${contentPackageOpeningZhCN}
 
 整理结束已完成或失效的进程、约定和限制，保留仍有意义的成果、后遗影响、经历与引用。补录、去重和归档不让事情再发生。长材料按需发现，软体积提示不授权截断；暂时离场不等于退役，退役也不会移除显式全文槽。
 
@@ -53,11 +58,11 @@ Start with the editing target, existing content and the user's goal. Discuss nec
 
 ## Editing target and world starting point
 
-Content-package setting improvement defines the world where the opening ends, including established history, current state, ongoing processes and individual knowledge. A simple starting point can be playable and ordinary undefined content can grow during play. Do not prewrite inevitable future experiences or mandatory plot stages.
+${contentPackageWorldStartEn}
 
-Running-world revision maintains the world as it has evolved: apply requested changes while preserving unaffected facts, events and knowledge instead of resetting initial values. This branch does not read or modify opening.md. Explicit revision is not an in-world event and needs no invented action to explain it.
+Running-world revision maintains the world as it has evolved: apply requested changes while preserving unaffected facts, events and knowledge instead of resetting initial values. Explicit revision is not an in-world event and needs no invented action to explain it.
 
-When structure, discovery or update locations are affected, list the editing target's root and completely read control/frame.yaml, enabled world instructions, the bound current situation and affected documents. Follow this request's actual tool boundary.
+When structure, discovery or update locations are affected, start from the directory, control documents and injected documents this request's bootstrap already provides; read affected documents with tools only when they were not provided. Follow this request's actual tool boundary.
 
 ## Organizing world information
 
@@ -81,7 +86,7 @@ world/ or state/ carries fictional facts. control/ arranges world-specific mater
 
 ## Opening and consolidation
 
-Inspect opening.md only in the content-package branch. Show a concrete situation the player can perceive, retaining unanswered requests and consequential wording without choosing player action, speech or inner thoughts. Solitude, quiet and waiting can also open a story. Documents and opening stop at the same moment; give outcomes constraining the first action to natural owners without copying the whole narrative.
+${contentPackageOpeningEn}
 
 Consolidation closes completed or expired processes, commitments and restrictions while retaining meaningful results, lasting effects, events and references. Recording, deduplication and archiving do not perform events again. Keep long material discoverable on demand; advisory size limits do not authorize truncation. Temporary absence is not retirement, and retirement does not remove explicit full-document slots.
 
@@ -93,3 +98,13 @@ export function defaultSettingImprovementPromptForLocale(locale) {
         ? defaultSettingImprovementPromptZhCN
         : defaultSettingImprovementPromptEn;
 }
+/**
+ * The same guidance for a running-world revision: the content-package-only
+ * paragraphs are omitted, and everything else stays byte-identical.
+ */
+export function revisionSettingImprovementPromptForLocale(locale) {
+    const paragraphs = locale === "zh-CN"
+        ? [contentPackageWorldStartZhCN, contentPackageOpeningZhCN]
+        : [contentPackageWorldStartEn, contentPackageOpeningEn];
+    return paragraphs.reduce((text, paragraph) => text.replace(`${paragraph}\n\n`, ""), defaultSettingImprovementPromptForLocale(locale));
+}

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

@@ -1,7 +1,7 @@
-import { defaultSettingImprovementPromptForLocale } from "./default-setting-improvement-prompt.js";
+import { defaultSettingImprovementPromptForLocale, revisionSettingImprovementPromptForLocale, } from "./default-setting-improvement-prompt.js";
 import { tabletopAuthorBody } from "./tabletop-guidance.js";
 /** Authoring uses the same permissions as play, with target-specific dynamic references. */
-export function builtinAuthorPrompts(locale) {
+export function builtinAuthorPrompts(locale, target = "setting") {
     const zh = locale === "zh-CN";
     return [
         {
@@ -18,7 +18,9 @@ export function builtinAuthorPrompts(locale) {
             name: zh ? "创作建议" : "Authoring guidance",
             required: false,
             category: "policy",
-            body: defaultSettingImprovementPromptForLocale(locale),
+            body: target === "world-revision"
+                ? revisionSettingImprovementPromptForLocale(locale)
+                : defaultSettingImprovementPromptForLocale(locale),
         },
         {
             id: "author.tabletop",
@@ -53,15 +55,15 @@ export function builtinAuthorPrompts(locale) {
 export function authoringMechanics(locale, target) {
     const zh = locale === "zh-CN";
     const common = zh
-        ? `只使用请求随附的工具及其参数契约。含工具调用的响应是中间步；收到全部工具结果后继续，非空且无工具调用的响应结束本次发送。完整工具响应按调用顺序结算，失败调用不撤销成功同级调用。修改既有文件前必须完整读取；cursor 只属于产生它的树 revision；本事务自身成功修改后的完整读取授权由 Runtime 承接。外部树变化或跨 epoch 后旧授权失效，需要重新读取。工具返回逻辑路径，不能访问宿主文件。文档引用使用返回的 @ref；YAML 整文档引用为单键 {$ref: "@ref"}，locator 使用 map key 或从零开始的数组下标。成功回执决定当前值，模型文字不构成提交。`
-        : `Use only the attached tools and their parameter contracts. Responses with tool calls are intermediate steps; continue after all results. A nonempty tool-free response ends this send. Complete tool responses settle calls in order; a failed call does not undo successful siblings. Completely read existing files before writing. Cursors belong to their producing tree revision. Runtime carries complete-read authorization through this transaction’s own successful changes. External tree changes or an epoch transition invalidate old authorization and require new reads. Tools expose logical paths, never host files. Use returned @refs for documents; YAML whole-document references are single-key {$ref: "@ref"} maps, and locators use map keys or zero-based array indexes. Actual receipts determine current values; model prose cannot commit changes.`;
+        ? `只使用请求随附的工具及其参数契约。含工具调用的响应是中间步；收到全部工具结果后继续，非空且无工具调用的响应结束本次发送。完整工具响应按调用顺序结算，失败调用不撤销成功同级调用。修改既有文件前必须完整读取；cursor 只属于产生它的树 revision；本事务自身成功修改后的完整读取授权由 Runtime 承接。外部树变化或跨 epoch 后旧授权失效，需要重新读取。bootstrap 中 Runtime 预载的完整文档视为已在该 revision 完整读取，可直接修改；目录不算读取。工具返回逻辑路径，不能访问宿主文件。文档引用使用返回的 @ref；YAML 整文档引用为单键 {$ref: "@ref"}，locator 使用 map key 或从零开始的数组下标。成功回执决定当前值，模型文字不构成提交。`
+        : `Use only the attached tools and their parameter contracts. Responses with tool calls are intermediate steps; continue after all results. A nonempty tool-free response ends this send. Complete tool responses settle calls in order; a failed call does not undo successful siblings. Completely read existing files before writing. Cursors belong to their producing tree revision. Runtime carries complete-read authorization through this transaction’s own successful changes. External tree changes or an epoch transition invalidate old authorization and require new reads. Runtime-preloaded complete documents in the bootstrap count as completely read at that revision; the directory does not. Tools expose logical paths, never host files. Use returned @refs for documents; YAML whole-document references are single-key {$ref: "@ref"} maps, and locators use map keys or zero-based array indexes. Actual receipts determine current values; model prose cannot commit changes.`;
     const boundary = target === "setting"
         ? zh
             ? "内容包工具的成功变化在完整响应结算时原子发布到当前树，无需应用。setting_create 建立新文档身份；删除仅在无绑定与引用阻挡时接受。"
             : "Successful content-package changes publish atomically to the current tree when the complete response settles, with no Apply step. setting_create establishes new document identities; deletion is accepted only without binding or reference blockers."
         : zh
-            ? "世界修订工具只修改持久独占 epoch 的 state/* 与 control/* 工作树。opening.md 不可读取或修改，既有状态文档不可删除或移动。只有玩家应用或放弃才结束 epoch；应用提交世界，放弃不改变世界。跨 epoch 全部旧读取授权失效。"
-            : "World-revision tools modify only state/* and control/* in the durably locked exclusive epoch. opening.md cannot be read or changed; existing state documents cannot be deleted or moved. Only player Apply or Discard ends the epoch; Apply commits the world, Discard leaves it unchanged. Every old read authorization expires across epochs.";
+            ? "世界修订工具只修改持久独占 epoch 的 state/* 与 control/* 工作树。opening.md 不可读取或修改；既有状态文档可以删除或移动，删除须无绑定与引用阻挡。只有玩家应用或放弃才结束 epoch；应用提交世界，放弃不改变世界。跨 epoch 全部旧读取授权失效。世界修订可用 history_list、history_search、history_read 只读导航已提交历史，历史不能被改写。"
+            : "World-revision tools modify only state/* and control/* in the durably locked exclusive epoch. opening.md cannot be read or changed; existing state documents can be deleted or moved, and deletion requires no binding or reference blockers. Only player Apply or Discard ends the epoch; Apply commits the world, Discard leaves it unchanged. Every old read authorization expires across epochs. World revision may read committed history with history_list, history_search and history_read; history cannot be rewritten.";
     const views = zh
         ? 'control/player-views.yaml 的 format 为 narraeon.player-views/v1；views 中每项有 id、title 和 items，items 中每项有 id、label、select。精确选择一个 YAML 字段使用 select: {document: "@ref", locator: {yaml: [字段名]}}；Markdown 小节使用 locator: {markdown: [标题]}。document 必须来自实际返回的引用，locator 必须对应已读正文；省略 locator 会展示整份文档，选择容器会递归展示子树。'
         : 'control/player-views.yaml uses format: narraeon.player-views/v1. Each views entry has id, title and items; each item has id, label and select. Select one YAML field with select: {document: "@ref", locator: {yaml: [field]}}; select a Markdown section with locator: {markdown: [heading]}. Use a returned document reference and a locator from the actual read body. Omitting locator displays the whole document; selecting a container recursively displays its subtree.';