narraeon 0.6.0 → 0.6.1

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

@@ -1,14 +1,15 @@
-import { isNarrativeOrigin, isHistoryBackground, } from "../history/HistoryBackground.js";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { link, mkdir, open, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 /**
- * Durable progress facts for the one play advance currently being settled.
+ * The single in-progress play advance of a call chain, if any.
  *
- * Every stage is immutable. `current.json` is only a small lookup projection;
- * deleting it cannot change Authority and a repeated user operation keeps the
- * same deterministic advance identity.
+ * 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.
  */
 export class FileNativePlayAdvanceStore {
     #worldsRoot;
@@ -18,121 +19,41 @@ export class FileNativePlayAdvanceStore {
     async begin(base) {
         assertBase(base);
         const current = await this.readCurrent(base.worldId, base.chainId);
-        if (current !== null && current.settled === null) {
-            if (!sameAdvanceBase(current.base, base))
+        if (current !== null) {
+            if (!sameAdvanceBase(current, base))
                 throw new Error("Another play advance is still awaiting settlement");
             return;
         }
-        const basePath = this.#factPath(base, "base.json");
-        const existing = await readOptionalJson(basePath);
-        if (existing === null)
-            await publishImmutableJson(basePath, base);
-        else {
-            assertBase(existing);
-            if (!sameAdvanceBase(existing, base))
-                throw new Error("A play advance identity is bound to different data");
-        }
-        await publishJson(this.#currentPath(base.worldId, base.chainId), {
-            schemaVersion: 1,
-            worldId: base.worldId,
-            chainId: base.chainId,
-            advanceId: base.advanceId,
-        });
-    }
-    async recordProviderCompleted(base, response) {
-        const durableBase = await this.#assertCurrent(base);
-        await publishImmutableJson(this.#factPath(base, "provider-completed.json"), {
-            schemaVersion: 1,
-            stage: "provider_completed",
-            response: structuredClone(response),
-            recordedAt: durableBase.createdAt,
-        });
-    }
-    async recordSettlementPrepared(base, settlement) {
-        const durableBase = await this.#assertCurrent(base);
-        await publishImmutableJson(this.#factPath(base, "settlement-prepared.json"), {
-            schemaVersion: 1,
-            stage: "settlement_prepared",
-            settlement: structuredClone(settlement),
-            recordedAt: durableBase.createdAt,
-        });
-    }
-    /**
-     * Return the advance's secret resolution seed, creating it on first need.
-     * Recovery reads the same fact, so every tool call in the advance draws from
-     * one persisted stream and a crashed batch cannot resample.
-     */
-    async resolutionSeed(base) {
-        const durableBase = await this.#assertCurrent(base);
-        const path = this.#factPath(base, "resolution-seed.json");
-        if ((await readOptionalJson(path)) === null) {
-            try {
-                await publishImmutableJson(path, {
-                    schemaVersion: 1,
-                    stage: "resolution_seed",
-                    seed: randomBytes(32).toString("hex"),
-                    recordedAt: durableBase.createdAt,
-                });
-            }
-            catch (error) {
-                // A concurrent writer may have published first; the stored fact wins.
-                if ((await readOptionalJson(path)) === null)
-                    throw error;
-            }
-        }
-        const fact = await readJson(path);
-        assertResolutionSeedFact(fact);
-        return fact.seed;
-    }
-    async markSettled(base, head) {
-        const durableBase = await this.#assertCurrent(base);
-        await publishImmutableJson(this.#factPath(base, "settled.json"), {
-            schemaVersion: 1,
-            stage: "settled",
-            head,
-            recordedAt: durableBase.createdAt,
-        });
+        await publishJson(this.#markerPath(base.worldId, base.chainId), base);
     }
     async readCurrent(worldId, chainId) {
         assertIdentity(worldId, "World ID");
         assertIdentity(chainId, "Call-chain ID");
-        const pointer = await readOptionalJson(this.#currentPath(worldId, chainId));
-        if (pointer === null)
+        const value = await readOptionalJson(this.#markerPath(worldId, chainId));
+        if (value === null)
             return null;
-        assertPointer(pointer);
-        if (pointer.worldId !== worldId || pointer.chainId !== chainId)
-            throw new Error("Play advance pointer belongs to another context");
-        const recordRoot = this.#recordRoot(worldId, chainId, pointer.advanceId);
-        const [base, providerCompleted, settlementPrepared, settled] = await Promise.all([
-            readJson(join(recordRoot, "base.json")),
-            readOptionalJson(join(recordRoot, "provider-completed.json")),
-            readOptionalJson(join(recordRoot, "settlement-prepared.json")),
-            readOptionalJson(join(recordRoot, "settled.json")),
-        ]);
-        assertBase(base);
-        if (base.worldId !== worldId ||
-            base.chainId !== chainId ||
-            base.advanceId !== pointer.advanceId)
-            throw new Error("Play advance durable identity is inconsistent");
-        assertProviderCompleted(providerCompleted);
-        assertSettlementPrepared(settlementPrepared);
-        assertSettled(settled);
-        return { base, providerCompleted, settlementPrepared, settled };
+        assertBase(value);
+        if (value.worldId !== worldId || value.chainId !== chainId)
+            throw new Error("Play advance marker belongs to another context");
+        return value;
     }
-    async #assertCurrent(base) {
+    async markSettled(base) {
         const current = await this.readCurrent(base.worldId, base.chainId);
-        if (current === null || !sameAdvanceBase(current.base, base))
+        if (current === null)
+            return;
+        if (!sameAdvanceBase(current, base))
             throw new Error("Play advance is no longer current");
-        return current.base;
+        await rm(this.#markerPath(base.worldId, base.chainId), { force: true });
     }
-    #currentPath(worldId, chainId) {
-        return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "current.json");
-    }
-    #recordRoot(worldId, chainId, advanceId) {
-        return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "records", digest(advanceId));
+    /** Remove the in-progress marker and all advance records of a discarded chain. */
+    async discardChain(worldId, chainId) {
+        await rm(dirname(this.#markerPath(worldId, chainId)), {
+            recursive: true,
+            force: true,
+        });
     }
-    #factPath(base, name) {
-        return join(this.#recordRoot(base.worldId, base.chainId, base.advanceId), name);
+    #markerPath(worldId, chainId) {
+        return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "in-progress.json");
     }
 }
 function sameAdvanceBase(left, right) {
@@ -142,15 +63,6 @@ function sameAdvanceBase(left, right) {
     void rightCreatedAt;
     return isDeepStrictEqual(leftIdentity, rightIdentity);
 }
-function assertResolutionSeedFact(value) {
-    if (!isRecord(value) ||
-        value.schemaVersion !== 1 ||
-        value.stage !== "resolution_seed" ||
-        typeof value.seed !== "string" ||
-        !/^[a-f0-9]{64}$/.test(value.seed) ||
-        typeof value.recordedAt !== "number")
-        throw new Error("Invalid persisted resolution seed");
-}
 function assertBase(value) {
     if (!isRecord(value) ||
         value.schemaVersion !== 1 ||
@@ -188,40 +100,6 @@ function assertBase(value) {
         Number(value.attempt) < 1)
         throw new Error("Response advance has an invalid shape");
 }
-function assertPointer(value) {
-    if (!isRecord(value) ||
-        value.schemaVersion !== 1 ||
-        typeof value.worldId !== "string" ||
-        typeof value.chainId !== "string" ||
-        typeof value.advanceId !== "string")
-        throw new Error("Play advance pointer has an invalid shape");
-}
-function assertProviderCompleted(value) {
-    if (value !== null &&
-        (value.schemaVersion !== 1 ||
-            value.stage !== "provider_completed" ||
-            !isRecord(value.response) ||
-            typeof value.recordedAt !== "number"))
-        throw new Error("Provider-completed play fact has an invalid shape");
-}
-function assertSettlementPrepared(value) {
-    if (value !== null &&
-        (value.schemaVersion !== 1 ||
-            value.stage !== "settlement_prepared" ||
-            !isRecord(value.settlement) ||
-            (value.settlement.background !== undefined &&
-                !isHistoryBackground(value.settlement.background)) ||
-            typeof value.recordedAt !== "number"))
-        throw new Error("Settlement-prepared play fact has an invalid shape");
-}
-function assertSettled(value) {
-    if (value !== null &&
-        (value.schemaVersion !== 1 ||
-            value.stage !== "settled" ||
-            typeof value.head !== "string" ||
-            typeof value.recordedAt !== "number"))
-        throw new Error("Settled play fact has an invalid shape");
-}
 function digest(value) {
     return createHash("sha256").update(value).digest("hex");
 }
@@ -232,12 +110,9 @@ function assertIdentity(value, label) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-async function readJson(path) {
-    return JSON.parse(await readFile(path, "utf8"));
-}
 async function readOptionalJson(path) {
     try {
-        return await readJson(path);
+        return JSON.parse(await readFile(path, "utf8"));
     }
     catch (error) {
         if (isNodeError(error) && error.code === "ENOENT")
@@ -245,6 +120,7 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
+/** Atomic publish: write a temporary file, then rename over the target. */
 async function publishJson(path, value) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${randomUUID()}.tmp`;
@@ -252,58 +128,7 @@ async function publishJson(path, value) {
         encoding: "utf8",
         mode: 0o600,
     });
-    await syncFile(temporary);
     await rename(temporary, path);
-    await syncDirectory(dirname(path));
-}
-async function publishImmutableJson(path, value) {
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const existing = await readOptionalJson(path);
-    if (existing !== null) {
-        if (!isDeepStrictEqual(existing, value))
-            throw new Error("Immutable play-advance fact already has different data");
-        return;
-    }
-    const temporary = `${path}.${randomUUID()}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    await syncFile(temporary);
-    try {
-        await link(temporary, path);
-    }
-    catch (error) {
-        if (!isNodeError(error) || error.code !== "EEXIST")
-            throw error;
-        const published = await readJson(path);
-        if (!isDeepStrictEqual(published, value))
-            throw new Error("Concurrent immutable play-advance fact conflicts", {
-                cause: error,
-            });
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
-    await syncDirectory(dirname(path));
-}
-async function syncFile(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function syncDirectory(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
 }
 function isNodeError(error) {
     return error instanceof Error && "code" in error;