narraeon 0.5.6 → 0.6.0

package/README.md

@@ -163,6 +163,8 @@ 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.
+
 ## Development
 
 ```bash
@@ -178,7 +180,7 @@ TMPDIR=/tmp npm run test:package
 
 Project contracts and architecture:
 
-- [CONTEXT.md](CONTEXT.md) — domain vocabulary
+- [GLOSSARY.md](GLOSSARY.md) — domain vocabulary
 - [docs/product-foundation.md](docs/product-foundation.md) — current V1 product contract
 - [docs/adr/](docs/adr/) — architectural decisions
 

package/README.zh-CN.md

@@ -153,6 +153,8 @@ 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 链，不记录请求里的玩家原文和世界内容。反馈问题时附上对应的那一行即可。
+
 ## 仓库开发
 
 ```bash
@@ -168,7 +170,7 @@ TMPDIR=/tmp npm run test:package
 
 项目契约与架构文档：
 
-- [CONTEXT.md](CONTEXT.md) —— 领域词汇
+- [GLOSSARY.md](GLOSSARY.md) —— 领域词汇
 - [docs/product-foundation.md](docs/product-foundation.md) —— 当前 V1 产品契约
 - [docs/adr/](docs/adr/) —— 架构决策
 

package/dist/node/protocol/appPreferences.js

