modwright 0.1.0

package/assets/claude/skills/mw-ship.md

@@ -0,0 +1,57 @@
+---
+name: mw-ship
+description: Build, verify the listing, deploy and pre-flight this mod for release.
+model: sonnet
+effort: high
+---
+
+<!-- modwright:asset modwright-ship@${version} -->
+
+Take `${project}` from source to a deployed, checked build. Every step here is dry-run
+first; every apply step is the user's decision, not yours.
+
+## 1. Validate
+
+`validate` with `includeInfo: true`. `blocking: true` or `counts.block > 0` stops the
+run — explain the findings (see the `mw-validate` skill for how to read `evidence`) and
+hand back. Read `skipped` too: a rule that could not run has not passed.
+
+## 2. Build
+
+`build` with `mode: "dry-run"` resolves and describes every step without running a tool.
+Check the step list, the `variant` if one applies, and the resolved `version`. Then
+`mode: "apply"`.
+
+The cheap validators run again before the first pack step and refuse the build on any
+block. Do not reach for `noValidate` — if a block is wrong, it is a rule to fix or
+suppress with a reason, not a gate to skip. On failure the stage tree is kept: say where
+it is.
+
+## 3. Deploy
+
+`deploy` with `mode: "dry-run"` first. It resolves every target, refuses an artifact this
+build did not produce or one older than its sources, and reports what it would copy,
+prune and back up. Note `deployMode` (`pak` or `loose`) and, for a pak deploy blocked by
+an existing junction, that `unlink` removes the link only.
+
+Then `mode: "apply"` once the user confirms. Report `deferred` targets (the game
+still held the file), the reload recommendation the result carries, and where the backup
+went.
+
+## 4. Pre-flight
+
+- `reload_plan` on the deployed paths if the deploy result's recommendation needs
+  restating, and tell the user what to relaunch.
+- `run_tests` (or the `mw-verify` skill) for anything the release claims to fix.
+- `rollback` with no `backupId` lists the backups this project has, newest stamp last —
+  name the one this deploy wrote so the user can undo it. Restoring is
+  `rollback` with that `backupId` and `mode: "apply"`.
+
+ModWright does not publish. Summarise for the user what was built, what was
+deployed where, what is still on the manual checklist, and the version to tag.
+
+## Stop and ask
+
+Stop before every apply. Stop on any block finding, any failed build step, any deferred
+deploy target, and before `unlink`, `noValidate` or a rollback — each of those either
+changes the game install or drops a safety check.

package/assets/claude/skills/mw-validate.md

@@ -0,0 +1,51 @@
+---
+name: mw-validate
+description: Run ModWright's validators over this mod and explain every finding.
+argument-hint: [--changed] [--rule <id>]
+model: sonnet
+effort: medium
+---
+
+<!-- modwright:asset modwright-validate@${version} -->
+
+Run ModWright's `validate` tool over this project (`${project}`, game `${game}`) and
+explain what it reports. You are the explainer, not the fixer: nothing is edited until
+the user says so.
+
+## Call it
+
+`validate` takes `path` (a `modwright.json` or a directory to search up from — omit for
+the repo root), `groups`, `cheapOnly`, `changedFiles`, `includeInfo` and `installPath`.
+
+- No argument: `validate` with `includeInfo: true` for the first pass of a session.
+- `--changed`: pass the absolute paths of the files edited so far as `changedFiles`;
+  file rules then run only on those. It is a filter, not a faster mode.
+- `--rule <id>`: `validate` has **no** per-rule input. Pass the rule's group in `groups`
+  when you know it, otherwise run unfiltered and report only the findings whose
+  `validatorId` matches. Say which of the two you did.
+- `cheapOnly: true` is the on-every-edit subset — use it while iterating, never as the
+  final word before a build.
+
+## Read the report
+
+`counts`, `blocking` and `suppressed` are computed over unsuppressed findings only.
+`blocking: false` with `counts.block === 0` is the clean result; `findings: []` alone is
+not, because a rule that could not run is in `skipped`, not in `findings`.
+
+- Walk `skipped` first. Each entry names its reason — no index (`build_index`), a tool
+  that was not found (`check_toolchain`), no install. Report those as unknowns, never as
+  passes.
+- For each finding, quote `file`, `line`, `message` and `fix` as the tool gave them.
+- Every finding carries `evidence`: knowledge fact ids. **Do not explain a rule from
+  memory.** For each id call `lookup` with `game: "${game}"`, `kind: "facts"`,
+  `query: { text: "<fact id>", full: "1" }`, and report the fact's `status`
+  (verified / unverified / contradicted / community / inferred) alongside the claim. An
+  `unverified` or `contradicted` fact behind a finding is worth saying out loud.
+- A finding with `suppressedBy` is already a recorded decision. Show it and move on.
+
+## Stop and ask
+
+Stop and hand back to the user before you: edit any file to fix a finding; add or
+widen an entry in `.modwright/suppressions.json` (a suppression needs their reason, in
+their words, not yours); or conclude a rule is a false positive. Propose the change,
+name the finding it answers, and wait.

