narraeon 0.1.1 → 0.2.0

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

@@ -0,0 +1,269 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, mkdir, open, 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.
+ *
+ * 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.
+ */
+export class FileNativePlayAdvanceStore {
+    #worldsRoot;
+    constructor(dataRoot) {
+        this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
+    }
+    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))
+                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,
+        });
+    }
+    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,
+        });
+    }
+    async readCurrent(worldId, chainId) {
+        assertIdentity(worldId, "World ID");
+        assertIdentity(chainId, "Call-chain ID");
+        const pointer = await readOptionalJson(this.#currentPath(worldId, chainId));
+        if (pointer === 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 };
+    }
+    async #assertCurrent(base) {
+        const current = await this.readCurrent(base.worldId, base.chainId);
+        if (current === null || !sameAdvanceBase(current.base, base))
+            throw new Error("Play advance is no longer current");
+        return current.base;
+    }
+    #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));
+    }
+    #factPath(base, name) {
+        return join(this.#recordRoot(base.worldId, base.chainId, base.advanceId), name);
+    }
+}
+function sameAdvanceBase(left, right) {
+    const { createdAt: leftCreatedAt, ...leftIdentity } = left;
+    const { createdAt: rightCreatedAt, ...rightIdentity } = right;
+    void leftCreatedAt;
+    void rightCreatedAt;
+    return isDeepStrictEqual(leftIdentity, rightIdentity);
+}
+function assertBase(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "play_advance" ||
+        (value.advanceKind !== "player" && value.advanceKind !== "response") ||
+        typeof value.worldId !== "string" ||
+        typeof value.chainId !== "string" ||
+        typeof value.advanceId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.parentHead !== "string" ||
+        !Number.isSafeInteger(value.eventId) ||
+        Number(value.eventId) < 1 ||
+        typeof value.createdAt !== "number")
+        throw new Error("Play advance base has an invalid shape");
+    assertIdentity(value.worldId, "World ID");
+    assertIdentity(value.chainId, "Call-chain ID");
+    assertIdentity(value.advanceId, "Advance ID");
+    assertIdentity(value.operationId, "Operation ID");
+    if (value.advanceKind === "player") {
+        if (typeof value.exchangeId !== "string" ||
+            typeof value.playerText !== "string" ||
+            (value.context !== "fresh" && value.context !== "append") ||
+            !Number.isSafeInteger(value.transcriptStart) ||
+            Number(value.transcriptStart) < 0 ||
+            !Number.isSafeInteger(value.exchange) ||
+            Number(value.exchange) < 1 ||
+            !isRecord(value.nextRequest))
+            throw new Error("Player advance has an invalid shape");
+    }
+    else if (!Number.isSafeInteger(value.exchange) ||
+        Number(value.exchange) < 0 ||
+        !Number.isSafeInteger(value.attempt) ||
+        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) ||
+            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");
+}
+function assertIdentity(value, label) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u.test(value))
+        throw new TypeError(`${label} is invalid`);
+}
+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);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function publishJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+        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;
+}