narraeon 0.5.4 → 0.5.6

package/dist/node/runtime/V1Runtime.js

@@ -116,6 +116,7 @@ export class V1Runtime {
                     controlFingerprint: fingerprintControl(Object.fromEntries(snapshot.files.map(({ path, contents }) => [path, contents]))),
                     documentSnapshot: snapshot,
                     history: structuredClone(binding.history),
+                    historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                     narrativeCheckpoint: binding.narrativeCheckpoint,
                     ...maintenance,
                     additionalMaterials: structuredClone(binding.additionalMaterials),
@@ -653,6 +654,7 @@ export class V1Runtime {
                         }),
                         additionalMaterials: structuredClone(binding.additionalMaterials),
                         history: structuredClone(binding.history),
+                        historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                         narrativeCheckpoint: baseline.narrativeCheckpoint,
                         historyAlreadyAppended: Object.keys(binding.history).filter((key) => !(key in baseline.history)),
                         ...(await this.#worlds.inspectDocumentMaintenance(request.worldId, binding.parentHead)),

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

@@ -0,0 +1,84 @@
+import { parseDocument } from "yaml";
+import { renderWorldYamlSource } from "../world/WorldYamlRendering.js";
+export function captureNarrativeOrigin(snapshot, firstEventId) {
+    const source = snapshot.files.find(({ path }) => path === "control/frame.yaml")?.contents;
+    if (source === undefined)
+        throw new Error("Current situation frame is missing");
+    const parsed = parseDocument(source, { schema: "core", uniqueKeys: true });
+    if (parsed.errors.length > 0)
+        throw new Error("Current situation frame is invalid");
+    const frame = parsed.toJS({ maxAliasCount: 0 });
+    const binding = record(frame) && record(frame.bindings)
+        ? frame.bindings.currentSituation
+        : undefined;
+    if (typeof binding !== "string" || binding.length === 0)
+        throw new Error("Current situation binding is invalid");
+    const read = snapshot.query({
+        kind: "read_document",
+        document: binding.startsWith("@")
+            ? { shortRef: binding.slice(1) }
+            : { documentId: binding },
+    });
+    if (read.kind !== "read_document")
+        throw new Error("Bound current situation cannot be read");
+    const documentId = read.document.documentId;
+    return {
+        firstEventId,
+        documentId,
+        value: readBackground(snapshot, documentId),
+    };
+}
+export function readBackground(snapshot, documentId) {
+    const selected = snapshot.query({
+        kind: "select_node",
+        document: { documentId },
+        locator: { yaml: ["背景"] },
+    });
+    if (selected.kind !== "select_node" || selected.node.codec !== "yaml")
+        return null;
+    const value = selected.node.value;
+    if (value === null ||
+        (typeof value === "string" && value.trim() === "") ||
+        (typeof value === "object" && Object.keys(value).length === 0))
+        return null;
+    // Quoted multiline scalars retain trailing newlines when display framing trims.
+    return renderWorldYamlSource(value, { blockQuote: false });
+}
+export function snapshotBackground(value) {
+    return value === null ? undefined : { kind: "snapshot", value };
+}
+export function narrativeBackground(origin, snapshot) {
+    // A released frozen request without an origin stays unrecorded on recovery.
+    if (origin === undefined)
+        return undefined;
+    const after = readBackground(snapshot, origin.documentId);
+    return origin.value === null && after === null
+        ? undefined
+        : { kind: "narrative", before: origin.value, after };
+}
+export function isHistoryBackground(value) {
+    if (!record(value))
+        return false;
+    if (value.kind === "snapshot")
+        return Object.keys(value).length === 2 && nonempty(value.value);
+    return (value.kind === "narrative" &&
+        Object.keys(value).length === 3 &&
+        (value.before === null || nonempty(value.before)) &&
+        (value.after === null || nonempty(value.after)) &&
+        (value.before !== null || value.after !== null));
+}
+export function isNarrativeOrigin(value) {
+    return (record(value) &&
+        Object.keys(value).length === 3 &&
+        Number.isSafeInteger(value.firstEventId) &&
+        Number(value.firstEventId) > 0 &&
+        typeof value.documentId === "string" &&
+        value.documentId.length > 0 &&
+        (value.value === null || nonempty(value.value)));
+}
+function nonempty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -12,6 +12,9 @@ export class HistoryQuery {
         const refs = inputs.map(({ id }) => historyMessageRef(id));
         this.messages = inputs.map((message, index) => Object.freeze({
             ...message,
+            ...(message.background === undefined
+                ? {}
+                : { background: Object.freeze(structuredClone(message.background)) }),
             ref: refs[index],
             position: index + 1,
             isOpening: message.isOpening === true,
@@ -20,11 +23,12 @@ export class HistoryQuery {
             length: Array.from(message.text).length,
         }));
         this.snapshotId = createHash("sha256")
-            .update(JSON.stringify(inputs.map(({ id, role, isOpening, text }) => [
+            .update(JSON.stringify(inputs.map(({ id, role, isOpening, text, background }) => [
             id,
             role,
             isOpening === true,
             text,
+            background ?? null,
         ])))
             .digest("hex");
     }
@@ -380,11 +384,12 @@ export function historyMessageRef(id) {
 }
 /** Decode storage identity once at the boundary; never infer order from it. */
 export function historyInputs(entries) {
-    return entries.map(({ path, contents }) => {
+    return entries.map(({ path, contents, background }) => {
         const id = path.replace(/\.md$/u, "");
         return {
             id,
             text: contents,
+            ...(background === undefined ? {} : { background }),
             role: /(?:\.|-)player(?:-|$)/u.test(id) ? "player" : "narrator",
             isOpening: id.endsWith("message.genesis.narrator"),
         };

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

@@ -1,3 +1,5 @@
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
 /** Shared metadata keeps injected refs and tool results directly navigable. */
 export function historyMessageLabel(message, locale) {
     const zh = locale === "zh-CN";
@@ -12,7 +14,7 @@ export function historyRoleLabel(message, locale) {
     return locale === "zh-CN" ? "主持叙事" : "Host narrative";
 }
 export function renderHistoryMessage(message, locale) {
-    return `## ${historyMessageLabel(message, locale)}\n\n${locale === "zh-CN" ? "[原文开始]" : "[Original text begins]"}\n${message.text}\n${locale === "zh-CN" ? "[原文结束；正文完整]" : "[Original text ends; body complete]"}`;
+    return `## ${historyMessageLabel(message, locale)}\n${renderHistoryBackground(message.background, locale)}\n${locale === "zh-CN" ? "[原文开始]" : "[Original text begins]"}\n${message.text}\n${locale === "zh-CN" ? "[原文结束；正文完整]" : "[Original text ends; body complete]"}`;
 }
 export function renderHistoryInjectionNotice(total, selected, kind, locale) {
     const zh = locale === "zh-CN";
@@ -51,7 +53,7 @@ export function renderHistoryResult(result, locale = "en", legacyRead = false) {
     if (result.kind === "legacy_list")
         return {
             ok: true,
-            markdown: `# Directory listing\n\n${header}\nOrder: ${result.order}\n${result.messages.map((message) => `- ${message.ref}, position ${message.position}, role=${message.role}${message.isOpening ? ", isOpening=true" : ""}, ${message.length} Unicode code points`).join("\n") || "(empty)"}\n\n---\nThis page: ${result.offset}..${result.offset + result.messages.length} / ${result.total} items\nComplete: ${result.nextCursor === null ? "yes" : "no"}${result.nextCursor === null ? "" : `\nNext-page cursor: ${result.nextCursor}`}`,
+            markdown: `# Directory listing\n\n${header}\nOrder: ${result.order}\n${result.messages.map((message) => `- ${message.ref}, position ${message.position}, role=${message.role}${message.isOpening ? ", isOpening=true" : ""}, ${message.length} Unicode code points${message.background === undefined ? "" : `\n${renderHistoryBackground(message.background, locale)}`}`).join("\n") || "(empty)"}\n\n---\nThis page: ${result.offset}..${result.offset + result.messages.length} / ${result.total} items\nComplete: ${result.nextCursor === null ? "yes" : "no"}${result.nextCursor === null ? "" : `\nNext-page cursor: ${result.nextCursor}`}`,
         };
     if (result.kind === "list")
         return {
@@ -59,7 +61,7 @@ export function renderHistoryResult(result, locale = "en", legacyRead = false) {
             markdown: `# ${zh ? "已提交历史列表" : "Committed history listing"}\n\n${header}\nOrder: oldest_first (${zh ? "页内始终由旧到新" : "every page oldest to newest"})\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[${zh ? "部分原文预览" : "Partial original preview"}]\n${preview}\n[${message.length > 120 ? (zh ? "预览有省略" : "preview omitted remaining text") : zh ? "预览结束" : "preview ends"}]`;
+                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"}]`;
             })
                 .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}"}` : ""}`,
         };
@@ -70,7 +72,7 @@ export function renderHistoryResult(result, locale = "en", legacyRead = false) {
         };
     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${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."}`,
+        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."}`,
     };
 }
 function localizedRecovery(result, zh) {
@@ -84,3 +86,28 @@ function localizedRecovery(result, zh) {
         return "该 ref 不在当前时间线中，可能仍保存在旧端点；请重新查询当前历史。";
     return `参数不符合要求，请按工具定义修正。${result.recovery}`;
 }
+/** Every result carries its own annotation; no implicit neighboring inheritance. */
+export function renderHistoryBackground(background, locale) {
+    if (background === undefined)
+        return "";
+    const zh = locale === "zh-CN";
+    const node = (value) => value === null
+        ? zh
+            ? "未记录"
+            : "not recorded"
+        : `\n[${zh ? "背景值开始" : "Background value begins"}]\n${value}\n[${zh ? "背景值结束" : "Background value ends"}]`;
+    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.";
+    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`;
+}
+function equalBackground(before, after) {
+    if (before === after)
+        return true;
+    if (before === null || after === null)
+        return false;
+    return isDeepStrictEqual(parseDocument(before).toJS({ maxAliasCount: 0 }), parseDocument(after).toJS({ maxAliasCount: 0 }));
+}

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

@@ -83,6 +83,7 @@ export class FileNativeContinuityCorrection {
                 materials: structuredClone(binding.additionalMaterials),
                 originalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 reads: new Map(),
                 previewedVersion: null,
                 stateOperationClaim: claimed.handle,
@@ -236,6 +237,7 @@ export class FileNativeContinuityCorrection {
                 documentSnapshot: candidate.snapshot,
                 additionalMaterials: materials,
                 history: candidate.history,
+                historyBackgrounds: candidate.historyBackgrounds,
                 documentMaintenance: candidate.documentMaintenance,
                 documentMaintenanceUnavailableReason: candidate.documentMaintenanceUnavailableReason,
                 narrativeCheckpoint: candidate.narrativeCheckpoint,

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

@@ -1,3 +1,4 @@
+import { isNarrativeOrigin, isHistoryBackground, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -119,6 +120,8 @@ function assertBase(value) {
         value.schemaVersion !== 1 ||
         value.kind !== "play_advance" ||
         (value.advanceKind !== "player" && value.advanceKind !== "response") ||
+        (value.narrativeOrigin !== undefined &&
+            !isNarrativeOrigin(value.narrativeOrigin)) ||
         typeof value.worldId !== "string" ||
         typeof value.chainId !== "string" ||
         typeof value.advanceId !== "string" ||
@@ -170,6 +173,8 @@ function assertSettlementPrepared(value) {
         (value.schemaVersion !== 1 ||
             value.stage !== "settlement_prepared" ||
             !isRecord(value.settlement) ||
+            (value.settlement.background !== undefined &&
+                !isHistoryBackground(value.settlement.background)) ||
             typeof value.recordedAt !== "number"))
         throw new Error("Settlement-prepared play fact has an invalid shape");
 }

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

@@ -1,3 +1,4 @@
+import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
 import { encodePlayPromptRun, decodePlayPromptRun, } from "./PlayPromptRun.js";
 import { createHash, randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, rename, rm, writeFile, } from "node:fs/promises";
@@ -162,6 +163,9 @@ export class FileNativePlayTimelineStore {
             chainId: value.chainId,
             nextMaterials: structuredClone(value.nextMaterials),
             lastRequestDigest,
+            ...(value.narrativeOrigin === undefined
+                ? {}
+                : { narrativeOrigin: structuredClone(value.narrativeOrigin) }),
         };
         const continuationDigest = createHash("sha256")
             .update(JSON.stringify(continuation))
@@ -313,6 +317,11 @@ export class FileNativePlayTimelineStore {
             promptRuns,
             changedDocuments: structuredClone(stateValue.changedDocuments),
             nextMaterials: structuredClone(continuationValue.nextMaterials),
+            ...(continuationValue.narrativeOrigin === undefined
+                ? {}
+                : {
+                    narrativeOrigin: structuredClone(continuationValue.narrativeOrigin),
+                }),
             nextEventId: stateValue.nextEventId,
             exchange: stateValue.exchange,
             lastRequest,
@@ -767,6 +776,8 @@ function assertContextContinuation(value) {
     if (!isRecord(value) ||
         value.schemaVersion !== 3 ||
         value.kind !== "play_context_continuation" ||
+        (value.narrativeOrigin !== undefined &&
+            !isNarrativeOrigin(value.narrativeOrigin)) ||
         typeof value.chainId !== "string" ||
         !Array.isArray(value.nextMaterials) ||
         (value.lastRequestDigest !== null &&

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

@@ -1,3 +1,5 @@
+import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
+import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
 import { PlayCallChainError } from "./PlayCallChainError.js";
 import { preparePlayerRevisionTrace, prepareForkTrace, restorePlayDocuments, independentContextCopy, } from "./PlayTraceRetention.js";
@@ -88,6 +90,7 @@ export class PlayCallChain {
                 documentSnapshot: documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
                 documentMaintenance,
                 documentMaintenanceUnavailableReason: documents.maintenanceWarning,
@@ -144,7 +147,7 @@ export class PlayCallChain {
             lastFailure: null,
             updatedAt: now,
             documents,
-            history: historyEntries(binding.history),
+            history: historyEntries(binding.history, binding.historyBackgrounds),
             narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(),
             persistenceCursor: {
@@ -182,8 +185,10 @@ export class PlayCallChain {
             const last = session.transcript.at(-1);
             if (last?.kind === "assistant" &&
                 last.toolCalls.length === 0 &&
-                last.text.trim().length > 0)
+                last.text.trim().length > 0) {
+                session.narrativeOrigin = await this.#captureOrigin(session);
                 session.transcript.push(continuationNotice(this.#compiler.locale));
+            }
             return this.#dispatch(session, input.modelHost, createRequest(session, input.modelHost, session.exchange), 1, signal, input.observer);
         }
         if (duplicatePlayerExchange(session, input.exchangeId, input.playerText, "append"))
@@ -213,6 +218,7 @@ export class PlayCallChain {
                 documentSnapshot: session.documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
             },
             playerInputPlacement: "append",
@@ -221,7 +227,7 @@ export class PlayCallChain {
         }, playPreset);
         // The native conversation already contains successful writes and exact reads.
         // Rebinding initial coverage here would incorrectly reauthorize stale scopes.
-        session.history = historyEntries(binding.history);
+        session.history = historyEntries(binding.history, binding.historyBackgrounds);
         session.narrativeCheckpoint = binding.narrativeCheckpoint;
         session.nextMaterials = structuredClone(binding.additionalMaterials);
         (session.promptRuns ??= []).push({
@@ -719,6 +725,7 @@ export class PlayCallChain {
                 documentSnapshot: documents.snapshot,
                 additionalMaterials: structuredClone(binding.additionalMaterials),
                 history: structuredClone(binding.history),
+                historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                 narrativeCheckpoint: binding.narrativeCheckpoint,
                 documentMaintenance,
                 documentMaintenanceUnavailableReason: documents.maintenanceWarning,
@@ -788,6 +795,10 @@ export class PlayCallChain {
             canRetry: false,
             bootstrap: structuredClone(fresh.bootstrap),
             tools: structuredClone(fresh.tools),
+            narrativeOrigin: captureNarrativeOrigin(WorldDocumentStore.open({
+                layout: "world_state",
+                files: Object.entries(input.binding.files).map(([path, contents]) => ({ path, contents })),
+            }), 1),
             transcript: playerInputAppend({
                 history: fresh.binding.history,
                 checkpoint: fresh.binding.narrativeCheckpoint,
@@ -928,11 +939,24 @@ export class PlayCallChain {
             this.#active.delete(activeId);
         this.#worldChains.delete(worldId);
     }
+    async #captureOrigin(session) {
+        const binding = await this.#worlds.bindPlayCallChain(session.worldId);
+        if (binding.parentHead !== session.parentHead)
+            throw new PlayCallChainError("World advanced before background capture; use a fresh context.");
+        return captureNarrativeOrigin(WorldDocumentStore.open({
+            layout: "world_state",
+            files: Object.entries(binding.files).map(([path, contents]) => ({
+                path,
+                contents,
+            })),
+        }), session.nextEventId);
+    }
     async #submitPlayer(session, exchangeId, playerText, context, modelHost, signal, observer) {
         if (duplicatePlayerExchange(session, exchangeId, playerText, context))
             return projectView(session);
         if (session.status === "running")
             throw new PlayCallChainError("The call chain is waiting for the model to return.");
+        session.narrativeOrigin = await this.#captureOrigin(session);
         const exchange = session.exchange + 1;
         const nextRequest = createRequest(session, modelHost, exchange, [
             ...session.transcript,
@@ -950,6 +974,7 @@ export class PlayCallChain {
             schemaVersion: 1,
             kind: "play_advance",
             advanceKind: "player",
+            narrativeOrigin: structuredClone(session.narrativeOrigin),
             playContext: session.continuityContextId ?? session.chainId,
             worldId: session.worldId,
             chainId: session.chainId,
@@ -1003,7 +1028,17 @@ export class PlayCallChain {
             operationId: advance.operationId,
             worldId: session.worldId,
             parentHead: advance.parentHead,
-            historyAppend: [{ role: "player", exactText: advance.playerText }],
+            historyAppend: [
+                {
+                    role: "player",
+                    exactText: advance.playerText,
+                    ...(advance.narrativeOrigin?.value == null
+                        ? {}
+                        : {
+                            background: snapshotBackground(advance.narrativeOrigin.value),
+                        }),
+                },
+            ],
             nextMaterials: structuredClone(session.nextMaterials),
             stateChanges: [],
         });
@@ -1031,6 +1066,10 @@ export class PlayCallChain {
         session.nextEventId = advance.eventId + 1;
         session.parentHead = outcome.head;
         appendCommittedHistory(session, outcome.head, outcome.historyAppend);
+        if (advance.narrativeOrigin === undefined)
+            delete session.narrativeOrigin;
+        else
+            session.narrativeOrigin = structuredClone(advance.narrativeOrigin);
         session.exchange = advance.exchange;
         session.lastRequest = structuredClone(advance.nextRequest);
         session.lastRequestAttempt = 0;
@@ -1167,7 +1206,11 @@ export class PlayCallChain {
                 : { providerState: response.providerState }),
             toolCalls: structuredClone(calls),
         };
+        const background = visibleText
+            ? narrativeBackground(advance.narrativeOrigin, session.documents.snapshot)
+            : undefined;
         return {
+            ...(background === undefined ? {} : { background }),
             assistantEvent,
             playContext: session.continuityContextId ?? session.chainId,
             ...(worldClock === undefined || stateChanges.length === 0
@@ -1226,6 +1269,9 @@ export class PlayCallChain {
                         {
                             role: "narrator",
                             exactText: settlement.assistantEvent.text,
+                            ...(settlement.background === undefined
+                                ? {}
+                                : { background: settlement.background }),
                         },
                     ]
                     : [],
@@ -1287,7 +1333,7 @@ export class PlayCallChain {
                 const binding = await this.#worlds.bindPlayCallChain(session.worldId);
                 session.documents = new FileNativePlayDocuments(binding.files);
                 session.documents.restoreAuthorizationCheckpoint(settlement.authorizationCheckpoint);
-                session.history = historyEntries(binding.history);
+                session.history = historyEntries(binding.history, binding.historyBackgrounds);
                 session.nextMaterials = structuredClone(binding.additionalMaterials);
             }
             mergeChangedDocuments(session, settlement.stateChanges);
@@ -1382,6 +1428,9 @@ export class PlayCallChain {
                 schemaVersion: 1,
                 kind: "play_advance",
                 advanceKind: "response",
+                ...(session.narrativeOrigin === undefined
+                    ? {}
+                    : { narrativeOrigin: structuredClone(session.narrativeOrigin) }),
                 worldId: session.worldId,
                 chainId: session.chainId,
                 advanceId: responseOperationId,
@@ -1784,7 +1833,7 @@ export class PlayCallChain {
             documentAuthorizationCheckpoints: persisted.documentAuthorizationCheckpoints?.map((checkpoint) => structuredClone(checkpoint)) ?? [],
             nextMaterials: structuredClone(binding.additionalMaterials),
             documents,
-            history: historyEntries(binding.history),
+            history: historyEntries(binding.history, binding.historyBackgrounds),
             narrativeCheckpoint: binding.narrativeCheckpoint,
             completedToolMap: new Map(persisted.completedTools.map((item) => [
                 item.key,
@@ -1935,11 +1984,18 @@ function appendCommittedHistory(session, head, messages) {
         const path = `message.${sequence}.${index + 1}.${message.role}`;
         const existing = session.history.find((item) => item.path === path);
         if (existing !== undefined) {
-            if (existing.contents !== message.exactText)
+            if (existing.contents !== message.exactText ||
+                !isDeepStrictEqual(existing.background, message.background))
                 throw new PlayCallChainError("Recovered Authority history conflicts with the call-chain history.");
             continue;
         }
-        session.history.push({ path, contents: message.exactText });
+        session.history.push({
+            path,
+            contents: message.exactText,
+            ...(message.background === undefined
+                ? {}
+                : { background: structuredClone(message.background) }),
+        });
     }
 }
 function prepareTool(session, working, exchange, call, locale) {
@@ -2219,10 +2275,13 @@ function playerRevisionTimelineGeneration(sourceGeneration, operationId, worldId
         .digest("hex")
         .slice(0, 40)}`;
 }
-function historyEntries(history) {
+function historyEntries(history, backgrounds = {}) {
     return Object.entries(history).map(([path, contents]) => ({
         path,
         contents,
+        ...(backgrounds[path] === undefined
+            ? {}
+            : { background: structuredClone(backgrounds[path]) }),
     }));
 }
 function operationId(chainId, key) {

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

@@ -1,3 +1,4 @@
+import { captureNarrativeOrigin } from "../history/HistoryBackground.js";
 import { FileNativePlayDocuments, } from "./PlayDocumentTools.js";
 import { currentPlayPrompt, playPromptRunsThroughEvents, } from "./PlayPromptRun.js";
 import { isPlayerRoundMarker, playerInputAppend } from "./PlayContinuity.js";
@@ -93,6 +94,7 @@ function assembleRetainedTrace(source, endpoint, selection) {
         ? null
         : completedToolKeys(selection.toolEvents);
     const documents = restorePlayDocuments(endpoint.binding.files, source, selection.authorizationEvents);
+    const lastEvent = selection.events.at(-1);
     return {
         continuityContextId: source.continuityContextId ?? source.chainId,
         baselineHead: source.baselineHead,
@@ -111,6 +113,11 @@ function assembleRetainedTrace(source, endpoint, selection) {
         ...(source.modelBinding === undefined
             ? {}
             : { modelBinding: structuredClone(source.modelBinding) }),
+        ...(lastEvent?.kind === "player" || lastEvent?.kind === "tool_result"
+            ? {
+                narrativeOrigin: captureNarrativeOrigin(documents.snapshot, lastEvent.kind === "player" ? lastEvent.id : lastEvent.id + 1),
+            }
+            : {}),
         status: "ready",
         canRetry: false,
         bootstrap: structuredClone(source.bootstrap),

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

@@ -8,7 +8,9 @@ import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-
 import { builtinPlayPrompts, } from "../../shared/ordered-play-prompts.js";
 import { parseOrderedPlayPrompts } from "../play/OrderedPlayPrompts.js";
 import { renderDocumentWritePosition } from "./WorldMaintenanceReport.js";
-import { parseDocument, stringify } from "yaml";
+import { parseDocument } from "yaml";
+import { renderWorldYamlSource } from "../world/WorldYamlRendering.js";
+export { renderWorldYamlSource } from "../world/WorldYamlRendering.js";
 import { measureWorldMaterials, refreshMaintenanceTotals, } from "./WorldMaintenanceReport.js";
 import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
 import { checkpointHistory, checkpointReplayBlocks, playerInputAppend, isPlayerRoundMarker, } from "../play/PlayContinuity.js";
@@ -52,7 +54,7 @@ ${historyUseGuidance("en")}`,
 
 A nonempty tool-free response ends the model/tool loop started by the current player submission. A response that calls any tool is an intermediate step; its text has not yet been displayed or committed as final story. After all tool results, use the receipts to present this turn's still-unshown content in a later tool-free response consistent with committed state.
 
-The player's next submission may choose a fresh context; the old model transcript will not enter that request. Fresh contexts include all committed original player inputs and final narratives after the last effective world_checkpoint, excluding tools, reasoning, and the opening. A checkpoint declaration takes effect only after the subsequent nonempty tool-free final prose successfully commits, including that prose in its boundary; further tool calls may follow registration. Normal replies need no checkpoint; registration neither ends an in-world event nor switches context. Author instructions decide save timing.
+The player's next submission may choose a fresh context; the old model transcript will not enter that request. Fresh contexts include all committed original player inputs and final narratives after the last effective world_checkpoint, excluding tools, reasoning, and the opening. A checkpoint declaration takes effect only after the subsequent nonempty tool-free final prose successfully commits, including that prose in its boundary; further tool calls may follow registration. Registration neither ends an in-world event nor switches context. Author instructions decide save timing.
 
 Runtime executes only real tool definitions, file validation, and authority commits. This block does not define story content, point of view, style, player agency, or state semantics.
 
@@ -83,7 +85,7 @@ ${historyUseGuidance("zh-CN")}`,
 
 非空且不调用工具的响应会结束本次玩家提交触发的模型／工具循环。只要响应调用了任何工具，它就是工具中间步，其中的文字尚未展示或提交为最终故事。收到全部工具结果后，根据回执在后续无工具响应中呈现本轮尚未展示的内容，并与已提交状态一致。
 
-下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。正常回复无需检查点，登记不结束世界内事件，也不自动切换上下文。具体保存时机由作者提示规定。
+下一次玩家提交可以选择“全新上下文”；旧模型 transcript 不会进入那个请求。新上下文会补入最近一次已生效 world_checkpoint 之后的全部已提交玩家原文与最终叙事，不含工具、推理和开场白。检查点登记仅在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。登记不结束世界内事件，也不自动切换上下文。具体保存时机由作者提示规定。
 
 Runtime 只执行真实工具定义、文件校验和权威提交；本段不规定故事、人称、文风、玩家代理权或状态语义。
 
@@ -1250,45 +1252,11 @@ function renderSnapshotDocument(snapshot, selector) {
         markdown: renderYamlDocument(read.descriptor, selected.node.value),
     };
 }
-/**
- * Serialize a YAML node exactly the way context_read does, so what bootstrap
- * injects is what a later read would hand back. Internal document ids become
- * the @shortRef handles the model can actually pass to a tool.
- */
-export function renderWorldYamlSource(value) {
-    return stringify(promptYamlValue(value), {
-        indent: 2,
-        lineWidth: 0,
-    }).trimEnd();
-}
 function renderYamlDocument(descriptor, value) {
     if (!isRecord(value))
         throw new PromptCompilationError("world_document_query_failed", "YAML world-document root node must be a map");
     return `## ${descriptor.title} [ref: @${descriptor.shortRef} · YAML]\n\n> ${descriptor.summary}\n\n${renderWorldYamlSource(value)}`;
 }
-function projectedReference(value) {
-    if (!isRecord(value) ||
-        Object.keys(value).length !== 2 ||
-        typeof value.$ref !== "string" ||
-        !isRecord(value.target))
-        return null;
-    return typeof value.target.shortRef === "string"
-        ? { shortRef: value.target.shortRef }
-        : null;
-}
-function promptYamlValue(value) {
-    const reference = projectedReference(value);
-    if (reference !== null)
-        return { $ref: `@${reference.shortRef}` };
-    if (Array.isArray(value))
-        return value.map(promptYamlValue);
-    if (isRecord(value))
-        return Object.fromEntries(Object.entries(value).map(([key, child]) => [
-            key,
-            promptYamlValue(child),
-        ]));
-    return value;
-}
 function throwQueryFailure(failure, operation) {
     throw new PromptCompilationError("world_document_query_failed", `World-document snapshot could not complete the ${operation} query`, {
         requestKind: failure.requestKind,
@@ -1310,6 +1278,9 @@ function resolveContext(input, worldFrame, snapshot, coverage, locale) {
     const history = new HistoryQuery("prompt-compilation", historyInputs(Object.entries(input.world.history ?? {}).map(([path, contents]) => ({
         path,
         contents,
+        ...(input.world.historyBackgrounds?.[path] === undefined
+            ? {}
+            : { background: input.world.historyBackgrounds[path] }),
     }))));
     const excluded = new Set(input.world.historyAlreadyAppended ?? []);
     const checkpointEntries = input.world.replayHistory === true