narraeon 0.6.0 → 0.6.2

package/dist/node/runtime/world/{FileNativeAuthorityV3.js → LegacyAuthorityV3Reader.js}

@@ -1,11 +1,15 @@
 import { isHistoryBackground, } from "../history/HistoryBackground.js";
-import { createHash, randomUUID } from "node:crypto";
-import { link, mkdir, open, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { cloneFilePhysically } from "../FileNativePhysicalClone.js";
 export const continuityHeadFile = "continuity-head.json";
 export const authorityV3Directory = "authority-v3";
+/**
+ * Stale files that v0.3.0–v0.6.0 worlds still carry from the layout they
+ * replaced. The conversion to the turn ledger removes them; nothing reads them.
+ */
+export const staleV3WorldFiles = [join("runtime", "materialized-head.json")];
 export class FileNativeAuthorityV3Error extends Error {
     code;
     constructor(code, message) {
@@ -15,6 +19,10 @@ export class FileNativeAuthorityV3Error extends Error {
     }
 }
 /**
+ * Read-only access to the retired Authority V3 fact chain. It exists only so
+ * the storage migrator can convert a V3 world into the current layout; nothing
+ * on the live path writes V3 facts.
+ *
  * World-neutral immutable Authority facts with one target-local mutable head.
  *
  * Every sequence owns an immutable epoch directory. A fork can therefore
@@ -22,7 +30,7 @@ export class FileNativeAuthorityV3Error extends Error {
  * ancestor facts. Object references include their creation epoch so unchanged
  * state/history/material objects remain directly addressable after a fork.
  */
-export class FileNativeAuthorityV3 {
+export class LegacyAuthorityV3Reader {
     #runtimeRoot;
     #authorityRoot;
     constructor(worldRoot) {
@@ -40,57 +48,6 @@ export class FileNativeAuthorityV3 {
             throw error;
         }
     }
-    async initialize(input) {
-        const epoch = 0;
-        const state = await this.#writeStateManifest(epoch, input.state);
-        const historySegment = {
-            schemaVersion: 3,
-            type: "file_native_history_segment",
-            previous: null,
-            messages: structuredClone(input.history),
-        };
-        assertHistorySegment(historySegment);
-        assertGenesisHistory(historySegment.messages);
-        const history = input.history.length === 0
-            ? null
-            : await this.#writeObject(epoch, "history.json", historySegment);
-        const materialSet = {
-            schemaVersion: 3,
-            type: "file_native_material_set",
-            items: structuredClone(input.additionalMaterials),
-        };
-        assertMaterialSet(materialSet);
-        const materials = await this.#writeObject(epoch, "materials.json", materialSet);
-        const endpointValue = {
-            schemaVersion: 3,
-            type: "file_native_authority_endpoint",
-            state,
-            history,
-            historyLength: input.history.length,
-            materials,
-        };
-        assertEndpoint(endpointValue);
-        const endpoint = await this.#writeObject(epoch, "endpoint.json", endpointValue);
-        const genesisValue = {
-            schemaVersion: 3,
-            type: "file_native_authority_genesis",
-            result: endpoint,
-        };
-        assertGenesis(genesisValue);
-        const genesis = await this.#writeObject(epoch, "authority.json", genesisValue);
-        const head = {
-            schemaVersion: 3,
-            type: "file_native_continuity_head",
-            head: "genesis",
-            sequence: 0,
-            genesisDigest: genesis.digest,
-            commitDigest: null,
-            result: endpoint,
-            operationId: input.operationId,
-        };
-        await publishJson(join(this.#runtimeRoot, continuityHeadFile), head);
-        return head;
-    }
     async readHead() {
         const value = await readJson(join(this.#runtimeRoot, continuityHeadFile));
         assertHead(value);
@@ -99,143 +56,6 @@ export class FileNativeAuthorityV3 {
     async currentOperationId() {
         return (await this.readHead()).operationId;
     }
-    async discardUnacceptedNextEpoch() {
-        const current = await this.readHead();
-        const epochsRoot = join(this.#authorityRoot, "epochs");
-        await rm(this.#epochRoot(current.sequence + 1), {
-            recursive: true,
-            force: true,
-        });
-        await syncDirectory(epochsRoot);
-    }
-    async prepareAppend(input) {
-        const current = await this.readHead();
-        if (current.head !== input.parentHead)
-            throw new FileNativeAuthorityV3Error("stale", "The parent endpoint of the Authority operation has changed");
-        const sequence = current.sequence + 1;
-        const head = `commit:${sequence}`;
-        const basisHead = input.timelineParentHead ?? input.parentHead;
-        const basisResult = await this.#resultRefAt(basisHead);
-        const basis = await this.#readEndpoint(basisResult);
-        const state = await this.#nextState(sequence, basis.state, input.stateChanges);
-        const historyAppend = input.historyAppend.map((message, index) => ({
-            messageId: `message.${sequence}.${index + 1}.${message.role}`,
-            ...structuredClone(message),
-        }));
-        const history = historyAppend.length === 0
-            ? basis.history
-            : await this.#writeHistorySegment(sequence, {
-                schemaVersion: 3,
-                type: "file_native_history_segment",
-                previous: basis.history,
-                messages: historyAppend,
-            });
-        const basisMaterials = await this.#readMaterials(basis.materials);
-        const nextMaterialSet = {
-            schemaVersion: 3,
-            type: "file_native_material_set",
-            items: structuredClone(input.nextMaterials),
-        };
-        assertMaterialSet(nextMaterialSet);
-        const materials = isDeepStrictEqual(basisMaterials.items, input.nextMaterials)
-            ? basis.materials
-            : await this.#writeObject(sequence, "materials.json", nextMaterialSet);
-        const endpointValue = {
-            schemaVersion: 3,
-            type: "file_native_authority_endpoint",
-            state,
-            history,
-            historyLength: basis.historyLength + historyAppend.length,
-            materials,
-            ...(input.narrativeCheckpoint === undefined
-                ? basis.narrativeCheckpoint === undefined
-                    ? {}
-                    : { narrativeCheckpoint: basis.narrativeCheckpoint }
-                : {
-                    narrativeCheckpoint: {
-                        ...input.narrativeCheckpoint,
-                        head,
-                        historyMessageId: historyAppend.at(-1)?.messageId ?? "",
-                    },
-                }),
-        };
-        assertEndpoint(endpointValue);
-        const endpoint = await this.#writeObject(sequence, "endpoint.json", endpointValue);
-        const storedChanges = [];
-        for (const change of input.stateChanges) {
-            const blob = await this.#writeBlob(sequence, change.canonicalNextBytes);
-            storedChanges.push({
-                kind: change.kind,
-                documentId: change.documentId,
-                stableShortRef: change.stableShortRef,
-                relativePath: change.relativePath,
-                codec: change.codec,
-                expectedPreviousHash: change.expectedPreviousHash,
-                nextHash: change.nextHash,
-                nextBlob: blob,
-            });
-        }
-        const auditParent = {
-            head: current.head,
-            digest: current.commitDigest ?? current.genesisDigest,
-        };
-        const timelineParent = await this.#authorityRefAt(basisHead);
-        const commit = {
-            ...(input.playContext === undefined
-                ? {}
-                : { playContext: input.playContext }),
-            ...(input.worldClock === undefined
-                ? {}
-                : { worldClock: input.worldClock }),
-            schemaVersion: 3,
-            type: "file_native_authority_commit",
-            sequence,
-            head,
-            auditParent,
-            timelineParent,
-            mode: input.mode,
-            historyAppend,
-            stateChanges: storedChanges,
-            nextAdditionalMaterials: structuredClone(input.nextMaterials),
-            result: endpoint,
-            ...(input.narrativeCheckpoint === undefined
-                ? {}
-                : { narrativeCheckpoint: structuredClone(input.narrativeCheckpoint) }),
-            ...(input.correctionTargets === undefined
-                ? {}
-                : { correctionTargets: structuredClone(input.correctionTargets) }),
-            ...(input.corrects === undefined ? {} : { corrects: input.corrects }),
-            ...(input.timelineRevision === undefined
-                ? {}
-                : { timelineRevision: structuredClone(input.timelineRevision) }),
-        };
-        assertCommit(commit);
-        const authority = await this.#writeObject(sequence, "authority.json", commit);
-        return {
-            commit,
-            commitDigest: authority.digest,
-            nextHead: {
-                schemaVersion: 3,
-                type: "file_native_continuity_head",
-                head,
-                sequence,
-                genesisDigest: current.genesisDigest,
-                commitDigest: authority.digest,
-                result: endpoint,
-                operationId: input.operationId,
-            },
-            stateChanges: structuredClone(input.stateChanges),
-        };
-    }
-    async publishPrepared(prepared) {
-        const current = await this.readHead();
-        if (current.sequence + 1 !== prepared.nextHead.sequence ||
-            current.head !== prepared.commit.auditParent.head ||
-            (current.commitDigest ?? current.genesisDigest) !==
-                prepared.commit.auditParent.digest)
-            throw new FileNativeAuthorityV3Error("stale", "The prepared Authority fact no longer extends the current endpoint");
-        await publishJson(join(this.#runtimeRoot, continuityHeadFile), prepared.nextHead);
-    }
     async recover(requestedHead) {
         const current = await this.readHead();
         const head = requestedHead ?? current.head;
@@ -350,54 +170,6 @@ export class FileNativeAuthorityV3 {
         await this.#assertAcceptedAuthorityRef(current, sequence, head, digest);
         return { commit: value, digest };
     }
-    async clonePrefixTo(input) {
-        const sourceHead = await this.readHead();
-        const selectedSequence = input.selectedHead === "genesis"
-            ? 0
-            : parseHeadSequence(input.selectedHead);
-        if (selectedSequence > sourceHead.sequence)
-            throw new FileNativeAuthorityV3Error("conflict", `Cannot fork a nonexistent Authority endpoint: ${input.selectedHead}`);
-        const selected = input.selectedHead === sourceHead.head
-            ? { ...structuredClone(sourceHead), operationId: input.operationId }
-            : selectedSequence === 0
-                ? await this.#headAtGenesis(sourceHead, input.operationId)
-                : await this.#headAtCommit(sourceHead, selectedSequence, input.operationId);
-        const targetRuntime = join(input.targetWorldRoot, "runtime");
-        const targetAuthority = join(targetRuntime, authorityV3Directory);
-        for (let epoch = 0; epoch <= selectedSequence; epoch += 1)
-            await cloneImmutableTree(this.#epochRoot(epoch), join(targetAuthority, "epochs", epochName(epoch)));
-        await publishJson(join(targetRuntime, continuityHeadFile), selected);
-        return selected;
-    }
-    async #headAtGenesis(current, operationId) {
-        const genesis = await this.#readObject({ epoch: 0, digest: current.genesisDigest }, "authority.json", "file_native_authority_genesis");
-        assertGenesis(genesis);
-        await this.#assertAcceptedGenesis(current);
-        return {
-            schemaVersion: 3,
-            type: "file_native_continuity_head",
-            head: "genesis",
-            sequence: 0,
-            genesisDigest: current.genesisDigest,
-            commitDigest: null,
-            result: genesis.result,
-            operationId,
-        };
-    }
-    async #headAtCommit(current, sequence, operationId) {
-        const { value, digest } = await this.#readAuthorityCommit(sequence);
-        await this.#assertAcceptedAuthorityRef(current, sequence, value.head, digest);
-        return {
-            schemaVersion: 3,
-            type: "file_native_continuity_head",
-            head: value.head,
-            sequence,
-            genesisDigest: current.genesisDigest,
-            commitDigest: digest,
-            result: value.result,
-            operationId,
-        };
-    }
     async #resultRefAt(head) {
         const current = await this.readHead();
         if (head === current.head) {
@@ -431,19 +203,6 @@ export class FileNativeAuthorityV3 {
         await this.#assertAcceptedAuthorityRef(current, sequence, head, digest);
         return value.result;
     }
-    async #authorityRefAt(head) {
-        const current = await this.readHead();
-        if (head === "genesis") {
-            await this.#assertAcceptedGenesis(current);
-            return { head, digest: current.genesisDigest };
-        }
-        const sequence = parseHeadSequence(head);
-        const { value, digest } = await this.#readAuthorityCommit(sequence);
-        if (value.head !== head || sequence > current.sequence)
-            throw new FileNativeAuthorityV3Error("conflict", `Authority endpoint does not exist: ${head}`);
-        await this.#assertAcceptedAuthorityRef(current, sequence, head, digest);
-        return { head, digest };
-    }
     async #assertAcceptedAuthorityRef(current, sequence, head, digest) {
         if (sequence > current.sequence)
             throw new FileNativeAuthorityV3Error("conflict", `Authority endpoint does not exist: ${head}`);
@@ -464,60 +223,6 @@ export class FileNativeAuthorityV3 {
             first.auditParent.digest !== current.genesisDigest)
             throw new FileNativeAuthorityV3Error("corrupt", "Authority audit chain does not extend its genesis anchor");
     }
-    async #nextState(epoch, basisRef, changes) {
-        if (changes.length === 0)
-            return basisRef;
-        const basis = await this.#readStateManifest(basisRef);
-        const files = new Map(basis.files.map((file) => [file.path, file]));
-        for (const change of changes) {
-            const previous = files.get(change.relativePath);
-            if ((previous?.sha256 ?? null) !== change.expectedPreviousHash)
-                throw new FileNativeAuthorityV3Error("conflict", `State-change previous hash conflicts: ${change.relativePath}`);
-            if (hashWithPrefix(change.canonicalNextBytes) !== change.nextHash)
-                throw new FileNativeAuthorityV3Error("conflict", `State-change next hash conflicts: ${change.relativePath}`);
-            const blob = await this.#writeBlob(epoch, change.canonicalNextBytes);
-            files.set(change.relativePath, {
-                path: change.relativePath,
-                sha256: change.nextHash,
-                blob,
-            });
-        }
-        const manifest = {
-            schemaVersion: 3,
-            type: "file_native_state_manifest",
-            files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
-        };
-        assertStateManifest(manifest);
-        return this.#writeObject(epoch, "state.json", manifest);
-    }
-    async #writeStateManifest(epoch, files) {
-        const entries = [];
-        for (const file of files) {
-            const blob = await this.#writeBlob(epoch, file.contents);
-            entries.push({
-                path: file.path,
-                sha256: hashWithPrefix(file.contents),
-                blob,
-            });
-        }
-        const manifest = {
-            schemaVersion: 3,
-            type: "file_native_state_manifest",
-            files: entries.sort((left, right) => left.path.localeCompare(right.path)),
-        };
-        assertStateManifest(manifest);
-        return this.#writeObject(epoch, "state.json", manifest);
-    }
-    async #writeHistorySegment(epoch, segment) {
-        assertHistorySegment(segment);
-        return this.#writeObject(epoch, "history.json", segment);
-    }
-    async #writeBlob(epoch, contents) {
-        const digest = hashHex(contents);
-        const path = join(this.#epochRoot(epoch), "blobs", `${digest}.txt`);
-        await publishImmutableText(path, contents);
-        return { epoch, digest, sha256: `sha256:${digest}` };
-    }
     async #recoverState(ref) {
         const manifest = await this.#readStateManifest(ref);
         const state = [];
@@ -568,7 +273,6 @@ export class FileNativeAuthorityV3 {
         return value;
     }
     async #readAuthorityCommit(sequence) {
-        forbidAuthorityFactDecodeForTest();
         const path = join(this.#epochRoot(sequence), "authority.json");
         const value = await readJson(path);
         if (!isRecord(value) ||
@@ -579,14 +283,7 @@ export class FileNativeAuthorityV3 {
         const commit = value;
         return { value: commit, digest: objectDigest(commit) };
     }
-    async #writeObject(epoch, name, value) {
-        const digest = objectDigest(value);
-        await publishImmutableJson(join(this.#epochRoot(epoch), name), value);
-        return { epoch, digest };
-    }
     async #readObject(ref, name, type) {
-        if (name === "authority.json")
-            forbidAuthorityFactDecodeForTest();
         const value = await readJson(join(this.#epochRoot(ref.epoch), name));
         if (!isRecord(value) ||
             value.schemaVersion !== 3 ||
@@ -667,15 +364,6 @@ function assertHistorySegment(value) {
         !value.messages.every(isHistoryMessage))
         throw corruptShape("Authority history segment");
 }
-function assertGenesisHistory(messages) {
-    for (const [index, message] of messages.entries()) {
-        const expected = index === 0 && message.role === "narrator"
-            ? "message.genesis.narrator"
-            : `message.genesis.${index + 1}.${message.role}`;
-        if (message.messageId !== expected)
-            throw corruptShape("Authority genesis history-message identity");
-    }
-}
 function assertMaterialSet(value) {
     if (!isRecord(value) ||
         !hasExactKeys(value, ["schemaVersion", "type", "items"]) ||
@@ -971,81 +659,6 @@ function hashWithPrefix(value) {
 function isDigest(value) {
     return /^[a-f0-9]{64}$/u.test(value);
 }
-async function cloneImmutableTree(source, target) {
-    await mkdir(target, { recursive: true, mode: 0o700 });
-    const entries = await readdir(source, { withFileTypes: true });
-    for (const entry of entries) {
-        const sourcePath = join(source, entry.name);
-        const targetPath = join(target, entry.name);
-        if (entry.isDirectory()) {
-            await cloneImmutableTree(sourcePath, targetPath);
-            continue;
-        }
-        if (!entry.isFile())
-            throw new FileNativeAuthorityV3Error("corrupt", `Immutable Authority closure contains a non-file entry: ${entry.name}`);
-        await cloneImmutableFile(sourcePath, targetPath);
-    }
-}
-async function cloneImmutableFile(source, target) {
-    await cloneFilePhysically({ source, target, immutable: true });
-}
-async function publishImmutableJson(path, value) {
-    await publishImmutableText(path, `${JSON.stringify(value, null, 2)}\n`);
-}
-async function publishImmutableText(path, contents) {
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, contents, {
-            encoding: "utf8",
-            flag: "wx",
-            mode: 0o600,
-        });
-        await syncFile(temporary);
-        try {
-            await link(temporary, path);
-            await syncDirectory(dirname(path));
-        }
-        catch (error) {
-            if (!isNodeError(error) || error.code !== "EEXIST")
-                throw error;
-            if ((await readFile(path, "utf8")) !== contents)
-                throw new FileNativeAuthorityV3Error("corrupt", `Immutable Authority object conflicts: ${path}`);
-        }
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
-}
-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 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();
-    }
-}
 async function readJson(path) {
     return JSON.parse(await readFile(path, "utf8"));
 }
@@ -1055,7 +668,3 @@ function isRecord(value) {
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }
-function forbidAuthorityFactDecodeForTest() {
-    if (process.env.NARRAEON_INTERNAL_TEST_FORBID_AUTHORITY_FACT_DECODE === "1")
-        throw new Error("Authority fact decoding is forbidden by this test");
-}

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

@@ -1,16 +1,26 @@
 import { randomUUID } from "node:crypto";
 import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { FileNativeAuthorityV3 } from "./FileNativeAuthorityV3.js";
+import { WorldLedgerAuthority } from "./WorldLedgerAuthority.js";
 import { fileNativeHistoryMessageIdFromProjectionPath } from "./FileNativeHistoryProjection.js";
+/** Listing never upgrades storage: a world without a ledger shows as pending. */
+export const pendingUpgradeActivity = {
+    lastActivityAt: null,
+    excerpt: null,
+    playerTurns: 0,
+    pendingUpgrade: true,
+};
 /** Read only the small head/cache on a hit; repair misses from the local projection. */
 export async function readWorldActivity(root, serializeRebuild = (rebuild) => rebuild()) {
-    const head = await currentHead(root);
+    const ledger = new WorldLedgerAuthority(root);
+    if (!(await ledger.exists()))
+        return pendingUpgradeActivity;
+    const head = (await ledger.readHead()).head;
     const cached = await readCache(root);
     if (cached?.head === head)
         return cached;
     return serializeRebuild(async () => {
-        const latestHead = await currentHead(root);
+        const latestHead = (await ledger.readHead()).head;
         const latestCache = await readCache(root);
         if (latestCache?.head === latestHead)
             return latestCache;
@@ -21,11 +31,7 @@ export async function readWorldActivity(root, serializeRebuild = (rebuild) => re
             excerpt: null,
             playerTurns: 0,
         };
-        // An accepted endpoint may still be awaiting recovery. Never label its old
-        // materialized history as a valid cache for the new endpoint.
-        const materialized = await readJson(join(root, "runtime/materialized-head.json"));
-        if (!isRecord(materialized) || materialized.head !== latestHead)
-            return empty;
+        // history/ is the current endpoint's own projection, so it is always valid to rebuild from.
         const entries = await readdir(join(root, "history"), {
             withFileTypes: true,
         });
@@ -73,20 +79,6 @@ function excerpt(text) {
         ? null
         : Array.from(singleLine).slice(0, 80).join("");
 }
-async function currentHead(root) {
-    try {
-        return (await new FileNativeAuthorityV3(root).readHead()).head;
-    }
-    catch (error) {
-        if (!isMissing(error))
-            throw error;
-        // Listing a released layout must not trigger an Authority migration/replay.
-        const checkpoint = await readJson(join(root, "runtime/materialized-head.json"));
-        return isRecord(checkpoint) && typeof checkpoint.head === "string"
-            ? checkpoint.head
-            : "genesis";
-    }
-}
 async function readCache(root) {
     const value = await readJson(join(root, "runtime/activity.json")).catch(() => null);
     return isRecord(value) &&

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

@@ -14,7 +14,7 @@ export async function readDocumentMaintenanceFacts(authority, head, cache) {
             throw new Error("Document maintenance history is not reachable");
         seen.add(cursor);
         timeline.push(commit);
-        cursor = commit.timelineParent.head;
+        cursor = commit.parentHead;
     }
     timeline.reverse();
     const prefix = cache.get(cursor);
@@ -86,7 +86,7 @@ export async function readDocumentMaintenanceFacts(authority, head, cache) {
             continue;
         const changed = await Promise.all(commit.stateChanges.map(async (change) => ({
             change,
-            contents: await authority.readStateChangeContents(change),
+            contents: await authority.readStateChangeContents(commit, change),
         })));
         for (const { change, contents } of changed)
             files.set(change.relativePath, contents);