narraeon 0.7.7 → 0.7.9

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

@@ -4,9 +4,10 @@ import { InvalidContentTreeError, } from "../content/ContentWorkspace.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { equalModelHostBinding } from "../model/ModelHost.js";
 import { settingImprovementPromptForBinding, } from "../play/FileNativePlayPresetStore.js";
+import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
 import { appendAuthoringUserMessage, ModelToolConversation, rememberAuthoringRequest, resumePausedAuthoringConversation, } from "../authoring/ModelToolConversation.js";
 import { summarizeStoredSettingImprovementSession, } from "./FileNativeSettingImprovementStore.js";
-import { SettingAuthoringTransaction, settingImprovementRuntimeContract, settingImprovementToolDefinitions, } from "./SettingAuthoringTransaction.js";
+import { SettingAuthoringTransaction, settingImprovementRuntimeContract, settingImprovementToolDefinitions, authoringPreloadAuthorization, buildAuthoringPreload, contentPackageAuthoringSurface, } from "./SettingAuthoringTransaction.js";
 class RecoveryWriteConflictError extends Error {
 }
 export class SettingImprovementRollbackError extends Error {
@@ -186,7 +187,7 @@ export class SettingImprovementSession {
                 assertPackage(session, input.packageId);
             }
             return this.#startRequest(session, requestId, async (next) => {
-                const { playPreset, bootstrap } = await this.#compileCurrent(input.packageId, next.modelBinding);
+                const { playPreset, bootstrap, preload } = await this.#compileCurrent(input.packageId, next.modelBinding);
                 next.schemaVersion = 3;
                 next.requests ??= [];
                 next.requests.push({
@@ -194,7 +195,9 @@ export class SettingImprovementSession {
                     modelItemStart: next.modelItems.length,
                     bootstrap,
                     playPreset: structuredClone(playPreset),
+                    preload: structuredClone(preload.record),
                 });
+                next.authorization = authoringPreloadAuthorization(next.authorization, preload.record);
                 appendAuthoringUserMessage(next, message, requestId);
             });
         });
@@ -244,6 +247,7 @@ export class SettingImprovementSession {
         const playPreset = await this.#bindPlayPreset();
         const locale = this.#locale();
         const package_ = await this.#content.readCurrentTreeContentPackage(packageId);
+        const preload = this.#preload(package_.files, modelBinding, playPreset, locale);
         const bootstrap = this.#compiler.compileSettingImprovement({
             contentPackageTitle: package_.title,
             gameplay: package_.gameplay,
@@ -252,8 +256,41 @@ export class SettingImprovementSession {
             playPreset,
             modelBinding: modelBinding,
             tools: settingImprovementToolDefinitions(locale, package_.gameplay),
+            preload: preload.blocks,
+        });
+        return { bootstrap, playPreset, preload };
+    }
+    /**
+     * Preloads the control documents and the documents the package frame injects.
+     * A preview that cannot be built degrades to the directory and control files.
+     */
+    #preload(files, modelBinding, playPreset, locale) {
+        const revision = contentTreeFingerprint(files);
+        const snapshot = WorldDocumentStore.open({
+            layout: "content_package",
+            files: [...files],
+        });
+        let injected = [];
+        let injectedUnavailable;
+        try {
+            const preview = this.#preview(snapshot, modelBinding, playPreset);
+            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: contentPackageAuthoringSurface,
+            locale,
+            revision,
+            sourcePrefix: "content-package:preload",
+            injected,
+            ...(injectedUnavailable === undefined ? {} : { injectedUnavailable }),
         });
-        return { bootstrap, playPreset };
     }
     async cancel(sessionId) {
         const running = this.#conversation.cancel(sessionId);

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

@@ -1114,10 +1114,20 @@ export class FileNativeWorldStore {
                     assertRelativePath(change.relativePath);
                     const previous = candidateState.get(change.relativePath);
                     const previousHash = previous === undefined ? null : sha256(previous);
-                    if (previousHash !== change.expectedPreviousHash ||
-                        sha256(change.canonicalNextBytes) !== change.nextHash)
+                    const nextBytes = change.canonicalNextBytes;
+                    const consistent = change.kind === "delete"
+                        ? previous !== undefined &&
+                            nextBytes === null &&
+                            change.nextHash === null
+                        : nextBytes !== null &&
+                            change.nextHash !== null &&
+                            sha256(nextBytes) === change.nextHash;
+                    if (previousHash !== change.expectedPreviousHash || !consistent)
                         throw new FileNativeWorldCreationError("operation_conflict", `State-change hash conflicts: ${change.relativePath}`);
-                    candidateState.set(change.relativePath, change.canonicalNextBytes);
+                    if (nextBytes === null)
+                        candidateState.delete(change.relativePath);
+                    else
+                        candidateState.set(change.relativePath, nextBytes);
                 }
                 const inspection = inspectContentPackageCurrentTree([
                     ...[...candidateState].map(([path, contents]) => ({

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

@@ -87,10 +87,15 @@ export async function readDocumentMaintenanceFacts(authority, head, cache) {
             continue;
         const changed = await Promise.all(commit.stateChanges.map(async (change) => ({
             change,
-            contents: await authority.readStateChangeContents(commit, change),
+            contents: change.kind === "delete"
+                ? null
+                : await authority.readStateChangeContents(commit, change),
         })));
         for (const { change, contents } of changed)
-            files.set(change.relativePath, contents);
+            if (contents === null)
+                files.delete(change.relativePath);
+            else
+                files.set(change.relativePath, contents);
         const next = snapshot();
         const position = {
             kind: isCorrectionCommit(commit.mode)
@@ -103,6 +108,8 @@ export async function readDocumentMaintenanceFacts(authority, head, cache) {
             worldTime: commit.worldClock ?? null,
         };
         for (const { change } of changed) {
+            if (change.kind === "delete")
+                continue;
             const ref = change.stableShortRef;
             const before = previous.query({
                 kind: "read_document",

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-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 {