narraeon 0.5.7 → 0.6.0

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

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
 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 +448,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
             ? {}

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,

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

@@ -2,6 +2,7 @@ import { captureNarrativeOrigin, snapshotBackground, isHistoryBackground, } from
 import { FileNativeArtifactStore } from "../artifact/FileNativeArtifactStore.js";
 import { WorldExtensionRequests } from "../extension/WorldExtensionRequests.js";
 import { WorldExtensionControls, extensionDefinitions, } from "../extension/WorldExtensionControls.js";
+import { assertSameGameplay, readGameplay, } from "../../protocol/gameplay.js";
 import { HistoryQuery } from "../history/HistoryQuery.js";
 import { exportStory } from "../history/StoryExport.js";
 import { PackageScriptPermissions } from "../extension/PackageScriptPermissions.js";
@@ -116,6 +117,13 @@ export class FileNativeWorldStore {
             throw new FileNativeWorldCreationError("world_corrupt", "Released world storage could not be migrated to the current format", error instanceof Error ? { cause: error } : undefined);
         }
     }
+    async gameplay(worldId) {
+        assertIdentity(worldId, "World ID");
+        await this.ensureCurrentStorage(worldId);
+        const root = join(this.#worldsRoot, worldId);
+        await readPublicationAt(root);
+        return readWorldGameplayAt(root);
+    }
     async readWorldSummary(worldId) {
         assertIdentity(worldId, "World ID");
         return readWorldSummaryAt(join(this.#worldsRoot, worldId));
@@ -472,6 +480,7 @@ export class FileNativeWorldStore {
                 await this.ensureCurrentStorage(worldId);
                 const root = join(this.#worldsRoot, worldId);
                 await readPublicationAt(root);
+                assertControlGameplayUnchanged(await readTree(join(root, "control")), files);
                 const staging = join(root, `runtime/.control-draft-${randomUUID()}`);
                 await writeSurface(staging, "control", files);
                 const final = join(root, "runtime/control-draft");
@@ -562,6 +571,7 @@ export class FileNativeWorldStore {
             }
             if (currentFingerprint !== input.expectedFingerprint)
                 throw new FileNativeWorldCreationError("operation_conflict", "World control changed after this revision epoch opened");
+            assertControlGameplayUnchanged(current, input.files);
             await rm(stagingRoot, { recursive: true, force: true });
             await rm(previousPath, { recursive: true, force: true });
             await writeSurface(stagingRoot, "control", input.files);
@@ -618,6 +628,7 @@ export class FileNativeWorldStore {
                     throw new FileNativeWorldCreationError("operation_conflict", "World control is frozen by a running attempt");
                 const preview = await this.previewControlDraft(worldId, prompt);
                 const root = join(this.#worldsRoot, worldId);
+                assertControlGameplayUnchanged(await readTree(join(root, "control")), await readTree(join(root, "runtime/control-draft")));
                 const draft = join(root, "runtime/control-draft");
                 const replacement = join(root, `runtime/.control-apply-${randomUUID()}`);
                 await rename(draft, replacement);
@@ -2179,9 +2190,10 @@ async function readPublicationAt(root) {
 }
 async function readWorldSummaryAt(root, publication, serializeRebuild) {
     const published = publication ?? (await readPublicationAt(root));
+    const gameplay = await readWorldGameplayAt(root);
     const { lastActivityAt, excerpt, playerTurns } = await readWorldActivity(root, serializeRebuild);
     const summary = {
-        ...toSummary(published),
+        ...toSummary(published, gameplay),
         title: await readWorldTitleAt(root, published),
         lastActivityAt,
         excerpt,
@@ -2197,6 +2209,15 @@ async function readWorldTitleAt(root, published) {
         throw new FileNativeWorldCreationError("world_corrupt", "Local world shell is corrupt");
     return metadata.name;
 }
+/** Worlds copy the package's gameplay identity with control; its absence means interactive fiction. */
+async function readWorldGameplayAt(root) {
+    try {
+        return readGameplay(controlGameplayFiles(await readTree(join(root, "control"))));
+    }
+    catch (error) {
+        throw new FileNativeWorldCreationError("world_corrupt", "World gameplay identity is corrupt", { cause: error });
+    }
+}
 async function readJson(path) {
     return JSON.parse(await readFile(path, "utf8"));
 }
@@ -2210,13 +2231,26 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
-function toSummary(publication) {
+function toSummary(publication, gameplay) {
     return {
         worldId: publication.worldId,
         title: publication.title,
         parentEndpoint: publication.parentEndpoint,
+        gameplay,
     };
 }
+/** World control is a fixed mode and scheme: drafts, revisions and applies may not change either. */
+function assertControlGameplayUnchanged(current, next) {
+    try {
+        assertSameGameplay(controlGameplayFiles(current), controlGameplayFiles(next));
+    }
+    catch (error) {
+        throw new FileNativeWorldCreationError("candidate_validation_failed", error instanceof Error ? error.message : "World gameplay is fixed", { cause: error });
+    }
+}
+function controlGameplayFiles(files) {
+    return files.map((file) => ({ ...file, path: `control/${file.path}` }));
+}
 const worldNamePattern = /^[^\r\n]{1,160}$/u;
 function validWorldName(name) {
     return worldNamePattern.test(name);

package/dist/node/runtime/world-revision/FileNativeWorldRevisionStore.js

@@ -4,6 +4,7 @@ import { validAuthoringRequests, } from "../authoring/AuthoringRequestSnapshot.j
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { gameplayPath } from "../../protocol/gameplay.js";
 import { contentTreeFingerprint } from "../content/ContentTreeFingerprint.js";
 import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
 const uuidV4Pattern = "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
@@ -604,6 +605,7 @@ function validRevisionPath(path) {
     return (safe &&
         (isPackageFollowupControlPath(path) ||
             /^state\/.+\.(?:ya?ml|md)$/u.test(path) ||
+            path === gameplayPath ||
             path === "control/frame.yaml" ||
             path === "control/player-views.yaml" ||
             /^control\/blocks\/.+\.md$/u.test(path)));