modwright 0.1.0

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

@@ -0,0 +1,985 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / Protocol.lua — file transport, marker framing, nonce arming, the
+-- heartbeat, and the request orchestration. This is the Lua half of the ModWright
+-- request/result protocol, and its output is parsed byte-for-byte by
+-- src/core/bridge/{types,paths,poll}.ts. Change nothing here without re-reading both.
+--
+-- ============================================================================
+-- Ext API used in this file (heading + signature quoted above each first use)
+-- ============================================================================
+-- API.md §"I/O - `Ext.IO`" / "Methods":
+--   `Ext.IO.LoadFile(path, [context]): string?`  -- Reads file contents. Returns `nil` if the file cannot be read.
+--   `Ext.IO.SaveFile(path, content): boolean`    -- Writes content to a file. Creates missing parent directories.
+--   (Note: that list is the WHOLE of Ext.IO. There is no delete and no rename, which is why
+--    a consumed request is retired by an in-memory nonce and an `armedUntil` expiry, not by
+--    removing the file.)
+-- API.md §"JSON support - `Ext.Json`":
+--   `Ext.Json.Parse` and `Ext.Json.Stringify`; `Stringify(value, [options])` with
+--   `IterateUserdata`, `AvoidRecursion`, `StringifyInternalTypes`, `MaxDepth`.
+-- API.md §"Timers - `Ext.Timer`" / "Delayed execution":
+--   `Ext.Timer.WaitForRealtime(ms, callback)`    -- Uses OS clock.
+-- API.md §"Timers - `Ext.Timer`" / "Clock helpers":
+--   `Ext.Timer.ClockEpoch(): int64`
+--   `Ext.Timer.MonotonicTime(): int64`
+-- API.md §"Utils - `Ext.Utils`" / "Common methods":
+--   `Ext.Utils.Version(): int32` - Script Extender API version.
+--   `Ext.Utils.GameVersion(): string?` - game version string.
+--   `Ext.Utils.GetGameState()` - current game state enum.
+--   `Ext.Utils.GetCommandLineParams(): string[]` - CLI arguments used to launch the game
+-- API.md §"Helper/aliased functions":
+--   `_P()`: Equivalent to `Ext.Utils.Print()`   (used via Log.lua)
+--
+-- ============================================================================
+-- Why this file carries its own JSON encoder
+-- ============================================================================
+-- `Ext.Json.Stringify` is used here for exactly one job — flattening ENGINE OBJECTS into
+-- plain Lua tables (`Protocol.dumpComponent`), which is what API.md §"JSON support" documents
+-- `IterateUserdata` for and what a hand-run console dump of a component uses.
+--
+-- It is NOT used to serialise the protocol envelope. API.md's Lua/JS type table says
+-- "`table` (sequential keys)" becomes an array and "`table` (non-sequential)" an object, and
+-- says nothing about an EMPTY table, which is both and neither. The Node schemas are
+-- `.strict()` and typed: `errors` and `probes` are `z.array(...)`, `evidence` is
+-- `z.record(...)`. An empty `errors` list emitted as `{}` — or an empty `evidence` map emitted
+-- as `[]` — fails `bridgeResultSchema.safeParse`, and `poll.ts`'s `tryReadComplete` silently
+-- discards a result that fails to parse, so the whole run reads back as a bridge that never
+-- answered. That is a relaunch cycle spent on a coin flip nothing on disk settles. The
+-- encoder below removes the coin flip: `Protocol.array(t)` tags a list, and a tagged empty
+-- list is always `[]` while an untagged empty table is always `{}`.
+-- ============================================================================
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+
+local Protocol = {}
+
+--- An integer duplicated in the Lua and in the Node constant
+--- (`PROTOCOL_VERSION` in src/core/bridge/types.ts), checked at arm time.
+Protocol.PROTOCOL_VERSION = 1
+
+--- Mirrors bridge.json's `version`. Reported in every heartbeat and result.
+Protocol.BRIDGE_NAME = "ModWrightBridge"
+Protocol.BRIDGE_VERSION = "0.1.0"
+
+--- The BG3 file names, flat names in the SE storage dir. These strings must equal
+--- `BG3_FILES` in src/core/bridge/paths.ts exactly.
+Protocol.FILES = {
+    heartbeatServer = "ModWright_hb.json",
+    heartbeatClient = "ModWright_hb_client.json",
+    request         = "ModWright_req.json",
+    requestMarker   = "ModWright_req.marker.json",
+}
+
+function Protocol.resultFile(id) return "ModWright_res_" .. tostring(id) .. ".json" end
+function Protocol.doneFile(id)   return "ModWright_res_" .. tostring(id) .. ".done.json" end
+
+--- Timer periods: 1000 ms for the request marker, 2000 ms for the heartbeat.
+Protocol.POLL_MS = 1000
+Protocol.HEARTBEAT_MS = 2000
+
+--- Hard stop for one request inside the bridge, on top of its own settle+window. Keeps a
+--- lost harvest timer from parking the bridge in `running` forever, where ModWright would
+--- only ever see poll.ts's "hung" verdict and never a result.
+Protocol.WATCHDOG_SLACK_MS = 30000
+
+--- Runtime state (all in-memory: a console `reset` reloads the Lua state and clears it,
+--- which is exactly why arming carries an `armedUntil`).
+Protocol.context = "server"
+Protocol.heartbeatFile = Protocol.FILES.heartbeatServer
+Protocol.state = "idle"
+Protocol.consumed = {}
+--- Raw bytes of the last marker seen with an already-consumed nonce (pollOnce's fast path).
+Protocol.lastConsumedMarkerRaw = nil
+Protocol.lastRequestId = nil
+Protocol.lastResultId = nil
+Protocol.osirisDegraded = false
+Protocol.osirisDegradedReason = nil
+Protocol.loadedAtMs = Log.monotonic()
+Protocol.busy = false
+Protocol.currentRun = nil
+Protocol.dispatcher = nil
+Protocol.pollingStarted = false
+Protocol.heartbeatStarted = false
+Protocol.pendingMismatch = nil
+Protocol.tornReads = 0
+
+-- ---------------------------------------------------------------------------
+-- JSON encoding (see the header note for why this is not Ext.Json.Stringify)
+-- ---------------------------------------------------------------------------
+
+local ARRAY_MT = { __modwright_array = true }
+
+--- Tag a Lua table so the encoder always emits a JSON array, even when it is empty.
+function Protocol.array(t)
+    return setmetatable(t or {}, ARRAY_MT)
+end
+
+local ESCAPES = {
+    ['"']  = '\\"',
+    ['\\'] = '\\\\',
+    ['\b'] = '\\b',
+    ['\f'] = '\\f',
+    ['\n'] = '\\n',
+    ['\r'] = '\\r',
+    ['\t'] = '\\t',
+}
+
+local function escapeChar(c)
+    local e = ESCAPES[c]
+    if e then return e end
+    return string.format("\\u%04x", string.byte(c))
+end
+
+local function encodeString(s)
+    -- `%c` (control characters) rather than `%z`: `%z` is gone in Lua 5.2+ and the bridge
+    -- lint job runs `luac -p` under both 5.1 and 5.4 over this tree.
+    local body = tostring(s):gsub('[%c"\\]', escapeChar)
+    return '"' .. body .. '"'
+end
+
+local function encodeNumber(n)
+    if n ~= n then return "null" end                          -- NaN
+    if n == math.huge or n == -math.huge then return "null" end
+    if n % 1 == 0 and n >= -9007199254740992 and n <= 9007199254740992 then
+        return string.format("%d", n)
+    end
+    return string.format("%.14g", n)
+end
+
+local function isArrayLike(t)
+    if getmetatable(t) == ARRAY_MT then return true end
+    local n = 0
+    for _ in pairs(t) do n = n + 1 end
+    if n == 0 then return false end                           -- untagged empty table -> {}
+    if #t ~= n then return false end
+    for i = 1, n do
+        if t[i] == nil then return false end
+    end
+    return true
+end
+
+local encodeValue
+
+local function encodeTable(t, depth, seen, maxDepth)
+    if depth > maxDepth then return '"<max-depth>"' end
+    if seen[t] then return '"<recursion>"' end
+    seen[t] = true
+
+    local parts = {}
+    local out
+    if isArrayLike(t) then
+        for i = 1, #t do
+            parts[#parts + 1] = encodeValue(t[i], depth + 1, seen, maxDepth)
+        end
+        out = "[" .. table.concat(parts, ",") .. "]"
+    else
+        -- Keys sorted so two runs over the same data produce byte-identical output; the
+        -- these files can be diffed by hand.
+        local keys = {}
+        for k in pairs(t) do
+            local kt = type(k)
+            if kt == "string" or kt == "number" then keys[#keys + 1] = k end
+        end
+        table.sort(keys, function(a, b) return tostring(a) < tostring(b) end)
+        for _, k in ipairs(keys) do
+            local encoded = encodeValue(t[k], depth + 1, seen, maxDepth)
+            if encoded ~= nil then
+                parts[#parts + 1] = encodeString(tostring(k)) .. ":" .. encoded
+            end
+        end
+        out = "{" .. table.concat(parts, ",") .. "}"
+    end
+
+    seen[t] = nil
+    return out
+end
+
+encodeValue = function(v, depth, seen, maxDepth)
+    local t = type(v)
+    if v == nil then return "null" end
+    if t == "boolean" then return v and "true" or "false" end
+    if t == "number" then return encodeNumber(v) end
+    if t == "string" then return encodeString(v) end
+    if t == "table" then return encodeTable(v, depth, seen, maxDepth) end
+    -- userdata / function / thread: engine objects reach this encoder only as already-flattened
+    -- tables (Protocol.dumpComponent). Anything else is reported, never guessed at.
+    return encodeString("<unencodable:" .. t .. ">")
+end
+
+--- Encode a value as compact JSON. Never throws; returns a string.
+function Protocol.encode(value, maxDepth)
+    local ok, out = pcall(function()
+        return encodeValue(value, 1, {}, maxDepth or 16)
+    end)
+    if ok and type(out) == "string" then return out end
+    return '{"encodeError":' .. encodeString(tostring(out)) .. "}"
+end
+
+--- Parse JSON with the attested API.md call. Returns nil on any failure.
+function Protocol.decode(raw)
+    if type(raw) ~= "string" or raw == "" then return nil end
+    local ok, value = pcall(function() return Ext.Json.Parse(raw) end)
+    if ok then return value end
+    return nil
+end
+
+--- Capability tiers. A request carries the tiers it was granted in
+--- `request.grant`; a mutating probe kind needs the `session` tier. `allowMutate: true` is
+--- accepted for one release as the retired alias for grant:["session"], so a request written
+--- by an older ModWright still gates correctly.
+function Protocol.grantsTier(request, tier)
+    if type(request) ~= "table" then return false end
+    if type(request.grant) == "table" then
+        for _, g in ipairs(request.grant) do
+            if tostring(g) == tier then return true end
+        end
+    end
+    if tier == "session" and request.allowMutate == true then return true end
+    return false
+end
+
+-- ---------------------------------------------------------------------------
+-- Files
+-- ---------------------------------------------------------------------------
+
+--- `Ext.IO.LoadFile(path, [context]): string?` — nil when the file cannot be read.
+function Protocol.load(name)
+    local ok, raw = pcall(function() return Ext.IO.LoadFile(name) end)
+    if ok and type(raw) == "string" then return raw end
+    return nil
+end
+
+--- `Ext.IO.SaveFile(path, content): boolean`.
+function Protocol.save(name, content)
+    local ok, res = pcall(function() return Ext.IO.SaveFile(name, content) end)
+    if not ok then
+        Log.err("save", tostring(name) .. ": " .. tostring(res))
+        return false
+    end
+    return res ~= false
+end
+
+-- ---------------------------------------------------------------------------
+-- Time
+-- ---------------------------------------------------------------------------
+-- Every timestamp this bridge writes is read on the Node side by `Date.parse`
+-- (`iso8601Schema` in src/core/bridge/types.ts), so it must be an ISO 8601 UTC string.
+-- The conversions below are Howard Hinnant's civil-calendar algorithms in pure Lua so the
+-- format never depends on an `os.date` that may or may not exist in the SE sandbox.
+
+local function daysFromCivil(y, m, d)
+    if m <= 2 then y = y - 1 end
+    local era = math.floor(y / 400)
+    local yoe = y - era * 400
+    local mp = m + ((m > 2) and -3 or 9)
+    local doy = math.floor((153 * mp + 2) / 5) + d - 1
+    local doe = yoe * 365 + math.floor(yoe / 4) - math.floor(yoe / 100) + doy
+    return era * 146097 + doe - 719468
+end
+
+local function civilFromDays(z)
+    z = z + 719468
+    local era = math.floor(z / 146097)
+    local doe = z - era * 146097
+    local yoe = math.floor((doe - math.floor(doe / 1460) + math.floor(doe / 36524) - math.floor(doe / 146096)) / 365)
+    local y = yoe + era * 400
+    local doy = doe - (365 * yoe + math.floor(yoe / 4) - math.floor(yoe / 100))
+    local mp = math.floor((5 * doy + 2) / 153)
+    local d = doy - math.floor((153 * mp + 2) / 5) + 1
+    local m = mp + ((mp < 10) and 3 or -9)
+    if m <= 2 then y = y + 1 end
+    return y, m, d
+end
+
+--- Seconds since the Unix epoch, UTC. Total.
+--- API.md §"Timers"/"Clock helpers" gives `Ext.Timer.ClockEpoch(): int64` but does NOT state
+--- its unit, so the value is normalised here rather than assumed: anything past 1e12 is
+--- treated as milliseconds. `os.time()` is the fallback (a shipped SE mod shows that the `os`
+--- library is reachable from SE Lua via `os.clock`).
+function Protocol.epochSeconds()
+    local ok, v = pcall(function() return Ext.Timer.ClockEpoch() end)
+    if ok then
+        local n = tonumber(v)
+        if n and n > 1000000000 then
+            if n > 1000000000000 then return math.floor(n / 1000) end
+            return math.floor(n)
+        end
+    end
+    local ok2, t = pcall(function() return os.time() end)
+    if ok2 then
+        local n2 = tonumber(t)
+        if n2 and n2 > 1000000000 then return math.floor(n2) end
+    end
+    return nil
+end
+
+function Protocol.isoFromEpoch(seconds)
+    if type(seconds) ~= "number" then return nil end
+    local days = math.floor(seconds / 86400)
+    local rem = seconds - days * 86400
+    local y, m, d = civilFromDays(days)
+    local h = math.floor(rem / 3600)
+    local mi = math.floor((rem % 3600) / 60)
+    local s = math.floor(rem % 60)
+    return string.format("%04d-%02d-%02dT%02d:%02d:%02dZ", y, m, d, h, mi, s)
+end
+
+--- Current time as an ISO 8601 UTC string. Falls back to the epoch itself (still a valid,
+--- parseable timestamp) and records the loss of accuracy in the run's `errors` instead of
+--- inventing a plausible-looking time.
+function Protocol.isoNow(run)
+    local secs = Protocol.epochSeconds()
+    if secs then
+        local iso = Protocol.isoFromEpoch(secs)
+        if iso then return iso end
+    end
+    if run and run.errors then
+        run.errors[#run.errors + 1] =
+            "no wall clock available (Ext.Timer.ClockEpoch and os.time both unavailable); timestamps are the Unix epoch"
+    end
+    return "1970-01-01T00:00:00Z"
+end
+
+--- Parse an ISO 8601 UTC timestamp to epoch seconds. Node writes `Date#toISOString()`, i.e.
+--- always `YYYY-MM-DDTHH:MM:SS.mmmZ`; fractional seconds and the trailing `Z` are ignored,
+--- and a value carrying a numeric UTC offset is rejected (nil) rather than silently misread.
+function Protocol.parseIso(s)
+    if type(s) ~= "string" then return nil end
+    local y, mo, d, h, mi, se = s:match("^(%d%d%d%d)%-(%d%d)%-(%d%d)T(%d%d):(%d%d):(%d%d)")
+    if not y then return nil end
+    local tail = s:sub(20)
+    if tail:match("[%+%-]%d%d:?%d%d$") then return nil end
+    local days = daysFromCivil(tonumber(y), tonumber(mo), tonumber(d))
+    return days * 86400 + tonumber(h) * 3600 + tonumber(mi) * 60 + tonumber(se)
+end
+
+-- ---------------------------------------------------------------------------
+-- Small shared helpers used by the probe dispatch tables
+-- ---------------------------------------------------------------------------
+
+--- GUID form mismatch: Osiris hands the same entity as a bare UUID in some events and
+--- prefixed `Name_UUID` in others (observed in game). Every compare in this bridge goes
+--- through this function.
+function Protocol.normGuid(g)
+    if type(g) ~= "string" then return g end
+    local uuid = g:match("(%x%x%x%x%x%x%x%x%-%x%x%x%x%-%x%x%x%x%-%x%x%x%x%-%x%x%x%x%x%x%x%x%x%x%x%x)$")
+    return uuid or g
+end
+
+--- Flatten an engine object (component, event, userdata) into a plain Lua table plus the raw
+--- JSON text. Returns (table|nil, json|nil).
+---
+--- API.md §"JSON support - `Ext.Json`": `Stringify(value, [options])` with `IterateUserdata`
+--- ("Dump engine objects similarly to tables instead of throwing an error"), `AvoidRecursion`,
+--- `StringifyInternalTypes` and `MaxDepth`; and "parsing a JSON with userdata objects will
+--- return them as normal tables" — which is precisely the round trip used here. The same
+--- call can be run by hand at the console:
+---   Ext.IO.SaveFile("ModWright_probe_resources.json",
+---     Ext.Json.Stringify(Ext.Entity.Get(...).ActionResources, {IterateUserdata=true, MaxDepth=4}))
+---
+--- Deliberately NOT `Ext.Types.Serialize`: that call appears nowhere in API.md, so it is
+--- attested(engine) only, and this route does not need it.
+function Protocol.dumpComponent(component, maxDepth)
+    if component == nil then return nil, nil end
+    local json
+    local ok = pcall(function()
+        json = Ext.Json.Stringify(component, {
+            IterateUserdata = true,
+            AvoidRecursion = true,
+            StringifyInternalTypes = true,
+            MaxDepth = maxDepth or 4,
+        })
+    end)
+    if not ok or type(json) ~= "string" then return nil, nil end
+    local tbl
+    pcall(function() tbl = Ext.Json.Parse(json) end)
+    return tbl, json
+end
+
+--- Deep, order-insensitive value search used by the `contains` operator. Strings are matched
+--- as plain substrings; tables are searched over their encoded form, which is what makes
+--- `expect: { op: contains, value: "<subclass uuid>" }` work against class rows
+--- without pinning a field path the docs never gave.
+local function containsValue(observed, value)
+    if observed == nil then return false end
+    local needle = tostring(value)
+    if type(observed) == "string" then
+        return observed:find(needle, 1, true) ~= nil
+    end
+    if type(observed) == "table" then
+        for _, v in pairs(observed) do
+            if type(v) == "table" then
+                if containsValue(v, value) then return true end
+            elseif tostring(v) == needle then
+                return true
+            end
+        end
+        local blob = Protocol.encode(observed)
+        return blob:find(needle, 1, true) ~= nil
+    end
+    return tostring(observed) == needle
+end
+
+local function deepEqual(a, b)
+    if type(a) ~= "table" or type(b) ~= "table" then return a == b end
+    return Protocol.encode(a) == Protocol.encode(b)
+end
+
+--- Apply a probe's `expect` block
+--- (`{ op: "eq"|"ne"|"gte"|"lte"|"contains"|"absent", value: unknown }`).
+--- Returns "pass" | "fail" | "error" plus a short explanation for `evidence.expect`.
+function Protocol.evaluateExpect(observed, expect)
+    if type(expect) ~= "table" or expect.op == nil then return nil, nil end
+    local op = tostring(expect.op)
+    local value = expect.value
+
+    if op == "eq" then
+        return deepEqual(observed, value) and "pass" or "fail", "eq"
+    elseif op == "ne" then
+        return (not deepEqual(observed, value)) and "pass" or "fail", "ne"
+    elseif op == "gte" or op == "lte" then
+        local a, b = tonumber(observed), tonumber(value)
+        if a == nil or b == nil then
+            return "error", op .. " needs two numbers; observed=" .. tostring(observed)
+        end
+        if op == "gte" then return (a >= b) and "pass" or "fail", "gte" end
+        return (a <= b) and "pass" or "fail", "lte"
+    elseif op == "contains" then
+        return containsValue(observed, value) and "pass" or "fail", "contains"
+    elseif op == "absent" then
+        -- "absent" is true for nil, false, an empty string and an empty table: the four shapes
+        -- a probe uses to say "there is nothing here".
+        local empty = (observed == nil) or (observed == false) or (observed == "")
+        if not empty and type(observed) == "table" then
+            empty = (next(observed) == nil)
+        end
+        return empty and "pass" or "fail", "absent"
+    end
+    return "error", "unknown expect op: " .. op
+end
+
+-- ---------------------------------------------------------------------------
+-- Heartbeat
+-- ---------------------------------------------------------------------------
+
+--- The `bridge` block shared by heartbeats and results (`bridgeInfoSchema`, .strict()).
+function Protocol.info()
+    if Protocol.cachedInfo then return Protocol.cachedInfo end
+    local info = {
+        name = Protocol.BRIDGE_NAME,
+        version = Protocol.BRIDGE_VERSION,
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        context = Protocol.context,
+    }
+    -- `Ext.Utils.Version(): int32` — an integer; the schema wants a string.
+    local okV, v = pcall(function() return Ext.Utils.Version() end)
+    if okV and v ~= nil then info.runtimeVersion = tostring(v) end
+    -- `Ext.Utils.GameVersion(): string?`
+    local okG, g = pcall(function() return Ext.Utils.GameVersion() end)
+    if okG and g ~= nil then info.gameVersion = tostring(g) end
+    -- Static for the life of the Lua state; cached once both versions resolved, so the
+    -- 2 s heartbeat stops re-asking the extender (item 6 above). `context` is set by
+    -- Protocol.init before the first heartbeat.
+    if info.runtimeVersion and info.gameVersion then Protocol.cachedInfo = info end
+    return info
+end
+
+--- `Ext.Utils.GetGameState()` - current game state enum. Stringified: the schema wants a
+--- string and the enum's Lua representation is not pinned by API.md.
+function Protocol.gameState()
+    local ok, s = pcall(function() return Ext.Utils.GetGameState() end)
+    if ok and s ~= nil then return tostring(s) end
+    return nil
+end
+
+--- `Ext.Utils.GetCommandLineParams(): string[]` — evidence that the game
+--- was launched the confirmed way (`--skip-launcher` as a Steam launch option). Attested by
+--- API.md, which also prints an example containing "--skip-launcher"; still pcall-guarded and
+--- omitted rather than faked when an older extender does not have it (the mod's
+--- RequiredVersion is pinned at 21, below API.md's own example of 29).
+function Protocol.commandLine()
+    if Protocol.cachedCommandLine then return Protocol.cachedCommandLine end
+    local ok, params = pcall(function() return Ext.Utils.GetCommandLineParams() end)
+    if not ok or type(params) ~= "table" then return nil end
+    local out = Protocol.array({})
+    for _, p in ipairs(params) do out[#out + 1] = tostring(p) end
+    Protocol.cachedCommandLine = out -- the process's own argv does not change
+    return out
+end
+
+--- Write the heartbeat (`bridgeHeartbeatSchema`, .strict() — every key below is in it, and
+--- no key that is not). `writeRoot` is the fixed "<SE>" label paths.ts documents for BG3.
+function Protocol.writeHeartbeat()
+    local t0 = Log.monotonic()
+    local hb = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        bridge = Protocol.info(),
+        at = Protocol.isoNow(),
+        uptimeMs = math.max(0, Log.monotonic() - Protocol.loadedAtMs),
+        state = Protocol.state,
+        writeRoot = "<SE>",
+        osirisDegraded = Protocol.osirisDegraded,
+    }
+    if Protocol.lastRequestId then hb.lastRequestId = Protocol.lastRequestId end
+    if Protocol.lastResultId then hb.lastResultId = Protocol.lastResultId end
+    local gs = Protocol.gameState()
+    if gs then hb.gameState = gs end
+    local cl = Protocol.commandLine()
+    if cl then hb.commandLine = cl end
+    local t1 = Log.monotonic()
+    local json = Protocol.encode(hb)
+    local t2 = Log.monotonic()
+    Protocol.save(Protocol.heartbeatFile, json)
+    local t3 = Log.monotonic()
+    -- One breadcrumb, on the third heartbeat (the first two pay one-off costs), so the
+    -- next field run can say which half of the tick the extender's slow-callback warning
+    -- is measuring: the extender API reads, the JSON encode, or the file write.
+    Protocol.heartbeatCount = (Protocol.heartbeatCount or 0) + 1
+    if Protocol.heartbeatCount == 3 then
+        Log.info(("heartbeat cost: fields %.2f ms, encode %.2f ms, save %.2f ms")
+            :format(t1 - t0, t2 - t1, t3 - t2))
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- Result writing: result first, `done` marker second (the atomicity rule on the game side)
+-- ---------------------------------------------------------------------------
+
+--- `bytes` is `#json` — Lua's byte length of the exact string handed to SaveFile, which is
+--- what poll.ts compares against `Buffer.byteLength(resultRaw, "utf8")`. Nothing may be
+--- appended to `json` after this point (no trailing newline).
+function Protocol.writeResult(result)
+    local json = Protocol.encode(result)
+    local probeCount = 0
+    if type(result.probes) == "table" then probeCount = #result.probes end
+
+    local okResult = Protocol.save(Protocol.resultFile(result.id), json)
+    if not okResult then
+        Log.err("writeResult", "result file write failed for " .. tostring(result.id) ..
+            "; the done marker is deliberately NOT written, so ModWright retries rather than reading a partial file")
+        return false
+    end
+
+    local done = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        id = result.id,
+        nonce = result.nonce,
+        bytes = #json,
+        probeCount = probeCount,
+    }
+    local okDone = Protocol.save(Protocol.doneFile(result.id), Protocol.encode(done))
+    Log.info(("result %s written (%d bytes, %d probes, done marker %s)")
+        :format(tostring(result.id), #json, probeCount, okDone and "ok" or "FAILED"))
+    return okDone
+end
+
+--- Build a Result envelope (`bridgeResultSchema`, .strict()).
+function Protocol.buildResult(request, startedAt, probeResults, errors, disarm)
+    local result = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        id = tostring(request.id),
+        nonce = tostring(request.nonce),
+        startedAt = startedAt,
+        finishedAt = Protocol.isoNow(),
+        complete = true,
+        bridge = Protocol.info(),
+        probes = Protocol.array(probeResults or {}),
+        errors = Protocol.array(errors or {}),
+    }
+    if Protocol.osirisDegraded then
+        result.degraded = {
+            osiris = true,
+            reason = Protocol.osirisDegradedReason or
+                "Ext.Events.ResetCompleted fired in this Lua state; a mid-session `reset` degrades Osiris",
+        }
+    end
+    if disarm then result.disarm = disarm end
+    return result
+end
+
+--- One `skipped` ProbeResult, used for every probe in a refused request (the bridge
+--- writes a Result with the matching `disarm.reason` and every probe `skipped`).
+function Protocol.skippedProbe(probe, why)
+    return {
+        id = tostring((probe and probe.id) or "?"),
+        kind = tostring((probe and probe.kind) or "?"),
+        status = "skipped",
+        observed = nil,
+        evidence = { reason = why },
+        error = why,
+        ranAt = Protocol.isoNow(),
+    }
+end
+
+--- Write a refusal and consume the nonce so it is not rewritten on every poll.
+function Protocol.refuse(request, reason, detail)
+    local probes = {}
+    if type(request.probes) == "table" then
+        for i, p in ipairs(request.probes) do
+            probes[i] = Protocol.skippedProbe(p, "request disarmed: " .. reason)
+        end
+    end
+    local startedAt = Protocol.isoNow()
+    local result = Protocol.buildResult(request, startedAt, probes, {}, { reason = reason, detail = detail })
+    Protocol.state = "disarmed"
+    Protocol.lastRequestId = tostring(request.id)
+    if request.nonce ~= nil then Protocol.consumed[tostring(request.nonce)] = true end
+    Protocol.writeResult(result)
+    Protocol.lastResultId = tostring(request.id)
+    Log.info("REFUSED request " .. tostring(request.id) .. " (" .. reason .. "): " .. tostring(detail))
+    Protocol.writeHeartbeat()
+end
+
+-- ---------------------------------------------------------------------------
+-- Running a request
+-- ---------------------------------------------------------------------------
+
+local function finish(run)
+    if run.finished then return end
+    run.finished = true
+
+    local probes = {}
+    for i = 1, run.probeCount do
+        local r = run.results[i]
+        if r == nil then
+            local p = run.request.probes[i]
+            r = {
+                id = tostring((p and p.id) or ("probe-" .. i)),
+                kind = tostring((p and p.kind) or "?"),
+                status = "error",
+                observed = nil,
+                evidence = { reason = "no result recorded" },
+                error = "the bridge finished the batch before this probe produced a result (watchdog or harvest failure)",
+                ranAt = Protocol.isoNow(),
+            }
+        end
+        probes[i] = r
+    end
+
+    local result = Protocol.buildResult(run.request, run.startedAt, probes, run.errors, nil)
+    Protocol.state = "idle"
+    Protocol.writeResult(result)
+    Protocol.lastResultId = tostring(run.request.id)
+    Protocol.busy = false
+    Protocol.currentRun = nil
+    Protocol.writeHeartbeat()
+end
+
+--- Harvest every armed observe probe, then finish.
+local function harvest(run)
+    for _, entry in ipairs(run.observe) do
+        local ok, res = pcall(function()
+            return Protocol.dispatcher.harvest(entry.probe, run, entry.armed)
+        end)
+        if ok and type(res) == "table" then
+            run.results[entry.index] = res
+        else
+            run.results[entry.index] = {
+                id = tostring(entry.probe.id),
+                kind = tostring(entry.probe.kind),
+                status = "error",
+                observed = nil,
+                evidence = {},
+                error = "harvest failed: " .. tostring(res),
+                ranAt = Protocol.isoNow(),
+            }
+        end
+    end
+    finish(run)
+end
+
+--- Run every read/mutate probe, then either harvest immediately or after `window.seconds`.
+local function runReadPhase(run)
+    for i, probe in ipairs(run.request.probes) do
+        if run.results[i] == nil and not run.observeIndex[i] then
+            local ok, res = pcall(function() return Protocol.dispatcher.run(probe, run) end)
+            if ok and type(res) == "table" then
+                run.results[i] = res
+            else
+                run.results[i] = {
+                    id = tostring(probe.id),
+                    kind = tostring(probe.kind),
+                    status = "error",
+                    observed = nil,
+                    evidence = {},
+                    error = "dispatch failed: " .. tostring(res),
+                    ranAt = Protocol.isoNow(),
+                }
+            end
+        end
+    end
+
+    if #run.observe > 0 and run.windowSeconds > 0 then
+        Ext.Timer.WaitForRealtime(math.floor(run.windowSeconds * 1000), Log.guarded("harvest", function()
+            harvest(run)
+        end))
+    else
+        if #run.observe > 0 then
+            run.errors[#run.errors + 1] =
+                "the request carries observe probes but no window.seconds, so they were harvested immediately"
+        end
+        harvest(run)
+    end
+end
+
+--- Execute an accepted request. Never throws into the timer callback.
+function Protocol.execute(request)
+    local run = {
+        request = request,
+        probeCount = #request.probes,
+        results = {},
+        observe = {},
+        observeIndex = {},
+        errors = {},
+        finished = false,
+        startedAt = nil,
+    }
+    run.startedAt = Protocol.isoNow(run)
+    run.windowSeconds = tonumber((type(request.window) == "table" and request.window.seconds) or 0) or 0
+
+    Protocol.busy = true
+    Protocol.state = "running"
+    Protocol.lastRequestId = tostring(request.id)
+    Protocol.consumed[tostring(request.nonce)] = true
+    Protocol.currentRun = run
+    Protocol.writeHeartbeat()
+
+    Log.info(("ARMED request %s: %d probe(s), window %ss, allowMutate=%s")
+        :format(tostring(request.id), run.probeCount, tostring(run.windowSeconds), tostring(request.allowMutate == true)))
+
+    -- Arm phase. `mutate` is gated here on capability tiers (they replace the older
+    -- "mutate runs only under allowMutate" boolean): a mutate probe runs only when
+    -- the request was granted the `session` tier, which Protocol.grantsTier resolves — honouring
+    -- the retired `allowMutate: true` alias for one release. `observe` registers its listener
+    -- now, before the settle delay, so the window really is the window the request asked for.
+    local settleSeconds = 0
+    for i, probe in ipairs(request.probes) do
+        local effect = tostring(probe.effect or "read")
+        local s = tonumber(probe.settleSeconds) or 0
+        if s > settleSeconds then settleSeconds = s end
+
+        if effect == "mutate" and not Protocol.grantsTier(request, "session") then
+            run.results[i] = Protocol.skippedProbe(probe,
+                "effect is \"mutate\" (session tier) and the request was not granted the \"session\" tier; " ..
+                "grant it via bridge.policy mode: workbench, grant: [\"session\"], or the retired allowMutate: true alias")
+        elseif effect == "observe" then
+            local ok, armed = pcall(function() return Protocol.dispatcher.arm(probe, run) end)
+            if not ok then
+                run.results[i] = {
+                    id = tostring(probe.id),
+                    kind = tostring(probe.kind),
+                    status = "error",
+                    observed = nil,
+                    evidence = {},
+                    error = "arm failed: " .. tostring(armed),
+                    ranAt = Protocol.isoNow(),
+                }
+            else
+                run.observeIndex[i] = true
+                run.observe[#run.observe + 1] = { index = i, probe = probe, armed = armed }
+            end
+        end
+    end
+
+    -- Watchdog: a lost harvest timer must not park the bridge in `running` forever.
+    local budgetMs = math.floor((settleSeconds + run.windowSeconds) * 1000) + Protocol.WATCHDOG_SLACK_MS
+    Ext.Timer.WaitForRealtime(budgetMs, Log.guarded("watchdog", function()
+        if not run.finished then
+            run.errors[#run.errors + 1] =
+                ("the bridge watchdog fired after %d ms; probes without a result are reported as errors"):format(budgetMs)
+            Log.err("watchdog", "request " .. tostring(request.id) .. " did not finish in " .. tostring(budgetMs) .. " ms")
+            finish(run)
+        end
+    end))
+
+    if settleSeconds > 0 then
+        Ext.Timer.WaitForRealtime(math.floor(settleSeconds * 1000), Log.guarded("settle", function()
+            runReadPhase(run)
+        end))
+    else
+        runReadPhase(run)
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- Polling and arming
+-- ---------------------------------------------------------------------------
+
+--- One poll. Reads the marker and the request, applies every arming check in
+--- order, and either refuses in writing or executes.
+function Protocol.pollOnce()
+    if Protocol.busy then return end
+
+    local markerRaw = Protocol.load(Protocol.FILES.requestMarker)
+    if markerRaw == nil or markerRaw == "" then return end
+    -- Observed in game: ModWright leaves the marker and
+    -- request files in place after a request completes, so every poll after that was
+    -- loading and decoding both files only to find the nonce consumed below. The extender
+    -- flagged the guarded tick as a slow callback (5 to 25 ms) on the console.
+    -- An unchanged marker whose nonce is already consumed needs no decode and no second read.
+    if markerRaw == Protocol.lastConsumedMarkerRaw then return end
+    local marker = Protocol.decode(markerRaw)
+    if type(marker) ~= "table" then return end
+
+    local requestRaw = Protocol.load(Protocol.FILES.request)
+    if requestRaw == nil or requestRaw == "" then return end
+    local request = Protocol.decode(requestRaw)
+    if type(request) ~= "table" then return end
+
+    local reqNonce = tostring(request.nonce or "")
+    local mkNonce = tostring(marker.nonce or "")
+    local reqId = tostring(request.id or "")
+    local mkId = tostring(marker.id or "")
+
+    -- Already handled (executed or refused). Silence: the nonce is consumed
+    -- precisely so a refusal is not rewritten on every poll.
+    if Protocol.consumed[reqNonce] then
+        Protocol.lastConsumedMarkerRaw = markerRaw
+        return
+    end
+
+    -- Identity mismatch. ModWright writes the request FIRST and the marker SECOND
+    -- (arm.ts `planArmRequest`), so a poll landing between the two writes legitimately sees a
+    -- new request beside the previous marker. Refusing that in writing would consume a nonce
+    -- that was about to become valid, so a mismatch must be STABLE across two polls (>= 1 s
+    -- apart) before it is treated as a real nonce mismatch rather than a torn read.
+    if reqNonce ~= mkNonce or reqId ~= mkId then
+        local key = reqId .. "/" .. reqNonce .. "|" .. mkId .. "/" .. mkNonce
+        if Protocol.pendingMismatch and Protocol.pendingMismatch.key == key then
+            Protocol.pendingMismatch = nil
+            Protocol.consumed[mkNonce] = true
+            Protocol.refuse(request, "nonce-mismatch",
+                ("marker names id=%s nonce=%s; request names id=%s nonce=%s (stable across two polls, so not a torn write)")
+                    :format(mkId, mkNonce, reqId, reqNonce))
+        else
+            Protocol.pendingMismatch = { key = key }
+        end
+        return
+    end
+    Protocol.pendingMismatch = nil
+
+    -- Byte length. A disagreement is the half-written case, which has no `disarm.reason`
+    -- on purpose: the right answer is to wait, not to refuse.
+    local markerBytes = tonumber(marker.bytes)
+    if markerBytes == nil or #requestRaw ~= markerBytes then
+        Protocol.tornReads = Protocol.tornReads + 1
+        if Protocol.tornReads % 20 == 0 then
+            Log.info(("request %s still incomplete after %d polls: marker says %s bytes, file is %d")
+                :format(reqId, Protocol.tornReads, tostring(marker.bytes), #requestRaw))
+        end
+        return
+    end
+    Protocol.tornReads = 0
+
+    -- protocolVersion: a bridge reading a different version writes
+    -- `disarm.reason = "protocol-mismatch"` rather than guessing.
+    local reqVersion = tonumber(request.protocolVersion)
+    local mkVersion = tonumber(marker.protocolVersion)
+    if reqVersion ~= Protocol.PROTOCOL_VERSION or mkVersion ~= Protocol.PROTOCOL_VERSION then
+        Protocol.refuse(request, "protocol-mismatch",
+            ("this bridge speaks protocolVersion %d; the request says %s and its marker says %s. Re-run `bridge stage`, then `deploy --variant withBridge`.")
+                :format(Protocol.PROTOCOL_VERSION, tostring(request.protocolVersion), tostring(marker.protocolVersion)))
+        return
+    end
+
+    -- game
+    if tostring(request.game) ~= "baldursgate3" then
+        Protocol.refuse(request, "wrong-game",
+            ("this is the Baldur's Gate 3 bridge; the request names game=%s"):format(tostring(request.game)))
+        return
+    end
+
+    -- probes present
+    if type(request.probes) ~= "table" or #request.probes == 0 then
+        Protocol.refuse(request, "protocol-mismatch", "the request carries no probes")
+        return
+    end
+
+    -- armedUntil
+    local nowSecs = Protocol.epochSeconds()
+    local untilSecs = Protocol.parseIso(tostring(request.armedUntil or ""))
+    if untilSecs == nil then
+        Protocol.refuse(request, "expired",
+            ("armedUntil is not a parseable ISO 8601 UTC timestamp: %s"):format(tostring(request.armedUntil)))
+        return
+    end
+    if nowSecs == nil then
+        -- No clock at all: honouring an expiry we cannot evaluate would break the one
+        -- guarantee arming exists to give (never fire in normal play).
+        Protocol.refuse(request, "expired",
+            "the bridge has no wall clock (Ext.Timer.ClockEpoch and os.time both unavailable), so it cannot prove the request is still armed")
+        return
+    end
+    if nowSecs >= untilSecs then
+        Protocol.refuse(request, "expired",
+            ("armedUntil %s has passed (bridge clock %s)"):format(tostring(request.armedUntil), Protocol.isoFromEpoch(nowSecs)))
+        return
+    end
+
+    Protocol.execute(request)
+end
+
+-- ---------------------------------------------------------------------------
+-- Timers (Ext.Timer.WaitForRealtime, re-armed inside the callback)
+-- ---------------------------------------------------------------------------
+-- Realtime rather than WaitFor so a paused or loading game still answers; not
+-- Ext.Events.Tick, which API.md §"Engine and SE Events" puts at "roughly every 33ms", where
+-- a per-tick Lua error floods the log for latency this bridge does not need.
+
+local function armHeartbeatTimer()
+    Ext.Timer.WaitForRealtime(Protocol.HEARTBEAT_MS, Log.guarded("heartbeat", function()
+        Protocol.writeHeartbeat()
+        armHeartbeatTimer()
+    end))
+end
+
+local function armPollTimer()
+    Ext.Timer.WaitForRealtime(Protocol.POLL_MS, Log.guarded("poll", function()
+        Protocol.pollOnce()
+        armPollTimer()
+    end))
+end
+
+--- Start the heartbeat. Idempotent; called at chunk scope so a heartbeat exists from the
+--- moment the bridge loads (it is rewritten every 2 s while the bridge is loaded),
+--- including at the main menu where `bridge status` needs it.
+function Protocol.startHeartbeat()
+    if Protocol.heartbeatStarted then return end
+    Protocol.heartbeatStarted = true
+    Protocol.writeHeartbeat()
+    armHeartbeatTimer()
+    Log.info("heartbeat started (" .. Protocol.heartbeatFile .. ", every " .. Protocol.HEARTBEAT_MS .. " ms)")
+end
+
+--- Start request polling. Idempotent; called from SessionLoaded and again from
+--- ResetCompleted, because a console `reset` reloads the Lua
+--- state WITHOUT re-running the session, so SessionLoaded may never fire again.
+function Protocol.startPolling()
+    if Protocol.pollingStarted then return end
+    Protocol.pollingStarted = true
+    armPollTimer()
+    Log.info("request polling started (" .. Protocol.FILES.request .. ", every " .. Protocol.POLL_MS .. " ms)")
+end
+
+--- Called from Ext.Events.ResetCompleted. API.md §"Engine and SE Events": `ResetCompleted` —
+--- "Thrown when `Ext.Debug.Reset()` or `reset` console command completes on the client or
+--- server. Indicates that the Lua state was reloaded." Observed consequence
+--- this flag records: a mid-session `reset` degrades Osiris; Osi queries return junk and Osi
+--- calls silently no-op afterward.
+function Protocol.markOsirisDegraded()
+    Protocol.osirisDegraded = true
+    Protocol.osirisDegradedReason =
+        "Ext.Events.ResetCompleted fired: the Lua state was reloaded mid-session, which degrades Osiris; a save reload (F8) is the only clean fix."
+    Log.info("ResetCompleted: osirisDegraded = true; probe bg3.osiris.health measures it")
+end
+
+--- Wire the dispatch table and the per-context file names, then start the heartbeat.
+function Protocol.init(opts)
+    Protocol.context = opts.context or "server"
+    Protocol.dispatcher = opts.dispatcher
+    Protocol.heartbeatFile = opts.heartbeatFile or Protocol.FILES.heartbeatServer
+    Protocol.loadedAtMs = Log.monotonic()
+    return Protocol
+end
+
+return Protocol