narraeon 0.7.2 → 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";
@@ -215,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);
     }
@@ -324,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":

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/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 },

package/dist/node/runtime/model/FileNativeModelAdapters.js

@@ -8,6 +8,8 @@ import { renderPromptDeltaMessage, } from "../prompt/FileNativePromptCompiler.js
 import { aggregateAnthropicModelStream, aggregateChatModelStream, aggregateResponsesModelStream, } from "./ModelHostStream.js";
 import { defaultRuntimeToolDefinitionStrategy, portableRuntimeToolInputSchema, } from "../prompt/FileNativeToolRegistry.js";
 import { AiExchangeCapture, errorDescription, } from "./AiFailureLog.js";
+/** Anthropic allows four cache_control breakpoints per request. */
+const explicitCacheBreakpointLimit = 4;
 const providerContinuationCodecVersion = 1;
 function resolveConnection(connection) {
     const resolved = structuredClone({
@@ -17,6 +19,7 @@ function resolveConnection(connection) {
         reasoningSummary: connection.reasoningSummary ?? "provider_default",
         thinkingMode: connection.thinkingMode ?? "provider_default",
         thinkingBudgetTokens: connection.thinkingBudgetTokens ?? null,
+        cacheSuffixBreakpoint: connection.cacheSuffixBreakpoint ?? true,
     });
     const issue = modelReasoningPolicyIssue({
         provider: resolved.provider,
@@ -95,6 +98,8 @@ export class FileNativeModelHost {
             throw new ModelHostBindingMismatchError("The request protocol does not match the selected model host");
         return new _a({
             ...request.modelConfig,
+            // A frozen request without this choice predates the transcript breakpoint.
+            cacheSuffixBreakpoint: request.modelConfig.cacheSuffixBreakpoint === true,
             baseUrl: this.#connection.baseUrl,
             apiKey: this.#connection.apiKey,
         }, this.#fetch, this.#failureLog);
@@ -458,19 +463,16 @@ async function trace(kind, value) {
         // Explicit acceptance diagnostics must never change provider semantics.
     }
 }
-function items(request) {
-    return request.appended;
-}
 function chatRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
     const allowedTools = providerAllowedTools(request);
     const hasPolicy = hasFrozenToolPolicy(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...chatReasoningRequest(connection),
         messages: [
             ...chatBootstrapMessages(connection, request),
-            ...chatAppend(request),
+            ...chatAppend(connection, request),
         ],
         ...(connection.dialect === "cliproxyapi"
             ? { prompt_cache_key: promptCacheKey(connection, request) }
@@ -495,17 +497,17 @@ function chatRequestBody(connection, request) {
         max_tokens: request.maxOutputTokens,
         stream: true,
         stream_options: { include_usage: true },
-    };
+    });
 }
 function anthropicRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...anthropicReasoningRequest(connection),
         system: request.bootstrap.provider.system,
         messages: [
             ...anthropicBootstrapMessages(request),
-            ...anthropicAppend(request),
+            ...anthropicAppend(connection, request),
         ],
         ...(tools.length === 0
             ? {}
@@ -522,14 +524,14 @@ function anthropicRequestBody(connection, request) {
             : {}),
         max_tokens: request.maxOutputTokens,
         stream: true,
-    };
+    });
 }
 function responsesRequestInput(connection, request) {
     return {
         connection,
         input: [
             ...responsesBootstrapMessages(connection, request),
-            ...responsesAppend(request),
+            ...responsesAppend(connection, request),
         ],
         tools: providerToolDefinitions(request).map((tool) => ({
             name: tool.name,
@@ -555,7 +557,7 @@ function responsesRequestBody(input) {
                 tools: allowedTools.map((name) => ({ type: "function", name })),
             }
             : "auto";
-    return {
+    return checkedCacheBreakpoints({
         model: input.connection.modelId,
         ...responsesReasoningRequest(resolveConnection(input.connection)),
         input: input.input,
@@ -582,7 +584,7 @@ function responsesRequestBody(input) {
         store: false,
         include: ["reasoning.encrypted_content"],
         stream: true,
-    };
+    });
 }
 /**
  * A frozen policy is present when the caller supplies the logical operation's
@@ -758,8 +760,88 @@ function promptCacheKey(connection, request) {
         .update(`${connection.provider}\0${connection.dialect}\0${connection.modelId}\0${scope}`)
         .digest("hex");
 }
-function chatAppend(request) {
-    return items(request).flatMap((item) => {
+/**
+ * Explicit-breakpoint encodings mark the last transcript item before the
+ * request-level suffix, so the next dispatch reads back the transcript it sent.
+ * A request without a suffix keeps its request end as the transcript's entry,
+ * so it is encoded exactly as before.
+ */
+function appendWithSuffixBreakpoint(connection, request, encode, markLast) {
+    const { transcript, suffix } = splitRequestSuffix(request.appended);
+    const encoded = encode(transcript);
+    const breakpoint = suffix.length > 0 &&
+        encoded.length > 0 &&
+        connection.cacheSuffixBreakpoint &&
+        modelCacheStrategy(connection) !== "provider_managed";
+    return [...(breakpoint ? markLast(encoded) : encoded), ...encode(suffix)];
+}
+/** Request-level suffix items are recompiled for every dispatch and never stored. */
+function splitRequestSuffix(appended) {
+    let end = appended.length;
+    while (end > 0 && isRequestSuffix(appended[end - 1]))
+        end -= 1;
+    return { transcript: appended.slice(0, end), suffix: appended.slice(end) };
+}
+function isRequestSuffix(item) {
+    return item.kind === "runtime_notice" && item.notice === "turn_guide";
+}
+/** Message-level cache_control, the form the CLIProxyAPI prefix breakpoints use. */
+function markLastMessage(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        { ...last, cache_control: { type: "ephemeral" } },
+    ];
+}
+/** Thinking blocks reject cache_control, so the breakpoint lands on the last block that accepts it. */
+function markLastAnthropicBlock(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    const content = typeof last.content === "string"
+        ? [{ type: "text", text: last.content }]
+        : Array.isArray(last.content)
+            ? last.content
+            : [];
+    const index = content.findLastIndex((block) => isRecord(block) &&
+        block.type !== "thinking" &&
+        block.type !== "redacted_thinking");
+    if (index < 0)
+        throw new Error("The Anthropic transcript tail has no block that can carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        {
+            ...last,
+            content: content.map((block, position) => position === index
+                ? {
+                    ...block,
+                    cache_control: { type: "ephemeral" },
+                }
+                : block),
+        },
+    ];
+}
+/** Refuses a request over the breakpoint limit instead of silently dropping one. */
+function checkedCacheBreakpoints(body) {
+    const count = countCacheBreakpoints(body);
+    if (count > explicitCacheBreakpointLimit)
+        throw new Error(`The request has ${count} cache breakpoints; the Anthropic limit is ${explicitCacheBreakpointLimit}.`);
+    return body;
+}
+function countCacheBreakpoints(value) {
+    if (Array.isArray(value))
+        return value.reduce((total, item) => total + countCacheBreakpoints(item), 0);
+    if (!isRecord(value))
+        return 0;
+    return Object.entries(value).reduce((total, [key, item]) => total + (key === "cache_control" ? 1 : 0) + countCacheBreakpoints(item), 0);
+}
+function chatAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, chatItems, markLastMessage);
+}
+function chatItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")
@@ -782,7 +864,10 @@ function chatAppend(request) {
         throw continuationError("Chat Completions");
     });
 }
