narraeon 0.5.7 → 0.6.1

package/README.md

@@ -144,6 +144,13 @@ English is the default interface language. Switching to Simplified Chinese updat
 
 Existing content packages, worlds, imported presets, copied presets, and user-edited prompt files are not translated or rewritten automatically.
 
+## Android
+
+An experimental Android app runs the same backend inside the app process: a
+foreground service starts the embedded Node runtime, and a WebView opens
+`127.0.0.1:4317`. It supports `arm64-v8a` devices only. Build steps and the
+runtime layout are in [android/README.md](android/README.md).
+
 ## Local data and privacy
 
 Narraeon uses the operating system's standard per-user application directories. To isolate an instance or choose explicit locations, set these variables before startup:
@@ -163,6 +170,12 @@ By default, the browser talks only to the same-machine Runtime. Local-first does
 
 When a provider, response-format, Runtime-tool, or candidate-check error occurs, Narraeon creates a JSONL incident under `NARRAEON_LOG_ROOT/ai-failures`. It preserves the raw provider exchange and later recovery attempts, including reasoning or thinking actually returned by the provider. It does not invent hidden reasoning or record API keys and request headers. The files can still contain private prompts, world content, tool arguments, and provider-returned reasoning, so treat the log directory as sensitive.
 
+Every Runtime request that fails, every play call that ends interrupted, and every failed live conversation sync is also appended to `NARRAEON_LOG_ROOT/runtime-errors/<UTC date>.jsonl` with the request type, its identifiers (world, context, event, and operation IDs), and the error message, code, stack, and cause chain. Player and world text from the request is not recorded. Include the matching line when reporting a bug.
+
+## Upgrading worlds
+
+Worlds written by v0.3.0 through v0.6.0 upgrade automatically the first time a current version opens them. Worlds written by v0.2.0 or earlier are not upgraded directly: open each one once with v0.3.0–v0.6.0, then open it with the current version. A world that cannot be upgraded is shown as unavailable and is not modified.
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -136,6 +136,10 @@ AI 设定完善只作用于内容包候选。在“先生成计划”的路径
 
 已有内容包、世界、导入预设、复制预设和用户编辑过的提示文件不会被自动翻译或重写。
 
+## Android
+
+实验性的 Android 应用在 App 进程内运行同一套后端：前台服务启动内嵌的 Node 运行时，WebView 打开 `127.0.0.1:4317`。目前只支持 `arm64-v8a` 设备。构建步骤与运行时目录结构见 [android/README.md](android/README.md)。
+
 ## 本地数据与隐私
 
 Narraeon 默认使用当前操作系统的标准用户应用目录。如果要隔离一份独立实例，或者自行指定存放位置，可在启动前设置：
@@ -153,6 +157,12 @@ Narraeon 默认使用当前操作系统的标准用户应用目录。如果要
 
 发生 Provider、响应格式、Runtime 工具或候选检查错误时，Narraeon 会在 `NARRAEON_LOG_ROOT/ai-failures` 下创建 JSONL 事故记录。它会保存原始 Provider 交换和后续恢复尝试，包括 Provider 真实返回的 reasoning／thinking。它不会伪造隐藏思考，也不会记录 API Key 和请求 header。不过日志仍可能包含私密提示词、世界内容、工具参数和 Provider 返回的思考，因此应当把该目录视为敏感数据。
 