package/assets/claude/skills/mw-verify.md

@@ -0,0 +1,59 @@
+---
+name: mw-verify
+description: Run this mod's test plan against the in-game bridge and record the result.
+argument-hint: [plan] [--rows <ids>]
+model: sonnet
+effort: high
+---
+
+<!-- modwright:asset modwright-verify@${version} -->
+
+Verify `${project}` in the running game. ModWright never launches the game, never sends a
+reload command, and never decides on the user's behalf that something is verified.
+
+## 1. Is what is deployed the thing you are testing?
+
+If a deploy happened this session, pass its destination paths to `reload_plan` as
+`paths` (an array, at least one). It answers `hot`, `hot-degraded`, `save-reload`,
+`restart` or `unknown` ("restart to be sure"). Tell the user what the answer
+requires *before* they load a save — a stale build is the usual mystery failure.
+
+## 2. Bridge
+
+`bridge` with `action: "status"` and `game: "${game}"` (or `path`) reports heartbeat
+freshness and whether `protocolVersion` matches. If the bridge is not staged in this
+project, `action: "stage"` copies it in (`mode: "dry-run"` first, then `"apply"`), and it
+reaches the game through `deploy --variant withBridge`.
+
+A stale or missing heartbeat means the game is not running with the bridge armed. Say so
+and stop; do not run the plan against a bridge that cannot answer.
+
+## 3. Run the plan
+
+`run_tests` takes `plan` (a planId from a plan's own header, or a path to its YAML —
+usually `tests/authored.yaml`), `rows` (the `--rows` ids, omit for all), `gates`, `mode`,
+`windowSeconds`, `allowMutate` and `timeoutSeconds`.
+
+- Always `mode: "dry-run"` first: it shows the combined bridge request and the full
+  checklist without arming anything.
+- Then `mode: "apply"`. Rows with a probe go to the bridge in one request; rows without
+  one are checklist items for the user to answer.
+- `allowMutate: true` lets mutating probes run. Ask first, every time.
+- A row on an `unverified` probe kind that passes is capped below `verified` on purpose —
+  report that cap, do not round it up.
+
+## 4. Record
+
+`run_tests` on apply writes observed/status/evidence back into the plan YAML and, for a
+row naming a ledger `claim`, records verified/contradicted against that claim itself —
+do not re-record it. Read it back with `ledger` `action: "list"`/`"show"`, and
+`action: "check"` to confirm every verified claim's evidence still exists on disk.
+
+Reach for `ledger` `action: "record"` (`mode: "apply"`) only for a manual corroboration
+the user dictates — and nothing reaches verified without an evidence block.
+
+## Stop and ask
+
+Stop if the bridge heartbeat is stale, if a manual row needs an in-game observation, if a
+probe times out (report which of the named timeout outcomes it was), or if a row failed.
+A failed row is a finding to hand back, not something to re-run until it passes.

package/assets/nivalisnights/extract_resources.py

