narraeon 0.5.7 → 0.6.1

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

@@ -0,0 +1,353 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+export class WorldTurnLedgerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorldTurnLedgerError";
+        this.code = code;
+    }
+}
+const headFile = join("runtime", "head.json");
+const turnsDirectory = join("runtime", "turns");
+function turnFileName(sequence) {
+    return join(turnsDirectory, `${String(sequence).padStart(8, "0")}.json`);
+}
+function assertSafePath(relativePath) {
+    const normalized = normalize(relativePath);
+    if (isAbsolute(relativePath) ||
+        normalized.startsWith(`..${sep}`) ||
+        normalized === ".." ||
+        normalized.length === 0 ||
+        normalized === headFile ||
+        normalized === turnsDirectory ||
+        normalized.startsWith(turnsDirectory + sep)) {
+        throw new WorldTurnLedgerError("invalid_path", `世界文件路径不合法：${relativePath}`);
+    }
+}
+async function writeFileAtomic(absolute, content) {
+    await mkdir(dirname(absolute), { recursive: true });
+    const temporary = `${absolute}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, "utf8");
+    await rename(temporary, absolute);
+}
+async function readTextOrNull(absolute) {
+    try {
+        return await readFile(absolute, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function initializeLedger(root) {
+    forgetLedger(root);
+    await writeFileAtomic(join(root, headFile), `${JSON.stringify({ sequence: 0 }, null, 2)}\n`);
+}
+export async function readHead(root) {
+    const text = await readTextOrNull(join(root, headFile));
+    if (text === null) {
+        throw new WorldTurnLedgerError("no_head", "世界缺少轮账本端点");
+    }
+    const parsed = JSON.parse(text);
+    if (typeof parsed.sequence !== "number" ||
+        !Number.isInteger(parsed.sequence) ||
+        parsed.sequence < 0) {
+        throw new WorldTurnLedgerError("corrupt", "世界轮账本端点格式不正确");
+    }
+    return parsed.sequence;
+}
+async function publishHead(root, sequence) {
+    await writeFileAtomic(join(root, headFile), `${JSON.stringify({ sequence }, null, 2)}\n`);
+}
+async function readAllRecords(root) {
+    let names;
+    try {
+        names = await readdir(join(root, turnsDirectory));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const text = await readFile(join(root, turnsDirectory, name), "utf8");
+        records.push(JSON.parse(text));
+    }
+    return records.sort((left, right) => left.sequence - right.sequence);
+}
+// 被某个 rewind 丢弃的轮是 (restores, rewind) 之间的位置；它们可能仍在磁盘上，
+// 直到清理完成，但读取时一律忽略。
+function viewOf(head, records) {
+    const byPosition = new Map();
+    for (const record of records) {
+        if (record.sequence <= head)
+            byPosition.set(record.sequence, record);
+    }
+    const discarded = new Set();
+    for (const record of byPosition.values()) {
+        if (record.restoresSequence === undefined)
+            continue;
+        for (let position = record.restoresSequence + 1; position < record.sequence; position += 1) {
+            discarded.add(position);
+        }
+    }
+    return { head, byPosition, discarded };
+}
+// 进程内视图缓存，按端点失效。一个数据目录只被一个进程操作（ADR-0044），
+// 所以 head 相同即记录相同：任何改变可见记录的写入都会先推进 head。
+// 只有 beginTurn 与 recoverIncomplete 会在 head 之上写入或删除记录，它们不影响视图
+// （视图只包含序号不大于 head 的记录，且 recoverIncomplete 本身会在结束时失效缓存）。
+const viewCache = new Map();
+async function loadView(root) {
+    const head = await readHead(root);
+    const cached = viewCache.get(resolve(root));
+    if (cached?.head === head)
+        return cached;
+    const view = viewOf(head, await readAllRecords(root));
+    viewCache.set(resolve(root), view);
+    return view;
+}
+// 世界目录被删除、归档导入或分叉发布到已存在路径之前调用：下一次读取从磁盘重建视图。
+export function forgetLedger(root) {
+    viewCache.delete(resolve(root));
+}
+// 把一个端点解析到它的逻辑位置：rewind 位置等价于它所恢复的位置。
+function resolvePosition(view, sequence) {
+    if (!Number.isInteger(sequence) || sequence < 0 || sequence > view.head) {
+        throw new WorldTurnLedgerError("unreachable", `端点 ${sequence} 不在当前账本范围内`);
+    }
+    let position = sequence;
+    for (;;) {
+        if (position === 0)
+            return 0;
+        if (view.discarded.has(position)) {
+            throw new WorldTurnLedgerError("unreachable", `端点 ${sequence} 已被回退丢弃`);
+        }
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        if (record.mode !== "rewind")
+            return position;
+        if (record.restoresSequence === undefined) {
+            throw new WorldTurnLedgerError("corrupt", `第 ${position} 轮缺少回退目标`);
+        }
+        position = record.restoresSequence;
+    }
+}
+// 从 sequence 之后的全部可见改动倒推：每个路径取最早一次修改前像。
+function overlayAfter(view, sequence) {
+    const overlay = new Map();
+    for (let position = sequence + 1; position <= view.head; position += 1) {
+        if (view.discarded.has(position))
+            continue;
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        if (record.mode === "rewind")
+            continue;
+        for (const file of record.files) {
+            if (!overlay.has(file.path))
+                overlay.set(file.path, file.before);
+        }
+    }
+    return overlay;
+}
+async function captureBefore(root, paths) {
+    const files = [];
+    for (const path of paths) {
+        assertSafePath(path);
+        files.push({ path, before: await readTextOrNull(join(root, path)) });
+    }
+    return files;
+}
+// 第一步：写入本轮记录（序号为 head + 1）。记录原子落盘，之后任何一步崩溃都可由 recoverIncomplete 回滚。
+export async function beginTurn(root, input) {
+    const head = await readHead(root);
+    const record = {
+        sequence: head + 1,
+        mode: input.mode,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        ...(input.restoresSequence === undefined
+            ? {}
+            : { restoresSequence: input.restoresSequence }),
+        ...(input.payload === undefined ? {} : { payload: input.payload }),
+        files: await captureBefore(root, input.changes.map((change) => change.path)),
+    };
+    await writeFileAtomic(join(root, turnFileName(record.sequence)), `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+// 第二步：逐文件原子替换（写临时文件后 rename；删除即 rm）。
+export async function applyChanges(root, changes) {
+    for (const change of changes) {
+        assertSafePath(change.path);
+        const absolute = join(root, change.path);
+        if (change.content === null) {
+            await rm(absolute, { force: true });
+        }
+        else {
+            await writeFileAtomic(absolute, change.content);
+        }
+    }
+}
+// 第三步：发布端点。只有这一步之后，本轮才算完成。
+export async function commitTurnHead(root, record) {
+    await publishHead(root, record.sequence);
+}
+export async function appendTurn(root, input) {
+    const record = await beginTurn(root, input);
+    await applyChanges(root, input.changes);
+    await commitTurnHead(root, record);
+    return record;
+}
+// 启动时调用：序号大于 head 的记录说明上一次推进未完成，逆序恢复其修改前像。
+// 被丢弃的轮记录（读取时已忽略）在这里清理。返回是否回滚了未完成的轮。
+export async function recoverIncomplete(root) {
+    const head = await readHead(root);
+    const records = await readAllRecords(root);
+    const incomplete = records
+        .filter((record) => record.sequence > head)
+        .sort((left, right) => right.sequence - left.sequence);
+    for (const record of incomplete) {
+        for (const file of [...record.files].reverse()) {
+            assertSafePath(file.path);
+            const absolute = join(root, file.path);
+            if (file.before === null) {
+                await rm(absolute, { force: true });
+            }
+            else {
+                await writeFileAtomic(absolute, file.before);
+            }
+        }
+        await rm(join(root, turnFileName(record.sequence)), { force: true });
+    }
+    const view = viewOf(head, records);
+    for (const position of view.discarded) {
+        await rm(join(root, turnFileName(position)), { force: true });
+    }
+    forgetLedger(root);
+    return incomplete.length > 0;
+}
+export async function listTurns(root) {
+    const view = await loadView(root);
+    const turns = [];
+    for (let position = 1; position <= view.head; position += 1) {
+        if (view.discarded.has(position))
+            continue;
+        const record = view.byPosition.get(position);
+        if (!record) {
+            throw new WorldTurnLedgerError("missing_record", `缺少第 ${position} 轮记录`);
+        }
+        turns.push(record);
+    }
+    return turns;
+}
+// 把端点解析为它所表示的逻辑位置（rewind 位置等价于它恢复的位置）。
+export async function resolveEndpoint(root, sequence) {
+    return resolvePosition(await loadView(root), sequence);
+}
+// 第 sequence 轮记录文件的 sha256；0 轮没有记录，返回 null。
+export async function readTurnDigest(root, sequence) {
+    if (sequence === 0)
+        return null;
+    const text = await readFile(join(root, turnFileName(sequence)), "utf8");
+    return createHash("sha256").update(text).digest("hex");
+}
+// 读取端点 sequence 处某个文件的内容；不存在返回 null。
+export async function readFileAt(root, sequence, relativePath) {
+    assertSafePath(relativePath);
+    const view = await loadView(root);
+    const position = resolvePosition(view, sequence);
+    const overlay = overlayAfter(view, position);
+    if (overlay.has(relativePath))
+        return overlay.get(relativePath) ?? null;
+    return readTextOrNull(join(root, relativePath));
+}
+// 读取端点 sequence 处 dirs 下的全部文件（相对路径 → 内容）。
+export async function readTreeAt(root, sequence, dirs) {
+    const view = await loadView(root);
+    const position = resolvePosition(view, sequence);
+    const overlay = overlayAfter(view, position);
+    const tree = new Map();
+    for (const dir of dirs) {
+        assertSafePath(dir);
+        for (const path of await listFiles(root, dir)) {
+            if (!overlay.has(path)) {
+                const text = await readTextOrNull(join(root, path));
+                if (text !== null)
+                    tree.set(path, text);
+            }
+        }
+    }
+    for (const [path, before] of overlay) {
+        const inDir = dirs.some((dir) => path === dir || path.startsWith(dir + "/"));
+        if (!inDir || before === null)
+            continue;
+        tree.set(path, before);
+    }
+    return tree;
+}
+async function listFiles(root, dir) {
+    const found = [];
+    const visit = async (relative) => {
+        let entries;
+        try {
+            entries = await readdir(join(root, relative), { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const child = `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                await visit(child);
+            }
+            else if (entry.isFile() && !entry.name.endsWith(".tmp")) {
+                found.push(child);
+            }
+        }
+    };
+    await visit(dir);
+    return found;
+}
+// 回退到端点 sequence：追加一轮 rewind（前像为回退前的文件），之后丢弃 (sequence, head] 的记录。
+// 已经处于 sequence 的端点是空操作。返回新轮记录，或 null。
+export async function rewindTo(root, sequence) {
+    const view = await loadView(root);
+    const target = resolvePosition(view, sequence);
+    if (target === view.head)
+        return null;
+    const overlay = overlayAfter(view, target);
+    const changes = [];
+    for (const [path, before] of overlay) {
+        const current = await readTextOrNull(join(root, path));
+        if (current === before)
+            continue;
+        changes.push({ path, content: before });
+    }
+    const record = await appendTurn(root, {
+        mode: "rewind",
+        changes,
+        restoresSequence: sequence,
+    });
+    // 端点已发布，丢弃的记录即可删除；失败可忽略，读取已把它们当作不可达，下次回退或恢复会再清理。
+    for (let position = target + 1; position <= view.head; position += 1) {
+        await rm(join(root, turnFileName(position)), { force: true }).catch(() => undefined);
+    }
+    return record;
+}

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}";
@@ -110,7 +111,6 @@ export class FileNativeWorldRevisionStore {
             if (session.worldId !== worldId)
                 throw new Error("World-revision conversation belongs to another world");
             await rm(this.#sessionPath(sessionId));
-            await syncDirectory(this.#sessionsRoot);
         });
     }
     async #readEpoch(epochId) {
@@ -604,6 +604,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)));
@@ -635,27 +636,16 @@ 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 });
     }
 }
-async function syncDirectory(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
 function count(value) {
     return Number.isSafeInteger(value) && Number(value) >= 0;
 }

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

@@ -1,5 +1,6 @@
 import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { defaultAppLocale } from "../../protocol/appPreferences.js";
+import { assertSameGameplay, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { inspectContentPackageCurrentTree } from "../content/FileNativeContentTree.js";
 import { SettingAuthoringTransaction, settingImprovementToolDefinitions, } from "../setting/SettingAuthoringTransaction.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
@@ -71,8 +72,8 @@ export class WorldRevisionAuthoringTransaction {
         });
     }
 }
-export function worldRevisionToolDefinitions(locale = defaultAppLocale) {
-    return settingImprovementToolDefinitions(locale).map((definition) => {
+export function worldRevisionToolDefinitions(locale, gameplay) {
+    return settingImprovementToolDefinitions(locale, gameplay).map((definition) => {
         const name = settingToRevisionTool.get(definition.name);
         if (name === undefined)
             throw new Error(`Unsupported setting authoring tool: ${definition.name}`);
@@ -84,7 +85,9 @@ export function worldRevisionToolDefinitions(locale = defaultAppLocale) {
         };
     });
 }
-export function worldRevisionRuntimeContract(locale) {
+export function worldRevisionRuntimeContract(locale, gameplay) {
+    // A world's mode and scheme are fixed, so only tabletop worlds mention the file.
+    const tabletop = gameplay.mode === "tabletop";
     return locale === "zh-CN"
         ? `# Runtime 世界修订对话契约
 
@@ -93,7 +96,7 @@ export function worldRevisionRuntimeContract(locale) {
 - 工具调用修改的是尚未应用的工作树。只有玩家点击“应用修订”才会把当前整棵树提交为新的世界状态和控制并解除锁；“放弃修订”会丢弃工作树并解除锁。你不得宣称自己已经应用或放弃修订。
 - 每个完整工具响应按调用顺序结算。成功调用留下逐文件 before-image，可以由玩家单独回滚；失败调用不会撤销同一响应内其他成功调用。
 - 修改既有文件前必须完整读取。list/search cursor 和 read 授权只属于产生它们的工作树 revision；工作树发生任何手动、AI 或回滚写入后，继续修改前必须重新读取。
-- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。可以创建新状态文档；既有状态文档不能删除或移动，因为 Authority 保留其稳定身份。
+- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。${tabletop ? "control/gameplay.json 记录世界的玩法模式与判定方案，修订中只能保持不变。" : ""}可以创建新状态文档；既有状态文档不能删除或移动，因为 Authority 保留其稳定身份。
 - 对话跨越“应用”或“放弃”继续时，Runtime 会明确宣布一个新修订 epoch。此前读取授权全部失效；先重新读取新世界，再继续修改。`
         : `# Runtime world-revision conversation contract
 
@@ -102,11 +105,12 @@ export function worldRevisionRuntimeContract(locale) {
 - Tools change the unapplied worktree. Only the player can Apply the complete tree to world state/control and unlock it, or Discard the tree and unlock it. Never claim that you applied or discarded the revision yourself.
 - Calls in each complete tool response settle in order. Every successful call retains per-file before-images for selective rollback; a failed sibling does not undo successful calls.
 - Completely read an existing file before changing it. List/search cursors and read authorization belong only to the worktree revision that produced them. Re-read after any manual, AI, or rollback write.
-- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. New state documents are allowed; existing state documents cannot be deleted or moved because Authority retains their stable identity.
+- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. ${tabletop ? "control/gameplay.json records the world's gameplay mode and resolution scheme; a revision must leave both unchanged. " : ""}New state documents are allowed; existing state documents cannot be deleted or moved because Authority retains their stable identity.
 - When a conversation continues after Apply or Discard, Runtime announces a new revision epoch and invalidates every prior read authorization. Re-read the new world before editing.`;
 }
 export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
     const diagnostics = [];
+    diagnostics.push(...gameplayDiagnostics(immutableBaseFiles, files));
     const paths = new Set();
     for (const file of files) {
         if (paths.has(file.path))
@@ -188,6 +192,30 @@ export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
         diagnostics,
     };
 }
+/** A malformed gameplay file is reported by content inspection, not as a scheme change. */
+function gameplayDiagnostics(immutableBaseFiles, files) {
+    try {
+        readGameplay(files);
+    }
+    catch {
+        return [];
+    }
+    try {
+        assertSameGameplay(immutableBaseFiles, files);
+        return [];
+    }
+    catch (error) {
+        return [
+            {
+                code: "gameplay_change_forbidden",
+                path: gameplayPath,
+                message: error instanceof Error
+                    ? error.message
+                    : "World gameplay mode and resolution scheme are fixed",
+            },
+        ];
+    }
+}
 export function assertUsableWorldRevisionFiles(files, immutableBaseFiles) {
     const inspection = inspectWorldRevisionFiles(files, immutableBaseFiles);
     if (inspection.status !== "usable")
@@ -370,7 +398,8 @@ function mapSchema(schema) {
 function isWritableWorldRevisionPath(path) {
     if (/^state\/.+\.(?:ya?ml|md)$/u.test(path))
         return true;
-    return (isPackageFollowupControlPath(path) ||
+    return (path === gameplayPath ||
+        isPackageFollowupControlPath(path) ||
         path === "control/frame.yaml" ||
         path === "control/player-views.yaml" ||
         /^control\/blocks\/.+\.md$/u.test(path));

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

@@ -233,16 +233,18 @@ export class WorldRevisionSession {
         const worlds = await this.#worlds.listWorlds();
         const playPreset = await this.#bindPlayPreset();
         const locale = this.#locale();
+        const gameplay = await this.#worlds.gameplay(worldId);
         const bootstrap = this.#compiler.compileWorldRevision({
             ...(epoch === null
                 ? {}
                 : { epoch: { id: epoch.epochId, baseHead: epoch.baseHead } }),
             worldTitle: worlds.find((world) => world.worldId === worldId)?.title ?? worldId,
-            runtimeContract: worldRevisionRuntimeContract(locale),
+            gameplay,
+            runtimeContract: worldRevisionRuntimeContract(locale, gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding: modelBinding,
-            tools: worldRevisionToolDefinitions(locale),
+            tools: worldRevisionToolDefinitions(locale, gameplay),
         });
         return { bootstrap, playPreset };
     }
@@ -253,19 +255,21 @@ export class WorldRevisionSession {
         return this.#mutate(async () => this.#view(await this.#recoverIfNeeded(await this.#store.readSession(sessionId))));
     }
     async #create(worldId, epoch, creationRequestId) {
-        const [host, playPreset, worlds] = await Promise.all([
+        const [host, playPreset, worlds, gameplay] = await Promise.all([
             this.#bindModelHost(),
             this.#bindPlayPreset(),
             this.#worlds.listWorlds(),
+            this.#worlds.gameplay(worldId),
         ]);
         const worldTitle = worlds.find((world) => world.worldId === worldId)?.title ?? worldId;
         const locale = this.#locale();
         const modelBinding = host.binding();
-        const tools = worldRevisionToolDefinitions(locale);
+        const tools = worldRevisionToolDefinitions(locale, gameplay);
         const bootstrap = this.#compiler.compileWorldRevision({
             epoch: { id: epoch.epochId, baseHead: epoch.baseHead },
             worldTitle,
-            runtimeContract: worldRevisionRuntimeContract(locale),
+            gameplay,
+            runtimeContract: worldRevisionRuntimeContract(locale, gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding,

package/dist/node/server/ConversationStream.js

@@ -68,6 +68,8 @@ export function registerConversationStream(server, runtime) {
                 }
             }
             catch (error) {
+                request.log.error({ err: error, conversationTarget: target }, "conversation observation failed");
+                await runtime.recordConversationFailure?.(target, error);
                 write(`event: failure\ndata: ${JSON.stringify({ message: error instanceof Error ? error.message : "Conversation observation failed" })}\n\n`);
                 stream.end();
                 cleanup();

package/dist/node/server/mobile.js

@@ -0,0 +1,20 @@
+import { resolveAppPaths } from "../runtime/config/appPaths.js";
+import { parseWebPort, startWebServer } from "./startWebServer.js";
+// Mobile entry: started inside the Android app's Node runtime. The native shell
+// owns the process lifecycle, so this module never registers signal handlers and
+// never calls process.exit(); a startup failure rejects and the native side reads
+// stderr.
+const staticRoot = process.env.NARRAEON_STATIC_ROOT?.trim();
+if (!staticRoot)
+    throw new Error("NARRAEON_STATIC_ROOT is required for the mobile entry");
+const port = parseWebPort(process.env.NARRAEON_PORT);
+const paths = resolveAppPaths(process.env);
+const server = await startWebServer({
+    paths,
+    staticRoot,
+    host: "127.0.0.1",
+    port,
+});
+const address = server.server.address();
+const listeningPort = typeof address === "object" && address !== null ? address.port : port;
+process.stdout.write(`NARRAEON_READY ${listeningPort}\n`);

package/dist/node/server/startWebServer.js

@@ -1,22 +1,29 @@
+import { acquireDataRootLock } from "../runtime/config/dataRootLock.js";
 import { createRuntime } from "./createRuntime.js";
 import { createServer } from "./createServer.js";
 export const defaultWebPort = 4317;
 export const defaultWebHost = "127.0.0.1";
 export const containerWebHost = "0.0.0.0";
 export async function startWebServer(input) {
-    const runtime = await createRuntime(input.paths);
-    const server = await createServer({
-        runtime,
-        staticRoot: input.staticRoot,
-        port: input.port,
-        ...(input.logger === undefined ? {} : { logger: input.logger }),
-    });
+    const lock = await acquireDataRootLock(input.paths.dataRoot);
+    let server;
     try {
+        const runtime = await createRuntime(input.paths);
+        server = await createServer({
+            runtime,
+            staticRoot: input.staticRoot,
+            port: input.port,
+            ...(input.logger === undefined ? {} : { logger: input.logger }),
+        });
+        server.addHook("onClose", () => lock.release());
         await server.listen({ host: input.host, port: input.port });
         return server;
     }
     catch (error) {
-        await server.close().catch(() => undefined);
+        if (server !== undefined)
+            await server.close().catch(() => undefined);
+        else
+            await lock.release();
         throw error;
     }
 }

package/dist/node/shared/ordered-author-prompts.js

@@ -1,4 +1,5 @@
 import { defaultSettingImprovementPromptForLocale } from "./default-setting-improvement-prompt.js";
+import { tabletopAuthorBody } from "./tabletop-guidance.js";
 /** Authoring uses the same permissions as play, with target-specific dynamic references. */
 export function builtinAuthorPrompts(locale) {
     const zh = locale === "zh-CN";
@@ -17,6 +18,13 @@ export function builtinAuthorPrompts(locale) {
             required: false,
             body: defaultSettingImprovementPromptForLocale(locale),
         },
+        {
+            id: "author.tabletop",
+            name: zh ? "跑团创作建议" : "Tabletop authoring guidance",
+            required: false,
+            body: tabletopAuthorBody(locale),
+            gameplay: "tabletop",
+        },
         {
             id: "author.target",
             name: zh

package/dist/node/shared/ordered-play-prompts.js

@@ -1,9 +1,25 @@
 import { historyUseGuidance } from "./history-use-guidance.js";
 import { defaultNarrationPromptForLocale } from "./default-play-prompts.js";
 import { defaultPresetHostFilesForLocale } from "./default-preset-host.js";
+import { tabletopPlayBody } from "./tabletop-guidance.js";
 export function isPromptMessageRole(value) {
     return value === "system" || value === "user" || value === "assistant";
 }
+/**
+ * Unscoped prompts always apply. A scoped prompt applies only when the compiled
+ * world or package is tabletop, so fiction requests never see it.
+ */
+export function promptScopeApplies(scope, gameplay) {
+    return scope === undefined || gameplay.mode === "tabletop";
+}
+/** The scope of an ordered entry: a user entry's own scope or its builtin's. */
+export function orderedPromptScope(entry, catalog) {
+    if (entry.kind === "user")
+        return entry.gameplay;
+    if (entry.kind === "builtin")
+        return catalog.find((item) => item.id === entry.builtin)?.gameplay;
+    return undefined;
+}
 /** Application-owned references. Persist references; freeze resolved text in requests. */
 export function builtinPlayPrompts(locale) {
     const zh = locale === "zh-CN";
@@ -67,6 +83,13 @@ ${historyUseGuidance(locale)}`,
             body,
             required: false,
         })),
+        {
+            id: "play.tabletop",
+            name: zh ? "跑团主持" : "Tabletop GM",
+            body: tabletopPlayBody(locale),
+            required: false,
+            gameplay: "tabletop",
+        },
     ];
 }
 export function defaultOrderedPlayPrompts() {