narraeon 0.7.1 → 0.7.4

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

@@ -20,7 +20,7 @@ import { FileNativePlayTimelineStore } from "../play/FileNativePlayTimelineStore
 import { FileNativePlayAdvanceStore } from "../play/FileNativePlayAdvanceStore.js";
 import { FileNativeWorldStorageMigrator, UnsupportedLegacyStorageError, } from "./FileNativeWorldStorageMigrator.js";
 import { WorldAuthorityError, WorldLedgerAuthority, } from "./WorldLedgerAuthority.js";
-import { forgetLedger, rewindTo } from "./WorldTurnLedger.js";
+import { forgetLedger, rewindTo, WorldTurnLedgerError, } from "./WorldTurnLedger.js";
 import { FileNativeWorldOperationCoordinator, WorldOperationBusyError, } from "./WorldOperationCoordinator.js";
 import { projectFileNativeHistorySurface, projectHistoryBackgrounds, historyBackgroundRecord, } from "./FileNativeHistoryProjection.js";
 const publicationFile = "publication.json";
@@ -105,7 +105,9 @@ export class FileNativeWorldStore {
         try {
             const root = join(this.#worldsRoot, worldId);
             const authority = new WorldLedgerAuthority(root);
-            if (await authority.exists()) {
+            if ((await authority.exists()) &&
+                (await this.playTimeline.layoutCurrent(worldId)) &&
+                (await this.playAdvances.layoutCurrent(worldId))) {
                 await authority.readHead();
                 this.#currentStorage.add(worldId);
                 return;
@@ -465,12 +467,14 @@ export class FileNativeWorldStore {
         assertIdentity(worldId, "World ID");
         await rm(join(this.#worldsRoot, worldId, "runtime", "archive-import.json"), { force: true });
     }
-    async currentHeadOperationId(worldId) {
+    /** 端点名称与它的操作标识取自同一次读取，回退不会让两者分属不同端点。 */
+    async currentEndpoint(worldId) {
         assertIdentity(worldId, "World ID");
         await this.ensureCurrentStorage(worldId);
         const root = join(this.#worldsRoot, worldId);
         await readPublicationAt(root);
-        return new WorldLedgerAuthority(root).currentOperationId();
+        const { head, operationId } = await new WorldLedgerAuthority(root).readHead();
+        return { head, operationId };
     }
     async saveControlDraft(worldId, files) {
         assertIdentity(worldId, "World ID");
@@ -793,6 +797,9 @@ 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);
         }
     }

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 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, readFileAt, readHead as readLedgerHead, readTreeAt, readTurnDigest, resolveEndpoint, } from "./WorldTurnLedger.js";
+import { appendTurn, initializeLedger, listTurns, readEndpoint, readFileAt, readHead as readLedgerHead, readTreeAt, readTurnDigest, resolveEndpoint, } from "./WorldTurnLedger.js";
 export class WorldAuthorityError extends Error {
     code;
     constructor(code, message) {
@@ -56,28 +56,31 @@ export class WorldLedgerAuthority {
     async initialize() {
         await initializeLedger(this.#root);
     }
-    /** 当前端点：逻辑位置（回退后即被恢复的轮）及其元数据。 */
+    /** 当前端点：逻辑位置（回退后即被恢复的轮）及其元数据，三者取自同一份账本视图。 */
     async readHead() {
-        const physical = await readLedgerHead(this.#root);
-        const position = await resolveEndpoint(this.#root, physical);
+        const endpoint = await readEndpoint(this.#root);
+        const { sequence } = endpoint;
         return {
-            head: headName(position),
-            sequence: position,
-            operationId: await this.#operationIdAt(position),
-            commitDigest: await readTurnDigest(this.#root, position),
+            head: headName(sequence),
+            sequence,
+            operationId: await this.#operationIdAt(sequence, endpoint.record),
+            commitDigest: endpoint.digest,
         };
     }
     async currentOperationId() {
         return (await this.readHead()).operationId;
     }
-    async #operationIdAt(position) {
+    async #operationIdAt(position, record) {
         if (position === 0) {
             const genesis = await readJsonOrNull(join(this.#root, genesisFile));
             return typeof genesis?.operationId === "string"
                 ? genesis.operationId
                 : null;
         }
-        return (await this.#commitAtPosition(position)).operationId;
+        const commit = record?.payload;
+        if (commit?.sequence !== position)
+            throw new WorldAuthorityError("corrupt", `第 ${position} 轮缺少提交元数据`);
+        return commit.operationId;
     }
     async #positionOf(head) {
         if (head === undefined)

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

@@ -154,6 +154,10 @@ export class FileNativeWorldOperationCoordinator {
     isWorldHeld(worldId) {
         return this.#queue.isHeld(worldId);
     }
+    /** World operations for this world that are running or waiting for their turn. */
+    pendingWorldOperations(worldId) {
+        return this.#queue.pendingCount(worldId);
+    }
     #releaseClaim(handle) {
         const current = this.#claims.get(handle.worldId);
         if (current?.operationId === handle.operationId &&

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

@@ -11,6 +11,7 @@ import { resolve } from "node:path";
  */
 export class WorldQueue {
     #tails = new Map();
+    #pending = new Map();
     #held = new AsyncLocalStorage();
     run(worldId, action) {
         const held = this.#held.getStore();
@@ -19,8 +20,9 @@ export class WorldQueue {
         const previous = this.#tails.get(worldId) ?? Promise.resolve();
         const nextHeld = new Set(held ?? []);
         nextHeld.add(worldId);
+        this.#pending.set(worldId, this.pendingCount(worldId) + 1);
         const result = previous.then(() => this.#held.run(nextHeld, action));
-        const tail = result.then(() => undefined, () => undefined);
+        const tail = result.then(() => this.#finish(worldId), () => this.#finish(worldId));
         this.#tails.set(worldId, tail);
         void tail.then(() => {
             if (this.#tails.get(worldId) === tail)
@@ -28,10 +30,21 @@ export class WorldQueue {
         });
         return result;
     }
+    /** Operations for worldId that are running or waiting for their turn. */
+    pendingCount(worldId) {
+        return this.#pending.get(worldId) ?? 0;
+    }
     /** True while the current async context is inside an operation for worldId. */
     isHeld(worldId) {
         return this.#held.getStore()?.has(worldId) ?? false;
     }
+    #finish(worldId) {
+        const remaining = this.pendingCount(worldId) - 1;
+        if (remaining > 0)
+            this.#pending.set(worldId, remaining);
+        else
+            this.#pending.delete(worldId);
+    }
 }
 const queuesByDataRoot = new Map();
 /** The queue shared by every store that changes a world under one data root. */

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

@@ -78,22 +78,32 @@ async function readAllRecords(root) {
             return [];
         throw error;
     }
-    const records = [];
+    const turns = [];
     for (const name of names) {
         if (!name.endsWith(".json"))
             continue;
-        const text = await readFile(join(root, turnsDirectory, name), "utf8");
-        records.push(JSON.parse(text));
+        // 回退在发布端点之后才删除被丢弃的轮记录：读到一半消失的记录一定已被丢弃，跳过即可。
+        // 端点若在读取期间变化，loadView 会重新读取。
+        const text = await readTextOrNull(join(root, turnsDirectory, name));
+        if (text === null)
+            continue;
+        turns.push({
+            record: JSON.parse(text),
+            digest: createHash("sha256").update(text).digest("hex"),
+        });
     }
-    return records.sort((left, right) => left.sequence - right.sequence);
+    return turns.sort((left, right) => left.record.sequence - right.record.sequence);
 }
 // 被某个 rewind 丢弃的轮是 (restores, rewind) 之间的位置；它们可能仍在磁盘上，
 // 直到清理完成，但读取时一律忽略。
-function viewOf(head, records) {
+function viewOf(head, turns) {
     const byPosition = new Map();
-    for (const record of records) {
-        if (record.sequence <= head)
-            byPosition.set(record.sequence, record);
+    const digests = new Map();
+    for (const { record, digest } of turns) {
+        if (record.sequence > head)
+            continue;
+        byPosition.set(record.sequence, record);
+        digests.set(record.sequence, digest);
     }
     const discarded = new Set();
     for (const record of byPosition.values()) {
@@ -103,21 +113,28 @@ function viewOf(head, records) {
             discarded.add(position);
         }
     }
-    return { head, byPosition, discarded };
+    return { head, byPosition, digests, discarded };
 }
 // 进程内视图缓存，按端点失效。一个数据目录只被一个进程操作（ADR-0044），
 // 所以 head 相同即记录相同：任何改变可见记录的写入都会先推进 head。
 // 只有 beginTurn 与 recoverIncomplete 会在 head 之上写入或删除记录，它们不影响视图
 // （视图只包含序号不大于 head 的记录，且 recoverIncomplete 本身会在结束时失效缓存）。
 const viewCache = new Map();
+// 一次读取只解析一个视图。回退先发布新端点、再删除被丢弃的轮记录：读完记录后端点仍未变化，
+// 说明读到的记录与这个端点一致；端点变了就用新端点重新读取。
 async function loadView(root) {
-    const head = await readHead(root);
-    const cached = viewCache.get(resolve(root));
-    if (cached?.head === head)
-        return cached;
-    const view = viewOf(head, await readAllRecords(root));
-    viewCache.set(resolve(root), view);
-    return view;
+    for (;;) {
+        const head = await readHead(root);
+        const cached = viewCache.get(resolve(root));
+        if (cached?.head === head)
+            return cached;
+        const turns = await readAllRecords(root);
+        if ((await readHead(root)) !== head)
+            continue;
+        const view = viewOf(head, turns);
+        viewCache.set(resolve(root), view);
+        return view;
+    }
 }
 // 世界目录被删除、归档导入或分叉发布到已存在路径之前调用：下一次读取从磁盘重建视图。
 export function forgetLedger(root) {
@@ -133,7 +150,7 @@ function resolvePosition(view, sequence) {
         if (position === 0)
             return 0;
         if (view.discarded.has(position)) {
-            throw new WorldTurnLedgerError("unreachable", `端点 ${sequence} 已被回退丢弃`);
+            throw new WorldTurnLedgerError("discarded", `端点 ${sequence} 已被回退丢弃`);
         }
         const record = view.byPosition.get(position);
         if (!record) {
@@ -217,8 +234,9 @@ export async function appendTurn(root, input) {
 // 被丢弃的轮记录（读取时已忽略）在这里清理。返回是否回滚了未完成的轮。
 export async function recoverIncomplete(root) {
     const head = await readHead(root);
-    const records = await readAllRecords(root);
-    const incomplete = records
+    const turns = await readAllRecords(root);
+    const incomplete = turns
+        .map(({ record }) => record)
         .filter((record) => record.sequence > head)
         .sort((left, right) => right.sequence - left.sequence);
     for (const record of incomplete) {
@@ -234,7 +252,7 @@ export async function recoverIncomplete(root) {
         }
         await rm(join(root, turnFileName(record.sequence)), { force: true });
     }
-    const view = viewOf(head, records);
+    const view = viewOf(head, turns);
     for (const position of view.discarded) {
         await rm(join(root, turnFileName(position)), { force: true });
     }
@@ -259,6 +277,16 @@ export async function listTurns(root) {
 export async function resolveEndpoint(root, sequence) {
     return resolvePosition(await loadView(root), sequence);
 }
+// 当前端点的逻辑位置、它的轮记录与记录摘要，三者来自同一个视图。
+export async function readEndpoint(root) {
+    const view = await loadView(root);
+    const sequence = resolvePosition(view, view.head);
+    return {
+        sequence,
+        record: view.byPosition.get(sequence) ?? null,
+        digest: view.digests.get(sequence) ?? null,
+    };
+}
 // 第 sequence 轮记录文件的 sha256；0 轮没有记录，返回 null。
 export async function readTurnDigest(root, sequence) {
     if (sequence === 0)

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,11 +167,19 @@ export async function createServer(input) {
         }
         catch (error) {
             if (error instanceof V1ProtocolError) {
-                return reply.status(400).send({
+                // 端点已被回退丢弃或内容包已被其他操作修改：客户端应重新读取，不是服务端错误。
+                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 }),
                     },
                 });
             }
@@ -180,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" &&

package/dist/node/server/startWebServer.js

@@ -1,11 +1,11 @@
-import { acquireDataRootLock } from "../runtime/config/dataRootLock.js";
+import { prepareDataRoot } from "../runtime/config/dataRootCleanup.js";
 import { createRuntime } from "./createRuntime.js";
 import { createServer } from "./createServer.js";
 export const defaultWebPort = 4317;
 export const defaultWebHost = "127.0.0.1";
 export const containerWebHost = "0.0.0.0";
 export async function startWebServer(input) {
-    const lock = await acquireDataRootLock(input.paths.dataRoot);
+    await prepareDataRoot(input.paths.dataRoot);
     let server;
     try {
         const runtime = await createRuntime(input.paths);
@@ -15,15 +15,12 @@ export async function startWebServer(input) {
             port: input.port,
             ...(input.logger === undefined ? {} : { logger: input.logger }),
         });
-        server.addHook("onClose", () => lock.release());
         await server.listen({ host: input.host, port: input.port });
         return server;
     }
     catch (error) {
         if (server !== undefined)
             await server.close().catch(() => undefined);
-        else
-            await lock.release();
         throw error;
     }
 }