@rpgm-tools/neo-angband-core 0.15.3 → 0.17.0

package/README.md

@@ -32,7 +32,7 @@ import { Rng, ENGINE_VERSION, PARITY_BASELINE } from "@rpgm-tools/neo-angband-co
 const rng = new Rng(1234);
 console.log(rng.damroll(3, 6), rng.damroll(3, 6), rng.damroll(3, 6)); // 9 13 8
 
-console.log(ENGINE_VERSION, PARITY_BASELINE); // 0.15.3 4.2.6
+console.log(ENGINE_VERSION, PARITY_BASELINE); // 0.17.0 4.2.6
 ```
 
 Two entry points:

package/dist/log.d.ts

@@ -0,0 +1,144 @@
+/**
+ * A log a player can hand you, and the rule that decides how much is in it.
+ *
+ * WHY THIS IS IN `core` WHEN THE ENGINE NEVER CALLS IT. It is not a parity
+ * module and nothing in the C corresponds to it - the honest reason is that
+ * `core` is the only package both the renderer and the Electron main process
+ * already depend on, and the alternative was two implementations of the same
+ * format. This project has been bitten by that shape before: two copies of a
+ * check, and only one of them learns. So it lives here, behind the `./log`
+ * subpath rather than in the barrel, next to `./host` - which is the same kind
+ * of thing, infrastructure the port needs and the original did not have.
+ *
+ * It does NO I/O and holds NO sinks of its own. Writing a line to a file is the
+ * main process's job and drawing one on a terminal is the renderer's; this
+ * module owns the level rule, the record, the ring, and the text - the four
+ * things that have to be identical on both sides of the IPC boundary or a log
+ * file becomes two interleaved formats.
+ *
+ * THE RING IS THE POINT, not the file. A player who hits a bug is asked for a
+ * report, and the report is "the last N things that happened" - which has to
+ * exist in memory already, because the interesting part is over by the time
+ * anybody presses a key.
+ */
+/**
+ * Four levels, and no `trace`.
+ *
+ * `debug` is already the level nobody ships; a fifth below it would only ever
+ * be reached by editing a constant, which is what a comment is for.
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/** Most severe first. Index is the rank, so the order here IS the ordering. */
+export declare const LOG_LEVELS: readonly LogLevel[];
+/** 0 for `error`, 3 for `debug`. -1 for anything that is not a level. */
+export declare function logLevelRank(level: string): number;
+export declare function isLogLevel(v: unknown): v is LogLevel;
+/** Would a log running at `active` record something logged at `of`? */
+export declare function logLevelAllows(active: LogLevel, of: LogLevel): boolean;
+/**
+ * How much this BUILD logs, decided by its own version rather than by a setting.
+ *
+ * A released build logs warnings and errors; a build somebody is testing logs
+ * what it is doing as well. The two states are already written down in the
+ * version string and nowhere else needs to agree:
+ *
+ *   `0.16.1-edge.2`  a per-commit build  -> info
+ *   `0.16.0`         a 0.x pre-release   -> info
+ *   `1.2.3`          a finished release  -> warn
+ *
+ * DELIBERATELY NOT THE UPDATE CHANNEL. The channel is a preference about which
+ * builds to accept next, stored in localStorage and changeable at any time; a
+ * player who installed a beta and then picked `stable` is still running the
+ * beta, and the log should still say so. Asking the version means the answer
+ * cannot drift from the thing it describes.
+ *
+ * While the project is 0.x this returns `info` for everything, which is correct
+ * and temporary: `stable` selects nothing before 1.0.0 either. Both facts stop
+ * being true on the same day, by themselves - see `defaultChannel`, which this
+ * mirrors and which `update.test.ts` ties it to.
+ */
+export declare function defaultLogLevel(version: string): LogLevel;
+/**
+ * One line of log, with its detail ALREADY rendered to text.
+ *
+ * Serialising at record time rather than at write time is what bounds the ring:
+ * a record holds a string, not a reference to a live game object that will have
+ * changed - or been mutated into a cycle - by the time anybody reads it. It also
+ * means a report cannot be the thing that throws while somebody is filing a bug.
+ */
+export interface LogRecord {
+    /** Epoch milliseconds. */
+    readonly at: number;
+    readonly level: LogLevel;
+    /** Where it came from: `update`, `mods`, `save`. Short and stable. */
+    readonly area: string;
+    readonly msg: string;
+    /** The extra detail, JSON-ish, or undefined when there was none. */
+    readonly data?: string;
+}
+/** Somewhere a line goes. Given the record and the text, so it need not reformat. */
+export type LogSink = (rec: LogRecord, line: string) => void;
+/** How many records the ring holds before the oldest is dropped. */
+export declare const LOG_RING_DEFAULT = 2000;
+/** Longest single message or detail string kept, in characters. */
+export declare const LOG_FIELD_MAX = 2000;
+/**
+ * JSON, but it cannot throw and it cannot run away.
+ *
+ * Everything a caller might hand this is in scope: a cycle (a game object
+ * pointing at the state that owns it), a BigInt (JSON.stringify throws on one),
+ * a 40,000-element array, a function, an Error (whose message and stack are the
+ * only interesting parts and neither is enumerable). A logger that throws while
+ * describing a failure replaces the failure with its own.
+ */
+export declare function describeValue(v: unknown, depth?: number): string;
+/**
+ * One line of the log file.
+ *
+ * Fixed-width level so the areas line up when a human reads a thousand of them,
+ * and the detail after a ` | ` so the message can be found by eye without the
+ * JSON in the way.
+ */
+export declare function formatLogLine(rec: LogRecord): string;
+/**
+ * A path with the user's home directory replaced by `~`.
+ *
+ * Called on the way into a REPORT, not on the way into the log file. The file
+ * lives on their machine and is theirs; the report is the thing they send to a
+ * stranger, and `C:\Users\firstname.lastname\...` is a real name in it. The
+ * comparison is case-insensitive because Windows paths are, and it is a plain
+ * substring so it catches the home directory wherever it appears in a line -
+ * inside a stack trace, inside a JSON blob - not only at the start.
+ */
+export declare function elideHome(text: string, home: string | undefined): string;
+export interface LogOptions {
+    /** Starting level. Callers pass `defaultLogLevel(ENGINE_VERSION)`. */
+    readonly level: LogLevel;
+    /** Records held in memory. */
+    readonly capacity?: number;
+    /** Injected so a test can assert a timestamp instead of tolerating one. */
+    readonly now?: () => number;
+}
+/** What the rest of the app holds. */
+export interface Log {
+    readonly level: LogLevel;
+    setLevel(level: LogLevel): void;
+    error(area: string, msg: string, data?: unknown): void;
+    warn(area: string, msg: string, data?: unknown): void;
+    info(area: string, msg: string, data?: unknown): void;
+    debug(area: string, msg: string, data?: unknown): void;
+    /** Add a destination. Returns the function that removes it again. */
+    addSink(sink: LogSink): () => void;
+    /** The ring, oldest first. */
+    recent(limit?: number): LogRecord[];
+    /**
+     * How many records the ring has thrown away.
+     *
+     * Reported on a report rather than kept quiet: "the last 2000 lines" and "the
+     * whole session" look identical in a text file, and the difference is whether
+     * the thing you are looking for could still be above the top.
+     */
+    dropped(): number;
+}
+export declare function createLog(opts: LogOptions): Log;
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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"}

package/dist/log.js

@@ -0,0 +1,273 @@
+/**
+ * A log a player can hand you, and the rule that decides how much is in it.
+ *
+ * WHY THIS IS IN `core` WHEN THE ENGINE NEVER CALLS IT. It is not a parity
+ * module and nothing in the C corresponds to it - the honest reason is that
+ * `core` is the only package both the renderer and the Electron main process
+ * already depend on, and the alternative was two implementations of the same
+ * format. This project has been bitten by that shape before: two copies of a
+ * check, and only one of them learns. So it lives here, behind the `./log`
+ * subpath rather than in the barrel, next to `./host` - which is the same kind
+ * of thing, infrastructure the port needs and the original did not have.
+ *
+ * It does NO I/O and holds NO sinks of its own. Writing a line to a file is the
+ * main process's job and drawing one on a terminal is the renderer's; this
+ * module owns the level rule, the record, the ring, and the text - the four
+ * things that have to be identical on both sides of the IPC boundary or a log
+ * file becomes two interleaved formats.
+ *
+ * THE RING IS THE POINT, not the file. A player who hits a bug is asked for a
+ * report, and the report is "the last N things that happened" - which has to
+ * exist in memory already, because the interesting part is over by the time
+ * anybody presses a key.
+ */
+/** Most severe first. Index is the rank, so the order here IS the ordering. */
+export const LOG_LEVELS = ["error", "warn", "info", "debug"];
+/** 0 for `error`, 3 for `debug`. -1 for anything that is not a level. */
+export function logLevelRank(level) {
+    return LOG_LEVELS.indexOf(level);
+}
+export function isLogLevel(v) {
+    return typeof v === "string" && logLevelRank(v) >= 0;
+}
+/** Would a log running at `active` record something logged at `of`? */
+export function logLevelAllows(active, of) {
+    return logLevelRank(of) <= logLevelRank(active);
+}
+/**
+ * How much this BUILD logs, decided by its own version rather than by a setting.
+ *
+ * A released build logs warnings and errors; a build somebody is testing logs
+ * what it is doing as well. The two states are already written down in the
+ * version string and nowhere else needs to agree:
+ *
+ *   `0.16.1-edge.2`  a per-commit build  -> info
+ *   `0.16.0`         a 0.x pre-release   -> info
+ *   `1.2.3`          a finished release  -> warn
+ *
+ * DELIBERATELY NOT THE UPDATE CHANNEL. The channel is a preference about which
+ * builds to accept next, stored in localStorage and changeable at any time; a
+ * player who installed a beta and then picked `stable` is still running the
+ * beta, and the log should still say so. Asking the version means the answer
+ * cannot drift from the thing it describes.
+ *
+ * While the project is 0.x this returns `info` for everything, which is correct
+ * and temporary: `stable` selects nothing before 1.0.0 either. Both facts stop
+ * being true on the same day, by themselves - see `defaultChannel`, which this
+ * mirrors and which `update.test.ts` ties it to.
+ */
+export function defaultLogLevel(version) {
+    if (version.includes("-edge."))
+        return "info";
+    return /^0\./u.test(version) ? "info" : "warn";
+}
+/** How many records the ring holds before the oldest is dropped. */
+export const LOG_RING_DEFAULT = 2000;
+/** Longest single message or detail string kept, in characters. */
+export const LOG_FIELD_MAX = 2000;
+/**
+ * JSON, but it cannot throw and it cannot run away.
+ *
+ * Everything a caller might hand this is in scope: a cycle (a game object
+ * pointing at the state that owns it), a BigInt (JSON.stringify throws on one),
+ * a 40,000-element array, a function, an Error (whose message and stack are the
+ * only interesting parts and neither is enumerable). A logger that throws while
+ * describing a failure replaces the failure with its own.
+ */
+export function describeValue(v, depth = 4) {
+    const seen = new Set();
+    const walk = (x, left) => {
+        if (x === null || typeof x !== "object") {
+            if (typeof x === "bigint")
+                return `${x.toString()}n`;
+            if (typeof x === "function")
+                return `[function ${x.name || "anonymous"}]`;
+            if (typeof x === "symbol")
+                return x.toString();
+            if (typeof x === "string" && x.length > LOG_FIELD_MAX) {
+                return `${x.slice(0, LOG_FIELD_MAX)}...[${String(x.length)} chars]`;
+            }
+            return x;
+        }
+        if (seen.has(x))
+            return "[circular]";
+        if (left <= 0)
+            return "[...]";
+        if (x instanceof Error) {
+            /* name/message/stack are not enumerable, so the generic branch below
+             * would render every Error as `{}` - which is the single most useless
+             * thing a log can say about a failure. */
+            const out = { name: x.name, message: x.message };
+            if (typeof x.stack === "string")
+                out["stack"] = x.stack.split("\n").slice(0, 8).join("\n");
+            if (x.cause !== undefined)
+                out["cause"] = walk(x.cause, left - 1);
+            return out;
+        }
+        seen.add(x);
+        try {
+            if (Array.isArray(x)) {
+                const head = x.slice(0, 50).map((e) => walk(e, left - 1));
+                return x.length > 50 ? [...head, `...[${String(x.length)} items]`] : head;
+            }
+            const out = {};
+            for (const [k, val] of Object.entries(x)) {
+                out[k] = walk(val, left - 1);
+            }
+            return out;
+        }
+        finally {
+            seen.delete(x);
+        }
+    };
+    try {
+        const text = JSON.stringify(walk(v, depth));
+        if (text === undefined)
+            return String(v);
+        return text.length > LOG_FIELD_MAX ? `${text.slice(0, LOG_FIELD_MAX)}...` : text;
+    }
+    catch {
+        /* Belt and braces: a getter that throws is reachable from Object.entries. */
+        return "[undescribable]";
+    }
+}
+/** `2026-08-02T13:06:09.123Z` - sortable, and the same in every timezone. */
+function stamp(at) {
+    try {
+        return new Date(at).toISOString();
+    }
+    catch {
+        /* A NaN or out-of-range timestamp must not cost the line it is attached to. */
+        return "????-??-??T??:??:??.???Z";
+    }
+}
+/**
+ * One line of the log file.
+ *
+ * Fixed-width level so the areas line up when a human reads a thousand of them,
+ * and the detail after a ` | ` so the message can be found by eye without the
+ * JSON in the way.
+ */
+export function formatLogLine(rec) {
+    const head = `${stamp(rec.at)} ${rec.level.toUpperCase().padEnd(5)} [${rec.area}] ${rec.msg}`;
+    return rec.data === undefined ? head : `${head} | ${rec.data}`;
+}
+/**
+ * A path with the user's home directory replaced by `~`.
+ *
+ * Called on the way into a REPORT, not on the way into the log file. The file
+ * lives on their machine and is theirs; the report is the thing they send to a
+ * stranger, and `C:\Users\firstname.lastname\...` is a real name in it. The
+ * comparison is case-insensitive because Windows paths are, and it is a plain
+ * substring so it catches the home directory wherever it appears in a line -
+ * inside a stack trace, inside a JSON blob - not only at the start.
+ */
+export function elideHome(text, home) {
+    const h = (home ?? "").replace(/[\\/]+$/u, "");
+    if (h.length < 4)
+        return text;
+    /*
+     * THREE SPELLINGS OF THE SAME PATH, and the third is the one that matters.
+     *
+     * A path reaches the log through `describeValue`, which JSON-encodes it - so
+     * on Windows it arrives with its backslashes DOUBLED, and neither of the two
+     * obvious forms matches a character of it. Checking only the raw and URL forms
+     * left every path this project actually logs untouched. It was caught by a
+     * test that used a realistic log line rather than a hand-written path, which
+     * is the only reason it was caught at all.
+     */
+    const forms = [
+        /* `{"path":"C:\\Users\\name\\..."}` - what describeValue produces. */
+        h.replace(/\\/gu, "\\\\"),
+        /* Raw, as node:path produces it. */
+        h,
+        /* A file:// URL in a stack trace, often in the same line as the above. */
+        h.replace(/\\/gu, "/"),
+    ];
+    let out = text;
+    /* Longest first, so the doubled form is taken before the single one can eat
+     * its leading segment and leave the rest looking like an unrelated path. */
+    for (const form of [...new Set(forms)].sort((a, b) => b.length - a.length)) {
+        const pattern = new RegExp(form.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), "giu");
+        out = out.replace(pattern, "~");
+    }
+    return out;
+}
+export function createLog(opts) {
+    const capacity = Math.max(1, opts.capacity ?? LOG_RING_DEFAULT);
+    const now = opts.now ?? (() => Date.now());
+    const ring = new Array(capacity);
+    let head = 0;
+    let count = 0;
+    let lost = 0;
+    let level = opts.level;
+    const sinks = new Set();
+    const write = (lvl, area, msg, data) => {
+        if (!logLevelAllows(level, lvl))
+            return;
+        const rec = {
+            at: now(),
+            level: lvl,
+            area,
+            msg: msg.length > LOG_FIELD_MAX ? `${msg.slice(0, LOG_FIELD_MAX)}...` : msg,
+            ...(data === undefined ? {} : { data: describeValue(data) }),
+        };
+        if (count === capacity)
+            lost++;
+        ring[head] = rec;
+        head = (head + 1) % capacity;
+        if (count < capacity)
+            count++;
+        const line = formatLogLine(rec);
+        for (const sink of sinks) {
+            try {
+                sink(rec, line);
+            }
+            catch {
+                /* A sink that throws - a full disk, a closed IPC channel - must not
+                 * take down the code that was only trying to say what it was doing,
+                 * and must not stop the OTHER sinks from getting the line. */
+            }
+        }
+    };
+    return {
+        get level() {
+            return level;
+        },
+        setLevel(next) {
+            level = next;
+        },
+        error: (a, m, d) => {
+            write("error", a, m, d);
+        },
+        warn: (a, m, d) => {
+            write("warn", a, m, d);
+        },
+        info: (a, m, d) => {
+            write("info", a, m, d);
+        },
+        debug: (a, m, d) => {
+            write("debug", a, m, d);
+        },
+        addSink(sink) {
+            sinks.add(sink);
+            return () => {
+                sinks.delete(sink);
+            };
+        },
+        recent(limit) {
+            const want = Math.max(0, Math.min(limit ?? count, count));
+            const out = [];
+            for (let i = count - want; i < count; i++) {
+                const rec = ring[(head - count + i + capacity * 2) % capacity];
+                if (rec)
+                    out.push(rec);
+            }
+            return out;
+        },
+        dropped() {
+            return lost;
+        },
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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"}

package/dist/mod/save-blocks.d.ts

@@ -128,7 +128,7 @@ export type OrphanStore = Record<string, OrphanEntry[]>;
  * core pack outright, and versionMap's versions are only ever used to key
  * quarantined MOD entities. An existing save keeps whatever it recorded.
  */
-export declare const CORE_PACK_VERSION = "0.15.3";
+export declare const CORE_PACK_VERSION = "0.17.0";
 /** A core-only manifest: the base game with no mods, deterministic. */
 export declare function coreOnlyManifest(): SaveManifest;
 /**

package/dist/version.d.ts

@@ -21,5 +21,5 @@ export declare const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export declare const ENGINE_VERSION = "0.15.3";
+export declare const ENGINE_VERSION = "0.17.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -21,5 +21,5 @@ export const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export const ENGINE_VERSION = "0.15.3";
+export const ENGINE_VERSION = "0.17.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgm-tools/neo-angband-core",
-  "version": "0.15.3",
+  "version": "0.17.0",
   "description": "Headless Neo Angband game engine: rules, world, entities, effects, generation",
   "license": "GPL-2.0-only",
   "author": "neostryder (RPGM Tools)",
@@ -34,6 +34,10 @@
       "types": "./dist/host/index.d.ts",
       "default": "./dist/host/index.js"
     },
+    "./log": {
+      "types": "./dist/log.d.ts",
+      "default": "./dist/log.js"
+    },
     "./package.json": "./package.json"
   },
   "//files": [

package/src/log.ts

@@ -0,0 +1,329 @@
+/**
+ * A log a player can hand you, and the rule that decides how much is in it.
+ *
+ * WHY THIS IS IN `core` WHEN THE ENGINE NEVER CALLS IT. It is not a parity
+ * module and nothing in the C corresponds to it - the honest reason is that
+ * `core` is the only package both the renderer and the Electron main process
+ * already depend on, and the alternative was two implementations of the same
+ * format. This project has been bitten by that shape before: two copies of a
+ * check, and only one of them learns. So it lives here, behind the `./log`
+ * subpath rather than in the barrel, next to `./host` - which is the same kind
+ * of thing, infrastructure the port needs and the original did not have.
+ *
+ * It does NO I/O and holds NO sinks of its own. Writing a line to a file is the
+ * main process's job and drawing one on a terminal is the renderer's; this
+ * module owns the level rule, the record, the ring, and the text - the four
+ * things that have to be identical on both sides of the IPC boundary or a log
+ * file becomes two interleaved formats.
+ *
+ * THE RING IS THE POINT, not the file. A player who hits a bug is asked for a
+ * report, and the report is "the last N things that happened" - which has to
+ * exist in memory already, because the interesting part is over by the time
+ * anybody presses a key.
+ */
+
+/**
+ * Four levels, and no `trace`.
+ *
+ * `debug` is already the level nobody ships; a fifth below it would only ever
+ * be reached by editing a constant, which is what a comment is for.
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+/** Most severe first. Index is the rank, so the order here IS the ordering. */
+export const LOG_LEVELS: readonly LogLevel[] = ["error", "warn", "info", "debug"];
+
+/** 0 for `error`, 3 for `debug`. -1 for anything that is not a level. */
+export function logLevelRank(level: string): number {
+  return (LOG_LEVELS as readonly string[]).indexOf(level);
+}
+
+export function isLogLevel(v: unknown): v is LogLevel {
+  return typeof v === "string" && logLevelRank(v) >= 0;
+}
+
+/** Would a log running at `active` record something logged at `of`? */
+export function logLevelAllows(active: LogLevel, of: LogLevel): boolean {
+  return logLevelRank(of) <= logLevelRank(active);
+}
+
+/**
+ * How much this BUILD logs, decided by its own version rather than by a setting.
+ *
+ * A released build logs warnings and errors; a build somebody is testing logs
+ * what it is doing as well. The two states are already written down in the
+ * version string and nowhere else needs to agree:
+ *
+ *   `0.16.1-edge.2`  a per-commit build  -> info
+ *   `0.16.0`         a 0.x pre-release   -> info
+ *   `1.2.3`          a finished release  -> warn
+ *
+ * DELIBERATELY NOT THE UPDATE CHANNEL. The channel is a preference about which
+ * builds to accept next, stored in localStorage and changeable at any time; a
+ * player who installed a beta and then picked `stable` is still running the
+ * beta, and the log should still say so. Asking the version means the answer
+ * cannot drift from the thing it describes.
+ *
+ * While the project is 0.x this returns `info` for everything, which is correct
+ * and temporary: `stable` selects nothing before 1.0.0 either. Both facts stop
+ * being true on the same day, by themselves - see `defaultChannel`, which this
+ * mirrors and which `update.test.ts` ties it to.
+ */
+export function defaultLogLevel(version: string): LogLevel {
+  if (version.includes("-edge.")) return "info";
+  return /^0\./u.test(version) ? "info" : "warn";
+}
+
+/**
+ * One line of log, with its detail ALREADY rendered to text.
+ *
+ * Serialising at record time rather than at write time is what bounds the ring:
+ * a record holds a string, not a reference to a live game object that will have
+ * changed - or been mutated into a cycle - by the time anybody reads it. It also
+ * means a report cannot be the thing that throws while somebody is filing a bug.
+ */
+export interface LogRecord {
+  /** Epoch milliseconds. */
+  readonly at: number;
+  readonly level: LogLevel;
+  /** Where it came from: `update`, `mods`, `save`. Short and stable. */
+  readonly area: string;
+  readonly msg: string;
+  /** The extra detail, JSON-ish, or undefined when there was none. */
+  readonly data?: string;
+}
+
+/** Somewhere a line goes. Given the record and the text, so it need not reformat. */
+export type LogSink = (rec: LogRecord, line: string) => void;
+
+/** How many records the ring holds before the oldest is dropped. */
+export const LOG_RING_DEFAULT = 2000;
+
+/** Longest single message or detail string kept, in characters. */
+export const LOG_FIELD_MAX = 2000;
+
+/**
+ * JSON, but it cannot throw and it cannot run away.
+ *
+ * Everything a caller might hand this is in scope: a cycle (a game object
+ * pointing at the state that owns it), a BigInt (JSON.stringify throws on one),
+ * a 40,000-element array, a function, an Error (whose message and stack are the
+ * only interesting parts and neither is enumerable). A logger that throws while
+ * describing a failure replaces the failure with its own.
+ */
+export function describeValue(v: unknown, depth = 4): string {
+  const seen = new Set<unknown>();
+  const walk = (x: unknown, left: number): unknown => {
+    if (x === null || typeof x !== "object") {
+      if (typeof x === "bigint") return `${x.toString()}n`;
+      if (typeof x === "function") return `[function ${x.name || "anonymous"}]`;
+      if (typeof x === "symbol") return x.toString();
+      if (typeof x === "string" && x.length > LOG_FIELD_MAX) {
+        return `${x.slice(0, LOG_FIELD_MAX)}...[${String(x.length)} chars]`;
+      }
+      return x;
+    }
+    if (seen.has(x)) return "[circular]";
+    if (left <= 0) return "[...]";
+    if (x instanceof Error) {
+      /* name/message/stack are not enumerable, so the generic branch below
+       * would render every Error as `{}` - which is the single most useless
+       * thing a log can say about a failure. */
+      const out: Record<string, unknown> = { name: x.name, message: x.message };
+      if (typeof x.stack === "string") out["stack"] = x.stack.split("\n").slice(0, 8).join("\n");
+      if (x.cause !== undefined) out["cause"] = walk(x.cause, left - 1);
+      return out;
+    }
+    seen.add(x);
+    try {
+      if (Array.isArray(x)) {
+        const head = x.slice(0, 50).map((e) => walk(e, left - 1));
+        return x.length > 50 ? [...head, `...[${String(x.length)} items]`] : head;
+      }
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(x as Record<string, unknown>)) {
+        out[k] = walk(val, left - 1);
+      }
+      return out;
+    } finally {
+      seen.delete(x);
+    }
+  };
+  try {
+    const text = JSON.stringify(walk(v, depth));
+    if (text === undefined) return String(v);
+    return text.length > LOG_FIELD_MAX ? `${text.slice(0, LOG_FIELD_MAX)}...` : text;
+  } catch {
+    /* Belt and braces: a getter that throws is reachable from Object.entries. */
+    return "[undescribable]";
+  }
+}
+
+/** `2026-08-02T13:06:09.123Z` - sortable, and the same in every timezone. */
+function stamp(at: number): string {
+  try {
+    return new Date(at).toISOString();
+  } catch {
+    /* A NaN or out-of-range timestamp must not cost the line it is attached to. */
+    return "????-??-??T??:??:??.???Z";
+  }
+}
+
+/**
+ * One line of the log file.
+ *
+ * Fixed-width level so the areas line up when a human reads a thousand of them,
+ * and the detail after a ` | ` so the message can be found by eye without the
+ * JSON in the way.
+ */
+export function formatLogLine(rec: LogRecord): string {
+  const head = `${stamp(rec.at)} ${rec.level.toUpperCase().padEnd(5)} [${rec.area}] ${rec.msg}`;
+  return rec.data === undefined ? head : `${head} | ${rec.data}`;
+}
+
+/**
+ * A path with the user's home directory replaced by `~`.
+ *
+ * Called on the way into a REPORT, not on the way into the log file. The file
+ * lives on their machine and is theirs; the report is the thing they send to a
+ * stranger, and `C:\Users\firstname.lastname\...` is a real name in it. The
+ * comparison is case-insensitive because Windows paths are, and it is a plain
+ * substring so it catches the home directory wherever it appears in a line -
+ * inside a stack trace, inside a JSON blob - not only at the start.
+ */
+export function elideHome(text: string, home: string | undefined): string {
+  const h = (home ?? "").replace(/[\\/]+$/u, "");
+  if (h.length < 4) return text;
+  /*
+   * THREE SPELLINGS OF THE SAME PATH, and the third is the one that matters.
+   *
+   * A path reaches the log through `describeValue`, which JSON-encodes it - so
+   * on Windows it arrives with its backslashes DOUBLED, and neither of the two
+   * obvious forms matches a character of it. Checking only the raw and URL forms
+   * left every path this project actually logs untouched. It was caught by a
+   * test that used a realistic log line rather than a hand-written path, which
+   * is the only reason it was caught at all.
+   */
+  const forms = [
+    /* `{"path":"C:\\Users\\name\\..."}` - what describeValue produces. */
+    h.replace(/\\/gu, "\\\\"),
+    /* Raw, as node:path produces it. */
+    h,
+    /* A file:// URL in a stack trace, often in the same line as the above. */
+    h.replace(/\\/gu, "/"),
+  ];
+  let out = text;
+  /* Longest first, so the doubled form is taken before the single one can eat
+   * its leading segment and leave the rest looking like an unrelated path. */
+  for (const form of [...new Set(forms)].sort((a, b) => b.length - a.length)) {
+    const pattern = new RegExp(form.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), "giu");
+    out = out.replace(pattern, "~");
+  }
+  return out;
+}
+
+export interface LogOptions {
+  /** Starting level. Callers pass `defaultLogLevel(ENGINE_VERSION)`. */
+  readonly level: LogLevel;
+  /** Records held in memory. */
+  readonly capacity?: number;
+  /** Injected so a test can assert a timestamp instead of tolerating one. */
+  readonly now?: () => number;
+}
+
+/** What the rest of the app holds. */
+export interface Log {
+  readonly level: LogLevel;
+  setLevel(level: LogLevel): void;
+  error(area: string, msg: string, data?: unknown): void;
+  warn(area: string, msg: string, data?: unknown): void;
+  info(area: string, msg: string, data?: unknown): void;
+  debug(area: string, msg: string, data?: unknown): void;
+  /** Add a destination. Returns the function that removes it again. */
+  addSink(sink: LogSink): () => void;
+  /** The ring, oldest first. */
+  recent(limit?: number): LogRecord[];
+  /**
+   * How many records the ring has thrown away.
+   *
+   * Reported on a report rather than kept quiet: "the last 2000 lines" and "the
+   * whole session" look identical in a text file, and the difference is whether
+   * the thing you are looking for could still be above the top.
+   */
+  dropped(): number;
+}
+
+export function createLog(opts: LogOptions): Log {
+  const capacity = Math.max(1, opts.capacity ?? LOG_RING_DEFAULT);
+  const now = opts.now ?? ((): number => Date.now());
+  const ring: (LogRecord | undefined)[] = new Array<LogRecord | undefined>(capacity);
+  let head = 0;
+  let count = 0;
+  let lost = 0;
+  let level = opts.level;
+  const sinks = new Set<LogSink>();
+
+  const write = (lvl: LogLevel, area: string, msg: string, data: unknown): void => {
+    if (!logLevelAllows(level, lvl)) return;
+    const rec: LogRecord = {
+      at: now(),
+      level: lvl,
+      area,
+      msg: msg.length > LOG_FIELD_MAX ? `${msg.slice(0, LOG_FIELD_MAX)}...` : msg,
+      ...(data === undefined ? {} : { data: describeValue(data) }),
+    };
+    if (count === capacity) lost++;
+    ring[head] = rec;
+    head = (head + 1) % capacity;
+    if (count < capacity) count++;
+    const line = formatLogLine(rec);
+    for (const sink of sinks) {
+      try {
+        sink(rec, line);
+      } catch {
+        /* A sink that throws - a full disk, a closed IPC channel - must not
+         * take down the code that was only trying to say what it was doing,
+         * and must not stop the OTHER sinks from getting the line. */
+      }
+    }
+  };
+
+  return {
+    get level(): LogLevel {
+      return level;
+    },
+    setLevel(next: LogLevel): void {
+      level = next;
+    },
+    error: (a, m, d?) => {
+      write("error", a, m, d);
+    },
+    warn: (a, m, d?) => {
+      write("warn", a, m, d);
+    },
+    info: (a, m, d?) => {
+      write("info", a, m, d);
+    },
+    debug: (a, m, d?) => {
+      write("debug", a, m, d);
+    },
+    addSink(sink: LogSink): () => void {
+      sinks.add(sink);
+      return () => {
+        sinks.delete(sink);
+      };
+    },
+    recent(limit?: number): LogRecord[] {
+      const want = Math.max(0, Math.min(limit ?? count, count));
+      const out: LogRecord[] = [];
+      for (let i = count - want; i < count; i++) {
+        const rec = ring[(head - count + i + capacity * 2) % capacity];
+        if (rec) out.push(rec);
+      }
+      return out;
+    },
+    dropped(): number {
+      return lost;
+    },
+  };
+}

package/src/version.ts

@@ -23,4 +23,4 @@ export const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export const ENGINE_VERSION = "0.15.3";
+export const ENGINE_VERSION = "0.17.0";