-function anthropicAppend(request) {
+function anthropicAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, anthropicItems, markLastAnthropicBlock);
+}
+function anthropicItems(items) {
     const messages = [];
     let toolResults = [];
     const flushToolResults = () => {
@@ -791,7 +876,7 @@ function anthropicAppend(request) {
         messages.push({ role: "user", content: toolResults });
         toolResults = [];
     };
-    for (const item of items(request)) {
+    for (const item of items) {
         if (item.kind === "tool") {
             toolResults.push({
                 type: "tool_result",
@@ -825,8 +910,11 @@ function anthropicAppend(request) {
     flushToolResults();
     return messages;
 }
-function responsesAppend(request) {
-    return items(request).flatMap((item) => {
+function responsesAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, responsesItems, markLastMessage);
+}
+function responsesItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")

package/dist/node/runtime/play/FileNativePlayAdvanceStore.js

@@ -1,15 +1,18 @@
 import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+/** Written last by the released-record cleanup (ADR-0034); its absence means "not yet run". */
+const LAYOUT_MARKER = "play-advance-layout.json";
 /**
  * The single in-progress play advance of a call chain, if any.
  *
  * It exists only between `begin` and `markSettled`. A marker that survives a
  * restart means the advance was interrupted; the runtime marks the chain
- * interrupted and the player retries. Legacy records from earlier layouts are
- * ignored, so they never block a world from opening.
+ * interrupted and the player retries. Released records from earlier layouts
+ * never block a world from opening, and the storage upgrade removes them
+ * (see `migrateLayout`).
  */
 export class FileNativePlayAdvanceStore {
     #worldsRoot;
@@ -52,6 +55,50 @@ export class FileNativePlayAdvanceStore {
             force: true,
         });
     }
+    /**
+     * Whether the world's advance records are free of the pre-ADR-0044 layout
+     * (ADR-0034). Reads never write: a world with no released records is current
+     * without a marker.
+     */
+    async layoutCurrent(worldId) {
+        assertIdentity(worldId, "World ID");
+        if ((await readOptionalJson(this.#layoutMarkerPath(worldId))) !==
+            null)
+            return true;
+        return (await this.#releasedChainRoots(worldId)).length === 0;
+    }
+    /**
+     * Remove the released `records/` and `current.json` of every chain. Each
+     * chain's `in-progress.json` stays as it is, and a chain left empty is removed.
+     * The marker is written last, so an interrupted run simply runs again.
+     */
+    async migrateLayout(worldId) {
+        assertIdentity(worldId, "World ID");
+        if (await this.layoutCurrent(worldId))
+            return;
+        for (const chainRoot of await this.#releasedChainRoots(worldId)) {
+            await rm(join(chainRoot, "records"), { recursive: true, force: true });
+            await rm(join(chainRoot, "current.json"), { force: true });
+            if ((await readdir(chainRoot)).length === 0)
+                await rm(chainRoot, { recursive: true, force: true });
+        }
+        await publishJson(this.#layoutMarkerPath(worldId), layoutMarker());
+    }
+    /** Chain directories that still hold a released record or pointer. */
+    async #releasedChainRoots(worldId) {
+        const advancesRoot = join(this.#worldsRoot, worldId, "runtime", "play-advances");
+        const roots = [];
+        for (const name of await readDirectoryNames(advancesRoot)) {
+            const chainRoot = join(advancesRoot, name);
+            if ((await pathExists(join(chainRoot, "records"))) ||
+                (await pathExists(join(chainRoot, "current.json"))))
+                roots.push(chainRoot);
+        }
+        return roots;
+    }
+    #layoutMarkerPath(worldId) {
+        return join(this.#worldsRoot, worldId, "runtime", LAYOUT_MARKER);
+    }
     #markerPath(worldId, chainId) {
         return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "in-progress.json");
     }
@@ -120,6 +167,26 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
+async function readDirectoryNames(directory) {
+    try {
+        return await readdir(directory);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function pathExists(path) {
+    return stat(path).then(() => true, (error) => {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+}
+function layoutMarker() {
+    return { schemaVersion: 1, kind: "play_advance_layout" };
+}
 /** Atomic publish: write a temporary file, then rename over the target. */
 async function publishJson(path, value) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });

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

@@ -106,7 +106,8 @@ export class FileNativeWorldStore {
             const root = join(this.#worldsRoot, worldId);
             const authority = new WorldLedgerAuthority(root);
             if ((await authority.exists()) &&
-                (await this.playTimeline.layoutCurrent(worldId))) {
+                (await this.playTimeline.layoutCurrent(worldId)) &&
+                (await this.playAdvances.layoutCurrent(worldId))) {
                 await authority.readHead();
                 this.#currentStorage.add(worldId);
                 return;

package/dist/node/server/createServer.js

@@ -91,6 +91,7 @@ export async function createServer(input) {
                 return await input.runtime.worldArchives.upload(request.body);
             }
             catch (error) {
+                await input.runtime.recordArchiveFailure({ type: "world.archive.upload" }, error);
                 if (error instanceof WorldArchiveError)
                     return reply
                         .status(error.code === "limit_exceeded" ? 413 : 400)
@@ -98,6 +99,21 @@ export async function createServer(input) {
                 throw error;
             }
         });
+        // The browser checks this before it starts the one-time download, so a
+        // missing or failing export is reported on the page instead of a blank file.
+        archives.get("/api/runtime/v1/world-archives/:archiveId/check", async (request, reply) => {
+            try {
+                await input.runtime.worldArchives.checkDownload(request.params.archiveId);
+                return reply.status(204).send();
+            }
+            catch (error) {
+                await input.runtime.recordArchiveFailure({
+                    type: "world.archive.download",
+                    archiveId: request.params.archiveId,
+                }, error);
+                return archiveDownloadFailure(reply, error);
+            }
+        });
         archives.get("/api/runtime/v1/world-archives/:archiveId", async (request, reply) => {
             try {
                 const archive = await input.runtime.worldArchives.download(request.params.archiveId);
@@ -111,20 +127,11 @@ export async function createServer(input) {
                     .send(archive.stream);
             }
             catch (error) {
-                if (error instanceof WorldArchiveError)
-                    return reply
-                        .status(400)
-                        .send({ error: { code: error.code, message: error.message } });
-                if (error instanceof Error &&
-                    "code" in error &&
-                    error.code === "ENOENT")
-                    return reply.status(404).send({
-                        error: {
-                            code: "invalid_archive",
-                            message: "The archive download is unavailable",
-                        },
-                    });
-                throw error;
+                await input.runtime.recordArchiveFailure({
+                    type: "world.archive.download",
+                    archiveId: request.params.archiveId,
+                }, error);
+                return archiveDownloadFailure(reply, error);
             }
         });
         done();
@@ -160,13 +167,19 @@ export async function createServer(input) {
         }
         catch (error) {
             if (error instanceof V1ProtocolError) {
-                // 端点已被回退丢弃：客户端应重新读取当前世界，不是服务端错误。
-                const status = error.code === "endpoint_discarded" ? 409 : 400;
+                // 端点已被回退丢弃或内容包已被其他操作修改：客户端应重新读取，不是服务端错误。
+                const status = error.code === "endpoint_discarded" ||
+                    error.code === "content_conflict"
+                    ? 409
+                    : 400;
                 return reply.status(status).send({
                     protocol: "narraeon.runtime/v1",
                     error: {
                         code: error.code,
                         message: error.message,
+                        ...(error.details === undefined
+                            ? {}
+                            : { details: error.details }),
                     },
                 });
             }
@@ -182,6 +195,20 @@ export async function createServer(input) {
     server.get("/index.html", index);
     return server;
 }
+function archiveDownloadFailure(reply, error) {
+    if (error instanceof WorldArchiveError)
+        return reply
+            .status(400)
+            .send({ error: { code: error.code, message: error.message } });
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+        return reply.status(404).send({
+            error: {
+                code: "invalid_archive",
+                message: "The archive download is unavailable",
+            },
+        });
+    throw error;
+}
 function acceptsPlayCallChainStream(request) {
     const accept = request.headers.accept;
     return (typeof accept === "string" &&