narraeon 0.5.6 → 0.6.0

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

@@ -2,6 +2,9 @@ import { captureNarrativeOrigin, snapshotBackground, isHistoryBackground, } from
 import { FileNativeArtifactStore } from "../artifact/FileNativeArtifactStore.js";
 import { WorldExtensionRequests } from "../extension/WorldExtensionRequests.js";
 import { WorldExtensionControls, extensionDefinitions, } from "../extension/WorldExtensionControls.js";
+import { assertSameGameplay, readGameplay, } from "../../protocol/gameplay.js";
+import { HistoryQuery } from "../history/HistoryQuery.js";
+import { exportStory } from "../history/StoryExport.js";
 import { PackageScriptPermissions } from "../extension/PackageScriptPermissions.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile, } from "node:fs/promises";
@@ -11,6 +14,7 @@ import { inspectContentPackageCurrentTree, isContentPackageWorldDocumentPath, }
 import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js";
 import { PlayerViewRenderer } from "./PlayerViewRenderer.js";
 import { WorldDocumentStore } from "./WorldDocumentStore.js";
+import { readWorldActivity, updateWorldActivity, } from "./WorldActivity.js";
 import { FileNativePlayTimelineStore } from "../play/FileNativePlayTimelineStore.js";
 import { FileNativePlayAdvanceStore } from "../play/FileNativePlayAdvanceStore.js";
 import { FileNativeWorldStorageMigrator } from "./FileNativeWorldStorageMigrator.js";
@@ -41,6 +45,7 @@ export class FileNativeWorldStore {
     #promptCompiler;
     #activeControlUsers = new Map();
     #openingWorldRevisions = new Set();
+    #archiveExports = new Set();
     operations;
     playTimeline;
     playAdvances;
@@ -112,16 +117,47 @@ export class FileNativeWorldStore {
             throw new FileNativeWorldCreationError("world_corrupt", "Released world storage could not be migrated to the current format", error instanceof Error ? { cause: error } : undefined);
         }
     }
