narraeon 0.6.0 → 0.6.2

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

@@ -0,0 +1,340 @@
+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";
+export class WorldAuthorityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorldAuthorityError";
+        this.code = code;
+    }
+}
+const genesisFile = join("runtime", "genesis.json");
+const materialsFile = join("runtime", "additional-materials.json");
+function headName(position) {
+    return position === 0 ? "genesis" : `commit:${String(position)}`;
+}
+function parsePosition(head) {
+    if (head === "genesis")
+        return 0;
+    const match = /^commit:([1-9][0-9]*)$/u.exec(head);
+    if (match === null)
+        throw new WorldAuthorityError("corrupt", `端点名称不合法：${head}`);
+    return Number.parseInt(match[1], 10);
+}
+async function readJsonOrNull(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return typeof error === "object" && error !== null && "code" in error;
+}
+export class WorldLedgerAuthority {
+    #root;
+    constructor(worldRoot) {
+        this.#root = worldRoot;
+    }
+    async exists() {
+        try {
+            await stat(join(this.#root, "runtime", "head.json"));
+            return true;
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    async initialize() {
+        await initializeLedger(this.#root);
+    }
+    /** 当前端点：逻辑位置（回退后即被恢复的轮）及其元数据。 */
+    async readHead() {
+        const physical = await readLedgerHead(this.#root);
+        const position = await resolveEndpoint(this.#root, physical);
+        return {
+            head: headName(position),
+            sequence: position,
+            operationId: await this.#operationIdAt(position),
+            commitDigest: await readTurnDigest(this.#root, position),
+        };
+    }
+    async currentOperationId() {
+        return (await this.readHead()).operationId;
+    }
+    async #operationIdAt(position) {
+        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;
+    }
+    async #positionOf(head) {
+        if (head === undefined)
+            return (await this.readHead()).sequence;
+        return resolveEndpoint(this.#root, parsePosition(head));
+    }
+    async #commitAtPosition(position) {
+        const turn = (await listTurns(this.#root)).find((candidate) => candidate.sequence === position);
+        const commit = turn?.payload;
+        if (commit?.sequence !== position)
+            throw new WorldAuthorityError("corrupt", `第 ${position} 轮缺少提交元数据`);
+        return commit;
+    }
+    /** 端点位置处可见的全部提交（按轮号），不含 genesis 与回退轮。 */
+    async #commitsUpTo(position) {
+        const turns = await listTurns(this.#root);
+        return turns
+            .filter((turn) => turn.sequence <= position && turn.payload !== undefined)
+            .map((turn) => turn.payload);
+    }
+    async #genesisHistory() {
+        const genesis = await readJsonOrNull(join(this.#root, genesisFile));
+        return structuredClone(genesis?.history ?? []);
+    }
+    async #materialsAt(position) {
+        const text = await readFileAt(this.#root, position, materialsFile);
+        if (text === null)
+            return [];
+        const parsed = JSON.parse(text);
+        return structuredClone(parsed.items ?? []);
+    }
+    async #stateAt(position) {
+        const tree = await readTreeAt(this.#root, position, ["state"]);
+        return [...tree]
+            .map(([path, contents]) => ({
+            path: path.slice("state/".length),
+            contents,
+        }))
+            .sort((left, right) => left.path.localeCompare(right.path));
+    }
+    #checkpointAt(commits) {
+        for (let index = commits.length - 1; index >= 0; index -= 1) {
+            const commit = commits[index];
+            if (commit.narrativeCheckpoint === undefined)
+                continue;
+            return {
+                ...commit.narrativeCheckpoint,
+                head: commit.head,
+                historyMessageId: commit.historyAppend.at(-1)?.messageId ?? "",
+            };
+        }
+        return undefined;
+    }
+    async recover(head) {
+        const position = await this.#positionOf(head);
+        const commits = await this.#commitsUpTo(position);
+        const history = [
+            ...(await this.#genesisHistory()),
+            ...commits.flatMap((commit) => commit.historyAppend),
+        ];
+        const checkpoint = this.#checkpointAt(commits);
+        return {
+            head: headName(position),
+            state: await this.#stateAt(position),
+            history: structuredClone(history),
+            additionalMaterials: await this.#materialsAt(position),
+            ...(checkpoint === undefined
+                ? {}
+                : { narrativeCheckpoint: structuredClone(checkpoint) }),
+        };
+    }
+    async recoverHeadResult() {
+        return this.recover();
+    }
+    async readNarrativeCheckpoint(head) {
+        const position = await this.#positionOf(head);
+        return this.#checkpointAt(await this.#commitsUpTo(position));
+    }
+    async recoverState(head) {
+        return this.#stateAt(await this.#positionOf(head));
+    }
+    async recoverMaterials(head) {
+        return this.#materialsAt(await this.#positionOf(head));
+    }
+    async readHistory() {
+        const position = await this.#positionOf();
+        return {
+            head: headName(position),
+            commits: await this.#commitsUpTo(position),
+        };
+    }
+    /** 已提交的一轮；genesis 没有提交，返回 null。 */
+    async commitAt(head) {
+        const position = await this.#positionOf(head);
+        if (position === 0)
+            return null;
+        return this.#commitAtPosition(position);
+    }
+    /** 某一轮修改的状态文件内容：即该轮结束时的文件，并校验哈希。 */
+    async readStateChangeContents(commit, change) {
+        const contents = await readFileAt(this.#root, commit.sequence, `state/${change.relativePath}`);
+        if (contents === null || sha256Hex(contents) !== change.nextHash)
+            throw new WorldAuthorityError("corrupt", `State change content conflicts with its commit: ${change.relativePath}`);
+        return contents;
+    }
+    /**
+     * 结构校验（归档导入使用）：头、轮记录与 genesis 可读，轮序号与路径合法。
+     * 当前文件本身不在账本里，因此这里不尝试从账本复算内容。
+     */
+    async verifyStructure() {
+        await this.readHead();
+        const turns = await listTurns(this.#root);
+        for (const turn of turns) {
+            for (const file of turn.files) {
+                if (file.path.startsWith("runtime/turns/") ||
+                    file.path === "runtime/head.json")
+                    throw new WorldAuthorityError("corrupt", "轮记录引用了账本自身的文件");
+            }
+            if (turn.payload !== undefined) {
+                const commit = turn.payload;
+                if (commit.sequence !== turn.sequence)
+                    throw new WorldAuthorityError("corrupt", `第 ${turn.sequence} 轮的提交序号不一致`);
+            }
+        }
+        const genesis = await readJsonOrNull(join(this.#root, genesisFile));
+        if (genesis === null || !Array.isArray(genesis.state))
+            throw new WorldAuthorityError("corrupt", "genesis.json 缺少状态");
+    }
+    /**
+     * 以账本端点重建当前文件（状态、历史投影、历史背景与材料清单）。
+     * 只用于尚未发布的 staging 世界：它先删除投影目录再写入，中途失败由调用方丢弃整个 staging。
+     */
+    async materializeCurrentFiles() {
+        const endpoint = await this.recover();
+        const writes = new Map();
+        for (const file of endpoint.state)
+            writes.set(`state/${file.path}`, file.contents);
+        for (const file of projectFileNativeHistorySurface(endpoint.history, (messageId) => {
+            throw new WorldAuthorityError("corrupt", `History-message identity cannot form a file path: ${messageId}`);
+        }))
+            writes.set(`history/${file.path}`, file.contents);
+        for (const file of projectHistoryBackgrounds(endpoint.history))
+            writes.set(`runtime/history-backgrounds/${file.path}`, file.contents);
+        writes.set(materialsFile, `${JSON.stringify({ head: endpoint.head, items: endpoint.additionalMaterials }, null, 2)}\n`);
+        for (const directory of [
+            "state",
+            "history",
+            join("runtime", "history-backgrounds"),
+        ])
+            await rm(join(this.#root, directory), { recursive: true, force: true });
+        for (const [path, contents] of writes)
+            await writeTextAtomic(join(this.#root, path), contents);
+    }
+    async authorityFactAt(head) {
+        const position = await this.#positionOf(head);
+        if (position === 0)
+            throw new WorldAuthorityError("conflict", "Genesis is not a commit");
+        const commit = await this.#commitAtPosition(position);
+        const digest = await readTurnDigest(this.#root, position);
+        if (digest === null)
+            throw new WorldAuthorityError("corrupt", `第 ${position} 轮缺少记录`);
+        return { commit, digest };
+    }
+    /**
+     * 在当前端点之上追加一轮。调用方先校验内容；这里校验状态的前像哈希，
+     * 并一次性计算本轮需要替换的全部文件（状态、历史、历史背景与材料清单）。
+     */
+    async appendCommit(input) {
+        const current = await this.readHead();
+        if (current.head !== input.parentHead)
+            throw new WorldAuthorityError("stale", "The parent endpoint of the Authority operation has changed");
+        const physical = await readLedgerHead(this.#root);
+        const sequence = physical + 1;
+        const head = `commit:${String(sequence)}`;
+        const currentState = new Map((await this.#stateAt(current.sequence)).map((file) => [
+            file.path,
+            file.contents,
+        ]));
+        const changes = [];
+        for (const change of input.stateChanges) {
+            const previous = currentState.get(change.relativePath);
+            if ((previous === undefined ? null : sha256Hex(previous)) !==
+                change.expectedPreviousHash)
+                throw new WorldAuthorityError("conflict", `State-change previous hash conflicts: ${change.relativePath}`);
+            if (sha256Hex(change.canonicalNextBytes) !== change.nextHash)
+                throw new WorldAuthorityError("conflict", `State-change next hash conflicts: ${change.relativePath}`);
+            changes.push({
+                path: `state/${change.relativePath}`,
+                content: change.canonicalNextBytes,
+            });
+        }
+        const messages = input.historyAppend.map((message, index) => ({
+            messageId: `message.${String(sequence)}.${String(index + 1)}.${message.role}`,
+            role: message.role,
+            exactText: message.exactText,
+            ...(message.background === undefined
+                ? {}
+                : { background: structuredClone(message.background) }),
+        }));
+        for (const file of projectFileNativeHistorySurface(messages, (messageId) => {
+            throw new WorldAuthorityError("corrupt", `History-message identity cannot form a file path: ${messageId}`);
+        }))
+            changes.push({ path: `history/${file.path}`, content: file.contents });
+        for (const file of projectHistoryBackgrounds(messages))
+            changes.push({
+                path: `runtime/history-backgrounds/${file.path}`,
+                content: file.contents,
+            });
+        changes.push({
+            path: materialsFile,
+            content: `${JSON.stringify({ head, items: input.nextMaterials }, null, 2)}\n`,
+        });
+        const commit = {
+            sequence,
+            head,
+            operationId: input.operationId,
+            parentHead: input.parentHead,
+            mode: input.mode,
+            ...(input.playContext === undefined
+                ? {}
+                : { playContext: input.playContext }),
+            ...(input.worldClock === undefined
+                ? {}
+                : { worldClock: input.worldClock }),
+            historyAppend: messages,
+            stateChanges: input.stateChanges.map((change) => {
+                const { canonicalNextBytes, ...stored } = change;
+                void canonicalNextBytes;
+                return structuredClone(stored);
+            }),
+            nextAdditionalMaterials: structuredClone([...input.nextMaterials]),
+            ...(input.correctionTargets === undefined
+                ? {}
+                : { correctionTargets: [...input.correctionTargets] }),
+            ...(input.corrects === undefined ? {} : { corrects: input.corrects }),
+            ...(input.narrativeCheckpoint === undefined
+                ? {}
+                : { narrativeCheckpoint: structuredClone(input.narrativeCheckpoint) }),
+        };
+        const record = await appendTurn(this.#root, {
+            mode: input.mode,
+            changes,
+            payload: commit,
+        });
+        const commitDigest = await readTurnDigest(this.#root, record.sequence);
+        if (commitDigest === null)
+            throw new WorldAuthorityError("corrupt", "新提交缺少轮记录");
+        return { commit, commitDigest };
+    }
+}
+// 与状态前像哈希保持同一格式（sha256:<hex>）。
+async function writeTextAtomic(path, contents) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, contents, "utf8");
+    await rename(temporary, path);
+}
+function sha256Hex(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}