narraeon 0.7.2 → 0.7.5

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

@@ -1,3 +1,4 @@
+import { FileNativePlayAdvanceStore } from "../play/FileNativePlayAdvanceStore.js";
 import { FileNativePlayTimelineStore } from "../play/FileNativePlayTimelineStore.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
@@ -21,9 +22,11 @@ export class UnsupportedLegacyStorageError extends Error {
 export class FileNativeWorldStorageMigrator {
     #worldsRoot;
     #playTimeline;
+    #playAdvances;
     constructor(dataRoot) {
         this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
         this.#playTimeline = new FileNativePlayTimelineStore(dataRoot);
+        this.#playAdvances = new FileNativePlayAdvanceStore(dataRoot);
     }
     async migrate(worldId) {
         assertIdentity(worldId, "World ID");
@@ -39,6 +42,7 @@ export class FileNativeWorldStorageMigrator {
             ])
                 await rm(residue, { recursive: true, force: true });
             await this.#playTimeline.migrateLayout(worldId);
+            await this.#playAdvances.migrateLayout(worldId);
             const head = await ledger.readHead();
             return { outcome: "already_current", authorityCommits: head.sequence };
         }
@@ -46,6 +50,7 @@ export class FileNativeWorldStorageMigrator {
         if (await authority.exists()) {
             const { commits } = await convertAuthorityV3ToLedger(worldRoot);
             await this.#playTimeline.migrateLayout(worldId);
+            await this.#playAdvances.migrateLayout(worldId);
             return { outcome: "migrated", authorityCommits: commits };
         }
         throw new UnsupportedLegacyStorageError(worldId);

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

@@ -19,8 +19,8 @@ import { readWorldActivity, updateWorldActivity, } from "./WorldActivity.js";
 import { FileNativePlayTimelineStore } from "../play/FileNativePlayTimelineStore.js";
 import { FileNativePlayAdvanceStore } from "../play/FileNativePlayAdvanceStore.js";
 import { FileNativeWorldStorageMigrator, UnsupportedLegacyStorageError, } from "./FileNativeWorldStorageMigrator.js";
-import { WorldAuthorityError, WorldLedgerAuthority, } from "./WorldLedgerAuthority.js";
-import { forgetLedger, rewindTo, WorldTurnLedgerError, } from "./WorldTurnLedger.js";
+import { isCorrectionCommit, WorldAuthorityError, WorldLedgerAuthority, } from "./WorldLedgerAuthority.js";
+import { forgetLedger, recoverIncomplete, rewindTo, WorldTurnLedgerError, } from "./WorldTurnLedger.js";
 import { FileNativeWorldOperationCoordinator, WorldOperationBusyError, } from "./WorldOperationCoordinator.js";
 import { projectFileNativeHistorySurface, projectHistoryBackgrounds, historyBackgroundRecord, } from "./FileNativeHistoryProjection.js";
 const publicationFile = "publication.json";
@@ -76,9 +76,11 @@ export class FileNativeWorldStore {
         this.#storageMigrator = new FileNativeWorldStorageMigrator(root);
     }
     /**
-     * Upgrade an Authority V3 world to the current ledger layout before current
-     * Authority or play-timeline behavior crosses its seam. Concurrent callers share one
-     * in-process promise; the durable world lock serializes processes.
+     * Open a world for this process: upgrade an Authority V3 world to the current
+     * ledger layout, then recover any turn that did not finish before the process
+     * stopped (ADR-0045). Runs once per world in the world's queue slot, so no
+     * in-process advance can interleave with recovery. Concurrent callers share one
+     * in-process promise.
      */
     async ensureCurrentStorage(worldId) {
         assertIdentity(worldId, "World ID");
@@ -104,18 +106,24 @@ export class FileNativeWorldStore {
     async #ensureCurrentStorageSerialized(worldId) {
         try {
             const root = join(this.#worldsRoot, worldId);
-            const authority = new WorldLedgerAuthority(root);
-            if ((await authority.exists()) &&
-                (await this.playTimeline.layoutCurrent(worldId))) {
-                await authority.readHead();
-                this.#currentStorage.add(worldId);
-                return;
-            }
             await this.operations.withWorldAuthorityLock(worldId, async () => {
-                await this.#storageMigrator.migrate(worldId);
-                await migrateLegacyArtifactStore(dirname(this.#worldsRoot), worldId);
+                // A caller queued behind the first open finds the world already open.
+                if (this.#currentStorage.has(worldId))
+                    return;
+                const authority = new WorldLedgerAuthority(root);
+                if ((await authority.exists()) &&
+                    (await this.playTimeline.layoutCurrent(worldId)) &&
+                    (await this.playAdvances.layoutCurrent(worldId))) {
+                    await authority.readHead();
+                }
+                else {
+                    await this.#storageMigrator.migrate(worldId);
+                    await migrateLegacyArtifactStore(dirname(this.#worldsRoot), worldId);
+                }
+                // Recovery follows migration; a world with no unfinished turn writes nothing.
+                await recoverIncomplete(root);
+                this.#currentStorage.add(worldId);
             });
-            this.#currentStorage.add(worldId);
         }
         catch (error) {
             if (error instanceof FileNativeWorldCreationError)
@@ -424,9 +432,9 @@ export class FileNativeWorldStore {
      * must never pair a mutable state tree with a different response head.
      */
     async renderPlayerViewsAtHead(worldId, head) {
-        const [state, control] = await Promise.all([
-            this.recoverEndpoint(worldId, head).then(({ state }) => state),
-            this.readSurface(worldId, "control"),
+        const [{ state }, control] = await Promise.all([
+            this.recoverEndpoint(worldId, head),
+            this.#recoverEndpointControl(worldId, head),
         ]);
         const source = control.find(({ path }) => path === "player-views.yaml");
         return new PlayerViewRenderer().render({
@@ -532,54 +540,6 @@ export class FileNativeWorldStore {
     async bindWorldRevision(handle) {
         return this.operations.withWorldRevisionLock(handle, () => this.bindPlayCallChain(handle.worldId));
     }
-    /** Replace control while the matching revision epoch retains exclusive ownership. */
-    async replaceWorldRevisionControl(input) {
-        for (const file of input.files)
-            assertRelativePath(file.path);
-        return this.operations.withWorldRevisionLock(input.handle, async () => {
-            if ((this.#activeControlUsers.get(input.handle.worldId)?.size ?? 0) > 0)
-                throw new FileNativeWorldCreationError("operation_conflict", "World control is frozen by another operation");
-            const root = join(this.#worldsRoot, input.handle.worldId);
-            const currentPath = join(root, "control");
-            const runtimeRoot = join(root, "runtime");
-            const stagingRoot = join(runtimeRoot, `.revision-control-${input.handle.epochId}-next`);
-            const stagedPath = join(stagingRoot, "control");
-            const previousPath = join(runtimeRoot, `.revision-control-${input.handle.epochId}-previous`);
-            let current = await readTree(currentPath);
-            let currentFingerprint = fingerprint(current);
-            const nextFingerprint = fingerprint(input.files);
-            if (currentFingerprint === nextFingerprint) {
-                await rm(stagingRoot, { recursive: true, force: true });
-                await rm(previousPath, { recursive: true, force: true });
-                return { fingerprint: nextFingerprint };
-            }
-            const previous = await readTree(previousPath);
-            const staged = await readTree(stagedPath);
-            if (current.length === 0 &&
-                fingerprint(previous) === input.expectedFingerprint) {
-                if (fingerprint(staged) === nextFingerprint) {
-                    await rename(stagedPath, currentPath);
-                    await rm(previousPath, { recursive: true, force: true });
-                    await rm(stagingRoot, { recursive: true, force: true });
-                    return { fingerprint: nextFingerprint };
-                }
-                await rename(previousPath, currentPath);
-                current = await readTree(currentPath);
-                currentFingerprint = fingerprint(current);
-            }
-            if (currentFingerprint !== input.expectedFingerprint)
-                throw new FileNativeWorldCreationError("operation_conflict", "World control changed after this revision epoch opened");
-            assertControlGameplayUnchanged(current, input.files);
-            await rm(stagingRoot, { recursive: true, force: true });
-            await rm(previousPath, { recursive: true, force: true });
-            await writeSurface(stagingRoot, "control", input.files);
-            await rename(currentPath, previousPath);
-            await rename(stagedPath, currentPath);
-            await rm(previousPath, { recursive: true, force: true });
-            await rm(stagingRoot, { recursive: true, force: true });
-            return { fingerprint: nextFingerprint };
-        });
-    }
     async previewControlDraft(worldId, prompt) {
         const { state, draft } = await this.#readControlDraft(worldId);
         const rendered = new PlayerViewRenderer().render({
@@ -620,20 +580,25 @@ export class FileNativeWorldStore {
                     throw new FileNativeWorldCreationError("operation_conflict", "World control is frozen by a running attempt");
                 const preview = await this.previewControlDraft(worldId, prompt);
                 const root = join(this.#worldsRoot, worldId);
-                assertControlGameplayUnchanged(await readTree(join(root, "control")), await readTree(join(root, "runtime/control-draft")));
-                const draft = join(root, "runtime/control-draft");
-                const replacement = join(root, `runtime/.control-apply-${randomUUID()}`);
-                await rename(draft, replacement);
-                const old = join(root, `runtime/.control-old-${randomUUID()}`);
-                await rename(join(root, "control"), old);
-                try {
-                    await rename(replacement, join(root, "control"));
-                    await rm(old, { recursive: true, force: true }).catch(() => undefined);
-                }
-                catch (error) {
-                    await rename(old, join(root, "control")).catch(() => undefined);
-                    throw error;
-                }
+                const draft = await readTree(join(root, "runtime/control-draft"));
+                const authority = new WorldLedgerAuthority(root);
+                const endpoint = await authority.recover();
+                assertControlGameplayUnchanged(await authority.recoverControl(endpoint.head), draft);
+                // 控制编辑应用是一轮 `control_apply`：只含 control 改动，与其他轮一样可回退。
+                await this.#commitHistoryChange({
+                    operationId: `control-apply-${randomUUID()}`,
+                    worldId,
+                    parentHead: endpoint.head,
+                    nextMaterials: worldNeutralMaterials(worldId, endpoint.additionalMaterials),
+                    stateChanges: [],
+                    mode: "control_apply",
+                    historyAppend: [],
+                    control: draft,
+                });
+                await rm(join(root, "runtime/control-draft"), {
+                    recursive: true,
+                    force: true,
+                });
                 return {
                     controlFingerprint: preview.diagnosticBinding.controlFingerprint,
                     preview,
@@ -701,8 +666,9 @@ export class FileNativeWorldStore {
         }
         try {
             return await this.operations.withWorldAuthorityLock(worldId, async () => {
-                const recovered = await new WorldLedgerAuthority(root).recover();
-                const control = await readTree(join(root, "control"));
+                const authority = new WorldLedgerAuthority(root);
+                const recovered = await authority.recover();
+                const control = await authority.recoverControl(recovered.head);
                 return {
                     worldId,
                     parentHead: recovered.head,
@@ -727,7 +693,7 @@ export class FileNativeWorldStore {
         }
     }
     /**
-     * Bind an immutable historical endpoint with the world's current control
+     * Bind an immutable historical endpoint with that endpoint's own control
      * surface. This is the same semantic input as a fresh context started while
      * that endpoint was current, without rewinding today's head.
      */
@@ -735,7 +701,7 @@ export class FileNativeWorldStore {
         assertIdentity(worldId, "World ID");
         const [endpoint, control] = await Promise.all([
             this.recoverEndpoint(worldId, head),
-            this.readSurface(worldId, "control"),
+            this.#recoverEndpointControl(worldId, head),
         ]);
         return {
             worldId,
@@ -794,12 +760,16 @@ export class FileNativeWorldStore {
             };
         }
         catch (error) {
-            if (error instanceof FileNativeWorldCreationError)
-                throw error;
-            // 端点在读取途中被回退丢弃不是损坏：调用方重新取得当前端点即可。
-            if (error instanceof WorldTurnLedgerError && error.code === "discarded")
-                throw new FileNativeWorldCreationError("endpoint_discarded", `Authority endpoint was rewound away${head === undefined ? "" : `: ${head}`}`, { cause: error });
-            throw new FileNativeWorldCreationError("world_corrupt", `Cannot recover immutable Authority endpoint${head === undefined ? "" : `: ${head}`}`, error instanceof Error ? { cause: error } : undefined);
+            throw endpointReadError(error, head);
+        }
+    }
+    /** 端点的控制文件；与 recoverEndpoint 的状态取同一个端点，回退与分叉随端点恢复。 */
+    async #recoverEndpointControl(worldId, head) {
+        try {
+            return await new WorldLedgerAuthority(join(this.#worldsRoot, worldId)).recoverControl(head);
+        }
+        catch (error) {
+            throw endpointReadError(error, head);
         }
     }
     async deriveWorld(input) {
@@ -845,10 +815,7 @@ export class FileNativeWorldStore {
             const sourceHead = input.sourceHead === "current"
                 ? (await sourceAuthority.readHead()).head
                 : input.sourceHead;
-            const [sourceGenesis, control] = await Promise.all([
-                readGenesisForFork(sourceRoot, input.sourceWorldId),
-                readTree(join(sourceRoot, "control")),
-            ]);
+            const sourceGenesis = await readGenesisForFork(sourceRoot, input.sourceWorldId);
             const staging = join(dirname(finalRoot), `.staging-${worldId}-${randomUUID()}`);
             await mkdir(dirname(finalRoot), { recursive: true, mode: 0o700 });
             try {
@@ -861,7 +828,9 @@ export class FileNativeWorldStore {
                 });
                 // 分叉不信任来源的投影文件：当前文件由副本上的账本端点重建。
                 await new WorldLedgerAuthority(staging).materializeCurrentFiles();
+                // 控制与状态一样取自所选端点：回退已把副本的 control/ 恢复到该端点。
                 const selected = await new WorldLedgerAuthority(staging).recover();
+                const selectedControl = await new WorldLedgerAuthority(staging).recoverControl(selected.head);
                 await PackageScriptPermissions.write(staging, input.resetPackageScriptPermissions
                     ? []
                     : await PackageScriptPermissions.read(sourceRoot));
@@ -873,7 +842,7 @@ export class FileNativeWorldStore {
                     operationId: input.operationId,
                     parentEndpoint: "genesis",
                     state: structuredClone(sourceGenesis.state),
-                    control: immutableFiles(control),
+                    control: immutableFiles(selectedControl),
                     history: structuredClone(sourceGenesis.history),
                     additionalMaterials: structuredClone(sourceGenesis.additionalMaterials),
                 };
@@ -890,7 +859,7 @@ export class FileNativeWorldStore {
                     binding: {
                         worldId,
                         parentHead: sourceHead,
-                        files: [...selected.state, ...control].reduce((files, { path, contents }, index) => {
+                        files: [...selected.state, ...selectedControl].reduce((files, { path, contents }, index) => {
                             files[`${index < selected.state.length ? "state" : "control"}/${path}`] = contents;
                             return files;
                         }, {}),
@@ -1020,9 +989,6 @@ export class FileNativeWorldStore {
                     mode: "correction",
                     historyAppend: [],
                     operationReserved,
-                    ...(input.validationControl === undefined
-                        ? {}
-                        : { validationControl: input.validationControl }),
                 });
             };
             if (input.stateOperationClaim !== undefined &&
@@ -1040,6 +1006,45 @@ export class FileNativeWorldStore {
             throw error;
         }
     }
+    /**
+     * 世界修订应用：state 与 control 的改动作为同一轮 `revision_apply` 提交。
+     * 操作身份由 epoch 决定，同一身份已是当前端点时直接返回该提交（崩溃后重放不重复推进）。
+     */
+    async commitWorldRevisionApply(input) {
+        await this.ensureCurrentStorage(input.worldId);
+        try {
+            return await this.operations.withWorldRevisionLock(input.worldRevisionLock, async () => {
+                const operationReserved = (await this.getOperationOutcome(input.operationId)).outcome ===
+                    "not_started" && (await this.reserveOperation(input.operationId));
+                try {
+                    return await this.#commitHistoryChange({
+                        ...(input.worldClock === undefined
+                            ? {}
+                            : { worldClock: input.worldClock }),
+                        operationId: input.operationId,
+                        worldId: input.worldId,
+                        parentHead: input.parentHead,
+                        nextMaterials: worldNeutralMaterials(input.worldId, input.nextMaterials),
+                        stateChanges: input.stateChanges,
+                        mode: "revision_apply",
+                        historyAppend: [],
+                        operationReserved,
+                        control: input.control,
+                    });
+                }
+                catch (error) {
+                    if (operationReserved)
+                        await this.releaseOperationReservation(input.operationId);
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "This world already has a durable state operation in progress");
+            throw error;
+        }
+    }
     /**
      * Persist one already-visible step of the model-directed play call chain.
      * Player text, assistant text and world changes deliberately arrive in
@@ -1093,11 +1098,16 @@ export class FileNativeWorldStore {
                     throw new FileNativeWorldCreationError("operation_conflict", "The same play operation ID is occupied by another durable operation");
                 const authorityStore = new WorldLedgerAuthority(root);
                 const authority = await authorityStore.readHead();
+                if (input.mode === "revision_apply" &&
+                    authority.operationId === input.operationId) {
+                    // 同一世界修订应用已经是当前端点：崩溃发生在端点发布之后、阶段记录之前。
+                    return this.#committedOutcomeAtHead(authorityStore, input, authority.head);
+                }
                 if (authority.head !== input.parentHead)
                     throw new FileNativeWorldCreationError("operation_conflict", "The parent endpoint of the play operation has changed");
-                const [basisState, storedControl] = await Promise.all([
+                const [basisState, basisControl] = await Promise.all([
                     authorityStore.recoverState(authority.head),
-                    readTree(join(root, "control")),
+                    authorityStore.recoverControl(authority.head),
                 ]);
                 const candidateState = new Map(basisState.map((file) => [file.path, file.contents]));
                 for (const change of input.stateChanges) {
@@ -1114,7 +1124,7 @@ export class FileNativeWorldStore {
                         path: `world/${path}`,
                         contents,
                     })),
-                    ...(input.validationControl ?? storedControl).map(({ path, contents }) => ({
+                    ...(input.control ?? basisControl).map(({ path, contents }) => ({
                         path: `control/${path}`,
                         contents,
                     })),
@@ -1134,10 +1144,11 @@ export class FileNativeWorldStore {
                     historyAppend: input.historyAppend,
                     stateChanges: input.stateChanges,
                     nextMaterials: input.nextMaterials,
+                    ...(input.control === undefined ? {} : { control: input.control }),
                     ...(input.narrativeCheckpoint === undefined
                         ? {}
                         : { narrativeCheckpoint: input.narrativeCheckpoint }),
-                    ...(input.mode === "correction"
+                    ...(isCorrectionCommit(input.mode)
                         ? {
                             correctionTargets: input.stateChanges.map(({ documentId }) => documentId),
                             corrects: input.parentHead,
@@ -1168,6 +1179,27 @@ export class FileNativeWorldStore {
             throw error;
         }
     }
+    /**
+     * 操作身份已经是当前端点的提交：核对它与本次输入一致，然后按它的结果返回。
+     * 不一致说明同一身份被用于另一份提交，拒绝而不是覆盖或重复推进。
+     */
+    async #committedOutcomeAtHead(authorityStore, input, head) {
+        const fact = await authorityStore.authorityFactAt(head);
+        if (!authorityCommitMatchesInput(fact.commit, input))
+            throw new FileNativeWorldCreationError("operation_conflict", "The same operation ID is bound to a different complete commit payload");
+        const outcome = {
+            outcome: "committed",
+            worldId: input.worldId,
+            parentHead: fact.commit.parentHead,
+            head: fact.commit.head,
+            commitDigest: fact.digest,
+            historyAppend: structuredClone(input.historyAppend),
+            nextAdditionalMaterials: structuredClone(input.nextMaterials),
+            mode: input.mode,
+        };
+        this.#rememberOperationOutcome(input.worldId, input.operationId, outcome);
+        return outcome;
+    }
     async readAuthorityHistory(worldId) {
         assertIdentity(worldId, "World ID");
         await this.ensureCurrentStorage(worldId);
@@ -1227,9 +1259,12 @@ export class FileNativeWorldStore {
             throw new FileNativeWorldCreationError("world_corrupt", `Historical endpoint does not exist: ${endpoint}`);
         return {
             endpoint,
-            corrects: commit?.mode === "correction" ? (commit.corrects ?? null) : null,
+            corrects: commit !== undefined && isCorrectionCommit(commit.mode)
+                ? (commit.corrects ?? null)
+                : null,
             correctedBy: commits
-                .filter((candidate) => candidate.mode === "correction" && candidate.corrects === endpoint)
+                .filter((candidate) => isCorrectionCommit(candidate.mode) &&
+                candidate.corrects === endpoint)
                 .map(({ head }) => head),
         };
     }
@@ -1513,7 +1548,8 @@ function authorityCommitMatchesInput(commit, input) {
                 nextHash: candidate.nextHash,
             });
         });
-    const expectedCorrection = input.mode === "correction"
+    const correction = isCorrectionCommit(input.mode);
+    const expectedCorrection = correction
         ? input.stateChanges.map(({ documentId }) => documentId)
         : undefined;
     return (commit.mode === input.mode &&
@@ -1529,8 +1565,15 @@ function authorityCommitMatchesInput(commit, input) {
         isDeepStrictEqual(commit.nextAdditionalMaterials, input.nextMaterials) &&
         isDeepStrictEqual(commit.narrativeCheckpoint, input.narrativeCheckpoint) &&
         isDeepStrictEqual(commit.correctionTargets, expectedCorrection) &&
-        commit.corrects ===
-            (input.mode === "correction" ? input.parentHead : undefined));
+        commit.corrects === (correction ? input.parentHead : undefined));
+}
+/** 读取某个端点失败的错误映射：端点在读取途中被回退丢弃不是损坏，调用方重新取得当前端点即可。 */
+function endpointReadError(error, head) {
+    if (error instanceof FileNativeWorldCreationError)
+        return error;
+    if (error instanceof WorldTurnLedgerError && error.code === "discarded")
+        return new FileNativeWorldCreationError("endpoint_discarded", `Authority endpoint was rewound away${head === undefined ? "" : `: ${head}`}`, { cause: error });
+    return new FileNativeWorldCreationError("world_corrupt", `Cannot recover immutable Authority endpoint${head === undefined ? "" : `: ${head}`}`, error instanceof Error ? { cause: error } : undefined);
 }
 function headPosition(head) {
     if (head === "genesis")

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

@@ -1,5 +1,6 @@
 import { listWorldDocuments } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "./WorldDocumentStore.js";
+import { isCorrectionCommit, } from "./WorldLedgerAuthority.js";
 /** Reachable committed bytes only. Cached prefixes are disposable accelerators. */
 export async function readDocumentMaintenanceFacts(authority, head, cache) {
     const exact = cache.get(head);
@@ -92,7 +93,7 @@ export async function readDocumentMaintenanceFacts(authority, head, cache) {
             files.set(change.relativePath, contents);
         const next = snapshot();
         const position = {
-            kind: commit.mode === "correction"
+            kind: isCorrectionCommit(commit.mode)
                 ? "correction"
                 : context === undefined
                     ? "history"

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

@@ -171,7 +171,7 @@ export class WorldDocumentStore {
                             code: "logical_path_invalid",
                             logicalPath: command.toLogicalPath,
                             documentId: target.entry.descriptor.documentId,
-                            message: "Move target must be a safe logical path under world/ with the original codec",
+                            message: `Move target must be a safe logical path under ${this.logicalRoot}/ with the original codec`,
                         });
                     if (working.some(({ file }) => file !== target.working.file &&
                         file.path === command.toLogicalPath))

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

@@ -3,6 +3,13 @@ import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { projectFileNativeHistorySurface, projectHistoryBackgrounds, } from "./FileNativeHistoryProjection.js";
 import { appendTurn, initializeLedger, listTurns, readEndpoint, readFileAt, readHead as readLedgerHead, readTreeAt, readTurnDigest, resolveEndpoint, } from "./WorldTurnLedger.js";
+/**
+ * 世界修订应用与连续性修正同属修订谱系：它们记录 `corrects` 与 `correctionTargets`，
+ * 维护报告与修订追溯按此归类。
+ */
+export function isCorrectionCommit(mode) {
+    return mode === "correction" || mode === "revision_apply";
+}
 export class WorldAuthorityError extends Error {
     code;
     constructor(code, message) {
@@ -113,14 +120,38 @@ export class WorldLedgerAuthority {
         return structuredClone(parsed.items ?? []);
     }
     async #stateAt(position) {
-        const tree = await readTreeAt(this.#root, position, ["state"]);
+        return this.#surfaceAt(position, "state");
+    }
+    async #controlAt(position) {
+        return this.#surfaceAt(position, "control");
+    }
+    async #surfaceAt(position, surface) {
+        const prefix = `${surface}/`;
+        const tree = await readTreeAt(this.#root, position, [surface]);
         return [...tree]
             .map(([path, contents]) => ({
-            path: path.slice("state/".length),
+            path: path.slice(prefix.length),
             contents,
         }))
             .sort((left, right) => left.path.localeCompare(right.path));
     }
+    /** 端点的控制文件：与状态同一账本视图，回退与分叉随端点恢复。 */
+    async recoverControl(head) {
+        return this.#controlAt(await this.#positionOf(head));
+    }
+    /** 把当前端点的控制文件替换为 next 所需的逐文件改动（写入或删除，未变化的不记录）。 */
+    async #controlChanges(position, next) {
+        const current = await readTreeAt(this.#root, position, ["control"]);
+        const wanted = new Map(next.map((file) => [`control/${file.path}`, file.contents]));
+        const changes = [];
+        for (const path of current.keys())
+            if (!wanted.has(path))
+                changes.push({ path, content: null });
+        for (const [path, contents] of wanted)
+            if (current.get(path) !== contents)
+                changes.push({ path, content: contents });
+        return changes;
+    }
     #checkpointAt(commits) {
         for (let index = commits.length - 1; index >= 0; index -= 1) {
             const commit = commits[index];
@@ -246,7 +277,8 @@ export class WorldLedgerAuthority {
     }
     /**
      * 在当前端点之上追加一轮。调用方先校验内容；这里校验状态的前像哈希，
-     * 并一次性计算本轮需要替换的全部文件（状态、历史、历史背景与材料清单）。
+     * 并一次性计算本轮需要替换的全部文件（状态、控制、历史、历史背景与材料清单）。
+     * `control` 是提交后的完整控制文件集合：与端点的差异作为本轮改动，逐文件记录前像。
      */
     async appendCommit(input) {
         const current = await this.readHead();
@@ -289,6 +321,8 @@ export class WorldLedgerAuthority {
                 path: `runtime/history-backgrounds/${file.path}`,
                 content: file.contents,
             });
+        if (input.control !== undefined)
+            changes.push(...(await this.#controlChanges(current.sequence, input.control)));
         changes.push({
             path: materialsFile,
             content: `${JSON.stringify({ head, items: input.nextMaterials }, null, 2)}\n`,

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

@@ -194,6 +194,10 @@ async function captureBefore(root, paths) {
 // 第一步：写入本轮记录（序号为 head + 1）。记录原子落盘，之后任何一步崩溃都可由 recoverIncomplete 回滚。
 export async function beginTurn(root, input) {
     const head = await readHead(root);
+    // head + 1 上还留着记录，说明上一轮没有发布端点（中断，或回滚失败）。
+    // 先恢复，否则新记录会把半写入的文件当作前像保存。
+    if ((await readTextOrNull(join(root, turnFileName(head + 1)))) !== null)
+        await recoverIncomplete(root);
     const record = {
         sequence: head + 1,
         mode: input.mode,
@@ -226,12 +230,21 @@ export async function commitTurnHead(root, record) {
 }
 export async function appendTurn(root, input) {
     const record = await beginTurn(root, input);
-    await applyChanges(root, input.changes);
-    await commitTurnHead(root, record);
+    try {
+        await applyChanges(root, input.changes);
+        await commitTurnHead(root, record);
+    }
+    catch (error) {
+        // 本轮未发布：用启动恢复的同一规则回滚。回滚本身失败时保留原始错误；
+        // 残留的记录留在 head + 1 上，下一次推进开始前会先恢复（见 beginTurn）。
+        await recoverIncomplete(root).catch(() => undefined);
+        throw error;
+    }
     return record;
 }
-// 启动时调用：序号大于 head 的记录说明上一次推进未完成，逆序恢复其修改前像。
-// 被丢弃的轮记录（读取时已忽略）在这里清理。返回是否回滚了未完成的轮。
+// 世界首次打开时调用（FileNativeWorldStore），进程内推进失败时也调用：序号大于 head 的记录
+// 说明对应推进未完成，逆序恢复其修改前像。被丢弃的轮记录（读取时已忽略）在这里清理。
+// 返回是否回滚了未完成的轮。
 export async function recoverIncomplete(root) {
     const head = await readHead(root);
     const turns = await readAllRecords(root);

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

@@ -320,9 +320,7 @@ function validApply(value) {
             nonEmptyString(value.operationId) &&
             typeof value.expectedRevision === "string" &&
             treeRevisionPattern.test(value.expectedRevision) &&
-            (value.phase === "prepared" ||
-                value.phase === "state_committed" ||
-                value.phase === "control_published") &&
+            (value.phase === "prepared" || value.phase === "committed") &&
             (value.phase === "prepared"
                 ? value.committedHead === null
                 : nonEmptyString(value.committedHead))));
@@ -337,7 +335,7 @@ function validEpochLifecycle(value) {
             value.apply.expectedRevision === value.revision);
     if (value.lifecycle === "applied")
         return (isRecord(value.apply) &&
-            value.apply.phase === "control_published" &&
+            value.apply.phase === "committed" &&
             value.apply.expectedRevision === value.revision &&
             value.finishedAt !== null);
     return (value.lifecycle === "discarded" &&