narraeon 0.5.5 → 0.5.7

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

@@ -1,6 +1,9 @@
+import { captureNarrativeOrigin, snapshotBackground, isHistoryBackground, } from "../history/HistoryBackground.js";
 import { FileNativeArtifactStore } from "../artifact/FileNativeArtifactStore.js";
 import { WorldExtensionRequests } from "../extension/WorldExtensionRequests.js";
 import { WorldExtensionControls, extensionDefinitions, } from "../extension/WorldExtensionControls.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";
@@ -10,12 +13,13 @@ 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";
 import { FileNativeAuthorityV3, FileNativeAuthorityV3Error, } from "./FileNativeAuthorityV3.js";
 import { FileNativeWorldOperationCoordinator, WorldOperationBusyError, } from "./WorldOperationCoordinator.js";
-import { fileNativeHistoryMessageIdFromProjectionPath, projectFileNativeHistorySurface, } from "./FileNativeHistoryProjection.js";
+import { fileNativeHistoryMessageIdFromProjectionPath, projectFileNativeHistorySurface, projectHistoryBackgrounds, historyBackgroundRecord, } from "./FileNativeHistoryProjection.js";
 const publicationFile = "publication.json";
 const localMetadataFile = "local.json";
 export class FileNativeWorldCreationError extends Error {
@@ -40,6 +44,7 @@ export class FileNativeWorldStore {
     #promptCompiler;
     #activeControlUsers = new Map();
     #openingWorldRevisions = new Set();
+    #archiveExports = new Set();
     operations;
     playTimeline;
     playAdvances;
@@ -111,16 +116,40 @@ 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 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");
@@ -143,7 +172,7 @@ export class FileNativeWorldStore {
                 worldId,
                 name: trimmed,
             });
-            return { ...toSummary(publication), title: trimmed };
+            return readWorldSummaryAt(root, publication);
         });
     }
     /**
@@ -266,7 +295,10 @@ export class FileNativeWorldStore {
         await mkdir(this.#operationsRoot, { recursive: true, mode: 0o700 });
         await rm(stagingRoot, { recursive: true, force: true });
         try {
-            const openingMessage = genesisOpeningMessage(openingText(packageFiles));
+            const openingMessage = {
+                ...genesisOpeningMessage(openingText(packageFiles)),
+                ...backgroundField(snapshotBackground(captureNarrativeOrigin(inspection.worldDocumentSnapshot, 1).value)),
+            };
             const initialMaterials = [
                 { kind: "history_message", message: openingMessage.messageId },
             ];
@@ -276,6 +308,7 @@ export class FileNativeWorldStore {
             await mkdir(join(stagingRoot, "history"), { recursive: true });
             await mkdir(join(stagingRoot, "runtime"), { recursive: true });
             await writeIdempotentText(join(stagingRoot, "history", historySurfaceFiles([openingMessage])[0].path), openingMessage.exactText);
+            await replaceMaterializedTree(join(stagingRoot, "runtime", "history-backgrounds"), projectHistoryBackgrounds([openingMessage]));
             const genesis = {
                 schemaVersion: 1,
                 type: "file_native_genesis",
@@ -304,6 +337,7 @@ export class FileNativeWorldStore {
                 head: "genesis",
                 sequence: 0,
                 commitDigest: null,
+                ...backgroundCount([openingMessage]),
             });
             await writeJson(join(stagingRoot, "runtime", "additional-materials.json"), { head: "genesis", items: initialMaterials });
             const publication = {
@@ -315,13 +349,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);
@@ -392,6 +431,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);
@@ -425,7 +489,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 {
@@ -581,6 +646,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();
@@ -634,7 +701,9 @@ export class FileNativeWorldStore {
                 const authorityStore = new FileNativeAuthorityV3(root);
                 const authority = await authorityStore.readHead();
                 const checkpoint = await readMaterializedCheckpoint(root);
-                if (!sameMaterializedEndpoint(checkpoint, authority)) {
+                const cachedBackgrounds = await readTree(join(root, "runtime", "history-backgrounds"));
+                if (!sameMaterializedEndpoint(checkpoint, authority) ||
+                    (checkpoint?.historyBackgroundCount ?? 0) !== cachedBackgrounds.length) {
                     const recovered = await authorityStore.recover();
                     let operation = null;
                     if (authority.operationId !== null && authority.sequence > 0) {
@@ -654,11 +723,12 @@ export class FileNativeWorldStore {
                     if (operation !== null)
                         await publishJson(this.#operationOutcomePath(authority.operationId), { ...operation, outcome: "committed" });
                 }
-                const [state, control, history, materials] = await Promise.all([
+                const [state, control, history, materials, backgrounds] = await Promise.all([
                     readTree(join(root, "state")),
                     readTree(join(root, "control")),
                     readTree(join(root, "history")),
                     readOptionalJson(join(root, "runtime", "additional-materials.json")),
+                    readTree(join(root, "runtime", "history-backgrounds")),
                 ]);
                 if ((materials?.head ?? "genesis") !== authority.head)
                     throw new FileNativeWorldCreationError("inconsistent_materialization", "Materialized additional materials do not match the current Authority endpoint");
@@ -672,6 +742,7 @@ export class FileNativeWorldStore {
                     }, {}),
                     additionalMaterials: materials?.items ?? [],
                     history: materializedHistoryRecord(history),
+                    historyBackgrounds: materializedBackgroundRecord(backgrounds, materializedHistoryRecord(history)),
                     narrativeCheckpoint: await authorityStore.readNarrativeCheckpoint(),
                 };
             });
@@ -702,6 +773,7 @@ export class FileNativeWorldStore {
             }, {}),
             additionalMaterials: structuredClone(endpoint.additionalMaterials),
             narrativeCheckpoint: endpoint.narrativeCheckpoint,
+            historyBackgrounds: historyBackgroundRecord(endpoint.history),
             history: Object.fromEntries(endpoint.history.map(({ messageId, exactText }) => [
                 messageId,
                 exactText,
@@ -785,32 +857,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);
@@ -819,28 +910,42 @@ 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))
                     await writeIdempotentText(join(staging, "history", file.path), file.contents);
+                await replaceMaterializedTree(join(staging, "runtime", "history-backgrounds"), projectHistoryBackgrounds(selected.history));
                 const genesis = {
                     schemaVersion: 1,
                     type: "file_native_genesis",
@@ -859,49 +964,63 @@ 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;
                         }, {}),
                         additionalMaterials: structuredClone(selected.additionalMaterials),
+                        historyBackgrounds: historyBackgroundRecord(selected.history),
                         history: Object.fromEntries(selected.history.map(({ messageId, exactText }) => [
                             messageId,
                             exactText,
                         ])),
                     },
                 });
+                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);
@@ -909,8 +1028,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;
             }
@@ -1032,11 +1156,26 @@ export class FileNativeWorldStore {
             !replaced.historyAppend.some(({ role }) => role === "player") ||
             logicalParent !== input.restoresHead)
             throw new FileNativeWorldCreationError("operation_conflict", "Selected player message does not match the logical parent endpoint to restore");
+        const binding = await this.bindPlayCallChainAt(input.worldId, input.restoresHead);
+        const snapshot = WorldDocumentStore.open({
+            layout: "world_state",
+            files: Object.entries(binding.files).map(([path, contents]) => ({
+                path,
+                contents,
+            })),
+        });
+        const background = snapshotBackground(captureNarrativeOrigin(snapshot, 1).value);
         return this.#commitHistoryChange({
             operationId: input.operationId,
             worldId: input.worldId,
             parentHead: input.expectedCurrentHead,
-            historyAppend: [{ role: "player", exactText: input.replacementText }],
+            historyAppend: [
+                {
+                    role: "player",
+                    exactText: input.replacementText,
+                    ...backgroundField(background),
+                },
+            ],
             nextMaterials: worldNeutralMaterials(input.worldId, replacementMaterials),
             stateChanges: [],
             mode: "timeline_revision",
@@ -1256,12 +1395,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);
@@ -1328,9 +1468,10 @@ export class FileNativeWorldStore {
         return {
             endpoint: recovered.head,
             state: recovered.state,
-            history: recovered.history.map(({ role, exactText }) => ({
+            history: recovered.history.map(({ role, exactText, background }) => ({
                 role,
                 exactText,
+                ...backgroundField(background),
             })),
             additionalMaterials: recovered.additionalMaterials,
         };
@@ -1636,7 +1777,11 @@ async function assertCommittedAuthorityOutcomeMatches(worldRoot, outcome) {
         commit.auditParent.head !== outcome.parentHead ||
         commit.head !== outcome.head ||
         commit.mode !== outcome.mode ||
-        !isDeepStrictEqual(commit.historyAppend.map(({ role, exactText }) => ({ role, exactText })), outcome.historyAppend) ||
+        !isDeepStrictEqual(commit.historyAppend.map(({ role, exactText, background }) => ({
+            role,
+            exactText,
+            ...backgroundField(background),
+        })), outcome.historyAppend) ||
         !isDeepStrictEqual(commit.nextAdditionalMaterials, outcome.nextAdditionalMaterials))
         throw corruptOperationOutcome();
     return commit;
@@ -1725,12 +1870,10 @@ async function readMaterializedCheckpoint(root) {
     if (value === null)
         return null;
     if (!isRecord(value) ||
-        !hasExactKeys(value, [
-            "schemaVersion",
-            "head",
-            "sequence",
-            "commitDigest",
-        ]) ||
+        !hasRequiredAndOptionalKeys(value, ["schemaVersion", "head", "sequence", "commitDigest"], ["historyBackgroundCount"]) ||
+        (value.historyBackgroundCount !== undefined &&
+            (!Number.isSafeInteger(value.historyBackgroundCount) ||
+                Number(value.historyBackgroundCount) < 1)) ||
         value.schemaVersion !== 3 ||
         typeof value.head !== "string" ||
         !Number.isSafeInteger(value.sequence) ||
@@ -1753,16 +1896,20 @@ function sameMaterializedEndpoint(checkpoint, authority) {
 }
 function isPlayHistoryAppendInput(value) {
     return (isRecord(value) &&
-        hasExactKeys(value, ["role", "exactText"]) &&
+        hasRequiredAndOptionalKeys(value, ["role", "exactText"], ["background"]) &&
+        (value.background === undefined ||
+            (isHistoryBackground(value.background) &&
+                (value.role !== "player" || value.background.kind === "snapshot"))) &&
         (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);
     crashAtFileNativeAuthorityEdge("after_state_materialization");
     await replaceMaterializedTree(join(root, "history"), historySurfaceFiles(endpoint.history));
+    await replaceMaterializedTree(join(root, "runtime", "history-backgrounds"), projectHistoryBackgrounds(endpoint.history));
     await publishJson(join(root, "runtime", "additional-materials.json"), {
         head: authority.head,
         items: endpoint.additionalMaterials,
@@ -1772,7 +1919,9 @@ async function materializeRecoveredEndpoint(root, authority, endpoint) {
         head: authority.head,
         sequence: authority.sequence,
         commitDigest: authority.commitDigest,
+        ...backgroundCount(endpoint.history),
     });
+    await updateWorldActivity(root, authority.head, endpoint.history, lastActivityAt);
 }
 async function replaceMaterializedTree(root, files) {
     const next = new Map();
@@ -1900,7 +2049,11 @@ function authorityCommitMatchesInput(commit, input) {
         commit.auditParent.head === input.parentHead &&
         commit.timelineParent.head ===
             (input.timelineRevision?.restoresHead ?? input.parentHead) &&
-        isDeepStrictEqual(commit.historyAppend.map(({ role, exactText }) => ({ role, exactText })), input.historyAppend) &&
+        isDeepStrictEqual(commit.historyAppend.map(({ role, exactText, background }) => ({
+            role,
+            exactText,
+            ...backgroundField(background),
+        })), input.historyAppend) &&
         stateChangesMatch &&
         isDeepStrictEqual(commit.nextAdditionalMaterials, input.nextMaterials) &&
         isDeepStrictEqual(commit.timelineRevision, input.timelineRevision) &&
@@ -1989,7 +2142,9 @@ async function readGenesisForFork(worldRoot, worldId) {
     const prefix = `${worldId}.`;
     const history = value.history.map((message, index) => {
         if (!isRecord(message) ||
-            !hasExactKeys(message, ["messageId", "role", "exactText"]) ||
+            !hasRequiredAndOptionalKeys(message, ["messageId", "role", "exactText"], ["background"]) ||
+            (message.background !== undefined &&
+                !isHistoryBackground(message.background)) ||
             typeof message.messageId !== "string" ||
             (message.role !== "player" && message.role !== "narrator") ||
             typeof message.exactText !== "string")
@@ -2007,6 +2162,7 @@ async function readGenesisForFork(worldRoot, worldId) {
             messageId,
             role,
             exactText: message.exactText,
+            ...backgroundField(message.background),
         };
     });
     let additionalMaterials;
@@ -2021,14 +2177,25 @@ 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 { lastActivityAt, excerpt, playerTurns } = await readWorldActivity(root, serializeRebuild);
+    const summary = {
+        ...toSummary(published),
+        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;
 }
 async function readJson(path) {
     return JSON.parse(await readFile(path, "utf8"));
@@ -2067,6 +2234,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) {
@@ -2122,3 +2299,21 @@ function crashAtFileNativeAuthorityEdge(edge) {
     }
 }
 import { readDocumentMaintenanceFacts, } from "./WorldDocumentMaintenance.js";
+function backgroundField(background) {
+    return background === undefined ? {} : { background };
+}
+function materializedBackgroundRecord(files, history) {
+    return Object.fromEntries(files.map(({ path, contents }) => {
+        const id = path.replace(/\.json$/u, "");
+        const value = JSON.parse(contents);
+        if (path !== `${id}.json` ||
+            !Object.hasOwn(history, id) ||
+            !isHistoryBackground(value))
+            throw new FileNativeWorldCreationError("world_corrupt", "Materialized history background is invalid or unreachable");
+        return [id, value];
+    }));
+}
+function backgroundCount(messages) {
+    const count = messages.filter(({ background }) => background !== undefined).length;
+    return count === 0 ? {} : { historyBackgroundCount: count };
+}