narraeon 0.7.6 → 0.7.9

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

@@ -213,7 +213,14 @@ export class WorldLedgerAuthority {
     /** 某一轮修改的状态文件内容：即该轮结束时的文件，并校验哈希。 */
     async readStateChangeContents(commit, change) {
         const contents = await readFileAt(this.#root, commit.sequence, `state/${change.relativePath}`);
-        if (contents === null || sha256Hex(contents) !== change.nextHash)
+        if (change.kind === "delete") {
+            if (contents !== null)
+                throw new WorldAuthorityError("corrupt", `Deleted state document still exists in its commit: ${change.relativePath}`);
+            return null;
+        }
+        if (change.nextHash === null ||
+            contents === null ||
+            sha256Hex(contents) !== change.nextHash)
             throw new WorldAuthorityError("corrupt", `State change content conflicts with its commit: ${change.relativePath}`);
         return contents;
     }
@@ -297,7 +304,16 @@ export class WorldLedgerAuthority {
             if ((previous === undefined ? null : sha256Hex(previous)) !==
                 change.expectedPreviousHash)
                 throw new WorldAuthorityError("conflict", `State-change previous hash conflicts: ${change.relativePath}`);
-            if (sha256Hex(change.canonicalNextBytes) !== change.nextHash)
+            if (change.kind === "delete") {
+                if (previous === undefined ||
+                    change.nextHash !== null ||
+                    change.canonicalNextBytes !== null)
+                    throw new WorldAuthorityError("conflict", `State-change delete conflicts: ${change.relativePath}`);
+                changes.push({ path: `state/${change.relativePath}`, content: null });
+                continue;
+            }
+            if (change.canonicalNextBytes === null ||
+                sha256Hex(change.canonicalNextBytes) !== change.nextHash)
                 throw new WorldAuthorityError("conflict", `State-change next hash conflicts: ${change.relativePath}`);
             changes.push({
                 path: `state/${change.relativePath}`,

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

@@ -1,4 +1,4 @@
-import { WorldDocumentStore, } from "./WorldDocumentStore.js";
+import { WorldDocumentStore, formatWorldDocumentLocator, } from "./WorldDocumentStore.js";
 export function beginWorldStateRevision(files) {
     const snapshot = WorldDocumentStore.open({
         layout: "world_state",
@@ -63,8 +63,11 @@ export function fileNativeStateChanges(candidate) {
     });
 }
 export function worldDocumentRevisionFailureMessage(diagnostics) {
-    return (diagnostics.map(({ message }) => message).join("; ") ||
-        "The revision is invalid");
+    return (diagnostics
+        .map(({ message, locator }) => locator === undefined
+        ? message
+        : `${message} (${formatWorldDocumentLocator(locator)})`)
+        .join("; ") || "The revision is invalid");
 }
 function revisionFileRecord(snapshot) {
     return Object.fromEntries(snapshot.files.map((file) => {

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

@@ -1,4 +1,5 @@
 import { validLogicalMessages } from "../prompt/PromptCompilationCodec.js";
+import { upgradeLegacyEpochs } from "./LegacyWorldRevisionEpochUpgrade.js";
 import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { validAuthoringRequests, } from "../authoring/AuthoringRequestSnapshot.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -15,11 +16,25 @@ const fingerprintPattern = /^sha256:[0-9a-f]{64}$/u;
 const treeRevisionPattern = /^[0-9a-f]{64}$/u;
 const epochName = new RegExp(`^revision-${uuidV4Pattern}\\.json$`, "u");
 const sessionName = new RegExp(`^world-session-${uuidV4Pattern}\\.json$`, "u");
+/**
+ * A world holds an apply that v0.7.4 interrupted after its state commit but
+ * before control was published. Current code cannot finish it without replaying
+ * the operation, so the world must be opened once with v0.7.4.
+ */
+export class UnsupportedLegacyWorldRevisionError extends Error {
+    code = "unsupported_legacy_world_revision";
+    constructor(worldId) {
+        super(`World ${worldId} has a world-revision apply interrupted by v0.7.4; open it once with v0.7.4 to finish the apply`);
+        this.name = "UnsupportedLegacyWorldRevisionError";
+    }
+}
 /** File-native persistence for revision worktrees and their conversations. */
 export class FileNativeWorldRevisionStore {
     #epochsRoot;
     #sessionsRoot;
     #mutationTail = Promise.resolve();
+    /** Epoch ID → world ID for v0.7.4 epochs that cannot be upgraded here. */
+    #legacyUpgrade = null;
     constructor(dataRoot) {
         const root = join(resolve(dataRoot), "world-revisions");
         this.#epochsRoot = join(root, "epochs");
@@ -35,7 +50,12 @@ export class FileNativeWorldRevisionStore {
         return `change-set:${randomUUID()}`;
     }
     readEpoch(epochId) {
-        return this.#afterMutations(() => this.#readEpoch(epochId));
+        return this.#afterMutations(async () => {
+            const blocked = (await this.#upgradeLegacyEpochs()).get(epochId);
+            if (blocked !== undefined)
+                throw new UnsupportedLegacyWorldRevisionError(blocked);
+            return this.#readEpoch(epochId);
+        });
     }
     async readEpochIfPresent(epochId) {
         try {
@@ -55,20 +75,15 @@ export class FileNativeWorldRevisionStore {
     }
     async listEpochs(worldId) {
         return this.#afterMutations(async () => {
-            const entries = await readdir(this.#epochsRoot, {
-                withFileTypes: true,
-            }).catch((error) => {
-                if (isNodeError(error) && error.code === "ENOENT")
-                    return [];
-                throw error;
-            });
+            if ([...(await this.#upgradeLegacyEpochs()).values()].includes(worldId))
+                throw new UnsupportedLegacyWorldRevisionError(worldId);
             const epochs = [];
-            for (const entry of entries) {
-                if (!entry.isFile() || !epochName.test(entry.name))
+            for (const epochId of await epochIds(this.#epochsRoot)) {
+                // Only this world's epochs are validated, so a damaged epoch elsewhere does not fail it.
+                const value = JSON.parse(await readFile(this.#epochPath(epochId), "utf8"));
+                if (!isRecord(value) || value.worldId !== worldId)
                     continue;
-                const epoch = await this.#readEpoch(entry.name.slice(0, -5));
-                if (epoch.worldId === worldId)
-                    epochs.push(epoch);
+                epochs.push(epochFromValue(epochId, value));
             }
             return epochs.sort(compareUpdated);
         });
@@ -116,10 +131,23 @@ export class FileNativeWorldRevisionStore {
     async #readEpoch(epochId) {
         assertEpochId(epochId);
         const value = JSON.parse(await readFile(this.#epochPath(epochId), "utf8"));
-        const epoch = validateEpoch(value);
-        if (epoch.epochId !== epochId)
-            throw new Error("World-revision epoch identity does not match its file");
-        return epoch;
+        return epochFromValue(epochId, value);
+    }
+    /**
+     * Runs once per store before its first epoch read or list, and is shared
+     * after that. Every v0.7.4 epoch is upgraded in place; others are untouched.
+     */
+    #upgradeLegacyEpochs() {
+        this.#legacyUpgrade ??= this.#mutate(async () => upgradeLegacyEpochs({
+            epochsRoot: this.#epochsRoot,
+            epochIds: await epochIds(this.#epochsRoot),
+            validate: validateEpoch,
+            publish: publishJson,
+        })).catch((error) => {
+            this.#legacyUpgrade = null;
+            throw error;
+        });
+        return this.#legacyUpgrade;
     }
     async #readSession(sessionId) {
         assertSessionId(sessionId);
@@ -156,6 +184,22 @@ export class FileNativeWorldRevisionStore {
         return join(this.#sessionsRoot, `${sessionId}.json`);
     }
 }
+async function epochIds(epochsRoot) {
+    const entries = await readdir(epochsRoot, { withFileTypes: true }).catch((error) => {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    return entries
+        .filter((entry) => entry.isFile() && epochName.test(entry.name))
+        .map((entry) => entry.name.slice(0, -5));
+}
+function epochFromValue(epochId, value) {
+    const epoch = validateEpoch(value);
+    if (epoch.epochId !== epochId)
+        throw new Error("World-revision epoch identity does not match its file");
+    return epoch;
+}
 function validateEpoch(value) {
     if (!isRecord(value) ||
         !hasExactKeys(value, [

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

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Rewrites v0.7.4 epochs whose control was published into the current
+ * `committed` phase. Returns the world of each v0.7.4 epoch left in
+ * `state_committed`, which cannot be finished here. Files that do not match a
+ * v0.7.4 schema, or cannot be parsed, are left as they are.
+ */
+export async function upgradeLegacyEpochs(input) {
+    const blocked = new Map();
+    for (const epochId of input.epochIds) {
+        const path = join(input.epochsRoot, `${epochId}.json`);
+        const value = await readFile(path, "utf8")
+            .then((text) => JSON.parse(text))
+            .catch(() => null);
+        if (!isRecord(value) || !isRecord(value.apply))
+            continue;
+        if (value.apply.phase === "control_published") {
+            const upgraded = epochWithApplyPhase(input, value, "committed");
+            if (upgraded !== null)
+                await input.publish(path, upgraded);
+        }
+        else if (value.apply.phase === "state_committed" &&
+            value.lifecycle === "applying") {
+            const legacy = epochWithApplyPhase(input, value, "committed");
+            if (legacy !== null)
+                blocked.set(epochId, legacy.worldId);
+        }
+    }
+    return blocked;
+}
+/** The epoch with its apply phase replaced, if that makes it a valid current epoch. */
+function epochWithApplyPhase(input, value, phase) {
+    try {
+        return input.validate({
+            ...value,
+            apply: { ...value.apply, phase },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -1,7 +1,10 @@
 import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
+import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { assertSameGameplay, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { inspectContentPackageCurrentTree } from "../content/FileNativeContentTree.js";
-import { authoringToolDefinitions, SettingAuthoringTransaction, worldRevisionAuthoringSurface, } from "../setting/SettingAuthoringTransaction.js";
+import { createHistoryQuery, historyToolNames, isHistoryToolName, runHistoryTool, } from "../history/HistoryTools.js";
+import { runtimeToolsForNames } from "../prompt/FileNativeToolRegistry.js";
+import { authoringToolDefinitions, SettingAuthoringTransaction, settingDocumentDeletionBlockers, worldRevisionAuthoringSurface, } from "../setting/SettingAuthoringTransaction.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
 /**
  * The authoring transaction over a playing world's state/control worktree.
@@ -10,10 +13,15 @@ import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
  */
 export class WorldRevisionAuthoringTransaction {
     #inner;
+    #history;
+    #locale;
     constructor(input) {
+        this.#locale = input.locale ?? defaultAppLocale;
+        this.#history = createHistoryQuery(input.history.scope, input.history.entries);
         this.#inner = new SettingAuthoringTransaction({
             baseFiles: input.baseFiles,
             surface: worldRevisionAuthoringSurface,
+            additionalToolNames: historyToolNames,
             ...(input.locale === undefined ? {} : { locale: input.locale }),
             ...(input.revision === undefined ? {} : { revision: input.revision }),
             ...(input.authorization === undefined
@@ -35,12 +43,33 @@ export class WorldRevisionAuthoringTransaction {
     authorization(revision) {
         return this.#inner.authorization(revision);
     }
+    /**
+     * History calls are read-only: they never reach the worktree, the change
+     * history or the read authorizations. Write calls run as one batch so the
+     * automatic review still follows the last successful write, and their
+     * results return to the positions of their calls.
+     */
     execute(calls) {
-        return this.#inner.execute(calls);
+        const settled = this.#inner.execute(calls.filter(({ name }) => !isHistoryToolName(name)));
+        let next = 0;
+        return calls.map((call) => {
+            if (!isHistoryToolName(call.name))
+                return settled[next++];
+            const result = runHistoryTool(this.#history, call, this.#locale);
+            return {
+                toolCallId: call.id,
+                markdown: result.markdown,
+                isError: !result.ok,
+                changes: [],
+            };
+        });
     }
 }
 export function worldRevisionToolDefinitions(locale, gameplay) {
-    return authoringToolDefinitions(worldRevisionAuthoringSurface, locale, gameplay);
+    return [
+        ...authoringToolDefinitions(worldRevisionAuthoringSurface, locale, gameplay),
+        ...runtimeToolsForNames(historyToolNames, locale),
+    ];
 }
 export function worldRevisionRuntimeContract(locale, gameplay) {
     // A world's mode and scheme are fixed, so only tabletop worlds mention the file.
@@ -51,18 +80,20 @@ export function worldRevisionRuntimeContract(locale, gameplay) {
 - 你正在修改一个已经开始游玩的世界，而不是创建世界所用的内容包。修订期间 Runtime 持有持久独占锁，游玩和其他世界写入均被禁止。
 - state/* 与 control/* 共同组成唯一的修订工作树；手动编辑和 AI 工具写入落到同一棵树，也进入同一份可回滚改动历史。opening.md 已经作为创世叙事提交，不能读取或修改。
 - 工具调用修改的是尚未应用的工作树。只有玩家点击“应用修订”才会把当前整棵树提交为新的世界状态和控制并解除锁；“放弃修订”会丢弃工作树并解除锁。你不得宣称自己已经应用或放弃修订。
+- history_list、history_search、history_read 只读导航这个世界已提交的历史原文（开场白如存在也包括在内）。历史是已经发生的证据，用于核对故事中的事实与因果，不能通过修订改写、删除或追加；历史调用不产生改动、不进入回滚历史，也不改变读取授权。修改 state/* 与 control/* 时以当前工作树为准，明确的当前修订优先于旧叙事。
 - 每个完整工具响应按调用顺序结算。成功调用留下逐文件 before-image，可以由玩家单独回滚；失败调用不会撤销同一响应内其他成功调用。
-- 修改既有文件前必须完整读取。list/search cursor 和 read 授权只属于产生它们的工作树 revision；工作树发生任何手动、AI 或回滚写入后，继续修改前必须重新读取。
-- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。${tabletop ? "control/gameplay.json 记录世界的玩法模式与判定方案，修订中只能保持不变。" : ""}可以创建新状态文档；既有状态文档不能删除或移动，因为 Authority 保留其稳定身份。
+- 修改既有文件前必须完整读取。search cursor 和 read 授权只属于产生它们的工作树 revision；工作树发生任何手动、AI 或回滚写入后，继续修改前必须重新读取。bootstrap 中 Runtime 预载的完整文档视为已在该 revision 完整读取，可直接修改；目录不算读取。
+- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。${tabletop ? "control/gameplay.json 记录世界的玩法模式与判定方案，修订中只能保持不变。" : ""}可以创建新状态文档；可以删除或移动既有状态文档：删除前必须完整读取，且 currentSituation、frame slot、player-view selector 与其他文档 $ref 都不能再指向它，否则 Runtime 会列出全部阻挡位置；移动保留文档身份与内容，且不覆盖已有路径。
 - 对话跨越“应用”或“放弃”继续时，Runtime 会明确宣布一个新修订 epoch。此前读取授权全部失效；先重新读取新世界，再继续修改。`
         : `# Runtime world-revision conversation contract
 
 - You are revising a world that is already in play, not its source content package. Runtime holds a durable exclusive lock during the revision, blocking play and every other world write.
 - state/* and control/* form one revision worktree. Manual edits and AI tool writes share that tree and one rollback history. opening.md was already committed as genesis narrative and cannot be read or changed.
 - Tools change the unapplied worktree. Only the player can Apply the complete tree to world state/control and unlock it, or Discard the tree and unlock it. Never claim that you applied or discarded the revision yourself.
+- history_list, history_search and history_read only navigate the world's committed history originals (the opening included when present). History is evidence of what already happened for checking facts and causality; a revision cannot rewrite, delete or append to it. History calls produce no changes, never enter rollback history and do not alter read authorization. When editing state/* or control/*, the current worktree governs; an explicit current revision takes precedence over old narrative.
 - Calls in each complete tool response settle in order. Every successful call retains per-file before-images for selective rollback; a failed sibling does not undo successful calls.
-- Completely read an existing file before changing it. List/search cursors and read authorization belong only to the worktree revision that produced them. Re-read after any manual, AI, or rollback write.
-- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. ${tabletop ? "control/gameplay.json records the world's gameplay mode and resolution scheme; a revision must leave both unchanged. " : ""}New state documents are allowed; existing state documents cannot be deleted or moved because Authority retains their stable identity.
+- Completely read an existing file before changing it. Search cursors and read authorization belong only to the worktree revision that produced them. Re-read after any manual, AI, or rollback write. Runtime-preloaded complete documents in the bootstrap count as completely read at that revision and may be changed directly; the directory does not count as a read.
+- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. ${tabletop ? "control/gameplay.json records the world's gameplay mode and resolution scheme; a revision must leave both unchanged. " : ""}New state documents are allowed; existing state documents may be deleted or moved: a deletion requires a complete read and no remaining currentSituation, frame slot, player-view selector, or other document $ref pointing to it, otherwise Runtime lists every blocking location; a move keeps the document identity and contents and never overwrites an existing path.
 - When a conversation continues after Apply or Discard, Runtime announces a new revision epoch and invalidates every prior read authorization. Re-read the new world before editing.`;
 }
 export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
@@ -90,49 +121,58 @@ export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
                 message: "Only state/* and supported control/* files are writable",
             });
     }
-    for (const base of immutableBaseFiles.filter(({ path }) => path.startsWith("state/"))) {
-        if (!paths.has(base.path))
-            diagnostics.push({
-                code: "existing_state_delete_forbidden",
-                path: base.path,
-                message: "An existing world-state document cannot be deleted",
-            });
-    }
+    // Existing documents are matched by document ID: a path change is a move, and only a
+    // missing ID is a deletion. Deletion is refused while any reference still points to it.
+    const baseStateFiles = immutableBaseFiles.filter(({ path }) => path.startsWith("state/"));
     const baseSnapshot = WorldDocumentStore.open({
         layout: "world_state",
-        files: immutableBaseFiles.filter(({ path }) => path.startsWith("state/")),
+        files: baseStateFiles,
     });
     const candidateSnapshot = WorldDocumentStore.open({
         layout: "world_state",
         files: files.filter(({ path }) => path.startsWith("state/")),
     });
-    for (const base of immutableBaseFiles.filter(({ path }) => path.startsWith("state/"))) {
+    const candidateWorldSnapshot = WorldDocumentStore.open({
+        layout: "world_revision",
+        files,
+    });
+    for (const base of baseStateFiles) {
         const before = baseSnapshot.query({
             kind: "read_document",
             document: { logicalPath: base.path },
         });
+        if (before.kind !== "read_document" || !before.ok)
+            continue;
         const after = candidateSnapshot.query({
             kind: "read_document",
-            document: { logicalPath: base.path },
+            document: { documentId: before.document.documentId },
         });
-        if (before.kind === "read_document" &&
-            before.ok &&
-            after.kind === "read_document" &&
-            after.ok &&
-            (before.document.documentId !== after.document.documentId ||
-                before.document.shortRef !== after.document.shortRef))
+        if (after.kind === "read_document" && after.ok) {
+            if (after.document.shortRef !== before.document.shortRef)
+                diagnostics.push(identityChangedDiagnostic(base.path));
+            continue;
+        }
+        if (paths.has(base.path)) {
+            diagnostics.push(identityChangedDiagnostic(base.path));
+            continue;
+        }
+        // References to the deleted document no longer resolve in the candidate, so the
+        // blocker scan reads a probe that restores the base document for resolution only.
+        const probe = WorldDocumentStore.open({
+            layout: "world_revision",
+            files: [...files, base],
+        });
+        const blockers = settingDocumentDeletionBlockers(probe, before.document);
+        if (blockers.length > 0)
             diagnostics.push({
-                code: "existing_state_identity_changed",
+                code: "existing_state_delete_blocked",
                 path: base.path,
-                message: "An existing world-state document must keep its document ID and short reference",
+                message: deletionBlockedMessage(before.document.shortRef, blockers),
             });
     }
     const inspection = inspectContentPackageCurrentTree(files, {
         requireOpening: false,
-        worldDocumentSnapshot: WorldDocumentStore.open({
-            layout: "world_revision",
-            files,
-        }),
+        worldDocumentSnapshot: candidateWorldSnapshot,
     });
     if (inspection.status !== "usable")
         diagnostics.push(...inspection.issues.map(({ code, path, message }) => ({
@@ -145,6 +185,19 @@ export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
         diagnostics,
     };
 }
+function identityChangedDiagnostic(path) {
+    return {
+        code: "existing_state_identity_changed",
+        path,
+        message: "An existing world-state document must keep its document ID and short reference",
+    };
+}
+function deletionBlockedMessage(shortRef, blockers) {
+    const locations = blockers
+        .map(({ path, locator }) => `${path} · ${locator}`)
+        .join("; ");
+    return `Cannot delete @${shortRef}; remove or redirect every reference first: ${locations}`;
+}
 /** A malformed gameplay file is reported by content inspection, not as a scheme change. */
 function gameplayDiagnostics(immutableBaseFiles, files) {
     try {

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