@@ -0,0 +1,177 @@
+"""Decode Nivalis Nights `Resources/` definition assets to JSONL, for ModWright's vanilla index.
+
+Run by the nivalisnights index builder (src/surfaces/nivalisnights/index/build.ts) through
+the `unitypy-python` tool: a Python with UnityPy and TypeTreeGeneratorAPI installed. Reads
+only the user's own install; writes only under --out. The notes below record why each
+step is shaped as it is:
+
+- The build strips type trees, so MonoBehaviour fields are decoded with type trees
+  generated from Cpp2IL dummy DLLs made with the attributeanalyzer + attributeinjector
+  processors (TypeTreeGeneratorAPI's own IL2CPP loader fails on this build).
+- The generated base nodes miss the align after m_Enabled, so m_Script is read from the
+  raw bytes (FileID int32 at 16, PathID int64 at 20) and the shifted base fields are dropped.
+- MonoScripts live in globalgamemanagers.assets, which is always loaded.
+- UnityPy loads whole files, so each folder loads only the files its entries live in.
+
+Output, under --out:
+  <folder>.jsonl  one record per decoded object: {"path", "folder", "key", "script", "data"}
+                  where key is "<file>:<path_id>" and every PPtr inside data is either
+                  null (path id 0) or {"$ref": "<file>:<path_id>"}.
+  summary.json    {"unity", "folders": {folder: {"entries", "decoded", "scripts", "errors"}}}
+
+Usage:
+  python extract_resources.py --data "<root>/Nivalis Nights_Data" --dlls <dummydll dir>
+      --out <dir> --folders itemtypes,recipes [--follow peopledatabase]
+"""
+
+import argparse
+import collections
+import json
+import os
+import struct
+import sys
+
+import UnityPy
+from UnityPy.helpers.TypeTreeGenerator import TypeTreeGenerator
+
+UNITY_VERSION = "2020.3.44f1"
+BASE_FIELDS = ("m_GameObject", "m_Enabled", "m_Script")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--data", required=True)
+    ap.add_argument("--dlls", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--folders", required=True, help="comma-separated top-level Resources folders")
+    ap.add_argument("--follow", default="", help="folders whose referenced objects are decoded too, as <folder>.refs")
+    args = ap.parse_args()
+
+    UnityPy.config.FALLBACK_UNITY_VERSION = UNITY_VERSION
+    gen = TypeTreeGenerator(UNITY_VERSION)
+    gen.load_local_dll_folder(args.dlls)
+    os.makedirs(args.out, exist_ok=True)
+
+    ggm = next(iter(UnityPy.load(os.path.join(args.data, "globalgamemanagers")).files.values()))
+    rm = next(o for o in ggm.objects.values() if o.type.name == "ResourceManager").read()
+
+    def ext_name(pptr) -> str:
+        return os.path.basename(ggm.externals[pptr.file_id - 1].path if pptr.file_id else "globalgamemanagers").lower()
+
+    folders = [f.strip().lower() for f in args.folders.split(",") if f.strip()]
+    follow = {f.strip().lower() for f in args.follow.split(",") if f.strip()}
+    by_folder = collections.defaultdict(list)
+    for path, pptr in rm.m_Container:
+        top = path.split("/")[0]
+        if top in folders:
+            by_folder[top].append((path, pptr))
+
+    summary = {"unity": UNITY_VERSION, "folders": {}}
+    for folder in folders:
+        wanted = by_folder.get(folder, [])
+        needed = sorted({ext_name(pp) for _, pp in wanted} - {"globalgamemanagers", "globalgamemanagers.assets"})
+        env = UnityPy.load(os.path.join(args.data, "globalgamemanagers.assets"), *[os.path.join(args.data, n) for n in needed])
+        env.typetree_generator = gen
+        files = {os.path.basename(k).lower(): v for k, v in env.files.items()}
+        scripts_cache = {}
+
+        def script_of(obj) -> str:
+            sf = obj.assets_file
+            fid, pid = struct.unpack_from("<iq", obj.get_raw_data(), 16)
+            owner = os.path.basename(sf.externals[fid - 1].path).lower() if fid else os.path.basename(sf.name).lower()
+            if (owner, pid) not in scripts_cache:
+                ms = files[owner].objects[pid].read_typetree()
+                scripts_cache[(owner, pid)] = (ms["m_Namespace"] + "." if ms["m_Namespace"] else "") + ms["m_ClassName"]
+            return scripts_cache[(owner, pid)]
+
+        def decode(obj, path, out, stats, folder_name):
+            file_name = os.path.basename(obj.assets_file.name).lower()
+            externals = [os.path.basename(e.path).lower() for e in obj.assets_file.externals]
+            refs = []
+
+            def norm(v):
+                if isinstance(v, dict):
+                    if set(v.keys()) == {"m_FileID", "m_PathID"}:
+                        if not v["m_PathID"]:
+                            return None
+                        fid = v["m_FileID"]
+                        target = file_name if fid == 0 else (externals[fid - 1] if 0 < fid <= len(externals) else f"?{fid}")
+                        key = f"{target}:{v['m_PathID']}"
+                        refs.append(key)
+                        return {"$ref": key}
+                    return {k: norm(x) for k, x in v.items()}
+                if isinstance(v, list):
+                    return [norm(x) for x in v]
+                return v
+
+            if obj.type.name != "MonoBehaviour":
+                stats["errors"][f"not a MonoBehaviour ({obj.type.name})"] += 1
+                return refs
+            try:
+                tree = obj.read_typetree()
+                cls = script_of(obj)
+            except Exception as e:  # one bad object never stops the folder
+                stats["errors"][f"{type(e).__name__}: {str(e)[:120]}"] += 1
+                return refs
+            data = norm({k: v for k, v in tree.items() if k not in BASE_FIELDS})
+            stats["scripts"][cls] += 1
+            stats["decoded"] += 1
+            record = {"path": path, "folder": folder_name, "key": f"{file_name}:{obj.path_id}", "script": cls, "data": data}
+            out.write(json.dumps(record, ensure_ascii=False, default=str) + "\n")
+            return refs
+
+        def new_stats(entries):
+            return {"entries": entries, "decoded": 0, "scripts": collections.Counter(), "errors": collections.Counter()}
+
+        stats = new_stats(len(wanted))
+        followed = set()
+        with open(os.path.join(args.out, f"{folder}.jsonl"), "w", encoding="utf-8") as out:
+            for path, pptr in wanted:
+                sf = files.get(ext_name(pptr))
+                obj = sf.objects.get(pptr.path_id) if sf else None
+                if obj is None:
+                    stats["errors"]["entry's file not loaded or object missing"] += 1
+                    continue
+                for ref in decode(obj, path, out, stats, folder):
+                    followed.add(ref)
+        summary["folders"][folder] = {k: (dict(v) if isinstance(v, collections.Counter) else v) for k, v in stats.items()}
+        print(f"{folder}: {stats['decoded']}/{stats['entries']} decoded", flush=True)
+
+        if folder in follow:
+            # Two levels: the folder's references (PeopleDatabase -> the NPCs), then
+            # theirs (an NPC -> its demographic group, action list). Only MonoBehaviours
+            # are decoded; a reference to a prefab, sprite or mesh is counted, not an error.
+            seen = set()
+            frontier = followed
+            for suffix in ("refs", "refs2"):
+                name = f"{folder}.{suffix}"
+                todo = sorted(k for k in frontier if k not in seen)
+                seen.update(todo)
+                fstats = new_stats(0)
+                fstats["skipped_non_monobehaviour"] = 0
+                nxt = set()
+                with open(os.path.join(args.out, f"{name}.jsonl"), "w", encoding="utf-8") as out:
+                    for key in todo:
+                        fname, _, pid = key.rpartition(":")
+                        sf = files.get(fname)
+                        obj = sf.objects.get(int(pid)) if sf and pid.lstrip("-").isdigit() else None
+                        if obj is None:
+                            fstats["skipped_unloaded_file"] = fstats.get("skipped_unloaded_file", 0) + 1
+                            continue
+                        if obj.type.name != "MonoBehaviour":
+                            fstats["skipped_non_monobehaviour"] += 1
+                            continue
+                        fstats["entries"] += 1
+                        nxt.update(decode(obj, key, out, fstats, name))
+                summary["folders"][name] = {k: (dict(v) if isinstance(v, collections.Counter) else v) for k, v in fstats.items()}
+                print(f"{name}: {fstats['decoded']}/{fstats['entries']} decoded", flush=True)
+                frontier = nxt
+        del env
+
+    with open(os.path.join(args.out, "summary.json"), "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=1)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bridges/bg3-se/Mods/ModWrightBridge/ScriptExtender/Config.json

@@ -0,0 +1,5 @@
+{
+    "RequiredVersion": 21,
+    "ModTable": "ModWrightBridge",
+    "FeatureFlags": ["Lua"]
+}

package/bridges/bg3-se/Mods/ModWrightBridge/ScriptExtender/Lua/BootstrapClient.lua

@@ -0,0 +1,55 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge — CLIENT bootstrap: heartbeat and client probes only.
+--
+-- It loads at the main menu, which is what makes the `bg3.client.loaded` row answerable
+-- without a save ("main menu is enough; no save needed"), the same client-marker pattern a
+-- shipped SE mod uses.
+--
+-- It deliberately does NOT poll for requests and does NOT write result files. API.md
+-- §"Client / Server States": the client and server Lua states "are completely separated from
+-- each other and cannot access the internal state of each other", and the protocol has
+-- exactly one request file and one result file per request id, so two pollers writing the
+-- same result would race. The server relays this state's answer out of the heartbeat instead
+-- (Probes.lua, `bg3.client.loaded`).
+--
+-- ============================================================================
+-- Ext API used in this file
+-- ============================================================================
+-- API.md §"Getting Started" / "Bootstrap Scripts": "the extender will attempt to load ...
+--   `BootstrapClient.lua` on the client side"; `Ext.Require` at module startup only.
+-- API.md §"Engine and SE Events": `SessionLoaded`, `ResetCompleted`.
+-- API.md §"SE Events": `Ext.Events.<EVENT_NAME>:Subscribe(fun)`.
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+local Protocol = Ext.Require("ModWrightBridge/Protocol.lua")
+local ProbesClient = Ext.Require("ModWrightBridge/ProbesClient.lua")
+
+-- Only the server state writes ModWright_log.json (the protocol has one breadcrumb file);
+-- the client keeps its breadcrumbs on the SE console so the two states never race over it.
+Log.mirrorToFile = false
+
+Protocol.init({
+    context = "client",
+    dispatcher = ProbesClient,
+    heartbeatFile = Protocol.FILES.heartbeatClient,
+})
+
+local function mark(stage)
+    ProbesClient.stage = stage
+    local res = ProbesClient.run("bg3.client.loaded")
+    pcall(function() Protocol.writeHeartbeat() end)
+    Log.info(("client %s (marker %s, heartbeat %s)")
+        :format(stage, tostring(res.status), Protocol.FILES.heartbeatClient))
+end
+
+mark("bootstrap")
+pcall(function() Protocol.startHeartbeat() end)
+
+Ext.Events.SessionLoaded:Subscribe(function()
+    pcall(function() mark("SessionLoaded") end)
+end)
+
+Ext.Events.ResetCompleted:Subscribe(function()
+    pcall(function() mark("ResetCompleted") end)
+end)

package/bridges/bg3-se/Mods/ModWrightBridge/ScriptExtender/Lua/BootstrapServer.lua

@@ -0,0 +1,81 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge — SERVER bootstrap. This is ModWright's author-only verification bridge,
+-- built to the ModWright request/result protocol. It is never shipped in a mod:
+-- `bg3.history.bridge-never-ships` (src/surfaces/baldursgate3/validators/bridge.ts) blocks a
+-- build whose output carries this folder or the banner on the first line above.
+--
+-- WHAT THIS MOD DOES, IN ONE PARAGRAPH: it writes a heartbeat every 2 s while loaded, polls
+-- for an armed request file every 1 s, runs the probes that request names, and writes a
+-- result followed by a `done` marker carrying the result's byte length. It reads. It never
+-- calls an Osiris action, never forces a cast, and writes no PersistentVars, ModVars or
+-- UserVars (API.md §"Persistence": "PersistentVars are deprecated and should not be used").
+--
+-- ============================================================================
+-- Registration shape and its citations
+-- ============================================================================
+-- API.md §"Getting Started" / "Bootstrap Scripts":
+--   "the extender will attempt to load `BootstrapServer.lua` on the server side"; and
+--   "The `Ext.Require` function is the extender's version of the Lua built-in `require`" —
+--   "`Ext.Require` should only be called during module startup". Hence every require below
+--   is at chunk scope, as a shipped SE mod does it.
+-- API.md §"Engine and SE Events - `Ext.Events`":
+--   `SessionLoaded` | "Thrown when the game session was set up."
+--   `ResetCompleted` | "Thrown when `Ext.Debug.Reset()` or `reset` console command completes
+--                       on the client or server. Indicates that the Lua state was reloaded."
+-- API.md §"SE Events":
+--   `Ext.Events.<EVENT_NAME>:Subscribe(fun)`
+--
+-- ONE SessionLoaded subscription, every call inside it `pcall`-guarded: a shape proven in a
+-- shipped SE mod. That pattern also explains why the poll timer exists at all: a mod that
+-- reads its flag file INSIDE SessionLoaded never sees a file dropped after the session is
+-- up, which is why the bridge polls.
+--
+-- ResetCompleted is subscribed for two reasons, both observed in game: a console `reset`
+-- reloads the Lua state WITHOUT re-running the session (so SessionLoaded may never fire
+-- again and the poll timer must be started from here too), and "`reset` mid-session degrades
+-- Osiris ... Osi queries return junk and Osi calls silently no-op afterward" — which is what
+-- `osirisDegraded` records and what probe `bg3.osiris.health` measures.
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+local Protocol = Ext.Require("ModWrightBridge/Protocol.lua")
+local Watch = Ext.Require("ModWrightBridge/Watch.lua")
+local Probes = Ext.Require("ModWrightBridge/Probes.lua")
+
+Protocol.init({
+    context = "server",
+    dispatcher = Probes,
+    heartbeatFile = Protocol.FILES.heartbeatServer,
+})
+
+local seVersion = "unknown"
+pcall(function() seVersion = tostring(Ext.Utils.Version()) end)
+
+local probeKinds = 0
+for _ in pairs(Probes.handlers) do probeKinds = probeKinds + 1 end
+
+Log.info(("server bootstrap loaded (bridge %s, protocolVersion %d, SE v%s, %d probe kinds, Watch %s)")
+    :format(Protocol.BRIDGE_VERSION, Protocol.PROTOCOL_VERSION, seVersion, probeKinds, tostring(Watch ~= nil)))
+
+-- The heartbeat starts at load, not at SessionLoaded: it is rewritten every 2 s while the
+-- bridge is loaded, and `bridge status` needs one at the main menu to
+-- tell "not deployed" from "deployed, game not in a session".
+pcall(function() Protocol.startHeartbeat() end)
+
+Ext.Events.SessionLoaded:Subscribe(function()
+    pcall(function() Protocol.startPolling() end)
+    pcall(function() Protocol.writeHeartbeat() end)
+    pcall(function()
+        Log.info("SessionLoaded: polling " .. Protocol.FILES.request ..
+            " every " .. Protocol.POLL_MS .. " ms; arm with `bridge arm` or by writing the request file by hand")
+    end)
+end)
+
+Ext.Events.ResetCompleted:Subscribe(function()
+    pcall(function() Protocol.markOsirisDegraded() end)
+    -- A `reset` clears the in-memory consumed-nonce set with the rest of the Lua state; that
+    -- is exactly why a request carries `armedUntil`, so a stale request cannot
+    -- silently execute a second time.
+    pcall(function() Protocol.startPolling() end)
+    pcall(function() Protocol.writeHeartbeat() end)
+end)

package/bridges/bg3-se/Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/Log.lua

@@ -0,0 +1,96 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / Log.lua — console breadcrumbs with a rolling file mirror.
+--
+-- Follows the common SE mod logging pattern: every line is printed AND appended to a rolling
+-- 250-entry JSON array in the SE storage dir, because the SE console often cannot be watched
+-- live while the game runs. The breadcrumb file is `ModWright_log.json` with a 250-line cap,
+-- and every `Ext.Utils.Print` carries the `[ModWrightBridge]` prefix.
+--
+-- This module deliberately has NO dependencies (not even Protocol) so that a failure anywhere
+-- else can still be reported. It is also the ONE place that uses `Ext.Json.Stringify` on a
+-- table of its own making: the buffer is never empty when it is written, so the empty-table
+-- array/object ambiguity that forced Protocol's own encoder (see Protocol.lua) cannot bite
+-- here, and nothing on the ModWright side parses this file — it is a human breadcrumb.
+--
+-- API.md §"Utils" / §"Helper/aliased functions":
+--   `_P()`: Equivalent to `Ext.Utils.Print()`
+-- API.md §"I/O":
+--   `Ext.IO.SaveFile(path, content): boolean`  -- Writes content to a file. Creates missing parent directories.
+-- API.md §"JSON support - `Ext.Json`":
+--   `Ext.Json.Stringify(value, [options])`
+-- API.md §"Timers - `Ext.Timer`":
+--   `Ext.Timer.MonotonicTime(): int64`  -- monotonic system time in milliseconds
+
+local Log = {}
+
+Log.PREFIX = "[ModWrightBridge]"
+Log.FILE = "ModWright_log.json"
+Log.MAX_LINES = 250
+
+-- Set false by BootstrapClient: the client Lua state must never write ModWright_log.json,
+-- or the two states race each other over the same file (there is exactly one breadcrumb
+-- file, written by the server).
+Log.mirrorToFile = true
+
+Log.buffer = {}
+
+--- Monotonic milliseconds; total (never throws, never returns nil).
+--- API.md §"Timers": `Ext.Timer.MonotonicTime(): int64`. Falls back through other clocks
+--- when the call is unavailable on an older extender.
+function Log.monotonic()
+    local ok, t = pcall(function() return Ext.Timer.MonotonicTime() end)
+    if ok then
+        local n = tonumber(t)
+        if n then return n end
+    end
+    local ok2, t2 = pcall(function() return Ext.Utils.MonotonicTime() end)
+    if ok2 then
+        local n2 = tonumber(t2)
+        if n2 then return n2 end
+    end
+    local ok3, c = pcall(function() return os.clock() end)
+    if ok3 and type(c) == "number" then return math.floor(c * 1000) end
+    return 0
+end
+
+local function mirror(line)
+    if not Log.mirrorToFile then return end
+    pcall(function()
+        local buf = Log.buffer
+        buf[#buf + 1] = { t = Log.monotonic(), line = line }
+        while #buf > Log.MAX_LINES do table.remove(buf, 1) end
+        Ext.IO.SaveFile(Log.FILE, Ext.Json.Stringify(buf))
+    end)
+end
+
+--- Print one prefixed line and mirror it. Never throws.
+function Log.write(msg)
+    local line = Log.PREFIX .. " " .. tostring(msg)
+    pcall(function() Ext.Utils.Print(line) end)
+    mirror(line)
+    return line
+end
+
+--- Ordinary breadcrumb.
+function Log.info(msg)
+    return Log.write(msg)
+end
+
+--- Error breadcrumb. Same transport; the word ERROR is what a reader greps for.
+function Log.err(where, msg)
+    return Log.write("ERROR [" .. tostring(where) .. "] " .. tostring(msg))
+end
+
+--- Wrap a callback so a raw error can never escape into an engine/Osiris callback.
+--- The guarded-callback pattern from a shipped SE mod; its reason — a bad error path leaves
+--- Osiris returning junk — applies to every listener and timer here.
+function Log.guarded(where, fn)
+    return function(...)
+        local ok, err = pcall(fn, ...)
+        if not ok then Log.err(where, err) end
+        return ok
+    end
+end
+
+return Log