narraeon 0.5.7 → 0.6.1

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

@@ -0,0 +1,141 @@
+import { gameplayLabel } from "../../protocol/gameplay.js";
+import { resolutionCheckToolForScheme, resolutionToolDefinition, } from "./TabletopResolution.js";
+/**
+ * The scheme's fixed rules, taken from the same description the check tool
+ * sends to the model, so the prompt and the tool cannot drift apart.
+ */
+export function tabletopSchemeRules(gameplay, locale) {
+    return resolutionToolDefinition(resolutionCheckToolForScheme(gameplay.scheme), locale).description;
+}
+/**
+ * Runtime-owned rules at the world placeholder of a tabletop world. The block
+ * is world-derived and carries no preset state, so a scheme never requires a
+ * preset change.
+ */
+export function tabletopWorldRulesBlock(gameplay, locale) {
+    const label = gameplayLabel(gameplay, locale);
+    const rules = tabletopSchemeRules(gameplay, locale);
+    // Only the bag scheme has a world-defined token list; other schemes never mention one.
+    const bagLine = gameplay.scheme !== "bag"
+        ? ""
+        : locale === "zh-CN"
+            ? "- 世界文档中定义的混乱袋必须读取，并原样提供其当前标记清单；袋的变化由你在世界文档中维护。\n"
+            : "- A chaos bag defined in the world documents must be read and supplied exactly as its current token list. You maintain the bag's changes in the world documents.\n";
+    const markdown = locale === "zh-CN"
+        ? `# 跑团判定规则
+
+本世界是跑团世界，判定方案为 ${label}。以下规则由 Runtime 固定，随本世界的玩法身份生效。
+
+## 判定工具
+
+${rules}
+
+## 辅助工具
+
+- roll_dice：辅助数值掷骰，用于伤害、数量等，不重新裁决已确定的行动成败。
+- calculate：对两个数执行加减乘除，不产生随机数，不修改世界。
+
+## 绑定契约
+
+- 调用判定工具前，先声明行动目标、所用数值与难度；只有有成败不确定性或对抗的行动才需要判定。
+- 必须先调用判定工具并取得回执，再叙述结果。
+- 判定成功必须实现已声明的目标，失败则不实现，不论情节是否看似合理。
+- 大成功与大失败按工具的固定规则兑现，不能由叙述改写。
+- 掷骰之后不得更改该行动的目标或难度，也不得为同一行动重掷。
+- 辅助掷骰与算术只决定伤害、数量等数值，不能推翻已经结算的判定。
+${bagLine}- 参数不合法属于工具错误，不等于行动失败；修正参数后重新调用即可。`
+        : `# Tabletop resolution rules
+
+This world is tabletop, with resolution scheme ${label}. The Runtime-fixed rules below apply because of this world's gameplay identity.
+
+## Check tool
+
+${rules}
+
+## Auxiliary tools
+
+- roll_dice: auxiliary numeric dice for damage, quantities and similar values. It never re-decides a resolved action.
+- calculate: add, subtract, multiply or divide two numbers. It draws no randomness and changes no world state.
+
+## Binding contract
+
+- Before calling the check tool, declare the action's goal, the inputs and the difficulty. Only actions with uncertain success or opposition need a check.
+- Call the check tool and receive its receipt before narrating the outcome.
+- A success must fulfil the declared goal and a failure must not, regardless of whether the story seems plausible.
+- Critical outcomes follow the tool's fixed rules and cannot be rewritten by narration.
+- After a draw, never change that action's goal or difficulty, and never reroll the same action.
+- Auxiliary dice and arithmetic decide numeric values such as damage or quantities; they never reverse a resolved check.
+${bagLine}- Invalid arguments are tool errors, not failed actions; correct the arguments and call the tool again.`;
+    return { source: "runtime:world-placeholder/gameplay", markdown };
+}
+/**
+ * Author-side statement of a tabletop package or world revision: the mode and
+ * scheme, what a write may change, and the scheme's rules.
+ */
+export function tabletopAuthoringRulesBlock(gameplay, target, locale) {
+    const label = gameplayLabel(gameplay, locale);
+    const rules = tabletopSchemeRules(gameplay, locale);
+    const source = target === "setting"
+        ? "runtime:content-package/gameplay"
+        : "runtime:world-revision/gameplay";
+    const markdown = target === "setting"
+        ? locale === "zh-CN"
+            ? `# 玩法模式与判定方案
+
+当前内容包是跑团内容包，当前判定方案为 ${label}。玩法模式固定为跑团，不能改为互动式小说。判定方案可通过写入 control/gameplay.json 改为 d20、d100 或 bag；这只影响之后创建的世界，已有世界不随源内容包变化。改变方案时，应同步调整人物数值、难度与规则，使其符合新方案的数值尺度。
+
+当前方案的判定工具规则：
+
+${rules}`
+            : `# Gameplay mode and resolution scheme
+
+This content package is tabletop, with current resolution scheme ${label}. The gameplay mode is fixed as tabletop and cannot become interactive fiction. The scheme may be changed by writing control/gameplay.json to d20, d100 or bag. The change affects only worlds created later; existing worlds never follow the source package. When changing the scheme, adjust character values, difficulty and rules so they match the new scheme's numeric scale.
+
+Check-tool rules for the current scheme:
+
+${rules}`
+        : locale === "zh-CN"
+            ? `# 玩法模式与判定方案（固定）
+
+当前修订的世界是跑团世界，判定方案为 ${label}。玩法模式与判定方案在世界创建后固定，修订不能修改 control/gameplay.json。数值与难度须遵循该方案。
+
+当前方案的判定工具规则：
+
+${rules}`
+            : `# Gameplay mode and resolution scheme (fixed)
+
+The world under revision is tabletop, with resolution scheme ${label}. Its gameplay mode and scheme were fixed at creation; a revision cannot change control/gameplay.json. Numeric values and difficulty must follow this scheme.
+
+Check-tool rules for the current scheme:
+
+${rules}`;
+    const bag = gameplay.scheme === "bag" ? `\n\n${bagAuthoringGuidance(locale)}` : "";
+    return { source, markdown: `${markdown}${bag}` };
+}
+/**
+ * Authoring guidance for a chaos-bag scheme: the default bag, or a bag the world
+ * documents, and who maintains its contents. Only the bag scheme carries it.
+ */
+export function bagAuthoringGuidance(locale) {
+    return locale === "zh-CN"
+        ? `## 混乱袋内容
+
+- 默认袋：世界文档未定义标记时，判定使用默认袋：+1、0×2、-1×2、-2、大成功、大失败。
+- 世界自定义袋：在世界文档中写明每种标记的名称与数量，并且每种标记恰好写明修正值或大成功／大失败之一。判定时必须读取该清单，并原样提供。
+- 袋内容的变化由你在世界文档中维护。每次抽取后标记放回，抽取本身不改变袋。`
+        : `## Chaos-bag contents
+
+- Default bag: when the world documents define no tokens, the check uses the default bag: +1, 0 ×2, -1 ×2, -2, critical success, critical failure.
+- World-documented bag: write each token's label and count in the world documents, and give each token exactly one of a modifier or a critical outcome. Read that list and supply it exactly when checking.
+- You maintain any change to the bag's contents in the world documents. Each drawn token returns to the bag, so drawing never changes the bag itself.`;
+}
+/** The receipt sent after a successful gameplay write; it teaches the new scheme's rules mid-conversation. */
+export function tabletopSchemeReceipt(gameplay, locale) {
+    const rules = tabletopSchemeRules(gameplay, locale);
+    const receipt = locale === "zh-CN"
+        ? `新判定方案规则（之后请按此调整数值与难度）：\n\n${rules}`
+        : `New resolution-scheme rules (adjust numbers and difficulty to match from now on):\n\n${rules}`;
+    return gameplay.scheme === "bag"
+        ? `${receipt}\n\n${bagAuthoringGuidance(locale)}`
+        : receipt;
+}

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