@@ -7,6 +7,7 @@ export const defaultAppReadingPreferences = {
     lineHeight: 1.7,
     letterSpacing: 0.01,
     measure: 48,
+    showTechnicalInfo: false,
 };
 export function isAppLocale(value) {
     return appLocales.includes(value);
@@ -15,12 +16,13 @@ export function isAppReadingPreferences(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const candidate = value;
-    return (Object.keys(candidate).length === 5 &&
+    return (Object.keys(candidate).length === 6 &&
         readingDensities.includes(candidate.density) &&
         isNumberInRange(candidate.fontSize, 15, 24) &&
         isNumberInRange(candidate.lineHeight, 1.4, 2.4) &&
         isNumberInRange(candidate.letterSpacing, 0, 0.12) &&
-        isNumberInRange(candidate.measure, 32, 72));
+        isNumberInRange(candidate.measure, 32, 72) &&
+        typeof candidate.showTechnicalInfo === "boolean");
 }
 function isNumberInRange(value, minimum, maximum) {
     return (typeof value === "number" &&

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/playFailure.js

@@ -0,0 +1,13 @@
+export const playFailureKinds = [
+    "outcome_unknown",
+    "context_limit",
+    "output_limit",
+    "context_unavailable",
+    "retryable",
+    "provider_error",
+    "other",
+    "configuration_mismatch",
+];
+export function isPlayFailureKind(value) {
+    return playFailureKinds.some((kind) => kind === value);
+}

package/dist/node/protocol/protagonistTemplates.js

@@ -0,0 +1,13 @@
+export function isProtagonistTemplateId(value) {
+    return (typeof value === "string" &&
+        /^template-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value));
+}
+export function isProtagonistTemplateContent(name, body) {
+    return (typeof name === "string" &&
+        name.trim().length > 0 &&
+        [...name].length <= 80 &&
+        !/[\r\n\u0085\u2028\u2029]/u.test(name) &&
+        typeof body === "string" &&
+        body.trim().length > 0 &&
+        new TextEncoder().encode(body).byteLength <= 16 * 1024);
+}

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,5 @@
+import { parseGameplay, resolutionSchemes, } from "./gameplay.js";
+import { isAppReadingPreferences, } from "./appPreferences.js";
 import { maxPortableContentArchiveBase64Characters } from "./contentTree.js";
 export const v1Protocol = "narraeon.runtime/v1";
 export class V1ProtocolError extends Error {
@@ -20,15 +22,20 @@ export function parseV1Envelope(value) {
 }
 const requiredFields = {
     "preferences.save": {},
+    "protagonist-templates.save": { name: "string", body: "string" },
+    "protagonist-templates.copy": { id: "string" },
+    "protagonist-templates.delete": { id: "string" },
     "model.save": { connection: "object" },
     "model.copy": { connectionId: "string", name: "string" },
     "model.select": { connectionId: "string" },
     "model.delete": { connectionId: "string" },
     "model.models": { provider: "string", baseUrl: "string" },
+    "content.create-sample": { locale: "string" },
     "content.scripts.read": { packageId: "string" },
     "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" },
@@ -82,8 +89,11 @@ const requiredFields = {
         packageId: "string",
         model: "object",
     },
+    "world.archive.export": { worldId: "string", operationId: "string" },
+    "world.archive.import": { operationId: "string", uploadId: "string" },
     "world.read": { worldId: "string" },
     "world.rename": { worldId: "string", name: "string" },
+    "world.story.export": { worldId: "string", format: "string" },
     "world.delete": { worldId: "string" },
     "artifacts.read": { worldId: "string" },
     "artifacts.debug": { worldId: "string" },
@@ -204,6 +214,14 @@ function validateRequestFields(request) {
         if (!valid || (kind === "string" && value === "" && !allowsEmptyString))
             throw new V1ProtocolError("invalid_request", `${String(request.type)}.${field} is invalid`);
     }
+    if (request.type === "world.story.export" &&
+        request.format !== "markdown" &&
+        request.format !== "text")
+        throw new V1ProtocolError("invalid_request", "world.story.export.format must be markdown or text");
+    if (request.type === "content.create-sample" &&
+        (Object.keys(request).some((key) => key !== "type" && key !== "locale") ||
+            (request.locale !== "en" && request.locale !== "zh-CN")))
+        throw new V1ProtocolError("invalid_request", "content.create-sample.locale must be en or zh-CN, with no extra fields");
     if (request.type === "world.extensions.set" &&
         !["on", "off", "default"].includes(String(request.value)))
         throw new V1ProtocolError("invalid_request", "Invalid world extension choice");
@@ -216,9 +234,21 @@ function validateRequestFields(request) {
             request.locale !== "zh-CN")
             throw new V1ProtocolError("invalid_request", "preferences.save.locale must be en or zh-CN");
         if (request.reading !== undefined &&
-            !isValidReadingPreferences(request.reading))
+            !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 ||
@@ -359,6 +389,10 @@ function validateRequestFields(request) {
 const requestTypes = new Set([
     "workspace.read",
     "preferences.read",
+    "protagonist-templates.read",
+    "protagonist-templates.save",
+    "protagonist-templates.copy",
+    "protagonist-templates.delete",
     "preferences.save",
     "model.read",
     "model.save",
@@ -367,6 +401,8 @@ const requestTypes = new Set([
     "model.delete",
     "model.models",
     "content.create",
+    "content.gameplay.set",
+    "content.create-sample",
     "content.scripts.read",
     "content.scripts.set",
     "world.package-scripts.read",
@@ -401,8 +437,11 @@ const requestTypes = new Set([
     "play.workbench.read",
     "prompt.preview",
     "world.create",
+    "world.archive.export",
+    "world.archive.import",
     "world.read",
     "world.rename",
+    "world.story.export",
     "world.delete",
     "artifacts.read",
     "artifacts.debug",
@@ -447,21 +486,3 @@ const requestTypes = new Set([
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isValidReadingPreferences(value) {
-    if (!isRecord(value))
-        return false;
-    return (Object.keys(value).length === 5 &&
-        (value.density === "compact" ||
-            value.density === "standard" ||
-            value.density === "relaxed") &&
-        isFiniteRange(value.fontSize, 15, 24) &&
-        isFiniteRange(value.lineHeight, 1.4, 2.4) &&
-        isFiniteRange(value.letterSpacing, 0, 0.12) &&
-        isFiniteRange(value.measure, 32, 72));
-}
-function isFiniteRange(value, minimum, maximum) {
-    return (typeof value === "number" &&
-        Number.isFinite(value) &&
-        value >= minimum &&
-        value <= maximum);
-}

package/dist/node/protocol/worldArchives.js

@@ -0,0 +1,7 @@
+export const worldArchiveFormat = "narraeon.world-archive/v1";
+export const worldArchiveLimits = {
+    archiveBytes: 1024 ** 3,
+    extractedBytes: 2 * 1024 ** 3,
+    entries: 200_000,
+    entryBytes: 256 * 1024 ** 2,
+};

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 }),
+    };
+}