narraeon 0.7.6 → 0.7.9

package/dist/node/runtime/authoring/AuthoringRequestSnapshot.js

@@ -1,4 +1,15 @@
 import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
+export function isAuthoringPreloadRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (Object.keys(record).length === 3 &&
+        typeof record.revision === "string" &&
+        Array.isArray(record.worldDocumentIds) &&
+        record.worldDocumentIds.every((id) => typeof id === "string") &&
+        Array.isArray(record.opaquePaths) &&
+        record.opaquePaths.every((path) => typeof path === "string"));
+}
 export function validAuthoringRequests(value, validPrompt, session) {
     if (!Array.isArray(value) ||
         value.length === 0 ||
@@ -14,7 +25,9 @@ export function validAuthoringRequests(value, validPrompt, session) {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return false;
         const item = raw;
-        if (Object.keys(item).length !== 4 ||
+        const keys = Object.keys(item).length;
+        if ((keys !== 4 && !(keys === 5 && "preload" in item)) ||
+            (item.preload !== undefined && !isAuthoringPreloadRecord(item.preload)) ||
             typeof item.requestId !== "string" ||
             !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u.test(item.requestId) ||
             ids.has(item.requestId) ||

package/dist/node/runtime/history/HistoryRendering.js

@@ -1,5 +1,15 @@
 import { isDeepStrictEqual } from "node:util";
 import { parseDocument } from "yaml";
+/** Scope and total only; ordering and continuation rules live in tool descriptions. */
+function compactHeader(total, locale) {
+    const zh = locale === "zh-CN";
+    return `Scope: ${zh ? "当前时间线" : "current timeline"}\n${zh ? "本次读取快照消息总数" : "Snapshot total messages"}: ${total}`;
+}
+/** Position, role and ref only; role=x would repeat the localized role label. */
+function compactMessageLabel(message, locale) {
+    const zh = locale === "zh-CN";
+    return `${zh ? "位置" : "position"} ${message.position} · ${historyRoleLabel(message, locale)}${message.isOpening ? " · isOpening=true" : ""} · ${message.ref} · ${message.length} Unicode code points`;
+}
 /** Shared metadata keeps injected refs and tool results directly navigable. */
 export function historyMessageLabel(message, locale) {
     const zh = locale === "zh-CN";
@@ -58,18 +68,26 @@ export function renderHistoryResult(result, locale = "en", legacyRead = false) {
     if (result.kind === "list")
         return {
             ok: true,
-            markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${header}\nOrder: oldest_first (${zh ? "页内始终由旧到新" : "every page oldest to newest"})\n${result.messages
+            markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${compactHeader(result.total, locale)}\n${result.messages
                 .map((message) => {
                 const preview = Array.from(message.text).slice(0, 120).join("");
-                return `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n${renderHistoryBackground(message.background, locale)}[${zh ? "部分原文预览" : "Partial original preview"}]\n${preview}\n[${message.length > 120 ? (zh ? "预览有省略" : "preview omitted remaining text") : zh ? "预览结束" : "preview ends"}]`;
+                const omitted = message.length > 120
+                    ? `\n${zh ? "…（预览省略）" : "…(preview omitted)"}`
+                    : "";
+                return `### ${compactMessageLabel(message, locale)}${renderHistoryBackground(message.background, locale, false)}\n${preview}${omitted}`;
             })
-                .join("\n\n") || (zh ? "（空页）" : "(empty page)")}\n\n---\n${zh ? "本页位置／条数" : "Page positions / count"}: ${range(result.messages)} / ${result.messages.length}\n${cursorLine("earlierCursor", result.earlierCursor)}\n${cursorLine("laterCursor", result.laterCursor)}\n${zh ? "续页只传 {cursor}。" : "Continue with only {cursor}."}${result.messages.length === 0 && result.anchor !== null ? `\n${zh ? "可从锚点转向浏览" : "Browse from the anchor in the other direction"}: {before:"${result.anchor}"} / {after:"${result.anchor}"}` : ""}`,
+                .join("\n\n") || (zh ? "（空页）" : "(empty page)")}\n\n---\n${zh ? "本页位置／条数" : "Page positions / count"}: ${range(result.messages)} / ${result.messages.length}\n${cursorLine("earlierCursor", result.earlierCursor)}\n${cursorLine("laterCursor", result.laterCursor)}${result.messages.length === 0 && result.anchor !== null ? `\n${zh ? "可从锚点转向浏览" : "Browse from the anchor in the other direction"}: {before:"${result.anchor}"} / {after:"${result.anchor}"}` : ""}`,
         };
     if (result.kind === "read")
         return {
             ok: true,
             markdown: `# ${zh ? "完整历史原文" : "Complete history originals"}\n\n${header}\nMode: ${result.mode}${result.center === null ? "" : `\nCenter: ${result.center}`}\nOrder: oldest_first\n${zh ? "实际位置" : "Actual positions"}: ${range(result.messages)}\n${zh ? "每条正文完整，无摘要、无截断" : "Each body is complete, without summary or truncation"}\n\n${result.messages.map((message) => renderHistoryMessage(message, locale)).join("\n\n") || (zh ? "（历史为空）" : "(empty history)")}\n\n---\n${cursorLine("earlier", result.earlier)}\n${cursorLine("later", result.later)}\n${result.earlier === null ? (zh ? "已到历史开头。" : "At the history beginning.") : legacyRead ? `context_read {ref:"${result.earlier}"}` : zh ? "向前不重复读取：history_read {ref:earlier,before:N}。" : "Read earlier without repeating this window: history_read {ref:earlier,before:N}."}\n${result.later === null ? (zh ? "已到历史结尾。" : "At the history end.") : legacyRead ? `context_read {ref:"${result.later}"}` : zh ? "向后不重复读取：history_read {ref:later,after:N}。" : "Read later without repeating this window: history_read {ref:later,after:N}."}\n${legacyRead ? (zh ? "按需逐条读取相邻原文。" : "Read adjacent originals one at a time as needed.") : zh ? "按需小步扩展；21 条消息不代表固定输出体积。" : "Expand in small windows as needed; 21 messages do not imply a fixed output size."}`,
         };
+    if (!result.legacy)
+        return {
+            ok: true,
+            markdown: `# ${zh ? "历史字面搜索" : "History literal search"}\n\n${compactHeader(result.total, locale)}\n${zh ? "搜索位置范围（排除边界）" : "Search position range (boundaries excluded)"}: ${result.range.start === null ? "empty" : `${result.range.start}..${result.range.end}`}\n${zh ? "查询词" : "Queries"}: ${JSON.stringify(result.queries)}\n${zh ? "命中消息总数" : "Total matching messages"}: ${result.matches}\n\n${result.messages.map(({ message, hits, fragments, omittedMatches }) => `### ${compactMessageLabel(message, locale)}${renderHistoryBackground(message.background, locale, false)}${zh ? "逐词命中次数" : "Matches per query"}: ${hits.map(({ query, count }) => `${JSON.stringify(query)}: ${count}`).join("; ")}\n${fragments.map((fragment) => `[${zh ? "部分原文片段" : "Partial original fragment"}: ${fragment.start}..${fragment.end}${fragment.omittedBefore ? "; prefix omitted" : ""}${fragment.omittedAfter ? "; suffix omitted" : ""}]\n${fragment.text}`).join("\n")}${omittedMatches ? `\n${zh ? "另有命中未展示；可完整读取核实。" : "Additional matches omitted; read the complete original to verify."}` : ""}`).join("\n\n") || (zh ? "零字面命中不证明事件没有发生；可改词、从 all 放宽为 any 或读取相邻上下文。" : "Zero literal matches do not prove an event never happened. Try other words, relax all to any, or read nearby context.")}\n\n---\n${cursorLine("nextCursor", result.nextCursor)}`,
+        };
     return {
         ok: true,
         markdown: `# ${zh ? "历史字面搜索" : "History literal search"}\n\n${header}${result.within === null ? "" : `\nLegacy selected scope: ${result.within}`}\n${zh ? "搜索位置范围（排除边界）" : "Search position range (boundaries excluded)"}: ${result.range.start === null ? "empty" : `${result.range.start}..${result.range.end}`}\nOrder: ${result.order}\nMatch: ${result.match} (${zh ? "同一消息内" : "within one message"})\nNormalization: NFKC${result.caseSensitive ? " (case sensitive)" : " + case folding (locale und)"}\n${zh ? "查询词" : "Queries"}: ${JSON.stringify(result.queries)}\n${zh ? "命中消息总数" : "Total matching messages"}: ${result.matches}\n\n${result.messages.map(({ message, hits, fragments, omittedMatches }) => `### ${historyMessageLabel(message, locale)}\n${message.length} Unicode code points\n${renderHistoryBackground(message.background, locale)}${zh ? "逐词命中次数" : "Matches per query"}: ${hits.map(({ query, count }) => `${JSON.stringify(query)}: ${count}`).join("; ")}\n${fragments.map((fragment) => `[${zh ? "部分原文片段" : "Partial original fragment"}: ${fragment.start}..${fragment.end}${fragment.omittedBefore ? "; prefix omitted" : ""}${fragment.omittedAfter ? "; suffix omitted" : ""}]\n${fragment.text}\n[${zh ? "片段结束" : "fragment ends"}]`).join("\n")}\n${omittedMatches ? (zh ? "另有命中未展示；可完整读取核实。" : "Additional matches omitted; read the complete original to verify.") : zh ? "全部命中均在所示片段内。" : "All matches are covered by these fragments."}`).join("\n\n") || (result.legacy ? (zh ? "零字面命中不证明事件没有发生；可改用其他 query 或读取相邻原文。" : "Zero literal matches do not prove an event never happened. Try another query or read adjacent originals.") : zh ? "零字面命中不证明事件没有发生；可改词、从 all 放宽为 any 或读取相邻上下文。" : "Zero literal matches do not prove an event never happened. Try other words, relax all to any, or read nearby context.")}\n\n---\n${cursorLine(result.legacy ? "Next-page cursor" : "nextCursor", result.nextCursor)}\n${result.legacy ? (zh ? "续页保留原source=history、query、caseSensitive、within与limit并使用返回cursor。" : "Legacy continuation keeps the original source=history, query, caseSensitive, within and limit with the returned cursor.") : zh ? "续页只传 {cursor}；已有原文足以判断时停止检索。all 仅限同一消息；相邻消息可改用 any 后读前后文。" : "Continue with only {cursor}; stop when the originals suffice. all applies to one message; use any then read context for terms in adjacent messages."}`,
@@ -87,7 +105,7 @@ function localizedRecovery(result, zh) {
     return `参数不符合要求，请按工具定义修正。${result.recovery}`;
 }
 /** Every result carries its own annotation; no implicit neighboring inheritance. */
-export function renderHistoryBackground(background, locale) {
+export function renderHistoryBackground(background, locale, withNotice = true) {
     if (background === undefined)
         return "";
     const zh = locale === "zh-CN";
@@ -99,10 +117,11 @@ export function renderHistoryBackground(background, locale) {
     const notice = zh
         ? "历史背景仅说明采集位置的状态，不是当前世界状态；回忆、梦境或段内局部时间结合原文解释，不认证事实或授予角色知识。"
         : "Historical background describes the captured state, not current world state; interpret memories, dreams and local times with the original text. It does not certify facts or grant character knowledge.";
+    const suffix = withNotice ? `\n${notice}` : "";
     if (background.kind === "snapshot" ||
         equalBackground(background.before, background.after))
-        return `\n${zh ? "历史背景" : "Historical background"}:${node(background.kind === "snapshot" ? background.value : background.before)}\n${notice}\n`;
-    return `\n${zh ? "推进前背景" : "Background before advancement"}:${node(background.before)}\n${zh ? "推进后背景" : "Background after advancement"}:${node(background.after)}\n${notice}\n`;
+        return `\n${zh ? "历史背景" : "Historical background"}:${node(background.kind === "snapshot" ? background.value : background.before)}${suffix}\n`;
+    return `\n${zh ? "推进前背景" : "Background before advancement"}:${node(background.before)}\n${zh ? "推进后背景" : "Background after advancement"}:${node(background.after)}${suffix}\n`;
 }
 function equalBackground(before, after) {
     if (before === after)

package/dist/node/runtime/history/HistoryTools.js

@@ -0,0 +1,31 @@
+import { HistoryQuery, historyInputs } from "./HistoryQuery.js";
+import { renderHistoryResult } from "./HistoryRendering.js";
+export const historyToolNames = [
+    "history_list",
+    "history_search",
+    "history_read",
+];
+export function isHistoryToolName(name) {
+    return historyToolNames.includes(name);
+}
+export function historyEntries(history, backgrounds = {}) {
+    return Object.entries(history).map(([path, contents]) => ({
+        path,
+        contents,
+        ...(backgrounds[path] === undefined
+            ? {}
+            : { background: structuredClone(backgrounds[path]) }),
+    }));
+}
+/** Read-only committed-history navigation shared by play and world revision. */
+export function createHistoryQuery(scope, entries) {
+    return new HistoryQuery(scope, historyInputs(entries));
+}
+export function runHistoryTool(query, call, locale) {
+    const result = call.name === "history_search"
+        ? query.search(call.arguments)
+        : call.name === "history_read"
+            ? query.read(call.arguments)
+            : query.list(call.arguments);
+    return renderHistoryResult(result, locale);
+}

package/dist/node/runtime/play/FileNativeContinuityCorrection.js

@@ -4,7 +4,7 @@ import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js
 import { validateMaterialList } from "../prompt/MaterialSelection.js";
 import { FileNativeWorldCreationError, } from "../world/FileNativeWorldStore.js";
 import { WorldOperationBusyError, } from "../world/WorldOperationCoordinator.js";
-import { beginWorldStateRevision, fileNativeStateChanges, reviseWorldState, worldDocumentRevisionFailureMessage, worldStateRevisionChanges, } from "../world/WorldStateRevision.js";
+import { beginWorldStateRevision, fileNativeStateChanges, acceptWorldStateRevision, worldDocumentRevisionFailureMessage, worldStateRevisionChanges, } from "../world/WorldStateRevision.js";
 export class FileNativeContinuityCorrection {
     #worlds;
     #compiler;
@@ -260,9 +260,17 @@ export class FileNativeContinuityCorrection {
         return document;
     }
     #reviseDocument(candidate, command) {
-        const revised = reviseWorldState(candidate, { commands: [command] });
-        if (!revised.ok || revised.snapshotStatus !== "usable")
-            throw new Error(worldDocumentRevisionFailureMessage(revised.diagnostics));
+        // A correction applies all of its edits or none of them, so a skipped edit
+        // is a failure here even though the revision itself settled.
+        const revised = candidate.snapshot.revise({ commands: [command] });
+        const failures = revised.ok
+            ? revised.editOutcomes.flatMap(({ status, diagnostic }) => status === "failed" && diagnostic !== undefined ? [diagnostic] : [])
+            : revised.diagnostics;
+        if (!revised.ok ||
+            revised.snapshotStatus !== "usable" ||
+            failures.length > 0)
+            throw new Error(worldDocumentRevisionFailureMessage(failures));
+        acceptWorldStateRevision(candidate, revised);
         candidate.reads.clear();
     }
     #advance(candidate) {

package/dist/node/runtime/play/PlayCallChain.js

@@ -2,6 +2,7 @@ import { projectLegacyModelBindingFailure } from "./LegacyModelBindingFailure.js
 import { dispatchFailureEnding, emptyResponseEnding, lastEndingCancelled, noContinuationEnding, PlayAdvanceLifecycle, settlementFailureEnding, } from "./PlayAdvanceLifecycle.js";
 import { isResolutionTool, resolutionMarkdown, resolutionToolNames, resolveTabletop, seededRandom, } from "./TabletopResolution.js";
 import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
+import { historyEntries } from "../history/HistoryTools.js";
 import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
 import { renderToolAliasNote, resolveToolName, } from "../prompt/ToolNameAlias.js";
@@ -13,7 +14,6 @@ import { createHash, randomBytes } from "node:crypto";
 import { isTurnGuideLine } from "../../shared/ordered-play-prompts.js";
 import { turnGuideWithTurnNote } from "../../shared/turn-guide.js";
 import { completedPlayerRounds, continuationNotice, playerInputAppend, toolStepNotice, turnGuideNotice, } from "./PlayContinuity.js";
-import { renderFreshContextCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { renderWriteSizeAdvice, readDeclaredWorldClock, } from "../prompt/WorldMaintenanceReport.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
 import { equalModelHostBinding, ModelHostCancelledError, } from "../model/ModelHost.js";
@@ -1329,7 +1329,7 @@ export class PlayCallChain {
                     ],
                 });
                 worldClock = readDeclaredWorldClock(snapshot);
-                const { coverage, maintenance } = this.#compiler.inspectWorldMaterials({
+                const { maintenance } = this.#compiler.inspectWorldMaterials({
                     controlFingerprint: "receipt",
                     documentSnapshot: snapshot,
                     history: Object.fromEntries(session.history.map(({ path, contents }) => [path, contents])),
@@ -1337,23 +1337,18 @@ export class PlayCallChain {
                 });
                 for (const { result } of writes) {
                     const write = result.candidateWrite;
-                    write.freshContextCoverage = renderFreshContextCoverage(snapshot, coverage, write.shortRef, this.#compiler.locale);
                     const previous = session.documents.committedSnapshot.query({
                         kind: "read_document",
                         document: { shortRef: write.shortRef },
                     });
-                    const advice = renderWriteSizeAdvice(maintenance, write.shortRef, previous.kind === "read_document"
+                    write.sizeAdvice = renderWriteSizeAdvice(maintenance, write.shortRef, previous.kind === "read_document"
                         ? Buffer.byteLength(previous.body, "utf8")
                         : null, this.#compiler.locale);
-                    if (advice.length > 0)
-                        write.freshContextCoverage += `\n${advice}`;
                 }
             }
-            catch (error) {
-                // A coverage prediction must never reject an otherwise valid write.
-                const reason = error instanceof Error ? error.message : "Material selection failed";
-                for (const { result } of writes)
-                    result.candidateWrite.freshContextCoverage = `${this.#compiler.locale === "zh-CN" ? "暂时无法判定下次注入；写入结果不受影响。原因" : "Fresh-context coverage unavailable; the write result is unaffected. Reason"}: ${reason}`;
+            catch {
+                // Maintenance advice is diagnostic: a failure omits it and never
+                // rejects or undoes an accepted write.
             }
         }
         const previousNarrative = session.events.findLast((event) => event.kind === "assistant" &&
@@ -2015,7 +2010,7 @@ function finalizeWriteReceipts(settlement) {
         const status = candidateWrite.changed && committedWriteRefs.has(candidateWrite.shortRef)
             ? `@${candidateWrite.shortRef} write succeeded`
             : `@${candidateWrite.shortRef} unchanged`;
-        const markdown = [status, candidateWrite.freshContextCoverage]
+        const markdown = [status, candidateWrite.sizeAdvice]
             .filter(Boolean)
             .join("\n");
         completed.result.markdown = markdown;
@@ -2169,6 +2164,9 @@ function duplicatePlayerExchange(session, exchangeId, playerText, context) {
 }
 function mergeChangedDocuments(session, changes) {
     for (const change of changes) {
+        // Play and continuity writes never remove a document; only world-revision apply does.
+        if (change.kind === "delete")
+            continue;
         const projected = {
             kind: change.kind,
             ref: `@${change.stableShortRef}`,
@@ -2352,15 +2350,6 @@ function revisionTimelineGeneration(sourceGeneration, operationId, worldId, cont
         .digest("hex")
         .slice(0, 40)}`;
 }
-function historyEntries(history, backgrounds = {}) {
-    return Object.entries(history).map(([path, contents]) => ({
-        path,
-        contents,
-        ...(backgrounds[path] === undefined
-            ? {}
-            : { background: structuredClone(backgrounds[path]) }),
-    }));
-}
 function operationId(chainId, key) {
     return `play-${createHash("sha256")
         .update(`${chainId}\0${key}`)

package/dist/node/runtime/play/PlayDocumentTools.js

@@ -8,7 +8,7 @@ import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
 import { coerceToolArguments, renderCoercionNote, } from "../model/ToolArgumentCoercion.js";
 import { runtimeToolInputSchema } from "../prompt/FileNativeToolRegistry.js";
 import { PromptCompilationError, } from "../prompt/FileNativePromptCompiler.js";
-import {} from "../world/WorldDocumentStore.js";
+import { formatWorldDocumentLocator, } from "../world/WorldDocumentStore.js";
 import { acceptWorldStateRevision, beginWorldStateRevision, fileNativeStateChanges, worldDocumentRevisionFailureMessage, } from "../world/WorldStateRevision.js";
 class PlayDocumentToolFailure extends Error {
     failureKind;
@@ -274,10 +274,12 @@ function applyPlayCandidatePatch(candidate, reads, args) {
                 },
             ],
         });
+        if (!revised.ok && revised.editOutcomes.length > 0)
+            throw new PlayDocumentToolFailure(`world_patch applied none of its edits to @${ref}. ${formatEditNotes(revised.editOutcomes)}`, "candidate");
         if (!revised.ok || revised.snapshotStatus !== "usable")
             throw new PlayDocumentToolFailure(worldDocumentRevisionFailureMessage(revised.diagnostics), "candidate");
         const changed = revised.changes.length > 0;
-        const receipt = formatToolRevisionReceipt(target.shortRef, revised.changes);
+        const receipt = formatToolRevisionReceipt(target.shortRef, revised.changes, revised.editOutcomes);
         const previousSnapshot = candidate.snapshot;
         acceptWorldStateRevision(candidate, revised);
         carryWriteAuthorizations(previousSnapshot, candidate, reads, revised.changes);
@@ -353,12 +355,41 @@ function authorizationsAfterEdits(authorization, edits) {
     }
     return authorization;
 }
-function formatToolRevisionReceipt(shortRef, changes) {
+function formatToolRevisionReceipt(shortRef, changes, outcomes) {
     if (changes.length > 1)
         throw new Error("A world_patch revision must affect only its target document");
-    return changes.length === 1
-        ? `@${shortRef} pending write`
-        : `@${shortRef} unchanged`;
+    const failed = outcomes.filter(({ status }) => status === "failed").length;
+    const parts = [
+        changes.length === 1
+            ? `@${shortRef} pending write`
+            : `@${shortRef} unchanged`,
+    ];
+    if (failed > 0)
+        parts.push(`${outcomes.length - failed}/${outcomes.length} edits applied`);
+    else if (outcomes.some(({ status }) => status === "no_op"))
+        parts.push(`${outcomes.length} edits applied`);
+    const notes = formatEditNotes(outcomes);
+    if (notes !== "")
+        parts.push(notes);
+    if (failed > 0)
+        parts.push("applied edits are not resent; send again only the edits listed above");
+    return parts.join(" · ");
+}
+/** Lists only the edits that did not apply cleanly: failed ones and no-ops. */
+function formatEditNotes(outcomes) {
+    return outcomes
+        .flatMap(({ editIndex, status, diagnostic }) => {
+        if (status === "applied" || diagnostic === undefined)
+            return [];
+        const label = `edit #${editIndex + 1}`;
+        if (status === "no_op")
+            return [`${label} no-op: ${diagnostic.message}`];
+        const location = diagnostic.locator
+            ? ` (${formatWorldDocumentLocator(diagnostic.locator)})`
+            : "";
+        return [`${label}${location}: ${diagnostic.message}`];
+    })
+        .join(" · ");
 }
 function applyPlayCandidateRetirement(candidate, reads, args) {
     if (!record(args) ||
@@ -640,15 +671,15 @@ function knownStateDirectory(snapshot, directory, declaredDirectories) {
     return snapshot.files.some(({ path }) => path.startsWith(logicalPrefix));
 }
 function executeStateList(snapshot, args, declaredDirectories) {
+    // Frozen sessions may still send obsolete cursor/limit; directories are
+    // listed in full, so those keys are accepted and ignored.
     if (!record(args) ||
         !hasOnlyToolKeys(args, ["parent", "cursor", "limit"]) ||
         typeof args.parent !== "string" ||
-        parseStateDirectoryHandle(args.parent) === null ||
-        (args.limit !== undefined && typeof args.limit !== "number") ||
-        !validOptionalCursor(args.cursor))
+        parseStateDirectoryHandle(args.parent) === null)
         return {
             ok: false,
-            markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime and accepts only cursor and limit in addition; use history_list for committed history.",
+            markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime; use history_list for committed history.",
         };
     return executeContextList(snapshot, { ...args, source: "state" }, declaredDirectories);
 }
@@ -668,19 +699,11 @@ function executeContextList(snapshot, args, declaredDirectories = []) {
             (args.order !== "newest_first" && args.order !== "oldest_first"));
     if (!hasOnlyToolKeys(args, allowedKeys) ||
         invalidStateShape ||
-        invalidHistoryShape ||
-        (args.limit !== undefined && typeof args.limit !== "number") ||
-        !validOptionalCursor(args.cursor))
+        invalidHistoryShape)
         return {
             ok: false,
             markdown: "# Runtime argument error\n\nstate must use an @dir-* parent returned by the Runtime and omit order; history must use newest_first or oldest_first order and omit parent.",
         };
-    const limit = typeof args.limit === "number" ? args.limit : 20;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nlimit must be between 1 and 100.",
-        };
     if (args.source === "state") {
         const parent = args.parent;
         const directory = parseStateDirectoryHandle(parent);
@@ -691,32 +714,38 @@ function executeContextList(snapshot, args, declaredDirectories = []) {
                 ok: false,
                 markdown: "# Runtime argument error\n\nThe parent is not a Runtime-known state directory; call state_list and descend only through its returned directory handles.",
             };
-        const result = snapshot.query({
-            kind: "catalog",
-            directory,
-            includeRetired: true,
-            declaredDirectories,
-            limit,
-            ...(typeof args.cursor === "string" || args.cursor === null
-                ? { cursor: args.cursor }
-                : {}),
-        });
-        if (result.kind === "error")
-            return renderStateQueryFailure(result);
-        if (result.kind !== "catalog")
-            return unexpectedStateQueryResult();
-        const entries = result.entries.map((entry) => {
-            if (entry.kind === "directory") {
-                const relative = entry.logicalPath.slice(`${snapshot.logicalRoot}/`.length);
-                return `- Directory ${stateDirectoryHandle(relative)}`;
-            }
-            if (entry.document === undefined)
-                return "- Damaged document (currently not addressable)";
-            return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.document.retired ? " · retired" : ""}${entry.status === "damaged" ? " · needs repair" : ""}`;
-        });
+        const entries = [];
+        let complete = true;
+        let cursor = null;
+        do {
+            const result = snapshot.query({
+                kind: "catalog",
+                directory,
+                includeRetired: true,
+                declaredDirectories,
+                limit: 100,
+                ...(cursor === null ? {} : { cursor }),
+            });
+            if (result.kind === "error")
+                return renderStateQueryFailure(result);
+            if (result.kind !== "catalog")
+                return unexpectedStateQueryResult();
+            if (result.coverage.status !== "complete")
+                complete = false;
+            entries.push(...result.entries.map((entry) => {
+                if (entry.kind === "directory") {
+                    const relative = entry.logicalPath.slice(`${snapshot.logicalRoot}/`.length);
+                    return `- Directory ${stateDirectoryHandle(relative)}`;
+                }
+                if (entry.document === undefined)
+                    return "- Damaged document (currently not addressable)";
+                return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.document.retired ? " · retired" : ""}${entry.status === "damaged" ? " · needs repair" : ""}`;
+            }));
+            cursor = result.page.nextCursor;
+        } while (cursor !== null);
         return {
             ok: true,
-            markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${result.coverage.status === "complete" ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} items\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
+            markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${complete ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nComplete: yes`,
         };
     }
     return toolFailure("Use history_list for committed history.");

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

@@ -43,7 +43,7 @@ const runtimeContracts = {
 
 - Use only tools attached to the current request. Read results state their scope, cursor, and completeness. Directories must use @dir-* handles returned by Runtime; documents and history must use @handles returned by Runtime. Never substitute a world/ path or natural-language name for a handle.
 - A document marked \`full body injected\` in the material-coverage report already has its complete writable body in the request and carries write authorization. Do not read it again merely to confirm body structure, check body fields, or “be safe.” context_read additionally exposes the current title, summary, and aliases. world_patch preserves metadata fields omitted from set_metadata, so do not read merely to copy unchanged metadata. Read only when a decision depends on unseen metadata or material the report says is not covered.
-- A YAML world_patch locator may mix map keys and zero-based array indexes; remove deletes exactly one existing key or array item. Retire an entity that should leave future frame catalogs with world_retire instead of destroying its document; retired documents remain listed, readable, referenceable, and restorable.
+- A YAML world_patch locator may mix map keys and zero-based array indexes. add and replace upsert: they write whether or not the target exists, and an index past the end appends. remove deletes one existing key or array item; a missing target is a no-op the receipt reports. Each edit settles on its own: a failed edit is skipped and the others still apply, so when a receipt lists failed edits, send again only those. Retire an entity that should leave future frame catalogs with world_retire instead of destroying its document; retired documents remain listed, readable, referenceable, and restorable.
 - Zero literal-search matches do not prove that a fact does not exist. Tools, directories, documents, archives, searches, matches, handles, Runtime, and failure processes are private adjudication details. Player-visible narrative must not mention internal phrases such as “nothing was found.” When information is insufficient, preserve uncertainty inside the world instead of inventing an internal process.
 - World-write tools change only an uncommitted working copy. Their changes are not official world facts until Runtime accepts and completes the commit.
 
@@ -74,7 +74,7 @@ ${historyUseGuidance("en")}`,
 
 - 只使用请求随附的工具；读取结果会明确范围、cursor 与完整性。目录只能使用 Runtime 返回的 @dir-*，文档和历史只能使用 Runtime 返回的 @句柄，不要把 world/路径或自然语言名称冒充句柄。
 - 材料覆盖报告标为 \`已注入完整正文\` 的文档，其完整可写正文已经在本次请求里，写入资格同样已经具备。不要为确认正文结构、核对正文字段或“保险起见”重读它。context_read 会额外显示当前 title、summary 和 aliases；world_patch 会保留 set_metadata 中未提供的元数据字段，因此不要只为照抄未改变的元数据而读取。只有后续决策确实依赖尚未显示的元数据，或材料覆盖报告未覆盖的内容时才读。
-- YAML world_patch 的 locator 可混合 map key 与从 0 开始的数组下标；remove 只删除一个精确的已有键或数组项。对象需要退出后续 frame catalog 时用 world_retire 退役，不要销毁文档；退役文档仍可列出、读取、引用和恢复。
+- YAML world_patch 的 locator 可混合 map key 与从 0 开始的数组下标。add 与 replace 是 upsert：无论目标是否存在都写入，数组下标达到或超过长度时追加。remove 只删除一个精确的已有键或数组项；目标不存在时为无操作，回执会注明。每条 edit 独立结算：失败的 edit 被跳过，其余照常生效；回执列出失败项时，只补发列出的 edit。对象需要退出后续 frame catalog 时用 world_retire 退役，不要销毁文档；退役文档仍可列出、读取、引用和恢复。
 - 字面搜索 0 命中不证明事实不存在。工具、目录、文档、档案、检索、命中、句柄、Runtime 及失败过程只供私下裁决；玩家可见叙事不得出现“没搜到／没找到资料”等内部措辞。信息不足时保持世界内的不确定性，不编造内部过程。
 - 世界写入工具只修改尚未提交的工作副本；Runtime 接受并完成提交前，这些修改都不是正式世界事实。
 
@@ -148,15 +148,13 @@ export class FileNativePromptCompiler {
             playPreset: input.playPreset,
             modelBinding: input.modelBinding,
             tools: input.tools,
+            ...(input.preload === undefined ? {} : { preload: input.preload }),
         });
     }
     compileWorldRevision(input) {
         const identity = this.#locale === "zh-CN"
             ? `# 当前修订世界\n\n${input.worldTitle}`
             : `# World being revised\n\n${input.worldTitle}`;
-        const boundary = this.#locale === "zh-CN"
-            ? "# 世界修订工作树边界\n\n随附工具只读写当前锁定 epoch 的 state/* 与 control/* 工作树。成功工具调用尚未进入世界 Authority；只有玩家点击应用才会整体提交并解锁。"
-            : "# World-revision worktree boundary\n\nThe attached tools read and write only state/* and control/* in the current locked epoch. Successful tool calls do not enter world Authority until the player applies the complete revision and unlocks it.";
         return this.#compileAuthoringConversation({
             identity: {
                 source: "world-revision:title",
@@ -165,10 +163,7 @@ export class FileNativePromptCompiler {
                         ? `\n\nEpoch: ${input.epoch.id}\nBase: ${input.epoch.baseHead}`
                         : ""),
             },
-            boundary: {
-                source: "runtime:world-revision-worktree-boundary",
-                markdown: boundary,
-            },
+            boundary: null,
             runtimeSource: "runtime:builtin/world-revision",
             target: "world-revision",
             gameplay: input.gameplay,
@@ -177,6 +172,7 @@ export class FileNativePromptCompiler {
             playPreset: input.playPreset,
             modelBinding: input.modelBinding,
             tools: input.tools,
+            ...(input.preload === undefined ? {} : { preload: input.preload }),
         });
     }
     #compileAuthoringConversation(input) {
@@ -185,7 +181,7 @@ export class FileNativePromptCompiler {
         const logicalMessages = [];
         const ordered = input.playPreset.definition.authorPrompts ??
             legacyAuthorPrompts(input.playPreset.definition);
-        const catalog = builtinAuthorPrompts(this.#locale);
+        const catalog = builtinAuthorPrompts(this.#locale, input.target);
         for (const entry of ordered) {
             if (entry.kind === "world" || !entry.enabled)
                 continue;
@@ -210,7 +206,7 @@ export class FileNativePromptCompiler {
             if (builtin?.id === "author.target")
                 blocks = [
                     input.identity,
-                    input.boundary,
+                    ...(input.boundary === null ? [] : [input.boundary]),
                     ...(input.gameplay.mode === "tabletop"
                         ? [
                             tabletopAuthoringRulesBlock(input.gameplay, input.target, this.#locale),
@@ -238,6 +234,20 @@ export class FileNativePromptCompiler {
                 blocks,
             });
         }
+        // Preloaded material follows every author prompt so the stable prefix stays byte-identical.
+        if (input.preload !== undefined && input.preload.length > 0) {
+            const preloadBlocks = input.preload.map(({ source, markdown }) => ({
+                source,
+                markdown,
+            }));
+            logicalMessages.push({
+                messageRole: "system",
+                promptId: "runtime.preload",
+                role: "world_context",
+                markdown: joinBlocks(preloadBlocks),
+                blocks: preloadBlocks,
+            });
+        }
         const tools = structuredClone(input.tools);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(input.modelBinding.provider);
@@ -870,9 +880,13 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
                 return [
                     {
                         ...worldInstructionPlaceholder,
-                        markdown: locale === "zh-CN"
-                            ? "世界指令在此展开；frame 选定材料仅在全新游玩上下文中作为初始工具结果提供。请通过本轮创作工具检查实际内容。"
-                            : "World instructions expand here; frame-selected material is supplied as an initial tool result only for a fresh play context. Inspect actual content through the current authoring tools.",
+                        markdown: revision
+                            ? locale === "zh-CN"
+                                ? "世界指令在此展开；启用块原文见本请求的 Runtime 预载。"
+                                : "World instructions expand here; enabled block text appears in this request's Runtime preload."
+                            : locale === "zh-CN"
+                                ? "世界指令在此展开；frame 选定材料仅在全新游玩上下文中作为初始工具结果提供。请通过本轮创作工具检查实际内容。"
+                                : "World instructions expand here; frame-selected material is supplied as an initial tool result only for a fresh play context. Inspect actual content through the current authoring tools.",
                     },
                 ];
             if (entry.kind === "tail" || !entry.enabled)
@@ -949,11 +963,13 @@ function settingImprovementPresetReference(binding, locale, target, gameplay) {
             : "Player-visible narrative semantics", locale === "zh-CN"
             ? "这些块只在未来游玩生成玩家可见正文时生效；不得把它们当作本轮 YAML 或 Markdown 设定正文的范文。"
             : "These blocks apply only when future play produces player-visible story. Do not use them as prose models for YAML or Markdown setting documents in this conversation.", narrativeBlocks),
-        settingImprovementReferenceGroup(locale === "zh-CN"
-            ? "本轮提示（每次发送的尾部）"
-            : "Turn guide (per-send suffix)", locale === "zh-CN"
-            ? "这些行在每次游玩发送时追加在玩家输入之后，由已启用块的尾部行按同一顺序拼成；它们是提醒，不是世界事实。"
-            : "These lines are appended after the player input on every play send, assembled from the enabled blocks' turn-guide lines in the same order. They are reminders, not world facts.", turnGuideBlocks),
+        revision
+            ? null
+            : settingImprovementReferenceGroup(locale === "zh-CN"
+                ? "本轮提示（每次发送的尾部）"
+                : "Turn guide (per-send suffix)", locale === "zh-CN"
+                ? "这些行在每次游玩发送时追加在玩家输入之后，由已启用块的尾部行按同一顺序拼成；它们是提醒，不是世界事实。"
+                : "These lines are appended after the player input on every play send, assembled from the enabled blocks' turn-guide lines in the same order. They are reminders, not world facts.", turnGuideBlocks),
     ].filter((group) => group !== null);
     return [
         heading,