@@ -5,7 +5,7 @@ import { hasLegacyHistoryTools } from "./FileNativeToolRegistry.js";
 import { effectiveFollowupDefinitions } from "../play/OrderedFollowups.js";
 import { legacyAuthorPrompts } from "../play/FileNativePlayPresetStore.js";
 import { builtinAuthorPrompts, authoringMechanics, } from "../../shared/ordered-author-prompts.js";
-import { builtinPlayPrompts, } from "../../shared/ordered-play-prompts.js";
+import { builtinPlayPrompts, orderedPromptScope, promptScopeApplies, } from "../../shared/ordered-play-prompts.js";
 import { parseOrderedPlayPrompts } from "../play/OrderedPlayPrompts.js";
 import { renderDocumentWritePosition } from "./WorldMaintenanceReport.js";
 import { parseDocument } from "yaml";
@@ -16,7 +16,10 @@ import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
 import { checkpointHistory, checkpointReplayBlocks, } from "../play/PlayContinuity.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
-import { defaultRuntimeToolDefinitionStrategy, registeredRuntimeToolNames, runtimeToolsForNames, } from "./FileNativeToolRegistry.js";
+import { defaultRuntimeToolDefinitionStrategy, runtimeToolNamesForGameplay, runtimeToolsForNames, } from "./FileNativeToolRegistry.js";
+import { resolutionToolNames } from "../play/TabletopResolution.js";
+import { readGameplay } from "../../protocol/gameplay.js";
+import { tabletopAuthoringRulesBlock, tabletopWorldRulesBlock, } from "../play/TabletopRules.js";
 import { stateDirectoryHandle } from "../world/StateDirectoryHandles.js";
 export class PromptCompilationError extends Error {
     code;
@@ -103,6 +106,7 @@ const playCallChainToolNames = new Set([
     "world_create",
     "world_retire",
     "world_checkpoint",
+    ...resolutionToolNames,
 ]);
 export class FileNativePromptCompiler {
     #toolStrategyOverride;
@@ -137,6 +141,7 @@ export class FileNativePromptCompiler {
             },
             runtimeSource: "runtime:builtin/setting-improvement",
             target: "setting",
+            gameplay: input.gameplay,
             runtimeContract: input.runtimeContract,
             authorPrompt: input.authorPrompt,
             playPreset: input.playPreset,
@@ -165,6 +170,7 @@ export class FileNativePromptCompiler {
             },
             runtimeSource: "runtime:builtin/world-revision",
             target: "world-revision",
+            gameplay: input.gameplay,
             runtimeContract: input.runtimeContract,
             authorPrompt: input.authorPrompt,
             playPreset: input.playPreset,
@@ -174,7 +180,7 @@ export class FileNativePromptCompiler {
     }
     #compileAuthoringConversation(input) {
         validateModel(input.modelBinding);
-        const presetReference = settingImprovementPresetReference(input.playPreset, this.#locale, input.target);
+        const presetReference = settingImprovementPresetReference(input.playPreset, this.#locale, input.target, input.gameplay);
         const logicalMessages = [];
         const ordered = input.playPreset.definition.authorPrompts ??
             legacyAuthorPrompts(input.playPreset.definition);
@@ -182,6 +188,8 @@ export class FileNativePromptCompiler {
         for (const entry of ordered) {
             if (entry.kind === "world" || !entry.enabled)
                 continue;
+            if (!promptScopeApplies(orderedPromptScope(entry, catalog), input.gameplay))
+                continue;
             const builtin = entry.kind === "builtin"
                 ? catalog.find((item) => item.id === entry.builtin)
                 : undefined;
@@ -199,7 +207,15 @@ export class FileNativePromptCompiler {
                     },
                 ];
             if (builtin?.id === "author.target")
-                blocks = [input.identity, input.boundary];
+                blocks = [
+                    input.identity,
+                    input.boundary,
+                    ...(input.gameplay.mode === "tabletop"
+                        ? [
+                            tabletopAuthoringRulesBlock(input.gameplay, input.target, this.#locale),
+                        ]
+                        : []),
+                ];
             if (builtin?.id === "author.play-reference")
                 blocks = [
                     {
@@ -336,7 +352,7 @@ export class FileNativePromptCompiler {
             markdown: joinBlocks(blocks[role]),
         }));
         scanRuntimeLeakage(logicalMessages);
-        const tools = runtimeToolsForNames(registeredRuntimeToolNames, this.#locale);
+        const tools = runtimeToolsForNames(runtimeToolNamesForGameplay(playGameplay(documentSnapshot)), this.#locale);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(effectiveInput.modelBinding.provider);
         const cacheStrategy = effectiveInput.modelBinding.cacheStrategy ??
@@ -468,7 +484,7 @@ export class FileNativePromptCompiler {
         const bootstrap = binding.definition.playPrompts === undefined
             ? this.compilePlayBootstrap(input)
             : this.compileOrderedPlayBootstrap(input, binding);
-        const compilation = compilePlayPresetCompilation(input, bootstrap, binding, this.#locale);
+        const compilation = compilePlayPresetCompilation(input, bootstrap, binding, this.#locale, runtimeToolNamesForGameplay(playGameplay(input.world.documentSnapshot)));
         refreshMaintenanceTotals(compilation.bootstrap);
         return compilation;
     }
@@ -493,7 +509,12 @@ export class FileNativePromptCompiler {
                     ...prompt,
                 });
         };
+        const playCatalog = builtinPlayPrompts(this.#locale);
+        const gameplay = playGameplay(effective.world.documentSnapshot);
         for (const entry of parseOrderedPlayPrompts(binding.definition.playPrompts)) {
+            // A scoped entry is absent from the request, not an empty message.
+            if (!promptScopeApplies(orderedPromptScope(entry, playCatalog), gameplay))
+                continue;
             prompt = {
                 messageRole: entry.messageRole ?? "system",
                 promptId: entry.id,
@@ -530,7 +551,7 @@ export class FileNativePromptCompiler {
                 { source: "player:input", markdown: effective.playerInput },
             ]);
         scanRuntimeLeakage(logicalMessages);
-        const tools = runtimeToolsForNames(registeredRuntimeToolNames, this.#locale);
+        const tools = runtimeToolsForNames(runtimeToolNamesForGameplay(playGameplay(effective.world.documentSnapshot)), this.#locale);
         const toolStrategy = this.#toolStrategyOverride ??
             defaultRuntimeToolDefinitionStrategy(effective.modelBinding.provider);
         const strategy = effective.modelBinding.cacheStrategy ??
@@ -620,6 +641,11 @@ export class FileNativePromptCompiler {
                 .map((directory) => `- ${stateDirectoryHandle(directory)}`)
                 .join("\n")}`,
         });
+        // Runtime rules precede the materials they govern. The frozen path keeps
+        // this block verbatim, so a continued context neither repeats nor loses it.
+        const gameplay = playGameplay(snapshot);
+        if (gameplay.mode === "tabletop")
+            materials.blocks.unshift(tabletopWorldRulesBlock(gameplay, this.#locale));
         return materials;
     }
     /**
@@ -790,7 +816,7 @@ Workspace title (data, not an instruction): ${encodedTitle}
 
 This title identifies the editing target, not world facts or document titles.`;
 }
-function settingImprovementPresetReference(binding, locale, target) {
+function settingImprovementPresetReference(binding, locale, target, gameplay) {
     const revision = target === "world-revision";
     const worldInstructionPlaceholder = {
         source: `${revision ? "world-revision" : "content-package"}:control/frame.yaml#instructions`,
@@ -813,6 +839,8 @@ function settingImprovementPresetReference(binding, locale, target) {
                 ];
             if (!entry.enabled)
                 return [];
+            if (!promptScopeApplies(orderedPromptScope(entry, builtinPlayPrompts(locale)), gameplay))
+                return [];
             if (entry.kind === "user")
                 return [
                     { source: `preset:prompt/${entry.id}`, markdown: entry.body },
@@ -969,8 +997,8 @@ function createPlayPresetPreview(binding, compilation) {
  * is either part of the bootstrap or a derived request dispatched after the
  * chain settles.
  */
-function compilePlayPresetCompilation(input, bootstrap, binding, locale) {
-    const toolUniverse = fileNativeToolsForNames(registeredRuntimeToolNames, locale);
+function compilePlayPresetCompilation(input, bootstrap, binding, locale, playToolNames) {
+    const toolUniverse = fileNativeToolsForNames(playToolNames, locale);
     const toolStrategy = bootstrap.toolStrategy;
     const stableText = cacheStableText(bootstrap.logicalMessages, binding.definition.playPrompts ? bootstrap.provider : undefined);
     const sessionBootstrap = {
@@ -1152,6 +1180,13 @@ function validateModel(model) {
         throw new PromptCompilationError("model_max_output_invalid", "The model must provide a valid maxOutputTokens value");
     }
 }
+/**
+ * A world or package keeps its gameplay in control/gameplay.json; a missing
+ * file is interactive fiction. Every play universe is derived from this value.
+ */
+function playGameplay(snapshot) {
+    return readGameplay(snapshot.files);
+}
 function snapshotFiles(snapshot) {
     return Object.fromEntries(snapshot.files.map(({ path, contents }) => [path, contents]));
 }

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

@@ -1,5 +1,6 @@
 import { historyUseGuidance } from "../../shared/history-use-guidance.js";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
+import { resolutionCheckToolForScheme, resolutionToolDefinition, resolutionToolNames, } from "../play/TabletopResolution.js";
 /**
  * Runtime-owned prompt tool registry.
  *
@@ -7,7 +8,12 @@ import { defaultAppLocale, } from "../../protocol/appPreferences.js";
  * schemas and descriptions stay here so authors cannot fork the executable
  * tool contract.
  */
-export const registeredRuntimeToolNames = [
+/**
+ * Tools that every current play and authoring surface may expose. Resolution
+ * tools are registered below but never enter a surface until a per-world
+ * selection (Phase 2) includes them.
+ */
+export const baseRuntimeToolNames = [
     "state_list",
     "history_list",
     "history_search",
@@ -21,8 +27,28 @@ export const registeredRuntimeToolNames = [
     "artifact_emit",
     "artifact_clear",
 ];
+/** The full executable Runtime vocabulary. Exposure is chosen per surface. */
+export const registeredRuntimeToolNames = [
+    ...baseRuntimeToolNames,
+    ...resolutionToolNames,
+];
+/**
+ * The tool surface of one world or package, derived only from its gameplay.
+ * Interactive fiction keeps the base surface exactly; tabletop adds the
+ * scheme's check plus auxiliary dice and arithmetic.
+ */
+export function runtimeToolNamesForGameplay(gameplay) {
+    if (gameplay.mode !== "tabletop")
+        return [...baseRuntimeToolNames];
+    return [
+        ...baseRuntimeToolNames,
+        resolutionCheckToolForScheme(gameplay.scheme),
+        "roll_dice",
+        "calculate",
+    ];
+}
 /** Changes only when the executable Runtime tool universe or schemas change. */
-export const runtimeToolRegistryRevision = "runtime-tools-v9";
+export const runtimeToolRegistryRevision = "runtime-tools-v10";
 export function defaultRuntimeToolDefinitionStrategy(provider) {
     return provider === "openai_responses"
         ? "native_allowed_subset"
@@ -89,6 +115,7 @@ function createToolDefinitions(locale) {
     }, ["yaml"]);
     const markdownLocator = object({ markdown: { type: "array", items: { type: "string" }, minItems: 1 } }, ["markdown"]);
     const definitions = {
+        ...resolutionDefinitions(locale),
         state_list: {
             description: descriptions.state_list,
             inputSchema: object({
@@ -237,6 +264,12 @@ function createToolDefinitions(locale) {
     };
     return definitions;
 }
+function resolutionDefinitions(locale) {
+    return Object.fromEntries(resolutionToolNames.map((name) => {
+        const { description, inputSchema } = resolutionToolDefinition(name, locale);
+        return [name, { description, inputSchema }];
+    }));
+}
 const toolDescriptions = {
     en: {
         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.",

package/dist/node/runtime/setting/FileNativeSettingImprovementStore.js

@@ -1,9 +1,11 @@
 import { validPromptCompilation, validLogicalMessages, validPromptTools, validPlayFollowup, validProviderKind, validCacheStrategy, validToolStrategy, } from "../prompt/PromptCompilationCodec.js";
 import { validAuthoringRequests, } from "../authoring/AuthoringRequestSnapshot.js";
 import { randomUUID } from "node:crypto";
-import { link, mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
+import { linkExclusive } from "../FileNativeExclusiveLink.js";
 import { dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { fictionGameplay } from "../../protocol/gameplay.js";
 import { ContentWorkspace } from "../content/ContentWorkspace.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
@@ -447,7 +449,9 @@ function migrateLegacySession(value, applyOutcome) {
         createdAt: value.createdAt,
         updatedAt: value.updatedAt,
         creationRequestId: `legacy:${value.sessionId}`,
-        bootstrap: compileSettingImprovementLegacyCurrentTreeBootstrap(structuredClone(value.bootstrap), value.locale, settingImprovementToolDefinitions(value.locale)),
+        bootstrap: compileSettingImprovementLegacyCurrentTreeBootstrap(structuredClone(value.bootstrap), value.locale, 
+        // Released sessions predate gameplay, and a package's mode is fixed, so they are fiction.
+        settingImprovementToolDefinitions(value.locale, fictionGameplay)),
         modelBinding: structuredClone(value.modelBinding),
         ...(value.playPreset === undefined
             ? {}
@@ -966,13 +970,11 @@ async function publishJson(path, value) {
         const handle = await open(temporary, "wx", 0o600);
         try {
             await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
-            await handle.sync();
         }
         finally {
             await handle.close();
         }
         await rename(temporary, path);
-        await syncDirectory(dirname(path));
     }
     finally {
         await rm(temporary, { force: true });
@@ -985,14 +987,12 @@ async function publishImmutableSource(path, contents) {
         const handle = await open(temporary, "wx", 0o600);
         try {
             await handle.writeFile(contents, "utf8");
-            await handle.sync();
         }
         finally {
             await handle.close();
         }
         try {
-            await link(temporary, path);
-            await syncDirectory(dirname(path));
+            await linkExclusive(temporary, path);
         }
         catch (error) {
             if (!isNodeError(error) || error.code !== "EEXIST")
@@ -1005,15 +1005,6 @@ async function publishImmutableSource(path, contents) {
         await rm(temporary, { force: true });
     }
 }
-async function syncDirectory(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/node/runtime/setting/SettingAuthoringTransaction.js

@@ -2,7 +2,9 @@ import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { renderWorldMaintenanceReport } from "../prompt/WorldMaintenanceReport.js";
 import { listWorldDocuments as listQueryableWorldDocuments } from "../prompt/WorldMaintenanceReport.js";
 import { defaultAppLocale } from "../../protocol/appPreferences.js";
+import { gameplayLabel, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { isScalar, isSeq, parseDocument, stringify } from "yaml";
+import { tabletopSchemeReceipt } from "../play/TabletopRules.js";
 import { inspectContentPackageCurrentTree } from "../content/FileNativeContentTree.js";
 import { worldMaterialCoverage } from "../prompt/WorldMaterialCoverage.js";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
@@ -60,7 +62,23 @@ export const settingAuthorContractExamples = {
     emptyPlayerViews: emptyPlayerViewsExample,
     playerViews: playerViewsExample,
 };
-export function settingImprovementRuntimeContract(locale) {
+/**
+ * Model-facing mention of control/gameplay.json. Only a tabletop package may
+ * change the scheme, so fiction packages never see the file in their contract
+ * or tool text. Runtime validation of the path is unaffected.
+ */
+function gameplayFileZh(tabletop) {
+    return tabletop
+        ? "、control/blocks/*.md 和 control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）"
+        : " 和 control/blocks/*.md";
+}
+function gameplayFileEn(tabletop) {
+    return tabletop
+        ? ", control/blocks/*.md, and control/gameplay.json (only a tabletop resolution scheme may change)"
+        : ", and control/blocks/*.md";
+}
+export function settingImprovementRuntimeContract(locale, gameplay) {
+    const tabletop = gameplay.mode === "tabletop";
     return locale === "zh-CN"
         ? `# Runtime 设定完善对话契约
 
@@ -69,7 +87,7 @@ export function settingImprovementRuntimeContract(locale) {
 - 工具写入直接修改内容包当前树。每个完整 Provider 工具响应中的调用按顺序执行，成功改动在该响应结算时原子发布，发布后立即成为内容包权威，无需另一步确认。
 - 每个写工具调用独立结算，并按本响应中的调用顺序读取之前已接受的结果。某个调用失败只在对应工具结果中返回精确原因，不回滚同一响应内其他成功调用，也不阻止后续调用。Runtime 在写调用结算后自动运行内容树检查和真实 Prompt Preview，并把检查结果附在最后一个成功写调用的结果中。
 - 修改既有文件前必须完整读取它。setting_list／setting_search 的 cursor，以及 setting_read 的读取授权，只属于产生它们的当前树 revision；任何其他对话或手动编辑改变当前树后，必须重新读取再写。setting_read 总是完整返回精确文件，不截断、不分页。工具只暴露逻辑路径，不暴露宿主路径。
-- world/ 下只写 .yaml 或 .md 世界文档；专用文件只允许 opening.md、control/frame.yaml、control/player-views.yaml 和 control/blocks/*.md，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。人物、地点、规则与当前情境放在 world/，本世界特有的主持要求放在 control/。
+- world/ 下只写 .yaml 或 .md 世界文档；专用文件只允许 opening.md、control/frame.yaml、control/player-views.yaml${gameplayFileZh(tabletop)}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。人物、地点、规则与当前情境放在 world/，本世界特有的主持要求放在 control/。
 - opening.md 是玩家看见的第一页，不得替玩家决定行动、台词或内心。会继续约束首次行动的事实也必须写入自然承载它的世界文档。
 - 新建 world 文档使用 setting_create：ref 由你提供，并同时提供路径、标题、摘要、别名与不含技术头的正文。ref 必须是唯一的 2～32 位小写 ASCII 短句柄；Runtime 自行完成技术存储。既有文档选择值会在读取时自动投影为对应的 @ref；跨文档引用和 control 中的文档选择只使用 @ref。
 - YAML 中指向整份文档的机械引用只写成单键 map，例如 { $ref: "@alex" }；普通字符串中的 @alex 仍只是文字。frame 与 player-view selector 的 document 值也写成 "@alex"，局部位置另用 locator 表达。
@@ -105,7 +123,7 @@ export function settingImprovementRuntimeContract(locale) {
 - Tool writes directly modify the content package's current tree. Calls in one complete Provider tool response execute in order; its successful changes publish atomically when that response settles, immediately become authoritative, and require no second confirmation.
 - Every write tool call settles independently and sees earlier accepted calls in response order. A failure returns its precise cause only in that call's result, does not roll back successful siblings, and does not stop later calls. Runtime automatically runs content-tree checks and a real Prompt Preview after writes and appends that review to the last successful write result.
 - Read an existing file completely before changing it. Cursors from setting_list and setting_search, and read authorization from setting_read, belong only to the current-tree revision that produced them. setting_read always returns the complete exact file without truncation or pagination. Re-read after another conversation or a manual edit changes the current tree. Tools expose logical paths, never host paths.
-- World documents are .yaml or .md files under world/. Special writes are limited to opening.md, control/frame.yaml, control/player-views.yaml, and control/blocks/*.md, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. Put characters, places, rules, and the current situation under world/, and world-specific hosting guidance under control/.
+- World documents are .yaml or .md files under world/. Special writes are limited to opening.md, control/frame.yaml, control/player-views.yaml${gameplayFileEn(tabletop)}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. Put characters, places, rules, and the current situation under world/, and world-specific hosting guidance under control/.
 - opening.md is the first page shown to the player. Never decide the player's action, dialogue, or inner thoughts. Facts that constrain the first action must also live in the world document that naturally owns them.
 - Create a world document with setting_create. You provide its unique 2-to-32-character lowercase ASCII ref, path, title, summary, aliases, and body without a technical header; Runtime completes the technical storage. Existing document selectors are automatically projected to their @refs when read. Cross-document references and control selectors use only @refs.
 - A mechanical YAML reference to one whole document is a one-key map such as { $ref: "@alex" }; @alex inside an ordinary string is still only text. The document value in frame and player-view selectors is likewise "@alex", with any local position expressed separately by a locator.
@@ -134,8 +152,11 @@ export function settingImprovementRuntimeContract(locale) {
 - Runtime commits durable state and narrative. Write results that must survive the next action to their natural owner; put short-lived cross-object situations with no single owner in the current situation; leave details that do not need to remain current in committed narrative.
 - Passing mechanical checks does not make content discoverable during play. Whenever important information is created or reorganized, decide its natural owner, initial injection or discovery path, future update location, and player-visible projection together.`;
 }
-export function settingImprovementToolDefinitions(locale = defaultAppLocale) {
-    const descriptions = locale === "zh-CN" ? toolDescriptionsZhCN : toolDescriptionsEn;
+export function settingImprovementToolDefinitions(locale, gameplay) {
+    const tabletop = gameplay.mode === "tabletop";
+    const descriptions = locale === "zh-CN"
+        ? toolDescriptionsZhCN(tabletop)
+        : toolDescriptionsEn(tabletop);
     const schema = (properties, required) => ({
         type: "object",
         additionalProperties: false,
@@ -243,26 +264,26 @@ export function settingImprovementToolDefinitions(locale = defaultAppLocale) {
         },
     ];
 }
-const toolDescriptionsEn = {
+const toolDescriptionsEn = (tabletop) => ({
     setting_list: "List the world root or a world/ subdirectory from the content package's current tree. The root also lists opening and control files. A cursor is valid only for the same query and current-tree revision.",
     setting_search: "Search literal source text in world documents in the content package's current tree. within may be world, a world/ directory or path, or @ref.",
     setting_read: "Read a complete world document by world/ path or @ref, or read a complete opening/control file by exact path. Existing document selectors are projected to @refs. The result is never truncated or paginated.",
     setting_create: "Create one world/ .yaml or .md document. Supply a unique lowercase ASCII ref, title, summary, aliases, and body without a technical header; Runtime completes the storage envelope. The created document is already fully read.",
-    setting_write_file: "Replace a completely read world/ .yaml or .md document body while preserving its identity and metadata, or create/replace opening.md, control/frame.yaml, control/player-views.yaml, or control/blocks/*.md, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. To repair a damaged world document, also provide ref, title, summary, and aliases; Runtime preserves any recoverable storage identity. Create new world documents with setting_create.",
+    setting_write_file: `Replace a completely read world/ .yaml or .md document body while preserving its identity and metadata, or create/replace opening.md, control/frame.yaml, control/player-views.yaml, ${tabletop ? "control/blocks/*.md, or control/gameplay.json (only a tabletop resolution scheme may change)" : "or control/blocks/*.md"}, plus control/followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. To repair a damaged world document, also provide ref, title, summary, and aliases; Runtime preserves any recoverable storage identity. Create new world documents with setting_create.`,
     setting_patch: 'Update a completely read YAML world document without rewriting unrelated content. locator is a non-empty path whose segments are map keys or zero-based array indexes. Use add for a missing map key or array index, replace for an existing node, append for the end of an existing array, and remove for an existing map key or array item. When title, summary, or aliases are stale, update all three together with op "set_metadata". Rewrite Markdown bodies with setting_write_file.',
     setting_move: "Move a completely read world document to a new world/ .yaml or .md logical path while preserving its identity and contents.",
     setting_delete: "Permanently delete a completely read world document from the content-package current tree. Runtime rejects deletion while currentSituation, a frame slot, a player-view selector, or another document's $ref still points to it, and reports every blocking location. Delete or redirect those references first.",
-};
-const toolDescriptionsZhCN = {
+});
+const toolDescriptionsZhCN = (tabletop) => ({
     setting_list: "列出内容包当前树的 world 根目录或 world/ 子目录；根目录同时列出 opening 和 control 专用文件。cursor 只对同一查询和当前树 revision 有效。",
     setting_search: "在内容包当前树的 world 文档中按原文字面搜索；within 可为 world、world/ 目录或路径或 @ref。",
     setting_read: "按 world/ 路径或 @ref 完整读取世界文档，或按精确路径完整读取 opening/control；既有文档选择值自动投影为 @ref。结果不会截断或分页。",
     setting_create: "创建一份 world/ 下的 .yaml 或 .md 文档；提供唯一的小写 ASCII ref、标题、摘要、别名和不含技术头的正文，Runtime 自行完成存储封装。创建成功的文档视为已经完整读取。",
-    setting_write_file: "整份替换已完整读取的 world/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 setting_create。",
+    setting_write_file: `整份替换已完整读取的 world/ .yaml 或 .md 正文并保留身份和元信息，或创建／替换 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md${tabletop ? "、control/gameplay.json（只能修改跑团判定方案，玩法模式不可改）" : ""}，以及 control/followups.yaml 和其中引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。修复损坏世界文档时同时提供 ref、title、summary、aliases，Runtime 会保留仍可恢复的存储身份。新建世界文档使用 setting_create。`,
     setting_patch: '细粒度更新已完整读取的 YAML 世界文档，不重写无关内容。locator 是非空路径，每段可以是 map key 或从 0 开始的数组下标；add 新建 map key 或数组位置，replace 更新既有节点，append 追加既有数组，remove 删除既有 map key 或数组项。title、summary 或 aliases 过时时用 op "set_metadata" 整组更新三项。Markdown 正文用 setting_write_file 整份重写。',
     setting_move: "把已完整读取的世界文档移动到新的 world/ .yaml 或 .md 逻辑路径，并保留身份与内容。",
     setting_delete: "从内容包当前树永久删除一份已完整读取的 world 文档。若 currentSituation、frame slot、player-view selector 或其他文档的 $ref 仍指向它，Runtime 会拒绝并返回全部精确阻挡位置；请先删除或改向这些引用。",
-};
+});
 export class SettingAuthoringTransaction {
     #baseFiles;
     #locale;
@@ -918,10 +939,12 @@ function writeOpaque(snapshot, call, reads, locale) {
         throw new SettingAuthoringError("Special-file writes accept only path and contents");
     const path = safePath(requiredString(call.arguments.path, "path"));
     if (!writableOpaquePath(path))
-        throw new SettingAuthoringError(localized(locale, "Special-file writes accept only opening.md, control/frame.yaml, control/player-views.yaml, or control/blocks/*.md", "专用文件只允许写入 opening.md、control/frame.yaml、control/player-views.yaml 或 control/blocks/*.md"));
+        throw new SettingAuthoringError(localized(locale, "Special-file writes accept only opening.md, control/frame.yaml, control/player-views.yaml, control/blocks/*.md, or control/gameplay.json", "专用文件只允许写入 opening.md、control/frame.yaml、control/player-views.yaml、control/blocks/*.md 或 control/gameplay.json"));
     const authoredContents = requiredString(call.arguments.contents, "contents");
     assertNoLiteralUnicodeEscapes(authoredContents, locale);
     const contents = projectOpaqueDocumentIds(snapshot, path, authoredContents);
+    if (path === gameplayPath)
+        assertGameplayWriteKeepsMode(snapshot.files, contents, locale);
     const next = cloneFiles(snapshot.files);
     const existing = next.find((file) => file.path === path);
     if (existing !== undefined && !reads.opaquePaths.has(path))
@@ -938,16 +961,36 @@ function writeOpaque(snapshot, call, reads, locale) {
     });
     rebaseReads(reads, revised);
     reads.opaquePaths.add(path);
+    const gameplay = path === gameplayPath ? readGameplay([{ path, contents }]) : null;
     return {
         snapshot: revised,
-        markdown: localized(locale, `# Current-tree write accepted\n\n${existing === undefined ? "Created" : "Updated"} ${path} in the content package's current tree. This file is already fully read; do not read it again unless a later decision needs Runtime's exact serialization.`, `# 当前树写入已接受\n\n已在内容包当前树中${existing === undefined ? "创建" : "更新"} ${path}。该文件已视为完整读取；除非后续判断依赖 Runtime 的精确序列化结果，否则不要再次读取。`),
+        markdown: [
+            localized(locale, `# Current-tree write accepted\n\n${existing === undefined ? "Created" : "Updated"} ${path} in the content package's current tree. This file is already fully read; do not read it again unless a later decision needs Runtime's exact serialization.`, `# 当前树写入已接受\n\n已在内容包当前树中${existing === undefined ? "创建" : "更新"} ${path}。该文件已视为完整读取；除非后续判断依赖 Runtime 的精确序列化结果，否则不要再次读取。`),
+            ...(gameplay === null
+                ? []
+                : [
+                    localized(locale, `Current gameplay: ${gameplayLabel(gameplay, locale)}.`, `当前玩法：${gameplayLabel(gameplay, locale)}。`),
+                    // Mid-conversation the model learns the new scheme's rules here (ADR-0037 append-only).
+                    ...(gameplay.mode === "tabletop"
+                        ? [tabletopSchemeReceipt(gameplay, locale)]
+                        : []),
+                ]),
+        ].join("\n\n"),
     };
 }
+/** The gameplay mode is fixed; a write may only keep it or change a tabletop scheme. */
+function assertGameplayWriteKeepsMode(files, contents, locale) {
+    const before = readGameplay(files);
+    const after = readGameplay([{ path: gameplayPath, contents }]);
+    if (before.mode !== after.mode)
+        throw new SettingAuthoringError(localized(locale, "Gameplay mode is fixed; control/gameplay.json may change only the resolution scheme of a tabletop package", "玩法模式固定；control/gameplay.json 只能修改跑团的判定方案，不能在互动式小说与跑团之间切换"));
+}
 function writableOpaquePath(path) {
     return (isPackageFollowupControlPath(path) ||
         path === "opening.md" ||
         path === "control/frame.yaml" ||
         path === "control/player-views.yaml" ||
+        path === gameplayPath ||
         /^control\/blocks\/[a-z0-9][a-z0-9/_-]*\.md$/u.test(path));
 }
 function assertWorldWritesAuthorized(snapshotId, reads, changes, locale) {

package/dist/node/runtime/setting/SettingImprovementSession.js

@@ -231,11 +231,12 @@ export class SettingImprovementSession {
         const package_ = await this.#content.readCurrentTreeContentPackage(packageId);
         const bootstrap = this.#compiler.compileSettingImprovement({
             contentPackageTitle: package_.title,
-            runtimeContract: settingImprovementRuntimeContract(locale),
+            gameplay: package_.gameplay,
+            runtimeContract: settingImprovementRuntimeContract(locale, package_.gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding: modelBinding,
-            tools: settingImprovementToolDefinitions(locale),
+            tools: settingImprovementToolDefinitions(locale, package_.gameplay),
         });
         return { bootstrap, playPreset };
     }
@@ -253,10 +254,11 @@ export class SettingImprovementSession {
         ]);
         const locale = this.#locale();
         const modelBinding = host.binding();
-        const tools = settingImprovementToolDefinitions(locale);
+        const tools = settingImprovementToolDefinitions(locale, package_.gameplay);
         const bootstrap = this.#compiler.compileSettingImprovement({
             contentPackageTitle: package_.title,
-            runtimeContract: settingImprovementRuntimeContract(locale),
+            gameplay: package_.gameplay,
+            runtimeContract: settingImprovementRuntimeContract(locale, package_.gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding,