narraeon 0.7.1 → 0.7.4

package/dist/node/protocol/v1.js

@@ -4,10 +4,12 @@ import { maxPortableContentArchiveBase64Characters } from "./contentTree.js";
 export const v1Protocol = "narraeon.runtime/v1";
 export class V1ProtocolError extends Error {
     code;
-    constructor(code, message, options) {
+    details;
+    constructor(code, message, options = {}) {
         super(message, options);
         this.name = "V1ProtocolError";
         this.code = code;
+        this.details = options.details;
     }
 }
 export function parseV1Envelope(value) {
@@ -37,7 +39,11 @@ const requiredFields = {
     "world.package-scripts.set": { worldId: "string", enabled: "boolean" },
     "content.gameplay.set": { packageId: "string", scheme: "string" },
     "content.read": { packageId: "string" },
-    "content.replace": { packageId: "string", files: "array" },
+    "content.replace": {
+        packageId: "string",
+        files: "array",
+        baseTreeRevision: "string",
+    },
     "content.copy": { packageId: "string" },
     "content.delete": { packageId: "string" },
     "content.rename": { packageId: "string", name: "string" },

package/dist/node/runtime/V1Runtime.js

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { maxPortableContentArchiveBase64Characters, maxPortableContentArchiveBytes, } from "../protocol/contentTree.js";
 import { V1ProtocolError, v1Protocol, } from "../protocol/v1.js";
 import { defaultAppLocale, } from "../protocol/appPreferences.js";
-import { ContentPackageImportError, ContentWorkspace, InvalidContentTreeError, } from "./content/ContentWorkspace.js";
+import { ContentPackageImportError, ContentTreeConflictError, ContentWorkspace, InvalidContentTreeError, } from "./content/ContentWorkspace.js";
 import { contentTreeFingerprint } from "./content/ContentTreeFingerprint.js";
 import { inspectContentPackageCurrentTree } from "./content/FileNativeContentTree.js";
 import { FileNativeModelHost } from "./model/FileNativeModelAdapters.js";
@@ -34,6 +34,8 @@ import { FileNativeWorldRevisionStore } from "./world-revision/FileNativeWorldRe
 import { WorldRevisionSession } from "./world-revision/WorldRevisionSession.js";
 import { WorldRevisionWorkspace, WorldRevisionWorkspaceError, } from "./world-revision/WorldRevisionWorkspace.js";
 import { ConversationChanges } from "./ConversationChanges.js";
+// 先取得当前端点再按它读取的请求，在端点被回退丢弃时最多重做这么多次（#94）。
+const currentEndpointReadAttempts = 3;
 export class V1Runtime {
     worldArchives;
     #conversationChanges = new ConversationChanges();
@@ -163,6 +165,9 @@ export class V1Runtime {
             await this.#errorLog?.recordRequestFailure(request, error);
             if (error instanceof WorldArchiveError)
                 throw new V1ProtocolError(error.code, error.message, { cause: error });
+            if (error instanceof FileNativeWorldCreationError &&
+                error.code === "endpoint_discarded")
+                throw new V1ProtocolError(error.code, error.message, { cause: error });
             if (request.type === "world.archive.export" &&
                 error instanceof FileNativeWorldCreationError &&
                 (error.code === "operation_conflict" ||
@@ -210,6 +215,10 @@ export class V1Runtime {
                 : {}),
         }, error);
     }
+    /** Archive routes sit outside `handle`, so they record their own failures. */
+    async recordArchiveFailure(target, error) {
+        await this.#errorLog?.recordRequestFailure(target, error);
+    }
     subscribeConversation(target, changed) {
         return this.#conversationChanges.subscribe(`${target.kind}:${target.id}`, changed);
     }
@@ -319,13 +328,18 @@ export class V1Runtime {
                 return this.#content.readCurrentTreeContentPackage(request.packageId);
             case "content.replace":
                 try {
-                    return await this.#content.replaceCurrentTreeContentPackage(request.packageId, request.files);
+                    return await this.#content.replaceCurrentTreeContentPackage(request.packageId, request.files, { baseTreeRevision: request.baseTreeRevision });
                 }
                 catch (error) {
                     if (error instanceof InvalidContentTreeError)
                         throw new V1ProtocolError("invalid_request", error.message, {
                             cause: error,
                         });
+                    if (error instanceof ContentTreeConflictError)
+                        throw new V1ProtocolError("content_conflict", error.message, {
+                            cause: error,
+                            details: { current: error.current },
+                        });
                     throw error;
                 }
             case "content.copy":
@@ -415,9 +429,12 @@ export class V1Runtime {
                     : await this.#playPresets.bindRevision(request.presetId, request.revision);
                 if (request.worldId === undefined)
                     return buildPlayPresetWorkbenchSnapshot(binding, undefined, request.draft);
-                const head = await this.#worlds.currentHead(request.worldId);
-                const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
-                return buildPlayPresetWorkbenchSnapshot(binding, { worldId: request.worldId, head, playerViews }, request.draft);
+                const { worldId } = request;
+                return this.#readingCurrentEndpoint(async () => {
+                    const head = await this.#worlds.currentHead(worldId);
+                    const playerViews = await this.#worlds.renderPlayerViewsAtHead(worldId, head);
+                    return buildPlayPresetWorkbenchSnapshot(binding, { worldId, head, playerViews }, request.draft);
+                });
             }
             case "prompt.preview": {
                 const [package_, connection, playPreset] = await Promise.all([
@@ -509,36 +526,37 @@ export class V1Runtime {
                 return this.worldArchives.exportWorld(request);
             case "world.archive.import":
                 return this.worldArchives.importWorld(request);
-            case "world.read": {
-                const head = await this.#worlds.currentHead(request.worldId);
-                const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
-                const extensionControls = await this.#currentExtensionControls(request.worldId);
-                const [playerViewPanels, playTimeline, revisionEpoch] = await Promise.all([
-                    this.#frontendPlayerViewPanels(request.worldId, head, playerViews, extensionControls),
-                    this.#worlds.playTimeline.readPage(request.worldId, 40),
-                    this.#worldRevisions.activeEpoch(request.worldId),
-                ]);
-                return {
-                    worldId: request.worldId,
-                    head,
-                    state: [],
-                    control: [],
-                    history: [],
-                    runtime: { head, surfaces: "lazy" },
-                    playerViews,
-                    committedMessages: [],
-                    artifacts: [],
-                    extensions: [],
-                    playerViewPanels,
-                    extensionControls,
-                    suppressedPlayerViewIds: await this.#suppressedPlayerViewIds(extensionControls),
-                    artifactDebug: [],
-                    playCallChain: null,
-                    playTimeline,
-                    worldRevision: revisionEpoch,
-                    archiveNeedsFreshContext: await this.#worlds.archiveNeedsFreshContext(request.worldId),
-                };
-            }
+            case "world.read":
+                return this.#readingCurrentEndpoint(async () => {
+                    const head = await this.#worlds.currentHead(request.worldId);
+                    const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
+                    const extensionControls = await this.#currentExtensionControls(request.worldId);
+                    const [playerViewPanels, playTimeline, revisionEpoch] = await Promise.all([
+                        this.#frontendPlayerViewPanels(request.worldId, head, playerViews, extensionControls),
+                        this.#worlds.playTimeline.readPage(request.worldId, 40),
+                        this.#worldRevisions.activeEpoch(request.worldId),
+                    ]);
+                    return {
+                        worldId: request.worldId,
+                        head,
+                        state: [],
+                        control: [],
+                        history: [],
+                        runtime: { head, surfaces: "lazy" },
+                        playerViews,
+                        committedMessages: [],
+                        artifacts: [],
+                        extensions: [],
+                        playerViewPanels,
+                        extensionControls,
+                        suppressedPlayerViewIds: await this.#suppressedPlayerViewIds(extensionControls),
+                        artifactDebug: [],
+                        playCallChain: null,
+                        playTimeline,
+                        worldRevision: revisionEpoch,
+                        archiveNeedsFreshContext: await this.#worlds.archiveNeedsFreshContext(request.worldId),
+                    };
+                });
             case "world.surface.read":
                 return request.surface === "runtime"
                     ? this.#worlds.readSurface(request.worldId, "runtime")
@@ -549,33 +567,33 @@ export class V1Runtime {
                 const result = await this.#worlds.extensionControls(request.worldId, await this.#playPresets.bindCurrent(), this.#locale, request);
                 return result;
             }
-            case "world.play-decorations.read": {
-                for (;;) {
-                    const extensionControls = await this.#currentExtensionControls(request.worldId);
-                    const head = await this.#reconcileArtifacts(request.worldId);
-                    const [projection, artifactDebug] = await Promise.all([
-                        this.#frontendDecorations(request.worldId),
-                        this.#frontendDebug(request.worldId),
-                    ]);
-                    const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
-                    const playerViewPanels = await this.#frontendPlayerViewPanels(request.worldId, head, playerViews, extensionControls);
-                    const suppressedPlayerViewIds = await this.#suppressedPlayerViewIds(extensionControls);
-                    // Never attach a newer controls revision to a projection read before
-                    // that choice was accepted. Concurrent toggles restart this read.
-                    if ((await this.#worlds.extensionControlsRevision(request.worldId)) !==
-                        extensionControls.revision)
-                        continue;
-                    return {
-                        head,
-                        ...projection,
-                        artifactDebug,
-                        playerViews,
-                        playerViewPanels,
-                        extensionControls,
-                        suppressedPlayerViewIds,
-                    };
-                }
-            }
+            case "world.play-decorations.read":
+                return this.#readingCurrentEndpoint(async () => {
+                    for (;;) {
+                        const extensionControls = await this.#currentExtensionControls(request.worldId);
+                        const head = await this.#reconcileArtifacts(request.worldId);
+                        const [projection, artifactDebug] = await Promise.all([
+                            this.#frontendDecorations(request.worldId),
+                            this.#frontendDebug(request.worldId),
+                        ]);
+                        const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
+                        const playerViewPanels = await this.#frontendPlayerViewPanels(request.worldId, head, playerViews, extensionControls);
+                        const suppressedPlayerViewIds = await this.#suppressedPlayerViewIds(extensionControls);
+                        // Never attach a newer controls revision to a projection read before
+                        // that choice was accepted. Concurrent toggles restart this read.
+                        if ((await this.#worlds.extensionControlsRevision(request.worldId)) !== extensionControls.revision)
+                            continue;
+                        return {
+                            head,
+                            ...projection,
+                            artifactDebug,
+                            playerViews,
+                            playerViewPanels,
+                            extensionControls,
+                            suppressedPlayerViewIds,
+                        };
+                    }
+                });
             case "artifacts.read":
                 await this.#reconcileArtifacts(request.worldId);
                 return (await this.#frontendDecorations(request.worldId, request.channel)).artifacts;
@@ -727,10 +745,10 @@ export class V1Runtime {
                         nextFreshContext: null,
                     };
                 const { modelHost, hostBinding, playPreset, modelBinding } = await this.#continuousBinding();
-                const persisted = currentContext === null
+                const live = currentContext === null
                     ? null
-                    : await this.#worlds.playTimeline.readCurrent(request.worldId);
-                const frozenBinding = persisted?.value.modelBinding;
+                    : await this.#playCallChains.currentContinuation(request.worldId);
+                const frozenBinding = live?.modelBinding;
                 const continueContext = currentContext !== null &&
                     !currentContext.stale &&
                     frozenBinding?.provider === modelBinding.provider;
@@ -768,7 +786,7 @@ export class V1Runtime {
                     toolUniverse: tools,
                     allowedTools: tools.map(({ name }) => name),
                     toolStrategy: preview.compilation.toolStrategy,
-                    appended: continueContext ? (persisted?.value.transcript ?? []) : [],
+                    appended: continueContext ? (live?.transcript ?? []) : [],
                     operationId: continueContext
                         ? currentContext.chainId
                         : "next-fresh-context-preview",
@@ -845,12 +863,27 @@ export class V1Runtime {
     async #matchingModelHost(binding) {
         return new FileNativeModelHost(await this.#models.bindMatching(binding), fetch, this.#failureLog);
     }
+    /**
+     * Reads that take the current endpoint first and then read at it (ADR-0044):
+     * a rewind published in between discards that endpoint, so the read starts
+     * again from the new current endpoint instead of failing.
+     */
+    async #readingCurrentEndpoint(read) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                return await read();
+            }
+            catch (error) {
+                if (!(error instanceof FileNativeWorldCreationError &&
+                    error.code === "endpoint_discarded") ||
+                    attempt >= currentEndpointReadAttempts)
+                    throw error;
+            }
+        }
+    }
     async #reconcileArtifacts(worldId) {
-        const [head, currentOperationId] = await Promise.all([
-            this.#worlds.currentHead(worldId),
-            this.#worlds.currentHeadOperationId(worldId),
-        ]);
-        await this.#artifacts.reconcileHead(worldId, head, currentOperationId ?? undefined);
+        const { head, operationId } = await this.#worlds.currentEndpoint(worldId);
+        await this.#artifacts.reconcileHead(worldId, head, operationId ?? undefined);
         return head;
     }
     async #frontendDecorations(worldId, channel) {

package/dist/node/runtime/archive/WorldArchives.js

@@ -108,7 +108,23 @@ export class WorldArchives {
             }
         });
     }
+    /**
+     * Confirms that `download` can serve this export without consuming it, so the
+     * browser can check before it starts the one-time download.
+     */
+    async checkDownload(archiveId) {
+        const { root } = await this.#readExport(archiveId);
+        await stat(join(root, "archive.zip"));
+    }
     async download(archiveId) {
+        const { root, metadata } = await this.#readExport(archiveId);
+        return {
+            metadata,
+            stream: createReadStream(join(root, "archive.zip")),
+            cleanup: () => rm(root, { recursive: true, force: true }),
+        };
+    }
+    async #readExport(archiveId) {
         identity(archiveId);
         const root = join(this.#root, "exports", archiveId);
         const metadata = JSON.parse(await readFile(join(root, "download.json"), "utf8"));
@@ -117,11 +133,7 @@ export class WorldArchives {
             await rm(root, { recursive: true, force: true });
             throw new WorldArchiveError("invalid_archive", "The download has expired; export the world again");
         }
-        return {
-            metadata,
-            stream: createReadStream(join(root, "archive.zip")),
-            cleanup: () => rm(root, { recursive: true, force: true }),
-        };
+        return { root, metadata };
     }
     async importWorld(input) {
         identity(input.operationId);

package/dist/node/runtime/artifact/FileNativeArtifactStore.js

@@ -23,8 +23,13 @@ export class FileNativeArtifactStore {
     #dataRoot;
     #worldsRoot;
     #extensionControls;
-    /** Records with `save: "none"` are never written to disk. */
+    /**
+     * Records with `save: "none"` are never written to disk. Superseded ones are
+     * dropped at once, cleared ones once their clearing operation closes.
+     */
     #memoryRecords = new Map();
+    /** Highest sequence handed out per world in this process, so removals never reuse one. */
+    #sequenceHighWater = new Map();
     #mutationContext = new AsyncLocalStorage();
     constructor(dataRoot) {
         this.#dataRoot = resolve(dataRoot);
@@ -109,9 +114,7 @@ export class FileNativeArtifactStore {
             throw new ArtifactStoreInvariantError("Artifact request attempt is missing an operation checkpoint");
         if (!sameContext(operation.context, context))
             throw new ArtifactStoreInvariantError("Artifact request attempt does not match the frozen operation");
-        if (operation.status === "core_failed" ||
-            operation.status === "completed" ||
-            operation.artifactProjectionStatus === "superseded")
+        if (isClosedOperation(operation))
             return;
         const mounts = [
             ...new Set(Object.values(context.frozenPresentations ?? {})
@@ -730,6 +733,12 @@ export class FileNativeArtifactStore {
         };
         assertRawRecord(finalized);
         if (record.save === "none") {
+            // A superseded record has no reader left: the debug listing shows only
+            // records that still exist, so it is not kept.
+            if (record.status === "superseded") {
+                await this.#removeRecord(finalized);
+                return;
+            }
             const records = this.#memoryRecords.get(record.operationId) ?? [];
             const index = records.findIndex((candidate) => candidate.recordId === record.recordId);
             if (index < 0)
@@ -744,18 +753,50 @@ export class FileNativeArtifactStore {
     async #removeRecord(record) {
         if (record.save === "none") {
             const records = (this.#memoryRecords.get(record.operationId) ?? []).filter((candidate) => candidate.recordId !== record.recordId);
-            this.#memoryRecords.set(record.operationId, records);
+            if (records.length === 0)
+                this.#memoryRecords.delete(record.operationId);
+            else
+                this.#memoryRecords.set(record.operationId, records);
             return;
         }
         await rm(join(this.#artifactsRoot(record.worldId), "records", artifactSequenceFileName(record.sequence)), { force: true });
     }
+    /**
+     * A cleared save:none record stays only while its clearing operation can still
+     * roll the clear back (see beginRequestAttempt). Once that operation is closed
+     * nothing reads the record, so it leaves memory.
+     */
+    async #releaseClosedClears(worldId) {
+        const cleared = [...this.#memoryRecords.values()]
+            .flat()
+            .filter((record) => record.worldId === worldId && record.status === "cleared");
+        if (cleared.length === 0)
+            return;
+        const operations = new Map((await this.#operationsForWorld(worldId)).map((operation) => [
+            operation.context.operationId,
+            operation,
+        ]));
+        for (const record of cleared) {
+            const clearing = record.clearedBy === undefined
+                ? undefined
+                : operations.get(record.clearedBy.operationId);
+            if (clearing !== undefined && !isClosedOperation(clearing))
+                continue;
+            await this.#removeRecord(record);
+        }
+    }
     async #operationsForWorld(worldId) {
         return [
             ...(await readOperationFiles(this.#artifactsRoot(worldId))).values(),
         ].filter((operation) => operation.context.worldId === worldId);
     }
+    /**
+     * The next sequence is one past the largest on disk or handed out in this
+     * process. The high-water mark outlives removed save:none records, so their
+     * sequences are never reused.
+     */
     async #nextSequence(worldId) {
-        let maximum = 0;
+        let maximum = this.#sequenceHighWater.get(worldId) ?? 0;
         try {
             for (const name of await readdir(join(this.#artifactsRoot(worldId), "records"))) {
                 if (!name.endsWith(".json"))
@@ -772,11 +813,9 @@ export class FileNativeArtifactStore {
             if (!isMissing(error))
                 throw error;
         }
-        for (const records of this.#memoryRecords.values())
-            for (const record of records)
-                if (record.worldId === worldId)
-                    maximum = Math.max(maximum, record.sequence);
-        return maximum + 1;
+        const next = maximum + 1;
+        this.#sequenceHighWater.set(worldId, next);
+        return next;
     }
     async #readOperation(worldId, operationId) {
         try {
@@ -807,7 +846,9 @@ export class FileNativeArtifactStore {
             return action();
         return worldQueueFor(this.#dataRoot).run(worldId, () => this.#mutationContext.run(new Set([...(active ?? []), worldId]), async () => {
             await migrateLegacyArtifactStore(this.#dataRoot, worldId);
-            return action();
+            const result = await action();
+            await this.#releaseClosedClears(worldId);
+            return result;
         }));
     }
     #artifactsRoot(worldId) {
@@ -1079,6 +1120,12 @@ function isTerminalExtensionStatus(status) {
         "superseded",
     ].includes(status);
 }
+/** A closed operation registers no further request attempts, so its clears are final. */
+function isClosedOperation(operation) {
+    return (operation.status === "core_failed" ||
+        operation.status === "completed" ||
+        operation.artifactProjectionStatus === "superseded");
+}
 function isStaleOperation(operation) {
     return (operation === null ||
         operation.artifactProjectionStatus === "superseded" ||

package/dist/node/runtime/config/dataRootCleanup.js

@@ -0,0 +1,52 @@
+import { mkdir, readdir, rm, rmdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+/** Persistent lock files and directories left by retired lock mechanisms. */
+const legacyLockPaths = [
+    "server.pid",
+    "runtime-locks",
+    join("operations", "world-locks"),
+    join("operations", "authority-locks"),
+    join("operations", "correction-claims"),
+];
+/**
+ * Startup housekeeping for a data directory. One service process per data
+ * directory is a product premise (ADR-0044), not something startup enforces:
+ * a pid lock cannot tell a crashed container's pid 1 from the restarted one.
+ */
+export async function prepareDataRoot(dataRoot) {
+    const root = resolve(dataRoot);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    await removeLegacyLocks(root);
+}
+async function removeLegacyLocks(root) {
+    for (const relative of legacyLockPaths)
+        await rm(join(root, relative), { recursive: true, force: true });
+    await removeLegacyOperationReceipts(root);
+}
+/**
+ * Operation receipts written before #76 (including archive import receipts) have
+ * no readers. The world-revision epoch markers in the same directory are kept.
+ */
+async function removeLegacyOperationReceipts(root) {
+    const directory = join(root, "operations");
+    const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (entries === null)
+        return;
+    for (const entry of entries)
+        if (entry.isFile() && entry.name.endsWith(".json"))
+            await rm(join(directory, entry.name), { force: true });
+    try {
+        await rmdir(directory);
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOTEMPTY")
+            throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/node/runtime/content/ContentWorkspace.js

@@ -7,7 +7,7 @@ import { defaultContentWorkspaceLimits, maximumPortableContentArchiveBytes, } fr
 import { CurrentTreeContentLibrary, InvalidContentTreeError, normalizeCurrentContentTreeFiles, } from "./CurrentTreeContentLibrary.js";
 import { sampleContentPackageForLocale } from "../../shared/sample-packages/index.js";
 import { inspectContentPackageCurrentTree, isContentPackageWorldDocumentPath, worldDocumentTextRequirement, } from "./FileNativeContentTree.js";
-export { CurrentTreeContentPackageBusyError, CurrentTreeContentLibraryError, CurrentTreeContentPackageNotFoundError, InvalidContentTreeError, } from "./CurrentTreeContentLibrary.js";
+export { ContentTreeConflictError, CurrentTreeContentPackageBusyError, CurrentTreeContentLibraryError, CurrentTreeContentPackageNotFoundError, InvalidContentTreeError, } from "./CurrentTreeContentLibrary.js";
 const portableTreeUtf8Decoder = new TextDecoder("utf-8", {
     fatal: true,
     ignoreBOM: true,
@@ -78,7 +78,7 @@ export class ContentWorkspace {
     validateCurrentTreeContentPackage(files) {
         normalizeCurrentContentTreeFiles(files, this.#limits);
     }
-    replaceCurrentTreeContentPackage(localId, files, options = {}) {
+    replaceCurrentTreeContentPackage(localId, files, options) {
         return this.#currentTreeLibrary.replaceCurrentTree(localId, files, options);
     }
     setCurrentTreeContentGameplayScheme(localId, scheme, options = {}) {

package/dist/node/runtime/content/CurrentTreeContentLibrary.js

@@ -1,5 +1,5 @@
 import { PackageScriptPermissions } from "../extension/PackageScriptPermissions.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, unlinkSync } from "node:fs";
 import { open, mkdir, readFile, readdir, rename, rm, stat, unlink, } from "node:fs/promises";
 import { linkExclusive } from "../FileNativeExclusiveLink.js";
@@ -31,6 +31,18 @@ export class CurrentTreeContentPackageBusyError extends CurrentTreeContentLibrar
         this.name = "CurrentTreeContentPackageBusyError";
     }
 }
+/**
+ * The current tree changed after the caller's base revision. Nothing was
+ * written; `current` is the tree the caller must reload before saving again.
+ */
+export class ContentTreeConflictError extends CurrentTreeContentLibraryError {
+    current;
+    constructor(current) {
+        super("The content package changed after this draft was opened; load the latest tree before saving");
+        this.name = "ContentTreeConflictError";
+        this.current = current;
+    }
+}
 export class InvalidContentTreeError extends Error {
     constructor(message) {
         super(message);
@@ -216,12 +228,19 @@ export class CurrentTreeContentLibrary {
             }
         });
     }
-    replaceCurrentTree(localId, files, options = {}) {
+    /**
+     * Replace the whole tree only if it is still the revision the draft was
+     * based on. The comparison runs under the package lease, so a publish that
+     * landed after the draft opened cannot be overwritten.
+     */
+    replaceCurrentTree(localId, files, options) {
         return this.#mutate(async () => {
             const lease = await this.acquireOperationLease(localId, {
                 wait: options.waitForLease !== false,
             });
             try {
+                if (lease.package.treeRevision !== options.baseTreeRevision)
+                    throw new ContentTreeConflictError(lease.package);
                 return await lease.replace(files, options);
             }
             finally {
@@ -490,6 +509,7 @@ export class CurrentTreeContentLibrary {
 function detail(localId, title, files, inspection) {
     return {
         ...summary(localId, title, readGameplay(files), inspection),
+        treeRevision: treeRevisionOf(files),
         files: files.map((file) => ({ ...file })),
         documents: structuredClone(inspection.documents),
         issues: structuredClone(inspection.issues),
@@ -497,6 +517,18 @@ function detail(localId, title, files, inspection) {
         control: structuredClone(inspection.control),
     };
 }
+/**
+ * Digest of every file's path, encoding and contents, independent of file
+ * order. Equal trees always share a revision; a tree that returns to earlier
+ * content is equal to it, so a draft based on that content loses nothing.
+ */
+function treeRevisionOf(files) {
+    const hash = createHash("sha256");
+    for (const file of [...files].sort((left, right) => compareStrings(left.path, right.path))) {
+        hash.update(JSON.stringify([file.path, file.encoding ?? null, file.contents]));
+    }
+    return hash.digest("hex");
+}
 function summary(localId, title, gameplay, inspection) {
     return {
         gameplay: { ...gameplay },