+每个失败的 Runtime 请求、每次以中断结束的游玩调用、每次失败的对话实时同步，也会追加到 `NARRAEON_LOG_ROOT/runtime-errors/<UTC 日期>.jsonl`，记录请求类型、请求中的标识（世界、上下文、事件和操作 ID）以及错误信息、错误码、调用栈和 cause 链，不记录请求里的玩家原文和世界内容。反馈问题时附上对应的那一行即可。
+
+## 升级世界
+
+由 v0.3.0 至 v0.6.0 创建的世界会在当前版本第一次打开时自动升级。由 v0.2.0 及更早版本创建的世界不再直接升级：先用 v0.3.0–v0.6.0 各打开一次，再用当前版本打开。无法升级的世界会显示为不可打开，并且不会被修改。
+
 ## 仓库开发
 
 ```bash

package/dist/node/protocol/gameplay.js

@@ -0,0 +1,69 @@
+export const resolutionSchemes = ["d20", "d100", "bag"];
+export const fictionGameplay = { mode: "interactive-fiction" };
+export const gameplayPath = "control/gameplay.json";
+const gameplayFormat = "narraeon.gameplay/v1";
+export function parseGameplay(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("Invalid gameplay choice / 玩法选择无效");
+    const record = value;
+    if (record.mode === "interactive-fiction" && Object.keys(record).length === 1)
+        return { mode: "interactive-fiction" };
+    if (record.mode === "tabletop" &&
+        Object.keys(record).every((key) => key === "mode" || key === "scheme") &&
+        resolutionSchemes.some((scheme) => scheme === record.scheme))
+        return { mode: "tabletop", scheme: record.scheme };
+    throw new Error("Unknown gameplay type or resolution scheme / 未知的玩法类型或判定方案");
+}
+/** A missing file is interactive fiction, so existing packages need no migration. */
+export function readGameplay(files) {
+    const matches = files.filter((file) => file.path.toLowerCase() === gameplayPath);
+    if (matches.length === 0)
+        return { ...fictionGameplay };
+    const file = matches[0];
+    if (matches.length !== 1 ||
+        file.path !== gameplayPath ||
+        file.encoding !== undefined)
+        throw new Error("Gameplay identity must be canonical UTF-8 control/gameplay.json / 玩法身份必须是规范的 UTF-8 control/gameplay.json");
+    let value;
+    try {
+        value = JSON.parse(file.contents);
+    }
+    catch (error) {
+        throw new Error("Gameplay identity must be valid JSON / 玩法文件必须是合法 JSON", { cause: error });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("Invalid gameplay identity / 玩法文件无效");
+    const { format, ...gameplay } = value;
+    if (format !== gameplayFormat)
+        throw new Error("Unknown gameplay format / 未知的玩法文件格式");
+    return parseGameplay(gameplay);
+}
+export function gameplayFile(gameplay) {
+    return {
+        path: gameplayPath,
+        contents: `${JSON.stringify({ format: gameplayFormat, ...parseGameplay(gameplay) }, null, 2)}\n`,
+    };
+}
+/** Content authoring may change the resolution scheme but never the gameplay mode. */
+export function assertSameGameplayMode(before, after) {
+    if (readGameplay(before).mode !== readGameplay(after).mode)
+        throw new Error("Gameplay mode is fixed / 玩法模式不能在互动式小说与跑团之间切换");
+}
+/** A world keeps both its gameplay mode and its resolution scheme. */
+export function assertSameGameplay(before, after) {
+    if (gameplayKey(readGameplay(before)) !== gameplayKey(readGameplay(after)))
+        throw new Error("Gameplay mode and resolution scheme are fixed / 玩法模式与判定方案固定，不能修改");
+}
+export function gameplayLabel(gameplay, locale) {
+    if (gameplay.mode !== "tabletop")
+        return locale === "zh-CN" ? "互动式小说" : "Interactive fiction";
+    const scheme = gameplay.scheme === "bag"
+        ? locale === "zh-CN"
+            ? "混乱袋"
+            : "Chaos bag"
+        : gameplay.scheme;
+    return locale === "zh-CN" ? `跑团 · ${scheme}` : `Tabletop · ${scheme}`;
+}
+function gameplayKey(gameplay) {
+    return gameplay.mode === "tabletop" ? gameplay.scheme : gameplay.mode;
+}

package/dist/node/protocol/resolution.js

@@ -0,0 +1,274 @@
+/**
+ * Structured mechanical receipts for tabletop resolution tools.
+ *
+ * Receipts store numbers and identifiers only. Localized prose is rendered by
+ * Runtime for the model and by the UI from these fields, never stored as text.
+ */
+/** Shared Narraeon v1 rules; the engine and the receipt validator both use them. */
+export function d20Outcome(selected, total, difficulty) {
+    if (selected === 20)
+        return "critical_success";
+    if (selected === 1)
+        return "critical_failure";
+    return total >= difficulty ? "success" : "failure";
+}
+export function arithmeticTotal(operation, left, right) {
+    switch (operation) {
+        case "add":
+            return left + right;
+        case "subtract":
+            return left - right;
+        case "multiply":
+            return left * right;
+        case "divide":
+            return left / right;
+    }
+}
+export function percentileCandidate(tens, units) {
+    return tens * 10 + units || 100;
+}
+export function d100Outcome(selected, target) {
+    if (selected === 1)
+        return "critical_success";
+    if (selected === 100)
+        return "critical_failure";
+    return selected <= target ? "success" : "failure";
+}
+const maximumMagnitude = 1_000_000;
+const maximumGoalLength = 1000;
+const maximumLabelLength = 80;
+const maximumBagTokens = 100;
+const outcomes = [
+    "success",
+    "failure",
+    "critical_success",
+    "critical_failure",
+];
+const criticalOutcomes = [
+    "critical_success",
+    "critical_failure",
+];
+const operations = ["add", "subtract", "multiply", "divide"];
+const modes = ["normal", "advantage", "disadvantage"];
+/** Strict structural and arithmetic validation for a persisted or received receipt. */
+export function isResolutionReceipt(value) {
+    if (!isRecord(value))
+        return false;
+    switch (value.kind) {
+        case "d20":
+            return isD20Receipt(value);
+        case "d100":
+            return isD100Receipt(value);
+        case "bag":
+            return isBagReceipt(value);
+        case "dice":
+            return isDiceReceipt(value);
+        case "arithmetic":
+            return isArithmeticReceipt(value);
+        default:
+            return false;
+    }
+}
+function isD20Receipt(value) {
+    if (!hasShape(value, [
+        "kind",
+        "goal",
+        "modifier",
+        "difficulty",
+        "mode",
+        "dice",
+        "selected",
+        "total",
+        "margin",
+        "outcome",
+    ], []) ||
+        !isGoal(value.goal) ||
+        !isInteger(value.modifier, -maximumMagnitude, maximumMagnitude) ||
+        !isInteger(value.difficulty, -maximumMagnitude, maximumMagnitude) ||
+        typeof value.mode !== "string" ||
+        !modes.includes(value.mode) ||
+        !Array.isArray(value.dice) ||
+        !value.dice.every((die) => isInteger(die, 1, 20)) ||
+        value.dice.length !== (value.mode === "normal" ? 1 : 2) ||
+        !isOutcome(value.outcome))
+        return false;
+    const dice = value.dice;
+    const selected = value.mode === "disadvantage" ? Math.min(...dice) : Math.max(...dice);
+    const modifier = value.modifier;
+    const difficulty = value.difficulty;
+    const total = selected + modifier;
+    return (value.selected === selected &&
+        value.total === total &&
+        value.margin === total - difficulty &&
+        value.outcome === d20Outcome(selected, total, difficulty));
+}
+function isD100Receipt(value) {
+    if (!hasShape(value, [
+        "kind",
+        "goal",
+        "target",
+        "bonusDice",
+        "penaltyDice",
+        "units",
+        "tens",
+        "candidates",
+        "selected",
+        "margin",
+        "outcome",
+    ], []) ||
+        !isGoal(value.goal) ||
+        !isInteger(value.target, 0, 100) ||
+        !isInteger(value.bonusDice, 0, 2) ||
+        !isInteger(value.penaltyDice, 0, 2) ||
+        !isInteger(value.units, 0, 9) ||
+        !Array.isArray(value.tens) ||
+        !value.tens.every((ten) => isInteger(ten, 0, 9)) ||
+        !Array.isArray(value.candidates) ||
+        !isOutcome(value.outcome))
+        return false;
+    const bonus = value.bonusDice;
+    const penalty = value.penaltyDice;
+    const units = value.units;
+    const tens = value.tens;
+    const candidates = value.candidates;
+    if (tens.length !== Math.abs(bonus - penalty) + 1)
+        return false;
+    if (candidates.length !== tens.length)
+        return false;
+    const expected = tens.map((ten) => percentileCandidate(ten, units));
+    if (!candidates.every((item, index) => item === expected[index]))
+        return false;
+    const selected = bonus < penalty ? Math.max(...expected) : Math.min(...expected);
+    const target = value.target;
+    return (value.selected === selected &&
+        value.margin === target - selected &&
+        value.outcome === d100Outcome(selected, target));
+}
+function isBagReceipt(value) {
+    if (!hasShape(value, [
+        "kind",
+        "goal",
+        "value",
+        "difficulty",
+        "defaultBag",
+        "tokens",
+        "drawn",
+        "outcome",
+    ], ["total", "margin"]) ||
+        !isGoal(value.goal) ||
+        !isNumber(value.value) ||
+        !isNumber(value.difficulty) ||
+        typeof value.defaultBag !== "boolean" ||
+        !Array.isArray(value.tokens) ||
+        value.tokens.length < 1 ||
+        value.tokens.length > maximumBagTokens ||
+        !value.tokens.every(isBagToken) ||
+        !isOutcome(value.outcome))
+        return false;
+    const tokens = value.tokens;
+    if (new Set(tokens.map((token) => token.label)).size !== tokens.length)
+        return false;
+    if (!isBagDraw(value.drawn))
+        return false;
+    const drawn = value.drawn;
+    const token = tokens.find((item) => item.label === drawn.label);
+    if (token === undefined ||
+        token.modifier !== drawn.modifier ||
+        token.outcome !== drawn.outcome)
+        return false;
+    if (drawn.outcome !== undefined)
+        return (value.total === undefined &&
+            value.margin === undefined &&
+            value.outcome === drawn.outcome);
+    if (drawn.modifier === undefined ||
+        !isNumber(value.total) ||
+        !isNumber(value.margin))
+        return false;
+    const difficulty = value.difficulty;
+    const total = value.value + drawn.modifier;
+    return (value.total === total &&
+        value.margin === total - difficulty &&
+        value.outcome === (total >= difficulty ? "success" : "failure"));
+}
+function isDiceReceipt(value) {
+    if (!hasShape(value, ["kind", "goal", "count", "sides", "modifier", "dice", "total"], []) ||
+        !isGoal(value.goal) ||
+        !isInteger(value.count, 1, 100) ||
+        !isInteger(value.sides, 2, 1000) ||
+        !isNumber(value.modifier) ||
+        !Array.isArray(value.dice) ||
+        value.dice.length !== value.count ||
+        !value.dice.every((die) => isInteger(die, 1, value.sides)))
+        return false;
+    const dice = value.dice;
+    return value.total === dice.reduce((sum, die) => sum + die, value.modifier);
+}
+function isArithmeticReceipt(value) {
+    if (!hasShape(value, ["kind", "goal", "left", "right", "operation", "total"], []) ||
+        !isGoal(value.goal) ||
+        !isNumber(value.left) ||
+        !isNumber(value.right) ||
+        typeof value.operation !== "string" ||
+        !operations.includes(value.operation))
+        return false;
+    const left = value.left;
+    const right = value.right;
+    if (value.operation === "divide" && right === 0)
+        return false;
+    const total = arithmeticTotal(value.operation, left, right);
+    return Number.isFinite(total) && value.total === total;
+}
+function isBagToken(value) {
+    return (isRecord(value) &&
+        hasShape(value, ["label", "count"], ["modifier", "outcome"]) &&
+        isLabel(value.label) &&
+        isInteger(value.count, 1, 100) &&
+        exactlyOneOf(value) &&
+        (value.modifier === undefined || isNumber(value.modifier)) &&
+        (value.outcome === undefined || isCriticalOutcome(value.outcome)));
+}
+function isBagDraw(value) {
+    return (isRecord(value) &&
+        hasShape(value, ["label"], ["modifier", "outcome"]) &&
+        isLabel(value.label) &&
+        exactlyOneOf(value) &&
+        (value.modifier === undefined || isNumber(value.modifier)) &&
+        (value.outcome === undefined || isCriticalOutcome(value.outcome)));
+}
+function exactlyOneOf(value) {
+    return (value.modifier === undefined) !== (value.outcome === undefined);
+}
+function hasShape(value, required, optional) {
+    return (required.every((key) => value[key] !== undefined) &&
+        Object.entries(value).every(([key, item]) => item !== undefined &&
+            (required.includes(key) || optional.includes(key))));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNumber(value) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        Math.abs(value) <= maximumMagnitude);
+}
+function isInteger(value, minimum, maximum) {
+    return (Number.isSafeInteger(value) &&
+        value >= minimum &&
+        value <= maximum);
+}
+function isGoal(value) {
+    return (typeof value === "string" &&
+        /\S/.test(value) &&
+        Array.from(value).length <= maximumGoalLength);
+}
+function isLabel(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        Array.from(value).length <= maximumLabelLength);
+}
+function isOutcome(value) {
+    return typeof value === "string" && outcomes.includes(value);
+}
+function isCriticalOutcome(value) {
+    return typeof value === "string" && criticalOutcomes.includes(value);
+}

package/dist/node/protocol/v1.js

@@ -1,3 +1,4 @@
+import { parseGameplay, resolutionSchemes, } from "./gameplay.js";
 import { isAppReadingPreferences, } from "./appPreferences.js";
 import { maxPortableContentArchiveBase64Characters } from "./contentTree.js";
 export const v1Protocol = "narraeon.runtime/v1";
@@ -34,6 +35,7 @@ const requiredFields = {
     "content.scripts.set": { packageId: "string", enabled: "boolean" },
     "world.package-scripts.read": { worldId: "string" },
     "world.package-scripts.set": { worldId: "string", enabled: "boolean" },
+    "content.gameplay.set": { packageId: "string", scheme: "string" },
     "content.read": { packageId: "string" },
     "content.replace": { packageId: "string", files: "array" },
     "content.copy": { packageId: "string" },
@@ -96,7 +98,6 @@ const requiredFields = {
     "artifacts.read": { worldId: "string" },
     "artifacts.debug": { worldId: "string" },
     "world.creation-outcome": { operationId: "string" },
-    "world.repair-materialization": { worldId: "string" },
     "world.control-draft.save": { worldId: "string", files: "array" },
     "world.control-draft.preview": { worldId: "string" },
     "world.control-draft.apply": { worldId: "string" },
@@ -235,6 +236,18 @@ function validateRequestFields(request) {
             !isAppReadingPreferences(request.reading))
             throw new V1ProtocolError("invalid_request", "preferences.save.reading is invalid");
     }
+    if (request.type === "content.create" && request.gameplay !== undefined) {
+        try {
+            parseGameplay(request.gameplay);
+        }
+        catch (error) {
+            throw new V1ProtocolError("invalid_request", "content.create.gameplay is invalid", { cause: error });
+        }
+    }
+    if (request.type === "content.gameplay.set") {
+        if (!resolutionSchemes.some((scheme) => scheme === request.scheme))
+            throw new V1ProtocolError("invalid_request", "content.gameplay.set.scheme is invalid");
+    }
     if (request.type === "content.import") {
         const archiveBase64 = request.archiveBase64;
         if (archiveBase64.length > maxPortableContentArchiveBase64Characters ||
@@ -387,6 +400,7 @@ const requestTypes = new Set([
     "model.delete",
     "model.models",
     "content.create",
+    "content.gameplay.set",
     "content.create-sample",
     "content.scripts.read",
     "content.scripts.set",
@@ -431,7 +445,6 @@ const requestTypes = new Set([
     "artifacts.read",
     "artifacts.debug",
     "world.creation-outcome",
-    "world.repair-materialization",
     "world.control-draft.save",
     "world.control-draft.preview",
     "world.control-draft.apply",

package/dist/node/runtime/FileNativeExclusiveLink.js

@@ -0,0 +1,39 @@
+import { constants } from "node:fs";
+import { copyFile, link } from "node:fs/promises";
+// Error codes that mean "hard links are unavailable here". Android app directories
+// return EACCES for link(), so that code is included.
+const linkFallbackCodes = new Set(["EPERM", "EACCES", "ENOTSUP", "EXDEV"]);
+/**
+ * Creates target as a new name for source, failing with EEXIST when target already
+ * exists. Uses a hard link where the filesystem allows it. Otherwise falls back to an
+ * exclusive byte copy, which also fails with EEXIST.
+ *
+ * Creation is exclusive in both paths. Content visibility is atomic only on the
+ * hard-link path: on the copy path a concurrent reader could in principle see a
+ * partially written target. This is acceptable under ADR-0044's single-process and
+ * per-world serial assumptions, because callers hold a process-local lock and
+ * readers only open targets after the creating call returns.
+ */
+export async function linkExclusive(source, target) {
+    const injectedErrorCode = process.env.NARRAEON_INTERNAL_TEST_LINK_ERROR_CODE;
+    try {
+        if (injectedErrorCode !== undefined) {
+            const error = new Error(`${injectedErrorCode}: injected hard link failure`);
+            error.code = injectedErrorCode;
+            throw error;
+        }
+        await link(source, target);
+    }
+    catch (error) {
+        if (!isFallbackError(error))
+            throw error;
+        await copyFile(source, target, constants.COPYFILE_EXCL);
+    }
+}
+function isFallbackError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        linkFallbackCodes.has(error.code));
+}

package/dist/node/runtime/RuntimeErrorLog.js

@@ -0,0 +1,95 @@
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+export const runtimeErrorLogFormat = "narraeon.runtime-error-log/v1";
+/**
+ * Append-only diagnostics for Runtime requests that fail or leave a play call
+ * interrupted. One JSONL file per UTC day; recording never changes the
+ * request's own outcome.
+ */
+export class FileNativeRuntimeErrorLog {
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    async recordRequestFailure(request, error) {
+        const [outer, ...causes] = describeErrorChain(error);
+        await this.#append({
+            kind: "request_failed",
+            request,
+            error: outer,
+            ...(causes.length === 0 ? {} : { causes }),
+        });
+    }
+    async recordPlayInterruption(request, failure) {
+        await this.#append({
+            kind: "play_interrupted",
+            request,
+            error: {
+                name: "PlayCallInterrupted",
+                message: failure.message,
+                ...(failure.kind === undefined ? {} : { code: failure.kind }),
+            },
+        });
+    }
+    async #append(input) {
+        try {
+            const recordedAt = new Date().toISOString();
+            const record = {
+                format: runtimeErrorLogFormat,
+                recordedAt,
+                kind: input.kind,
+                requestType: requestType(input.request),
+                request: requestIdentifiers(input.request),
+                error: input.error,
+                ...(input.causes === undefined ? {} : { causes: input.causes }),
+            };
+            await mkdir(this.#root, { recursive: true, mode: 0o700 });
+            await chmod(this.#root, 0o700);
+            const path = join(this.#root, `${recordedAt.slice(0, 10)}.jsonl`);
+            await appendFile(path, `${JSON.stringify(record)}\n`, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+            await chmod(path, 0o600);
+        }
+        catch {
+            // Diagnostics must never change Runtime request semantics.
+        }
+    }
+}
+function requestType(request) {
+    const type = request.type;
+    return typeof type === "string" ? type : "unknown";
+}
+function requestIdentifiers(request) {
+    const identifiers = {};
+    for (const [key, value] of Object.entries(request)) {
+        if (!/(?:Id|Head|^continuation|^context|^format|^limit)$/u.test(key))
+            continue;
+        if (typeof value === "string" || typeof value === "number")
+            identifiers[key] = value;
+    }
+    return identifiers;
+}
+function describeErrorChain(error) {
+    const chain = [];
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && !seen.has(current) && chain.length < 8) {
+        seen.add(current);
+        chain.push(describeError(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return chain;
+}
+function describeError(error) {
+    if (!(error instanceof Error))
+        return { name: "UnknownError", message: String(error) };
+    const code = error.code;
+    return {
+        name: error.name,
+        message: error.message,
+        ...(typeof code === "string" ? { code } : {}),
+        ...(error.stack === undefined ? {} : { stack: error.stack }),
+    };
+}