narraeon 0.5.6 → 0.5.7

package/dist/node/runtime/prompt/FileNativeToolRegistry.js

@@ -239,7 +239,7 @@ function createToolDefinitions(locale) {
 }
 const toolDescriptions = {
     en: {
-        world_checkpoint: "Register a consolidation declaration and a history-replay boundary. No arguments. Registration takes effect only after the subsequent nonempty tool-free final prose successfully commits, and includes that prose. A fresh context replays committed player inputs and final narratives after this boundary. The player may choose a fresh context; registration neither switches context nor ends an in-world event. Further tool calls may follow registration; Runtime does not verify semantic completeness.",
+        world_checkpoint: "Register a gap between events: the previous event has naturally settled at this turn's stopping point, or the scene has actually changed, suggesting that the player start a fresh context here. Arguments must be an empty object. Registration takes effect only after the subsequent nonempty tool-free final prose successfully commits, and includes that prose. A fresh context replays only committed player inputs and final narratives after this boundary, so save still-needed outcomes before registration. Consolidation and maintenance do not require this tool. Do not advance the story to register a checkpoint; registration neither switches context nor ends an in-world event. Further tool calls may follow registration; Runtime does not verify semantic completeness.",
         state_list: "List document and state directory handles known to Runtime. parent must be @dir-/ for the state root or an @dir-* handle from the initial directory index or an earlier state_list result; no preliminary listing is needed for an already supplied handle. Catalog directories declared by the frozen world frame remain listed and usable when empty. A cursor is valid only for the same state snapshot, parent, and limit. Pass returned document handles to context_read. This tool never lists committed history.",
         history_list: "Browse committed history on the current timeline. Omit anchors for the latest page; use only before or after with a Runtime ref (including refs in injected history) for the immediately adjacent page, excluding the anchor. Every page is oldest to newest. limit defaults to 20 (1–100 messages). Previews are only the first 120 Unicode code points. Use independent earlierCursor/laterCursor with {cursor} alone; no first-query parameters on continuation. Cursors bind world, tool, query and immutable ordered history. After history_changed rerun the query. Opening messages are queryable. Read full originals with history_read; positions are snapshot locations, not identities or turns.",
         history_search: "Search committed originals on the current timeline with queries: 1–5 nonempty literal strings (max 256 code points each); no query alias or semantic filters. match defaults to any, or all within one message. NFKC normalization always applies; caseSensitive defaults to false (locale-und case folding), normalized duplicate queries collapse. order defaults to newest_first, or oldest_first. limit defaults to 10 (1–50 matching messages). Optional after/before refs exclude timeline boundaries independently of order; after must precede before. Each result has at most 3 partial original fragments, query occurrence counts and complete-original length. Read a hit and nearby context with history_read. Continue with {cursor} alone; history_changed requires a new query.",
@@ -253,7 +253,7 @@ const toolDescriptions = {
         artifact_clear: "Clear the projection of an artifact that this follow-up declared in advance and explicitly allows to be cleared. The call cannot choose a channel, key, or any other output contract.",
     },
     "zh-CN": {
-        world_checkpoint: "登记整理声明与历史重放边界，参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文补入边界之后的已提交玩家原文与最终叙事。玩家可自行选择全新上下文，登记不切换上下文，也不结束世界内事件。登记后仍可继续工具调用；Runtime 不认证语义整理完整。",
+        world_checkpoint: "登记事件间隙：上一事件已在本轮停笔位置自然告一段落，或场景已实际转换，建议玩家从这里开始全新上下文。参数为空对象。仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；全新上下文只补入边界之后的已提交玩家原文与最终叙事，因此登记前应已保存后续仍需要的结果。整理与归并不需要调用本工具。不要为了登记而推进剧情；登记不切换上下文，也不结束世界内事件。登记后仍可继续工具调用；Runtime 不认证语义完整。",
         state_list: "列出 Runtime 已知的文档与状态目录句柄。状态根目录的 parent 使用 @dir-/；继续下级时使用初始目录索引或 state_list 返回的 @dir-*；已有句柄无需再次列目录确认。冻结世界 frame 声明的 catalog 目录即使为空，也会继续列出并可用。cursor 只对同一状态快照、parent 和 limit 有效。返回的文档句柄交给 context_read；本工具不列出已提交历史。",
         history_list: "浏览当前时间线已提交历史。无锚点时取最新一页；before 或 after 只能选一个，取锚点紧邻前／后的一页且不含锚点。页内始终由旧到新。limit 默认20，整数1–100。预览仅含前120个Unicode码点；完整原文用history_read。earlierCursor／laterCursor独立翻页，续页只传{cursor}，不可混用首次参数。游标绑定世界、工具、查询和有序历史快照；history_changed须重新查询。开场白可查询。提示词注入中的ref可直接使用，无需再次列举；位置不是身份或回合数。",
         history_search: "搜索当前时间线已提交原文。queries必填：1–5个非空字面词，每词最多256个Unicode码点，不接受query别名或语义筛选。match默认any，all限于同一消息。始终NFKC规范化，caseSensitive默认false（locale-und大小写折叠），规范化重复词合并。order默认newest_first，可选oldest_first；limit默认10，整数1–50条命中消息。after／before始终按时间线先后排除边界，after必须早于before，与结果排序无关。每项最多3个部分原文片段、逐词命中次数及完整原文长度；可用history_read读取前后文。续页只传{cursor}；history_changed须重新查询。",

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

@@ -2,6 +2,8 @@ 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 { 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 +13,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 +44,7 @@ export class FileNativeWorldStore {
     #promptCompiler;
     #activeControlUsers = new Map();
     #openingWorldRevisions = new Set();
+    #archiveExports = new Set();
     operations;
     playTimeline;
     playAdvances;
@@ -112,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");
@@ -144,7 +172,7 @@ export class FileNativeWorldStore {
                 worldId,
                 name: trimmed,
             });
-            return { ...toSummary(publication), title: trimmed };
+            return readWorldSummaryAt(root, publication);
         });
     }
     /**
@@ -321,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);
@@ -398,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);
@@ -431,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 {
@@ -587,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();
@@ -796,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);
@@ -830,24 +910,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 +964,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 +993,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 +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;
             }
@@ -1285,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);
@@ -1792,7 +1903,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 +1921,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 +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"));
@@ -2111,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) {

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/server/createServer.js

@@ -6,6 +6,7 @@ import fastifyStatic from "@fastify/static";
 import Fastify, { LogController, } from "fastify";
 import { maxPortableContentArchiveBase64Characters } from "../protocol/contentTree.js";
 import { parseV1Envelope, V1ProtocolError, v1Protocol, } from "../protocol/v1.js";
+import { WorldArchiveError } from "../runtime/archive/WorldArchiveZip.js";
 const runtimeRequestBodyLimit = maxPortableContentArchiveBase64Characters + 64 * 1024;
 const playCallChainStreamContentType = "application/x-ndjson";
 class RuntimeLogController extends LogController {
@@ -81,6 +82,53 @@ export async function createServer(input) {
         done(null, payload);
     });
     registerConversationStream(server, input.runtime);
+    // Keep uploads as a backpressured stream with their own archive-size limit.
+    // Fastify's JSON parser and content-package body limit never buffer this route.
+    await server.register((archives, _options, done) => {
+        archives.addContentTypeParser("application/zip", (_request, payload, done) => done(null, payload));
+        archives.post("/api/runtime/v1/world-archives", async (request, reply) => {
+            try {
+                return await input.runtime.worldArchives.upload(request.body);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(error.code === "limit_exceeded" ? 413 : 400)
+                        .send({ error: { code: error.code, message: error.message } });
+                throw error;
+            }
+        });
+        archives.get("/api/runtime/v1/world-archives/:archiveId", async (request, reply) => {
+            try {
+                const archive = await input.runtime.worldArchives.download(request.params.archiveId);
+                reply.raw.once("finish", () => {
+                    void archive.cleanup().catch(() => undefined);
+                });
+                return reply
+                    .type("application/zip")
+                    .header("Content-Length", archive.metadata.bytes)
+                    .header("Content-Disposition", `attachment; filename="world.narraeon-world.zip"; filename*=UTF-8''${encodeURIComponent(archive.metadata.fileName)}`)
+                    .send(archive.stream);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(400)
+                        .send({ error: { code: error.code, message: error.message } });
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return reply.status(404).send({
+                        error: {
+                            code: "invalid_archive",
+                            message: "The archive download is unavailable",
+                        },
+                    });
+                throw error;
+            }
+        });
+        done();
+    });
     server.get("/health", () => ({
         status: "ok",
         protocol: "narraeon.runtime/v1",