+    async gameplay(worldId) {
+        assertIdentity(worldId, "World ID");
+        await this.ensureCurrentStorage(worldId);
+        const root = join(this.#worldsRoot, worldId);
+        await readPublicationAt(root);
+        return readWorldGameplayAt(root);
+    }
+    async readWorldSummary(worldId) {
+        assertIdentity(worldId, "World ID");
+        return readWorldSummaryAt(join(this.#worldsRoot, worldId));
+    }
     async listWorlds() {
         await mkdir(this.#worldsRoot, { recursive: true, mode: 0o700 });
-        const entries = await readdir(this.#worldsRoot, { withFileTypes: true });
+        const entries = (await readdir(this.#worldsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith("."));
         const worlds = [];
-        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-            if (!entry.isDirectory() || entry.name.startsWith("."))
-                continue;
-            worlds.push(await readWorldSummaryAt(join(this.#worldsRoot, entry.name)));
+        // Bound concurrent shell/head/cache reads even in a large workspace.
+        for (let offset = 0; offset < entries.length; offset += 16) {
+            worlds.push(...(await Promise.all(entries
+                .slice(offset, offset + 16)
+                .map((entry) => readWorldSummaryAt(join(this.#worldsRoot, entry.name), undefined, (rebuild) => this.operations.withWorldAuthorityLock(entry.name, rebuild))))));
         }
-        return worlds;
+        return worlds.sort((left, right) => (right.lastActivityAt ?? -1) - (left.lastActivityAt ?? -1) ||
+            left.title.localeCompare(right.title) ||
+            left.worldId.localeCompare(right.worldId));
+    }
+    /** Explicit full-history read; independent of page and model projections. */
+    async exportStory(worldId, format, locale) {
+        assertIdentity(worldId, "World ID");
+        await this.ensureCurrentStorage(worldId);
+        return this.operations.withWorldAuthorityLock(worldId, async () => {
+            const root = join(this.#worldsRoot, worldId);
+            const publication = await readPublicationAt(root);
+            const title = await readWorldTitleAt(root, publication);
+            const endpoint = await new FileNativeAuthorityV3(root).recoverHeadResult();
+            const history = new HistoryQuery(worldId, endpoint.history.map(({ messageId, role, exactText }) => ({
+                id: messageId,
+                role,
+                text: exactText,
+            })));
+            return exportStory(title, history.messages, format, locale);
+        });
     }
     async renameWorld(worldId, name) {
         assertIdentity(worldId, "World ID");
@@ -144,7 +180,7 @@ export class FileNativeWorldStore {
                 worldId,
                 name: trimmed,
             });
-            return { ...toSummary(publication), title: trimmed };
+            return readWorldSummaryAt(root, publication);
         });
     }
     /**
@@ -321,13 +357,18 @@ export class FileNativeWorldStore {
                 sourceFingerprint,
             };
             await writeJson(join(stagingRoot, publicationFile), publication);
+            await updateWorldActivity(stagingRoot, "genesis", [openingMessage], Date.now());
             await durableTree(stagingRoot);
             crashAtFileNativeWorldCreationEdge("after_staging");
             await rename(stagingRoot, finalRoot);
             await syncDirectory(this.#worldsRoot);
             crashAtFileNativeWorldCreationEdge("after_atomic_publish");
             await publishOperation(operationPath, publication);
-            return { outcome: "created", world: toSummary(publication), preview };
+            return {
+                outcome: "created",
+                world: await this.#currentSummary(publication),
+                preview,
+            };
         }
         catch (error) {
             await rm(stagingRoot, { recursive: true, force: true }).catch(() => undefined);
@@ -398,6 +439,31 @@ export class FileNativeWorldStore {
         await readPublicationAt(root);
         return (await new FileNativeAuthorityV3(root).readHead()).head;
     }
+    async withArchiveExport(worldId, action) {
+        assertIdentity(worldId, "World ID");
+        if ((this.#activeControlUsers.get(worldId)?.size ?? 0) > 0 ||
+            this.#archiveExports.has(worldId) ||
+            this.#openingWorldRevisions.has(worldId))
+            throw new FileNativeWorldCreationError("operation_conflict", "Wait for the current generation or world operation before exporting a backup");
+        this.#archiveExports.add(worldId);
+        try {
+            if (await this.readWorldRevisionLock(worldId))
+                throw new FileNativeWorldCreationError("operation_conflict", "Please apply or discard the world revision before exporting a backup");
+            return await action();
+        }
+        finally {
+            this.#archiveExports.delete(worldId);
+        }
+    }
+    async archiveNeedsFreshContext(worldId) {
+        assertIdentity(worldId, "World ID");
+        return ((await readOptionalJson(join(this.#worldsRoot, worldId, "runtime", "archive-import.json"))) !== null ||
+            (await this.playTimeline.currentContextRequiresFreshContext(worldId)));
+    }
+    async completeArchiveFreshContext(worldId) {
+        assertIdentity(worldId, "World ID");
+        await rm(join(this.#worldsRoot, worldId, "runtime", "archive-import.json"), { force: true });
+    }
     async currentHeadOperationId(worldId) {
         assertIdentity(worldId, "World ID");
         await this.ensureCurrentStorage(worldId);
@@ -414,6 +480,7 @@ export class FileNativeWorldStore {
                 await this.ensureCurrentStorage(worldId);
                 const root = join(this.#worldsRoot, worldId);
                 await readPublicationAt(root);
+                assertControlGameplayUnchanged(await readTree(join(root, "control")), files);
                 const staging = join(root, `runtime/.control-draft-${randomUUID()}`);
                 await writeSurface(staging, "control", files);
                 const final = join(root, "runtime/control-draft");
@@ -431,7 +498,8 @@ export class FileNativeWorldStore {
     }
     async acquireWorldRevisionLock(worldId, epochId) {
         if ((this.#activeControlUsers.get(worldId)?.size ?? 0) > 0 ||
-            this.#openingWorldRevisions.has(worldId))
+            this.#openingWorldRevisions.has(worldId) ||
+            this.#archiveExports.has(worldId))
             return { kind: "busy" };
         this.#openingWorldRevisions.add(worldId);
         try {
@@ -503,6 +571,7 @@ export class FileNativeWorldStore {
             }
             if (currentFingerprint !== input.expectedFingerprint)
                 throw new FileNativeWorldCreationError("operation_conflict", "World control changed after this revision epoch opened");
+            assertControlGameplayUnchanged(current, input.files);
             await rm(stagingRoot, { recursive: true, force: true });
             await rm(previousPath, { recursive: true, force: true });
             await writeSurface(stagingRoot, "control", input.files);
@@ -559,6 +628,7 @@ export class FileNativeWorldStore {
                     throw new FileNativeWorldCreationError("operation_conflict", "World control is frozen by a running attempt");
                 const preview = await this.previewControlDraft(worldId, prompt);
                 const root = join(this.#worldsRoot, worldId);
+                assertControlGameplayUnchanged(await readTree(join(root, "control")), await readTree(join(root, "runtime/control-draft")));
                 const draft = join(root, "runtime/control-draft");
                 const replacement = join(root, `runtime/.control-apply-${randomUUID()}`);
                 await rename(draft, replacement);
@@ -587,6 +657,8 @@ export class FileNativeWorldStore {
     freezeControl(worldId, operationId) {
         assertIdentity(worldId, "World ID");
         assertIdentity(operationId, "operation ID");
+        if (this.#archiveExports.has(worldId))
+            throw new FileNativeWorldCreationError("operation_conflict", "A world backup is being exported; wait for it to finish");
         if (this.#openingWorldRevisions.has(worldId))
             throw new FileNativeWorldCreationError("operation_conflict", "World control is locked while a world revision opens");
         const users = this.#activeControlUsers.get(worldId) ?? new Set();
@@ -796,32 +868,51 @@ export class FileNativeWorldStore {
         if (input.requestDiscriminator !== undefined)
             assertIdentity(input.requestDiscriminator, "Fork request discriminator");
         if (input.sourceHead !== "genesis" &&
+            input.sourceHead !== "current" &&
             !/^commit:[1-9][0-9]*$/u.test(input.sourceHead))
             throw new TypeError("Source endpoint is invalid");
-        const operationPath = this.#derivationOperationPath(input.operationId);
+        if (input.targetName !== undefined && !validWorldName(input.targetName))
+            throw new TypeError("Target world name is invalid");
+        if (input.publish === false && input.targetWorldRoot === undefined)
+            throw new TypeError("An unpublished closure requires a target directory");
+        const target = input.targetDataRoot === undefined
+            ? this
+            : new FileNativeWorldStore(input.targetDataRoot);
+        const operationPath = input.identityPrefix === "import"
+            ? join(target.#operationsRoot, `import-${operationDigest(input.operationId)}.json`)
+            : target.#derivationOperationPath(input.operationId);
         const requestFingerprint = derivationRequestFingerprint(input);
-        const worldId = `world-${operationDigest(`derive:${input.operationId}`).slice(0, 24)}`;
-        const finalRoot = join(this.#worldsRoot, worldId);
-        const previous = await readOptionalJson(operationPath);
+        const worldId = `world-${operationDigest(`${input.identityPrefix ?? "derive"}:${input.operationId}`).slice(0, 24)}`;
+        const finalRoot = input.publish === false
+            ? resolve(input.targetWorldRoot)
+            : join(target.#worldsRoot, worldId);
+        const previous = input.publish === false
+            ? null
+            : await readOptionalJson(operationPath);
         if (previous !== null) {
-            await this.ensureCurrentStorage(previous.worldId);
-            if (!(await derivationPublicationMatches(join(this.#worldsRoot, previous.worldId), previous, input, requestFingerprint)))
+            await target.ensureCurrentStorage(previous.worldId);
+            if (!(await derivationPublicationMatches(join(target.#worldsRoot, previous.worldId), previous, input, requestFingerprint)))
                 throw new FileNativeWorldCreationError("operation_conflict", "The same fork operation ID is bound to a different fork payload");
             return {
                 outcome: "derived",
-                world: await this.#currentSummary(previous),
+                world: await target.#currentSummary(previous),
+                worldRoot: finalRoot,
             };
         }
         const alreadyPublished = await readOptionalJson(join(finalRoot, publicationFile));
         if (alreadyPublished !== null) {
-            await this.ensureCurrentStorage(alreadyPublished.worldId);
+            if (input.publish !== false)
+                await target.ensureCurrentStorage(alreadyPublished.worldId);
             if (!(await derivationPublicationMatches(finalRoot, alreadyPublished, input, requestFingerprint)))
                 throw new FileNativeWorldCreationError("operation_conflict", "Published fork world does not match the operation payload");
-            await mkdir(this.#operationsRoot, { recursive: true, mode: 0o700 });
-            await publishJson(operationPath, alreadyPublished);
+            if (input.publish !== false) {
+                await mkdir(target.#operationsRoot, { recursive: true, mode: 0o700 });
+                await publishJson(operationPath, alreadyPublished);
+            }
             return {
                 outcome: "derived",
-                world: await this.#currentSummary(alreadyPublished),
+                world: await readWorldSummaryAt(finalRoot, alreadyPublished),
+                worldRoot: finalRoot,
             };
         }
         await this.ensureCurrentStorage(input.sourceWorldId);
@@ -830,24 +921,37 @@ export class FileNativeWorldStore {
             const sourcePublication = await readPublicationAt(sourceRoot);
             const sourceSummary = await readWorldSummaryAt(sourceRoot, sourcePublication);
             const sourceAuthority = new FileNativeAuthorityV3(sourceRoot);
+            const sourceHead = input.sourceHead === "current"
+                ? (await sourceAuthority.readHead()).head
+                : input.sourceHead;
+            if (input.requireMaterialized) {
+                const authorityHead = await sourceAuthority.readHead();
+                const materialized = await readMaterializedCheckpoint(sourceRoot);
+                if (materialized?.head !== authorityHead.head ||
+                    materialized.commitDigest !== authorityHead.commitDigest)
+                    throw new FileNativeWorldCreationError("inconsistent_materialization", "Please repair the world before exporting a backup");
+            }
             const [sourceGenesis, control] = await Promise.all([
                 readGenesisForFork(sourceRoot, input.sourceWorldId),
                 readTree(join(sourceRoot, "control")),
             ]);
-            const staging = join(this.#worldsRoot, `.staging-${worldId}-${randomUUID()}`);
-            await mkdir(this.#worldsRoot, { recursive: true, mode: 0o700 });
-            await mkdir(this.#operationsRoot, { recursive: true, mode: 0o700 });
+            const staging = join(dirname(finalRoot), `.staging-${worldId}-${randomUUID()}`);
+            await mkdir(dirname(finalRoot), { recursive: true, mode: 0o700 });
+            if (input.publish !== false)
+                await mkdir(target.#operationsRoot, { recursive: true, mode: 0o700 });
             try {
                 await mkdir(join(staging, "runtime"), { recursive: true });
                 const clonedHead = await sourceAuthority.clonePrefixTo({
                     targetWorldRoot: staging,
-                    selectedHead: input.sourceHead,
+                    selectedHead: sourceHead,
                     operationId: input.operationId,
                 });
                 const selected = await new FileNativeAuthorityV3(staging).recoverHeadResult();
                 await writeSurface(staging, "state", selected.state);
                 await writeSurface(staging, "control", control);
-                await PackageScriptPermissions.write(staging, await PackageScriptPermissions.read(sourceRoot));
+                await PackageScriptPermissions.write(staging, input.resetPackageScriptPermissions
+                    ? []
+                    : await PackageScriptPermissions.read(sourceRoot));
                 await WorldExtensionControls.copy(sourceRoot, staging);
                 await mkdir(join(staging, "history"), { recursive: true });
                 for (const file of historySurfaceFiles(selected.history))
@@ -871,22 +975,23 @@ export class FileNativeWorldStore {
                     history: genesis.history,
                 });
                 await writeJson(join(staging, "runtime", "additional-materials.json"), {
-                    head: input.sourceHead,
+                    head: sourceHead,
                     items: selected.additionalMaterials,
                 });
                 await writeJson(join(staging, "runtime", "materialized-head.json"), {
                     schemaVersion: 3,
-                    head: input.sourceHead,
+                    head: sourceHead,
                     sequence: clonedHead.sequence,
                     commitDigest: clonedHead.commitDigest,
                     ...backgroundCount(selected.history),
                 });
                 await input.stageTarget?.({
+                    sourceHead,
                     targetWorldRoot: staging,
                     targetWorldId: worldId,
                     binding: {
                         worldId,
-                        parentHead: input.sourceHead,
+                        parentHead: sourceHead,
                         files: [...selected.state, ...control].reduce((files, { path, contents }, index) => {
                             files[`${index < selected.state.length ? "state" : "control"}/${path}`] = contents;
                             return files;
@@ -899,23 +1004,34 @@ export class FileNativeWorldStore {
                         ])),
                     },
                 });
+                if (input.identityPrefix === "import" ||
+                    (await this.archiveNeedsFreshContext(input.sourceWorldId)))
+                    await writeJson(join(staging, "runtime", "archive-import.json"), {
+                        schemaVersion: 1,
+                    });
                 crashAtFileNativeAuthorityEdge("derivation_after_target_staging");
                 const publication = {
                     schemaVersion: 1,
                     worldId,
-                    title: derivedWorldName(sourceSummary.title),
+                    title: input.targetName ?? derivedWorldName(sourceSummary.title),
                     parentEndpoint: "genesis",
                     operationId: input.operationId,
                     sourceFingerprint: requestFingerprint,
                 };
                 await writeJson(join(staging, publicationFile), publication);
+                await updateWorldActivity(staging, sourceHead, selected.history, Date.now());
                 await durableTree(staging);
                 crashAtFileNativeAuthorityEdge("derivation_before_publish");
                 await rename(staging, finalRoot);
-                await syncDirectory(this.#worldsRoot);
+                await syncDirectory(dirname(finalRoot));
                 crashAtFileNativeAuthorityEdge("derivation_after_publish");
-                await publishJson(operationPath, publication);
-                return { outcome: "derived", world: toSummary(publication) };
+                if (input.publish !== false)
+                    await publishJson(operationPath, publication);
+                return {
+                    outcome: "derived",
+                    world: await readWorldSummaryAt(finalRoot, publication),
+                    worldRoot: finalRoot,
+                };
             }
             catch (error) {
                 await rm(staging, { recursive: true, force: true }).catch(() => undefined);
@@ -923,8 +1039,13 @@ export class FileNativeWorldStore {
                 if (published !== null) {
                     if (!(await derivationPublicationMatches(finalRoot, published, input, requestFingerprint)))
                         throw new FileNativeWorldCreationError("operation_conflict", "Published fork world does not match the operation payload");
-                    await publishJson(operationPath, published);
-                    return { outcome: "derived", world: toSummary(published) };
+                    if (input.publish !== false)
+                        await publishJson(operationPath, published);
+                    return {
+                        outcome: "derived",
+                        world: await readWorldSummaryAt(finalRoot, published),
+                        worldRoot: finalRoot,
+                    };
                 }
                 throw error;
             }
@@ -1285,12 +1406,13 @@ export class FileNativeWorldStore {
                 });
                 crashAtFileNativeAuthorityEdge("after_acceptance_prepared");
                 await authorityStore.publishPrepared(preparedAppend);
+                const acceptedAt = Date.now();
                 crashAtFileNativeAuthorityEdge("after_commit_acceptance");
                 await publishJson(this.#operationOutcomePath(input.operationId), pending);
                 try {
                     const recovered = await authorityStore.recover(commit.head);
                     await assertPendingMaterializationCompatible(root, pending);
-                    await materializeRecoveredEndpoint(root, preparedAppend.nextHead, recovered);
+                    await materializeRecoveredEndpoint(root, preparedAppend.nextHead, recovered, acceptedAt);
                     crashAtFileNativeAuthorityEdge("after_materialization");
                     const outcome = { ...pending, outcome: "committed" };
                     await publishJson(this.#operationOutcomePath(input.operationId), outcome);
@@ -1792,7 +1914,7 @@ function isPlayHistoryAppendInput(value) {
         (value.role === "player" || value.role === "narrator") &&
         typeof value.exactText === "string");
 }
-async function materializeRecoveredEndpoint(root, authority, endpoint) {
+async function materializeRecoveredEndpoint(root, authority, endpoint, lastActivityAt = null) {
     if (authority.head !== endpoint.head)
         throw new FileNativeWorldCreationError("world_corrupt", "Recovered endpoint does not match the Authority head to materialize");
     await replaceMaterializedTree(join(root, "state"), endpoint.state);
@@ -1810,6 +1932,7 @@ async function materializeRecoveredEndpoint(root, authority, endpoint) {
         commitDigest: authority.commitDigest,
         ...backgroundCount(endpoint.history),
     });
+    await updateWorldActivity(root, authority.head, endpoint.history, lastActivityAt);
 }
 async function replaceMaterializedTree(root, files) {
     const next = new Map();
@@ -2065,14 +2188,35 @@ async function readGenesisForFork(worldRoot, worldId) {
 async function readPublicationAt(root) {
     return readJson(join(root, publicationFile));
 }
-async function readWorldSummaryAt(root, publication) {
+async function readWorldSummaryAt(root, publication, serializeRebuild) {
     const published = publication ?? (await readPublicationAt(root));
+    const gameplay = await readWorldGameplayAt(root);
+    const { lastActivityAt, excerpt, playerTurns } = await readWorldActivity(root, serializeRebuild);
+    const summary = {
+        ...toSummary(published, gameplay),
+        title: await readWorldTitleAt(root, published),
+        lastActivityAt,
+        excerpt,
+        playerTurns,
+    };
+    return summary;
+}
+async function readWorldTitleAt(root, published) {
     const metadata = await readOptionalJson(join(root, localMetadataFile));
     if (metadata === null)
-        return toSummary(published);
+        return published.title;
     if (!isWorldLocalMetadata(metadata) || metadata.worldId !== published.worldId)
         throw new FileNativeWorldCreationError("world_corrupt", "Local world shell is corrupt");
-    return { ...toSummary(published), title: metadata.name };
+    return metadata.name;
+}
+/** Worlds copy the package's gameplay identity with control; its absence means interactive fiction. */
+async function readWorldGameplayAt(root) {
+    try {
+        return readGameplay(controlGameplayFiles(await readTree(join(root, "control"))));
+    }
+    catch (error) {
+        throw new FileNativeWorldCreationError("world_corrupt", "World gameplay identity is corrupt", { cause: error });
+    }
 }
 async function readJson(path) {
     return JSON.parse(await readFile(path, "utf8"));
@@ -2087,13 +2231,26 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
-function toSummary(publication) {
+function toSummary(publication, gameplay) {
     return {
         worldId: publication.worldId,
         title: publication.title,
         parentEndpoint: publication.parentEndpoint,
+        gameplay,
     };
 }
+/** World control is a fixed mode and scheme: drafts, revisions and applies may not change either. */
+function assertControlGameplayUnchanged(current, next) {
+    try {
+        assertSameGameplay(controlGameplayFiles(current), controlGameplayFiles(next));
+    }
+    catch (error) {
+        throw new FileNativeWorldCreationError("candidate_validation_failed", error instanceof Error ? error.message : "World gameplay is fixed", { cause: error });
+    }
+}
+function controlGameplayFiles(files) {
+    return files.map((file) => ({ ...file, path: `control/${file.path}` }));
+}
 const worldNamePattern = /^[^\r\n]{1,160}$/u;
 function validWorldName(name) {
     return worldNamePattern.test(name);
@@ -2111,6 +2268,16 @@ function derivationRequestFingerprint(input) {
         sourceHead: input.sourceHead,
         hostPresetId: input.hostPresetId,
         requestDiscriminator: input.requestDiscriminator ?? null,
+        ...(input.retainCompleteTimeline ? { retainCompleteTimeline: true } : {}),
+        ...(input.targetName === undefined &&
+            input.identityPrefix === undefined &&
+            !input.resetPackageScriptPermissions
+            ? {}
+            : {
+                targetName: input.targetName ?? null,
+                identityPrefix: input.identityPrefix ?? "derive",
+                resetPackageScriptPermissions: input.resetPackageScriptPermissions ?? false,
+            }),
     }));
 }
 async function derivationPublicationMatches(worldRoot, publication, input, requestFingerprint) {

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

@@ -0,0 +1,143 @@
+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 { fileNativeHistoryMessageIdFromProjectionPath } from "./FileNativeHistoryProjection.js";
+/** 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 cached = await readCache(root);
+    if (cached?.head === head)
+        return cached;
+    return serializeRebuild(async () => {
+        const latestHead = await currentHead(root);
+        const latestCache = await readCache(root);
+        if (latestCache?.head === latestHead)
+            return latestCache;
+        const empty = {
+            schemaVersion: 1,
+            head: latestHead,
+            lastActivityAt: null,
+            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;
+        const entries = await readdir(join(root, "history"), {
+            withFileTypes: true,
+        });
+        const messages = entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => ({
+            path: entry.name,
+            id: fileNativeHistoryMessageIdFromProjectionPath(entry.name),
+        }))
+            .filter((message) => message.id !== null)
+            .sort((left, right) => {
+            const a = left.path.split("-");
+            const b = right.path.split("-");
+            return Number(a[0]) - Number(b[0]) || Number(a[1]) - Number(b[1]);
+        });
+        const narrator = messages.findLast(({ id }) => id.endsWith(".narrator"));
+        const activity = {
+            ...empty,
+            excerpt: narrator === undefined
+                ? null
+                : excerpt(await readFile(join(root, "history", narrator.path), "utf8")),
+            playerTurns: messages.filter(({ id }) => id.endsWith(".player")).length,
+        };
+        await publishCache(root, activity);
+        return activity;
+    });
+}
+/** Best effort: activity is never part of accepting or recovering Authority. */
+export async function updateWorldActivity(root, head, history, lastActivityAt) {
+    const narrator = history.findLast(({ role }) => role === "narrator");
+    // Recovery cannot reconstruct a clock time, but can retain a matching cache.
+    const previous = lastActivityAt === null ? await readCache(root) : null;
+    await publishCache(root, {
+        schemaVersion: 1,
+        head,
+        lastActivityAt: lastActivityAt ??
+            (previous?.head === head ? previous.lastActivityAt : null),
+        excerpt: narrator === undefined ? null : excerpt(narrator.exactText),
+        playerTurns: history.filter(({ role }) => role === "player").length,
+    });
+}
+function excerpt(text) {
+    const singleLine = text.replace(/[\r\n\u2028\u2029]+/gu, " ").trim();
+    return singleLine === ""
+        ? 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) &&
+        Object.keys(value).length === 5 &&
+        value.schemaVersion === 1 &&
+        typeof value.head === "string" &&
+        /^(?:genesis|commit:[1-9][0-9]*)$/u.test(value.head) &&
+        (value.lastActivityAt === null ||
+            (typeof value.lastActivityAt === "number" &&
+                Number.isSafeInteger(value.lastActivityAt) &&
+                value.lastActivityAt >= 0 &&
+                Number.isFinite(new Date(value.lastActivityAt).valueOf()))) &&
+        (value.excerpt === null ||
+            (typeof value.excerpt === "string" &&
+                Array.from(value.excerpt).length <= 80 &&
+                !/[\r\n\u2028\u2029]/u.test(value.excerpt))) &&
+        typeof value.playerTurns === "number" &&
+        Number.isSafeInteger(value.playerTurns) &&
+        value.playerTurns >= 0
+        ? value
+        : null;
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isMissing(error) || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function publishCache(root, activity) {
+    const path = join(root, "runtime/activity.json");
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(activity)}\n`, {
+            mode: 0o600,
+        });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        console.warn("Could not write world activity cache", root, error);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/node/runtime/world-revision/FileNativeWorldRevisionStore.js

@@ -4,6 +4,7 @@ import { validAuthoringRequests, } from "../authoring/AuthoringRequestSnapshot.j
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { gameplayPath } from "../../protocol/gameplay.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
 const uuidV4Pattern = "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
@@ -604,6 +605,7 @@ function validRevisionPath(path) {
     return (safe &&
         (isPackageFollowupControlPath(path) ||
             /^state\/.+\.(?:ya?ml|md)$/u.test(path) ||
+            path === gameplayPath ||
             path === "control/frame.yaml" ||
             path === "control/player-views.yaml" ||
             /^control\/blocks\/.+\.md$/u.test(path)));