narraeon 0.7.0 → 0.7.2

package/dist/node/runtime/V1Runtime.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" ||
@@ -415,9 +420,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 +517,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 +558,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 +736,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 +777,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 +854,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/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;
+}