modwright 0.1.0

package/bridges/cp2077-cet/ModWrightBridge/protocol.lua

@@ -0,0 +1,1306 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / protocol.lua — write-root discovery, the log-only fallback, JSON
+-- framing, nonce arming, the heartbeat and the request state machine. This is the CET half
+-- of the bridge protocol, and its output is parsed byte-for-byte by
+-- src/core/bridge/{types,paths,poll}.ts. Change nothing here without re-reading both.
+--
+-- ============================================================================
+-- WHAT IS ATTESTED HERE, AND WHAT IS NOT
+-- ============================================================================
+-- The ONLY sources that may attest a CET call are the CyberEngineTweaks wiki pages, shipped
+-- CET mods, and knowledge/cyberpunk2077/*.yaml facts whose status is `verified`. Each
+-- call's first use below carries its source as a comment.
+--
+-- ATTESTED and used freely:
+--   `print(...)`                      used by shipped CET mods
+--   `string.format(...)`              used by shipped CET mods
+--   `table.concat/table.insert`       used by shipped CET mods
+--   `pcall(fn)`                       used by shipped CET mods
+--   `ipairs`, `tostring`              used by shipped CET mods
+--   `registerForEvent(name, fn)`      used by shipped CET mods
+--   a returned table for GetMod()     shipped CET mods; knowledge fact
+--                                     cp2077.process.cet-mods-sandboxed
+--                                     (status verified, 2.31, observed in game 2026-08-16)
+--   dt accumulation in onUpdate       shipped CET mods (the ONLY attested timer)
+--
+-- NOT ATTESTED BY ANY SOURCE — every one of these is feature-detected at load,
+-- reported in the heartbeat's capability line, and can never crash the mod:
+--   `io` (io.open/read/write/close)   nothing attests CET's `io` for a mod at all; it was
+--                                     observed nil only in the console (2026-09-08).
+--   `json` (a built-in decoder)       used only if `json.decode` is actually a function.
+--   `os` (os.time/os.date/os.clock)   no wall clock is attested; see "TIME" below.
+--   `math`                            not used by either shipped mod; guarded all the same.
+--   `Cron`, `Observe`, `ObserveAfter` CET extras that no source here mentions. Never called;
+--                                     their presence is only reported.
+--   `TweakDB:GetRecord/GetFlat`       reported, and used only by the two probes the catalogue
+--                                     marks `unverified` (see probes.lua).
+--   `require` / `dofile`              the module loader ladder lives in init.lua, not here.
+--
+-- ============================================================================
+-- TIME
+-- ============================================================================
+-- Every timestamp this bridge writes is read on the Node side by `Date.parse`
+-- (`iso8601Schema`, src/core/bridge/types.ts), so it must be a parseable ISO 8601 UTC
+-- string. CET attests no clock at all. Two clocks are therefore used:
+--   * MONOTONIC: `dt` accumulated in onUpdate (the common CET pattern). Always available,
+--     and the only thing the poll/heartbeat/settle intervals are ever measured with.
+--   * WALL: `os.time()` when the sandbox has it. When it does not, the bridge ADOPTS the
+--     `issuedAt` of the first request it sees as an anchor and counts monotonic seconds from
+--     there. Until a request arrives its timestamps are Unix-epoch offsets, which ModWright
+--     will classify as a stale heartbeat — honest, and named in the capability line rather
+--     than papered over with an invented date.
+--   Arming without a wall clock is handled in `Protocol.pollOnce` (see ARMING WITHOUT A
+--   CLOCK there); it is the one place where the missing clock changes a decision instead of
+--   just a displayed value.
+--
+-- ============================================================================
+-- WHY THIS FILE CARRIES ITS OWN JSON ENCODER
+-- ============================================================================
+-- Same reason as the BG3 bridge's Protocol.lua, and the reason survives the change of
+-- runtime: an empty Lua table is both an array and an object, and nothing on disk says which
+-- one CET's `json` global (if it even exists) would emit. The Node schemas are `.strict()`
+-- and typed — `errors` and `probes` are `z.array(...)`, `evidence` is `z.record(...)` — and
+-- poll.ts's `tryReadComplete` SILENTLY DISCARDS a result that fails to parse, so an empty
+-- `errors` emitted as `{}` reads back as a bridge that never answered. `Protocol.array(t)`
+-- tags a list: a tagged empty table is always `[]`, an untagged empty table always `{}`.
+-- Decoding is the opposite case — the request is written by ModWright and its shape is
+-- known — so `json.decode` is used there when it exists, and a small in-house decoder
+-- otherwise. The heartbeat says which.
+
+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 Cyberpunk file names. These basenames must equal `CP2077_FILES` in
+--- src/core/bridge/paths.ts exactly.
+Protocol.FILES = {
+    heartbeat     = "modwright_hb.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
+
+--- The write-root candidate list, in order, as relative path PREFIXES. The first
+--- one whose `io.open(prefix .. "modwright_hb.json", "w")` succeeds wins. The absolute path
+--- is unknowable from Lua, which is exactly why the heartbeat reports the candidate that
+--- worked and ModWright polls the matching absolute directories under the install
+--- (`bridgeCandidateDirs`, src/core/bridge/paths.ts).
+---
+--- The empty prefix is first ON PURPOSE and is expected to be the one that wins: "All pathing
+--- is now relative to mod (breaking change, includes all io functions, dofile() and such
+--- included)" (CET Nexus changelog, version 1.10). Under that rule "" IS this mod's own
+--- folder, which is the directory ModWright polls first. The other two are kept below it for
+--- a CET that does not behave that way; under 1.10 they would resolve to subdirectories of
+--- the mod folder that do not exist, and simply fail.
+Protocol.WRITE_ROOT_CANDIDATES = {
+    "",
+    "mods/ModWrightBridge/",
+    "plugins/cyber_engine_tweaks/mods/ModWrightBridge/",
+}
+
+--- A 1.0 s accumulator, the common CET pattern. The
+--- heartbeat is 2 s. Both are measured in accumulated `dt`, the only timer CET
+--- attests.
+Protocol.POLL_SECONDS = 1.0
+Protocol.HEARTBEAT_SECONDS = 2.0
+--- Log-only mode has no file for ModWright to poll, so the heartbeat is PRINTED instead —
+--- far less often, because the CET log is read by a human and by `triage_logs`, not by a
+--- 500 ms poller.
+Protocol.LOG_HEARTBEAT_SECONDS = 15.0
+--- A run that never finishes must not park the bridge in `running` forever, where poll.ts
+--- would only ever return its "hung" verdict.
+Protocol.WATCHDOG_SLACK_SECONDS = 30.0
+
+--- Machine-readable log tags.
+Protocol.LOG_PREFIX = "[ModWrightBridge]"
+Protocol.RESULT_TAG = "[MODWRIGHT-RESULT]"
+Protocol.DONE_TAG = "[MODWRIGHT-DONE]"
+Protocol.HEARTBEAT_TAG = "[MODWRIGHT-HEARTBEAT]"
+
+-- ---------------------------------------------------------------------------
+-- Runtime state (all in memory; a CET mod reload clears it, which is why arming carries an
+-- `armedUntil`)
+-- ---------------------------------------------------------------------------
+Protocol.context = "cet"
+Protocol.state = "idle"
+Protocol.consumed = {}
+Protocol.lastRequestId = nil
+Protocol.lastResultId = nil
+Protocol.uptime = 0.0
+Protocol.pollAcc = 0.0
+Protocol.hbAcc = 0.0
+Protocol.logHbAcc = 0.0
+Protocol.run = nil
+Protocol.dispatcher = nil
+Protocol.firstPollDone = false
+Protocol.preexistingNonce = nil
+Protocol.pendingMismatch = nil
+Protocol.tornReads = 0
+Protocol.loaderUsed = "?"
+--- Set on the first `tick`, when RTTI-dependent globals can honestly be asked about (CET 1.14).
+Protocol.rttiRechecked = false
+
+--- Transport, decided by `Protocol.discoverWriteRoot()`: "file" or "log".
+Protocol.transport = "log"
+--- The candidate that worked, as the relative path of the heartbeat file, or "log-only".
+Protocol.writeRoot = "log-only"
+--- The relative prefix that won ("" for the game's own working directory).
+Protocol.writeRootPrefix = nil
+--- One string per failed candidate, plus the capability line. Rides in the heartbeat's
+--- `writeRootErrors` (see `Protocol.writeHeartbeat`).
+Protocol.writeRootErrors = {}
+
+--- Wall-clock anchor: `epoch` seconds observed at monotonic `uptime`.
+Protocol.clockAnchorEpoch = nil
+Protocol.clockAnchorUptime = 0.0
+Protocol.clockSource = "none"
+
+-- ---------------------------------------------------------------------------
+-- Capability detection
+-- ---------------------------------------------------------------------------
+-- Nothing below calls anything: it only asks whether a global is there. Every capability is
+-- consulted through `Protocol.caps` at the point of use, and every use is additionally
+-- pcall-guarded, because "the global exists" and "the call works" are different claims and
+-- only the first one is testable from here.
+
+-- Globals are referenced by NAME inside a closure, never through `_G`. CET builds each mod's
+-- environment as a fresh table that falls back to a whitelisted copy of the globals
+-- (CyberEngineTweaks/src/scripting/Sandbox.cpp:9 `sol::environment(state, sol::create,
+-- aBaseEnvironment)`; the whitelist is s_cGlobalObjectsWhitelist in LuaSandbox.cpp), and
+-- `_G` is not on that whitelist. So `_G[name]` indexes nil, the pcall fails, and every
+-- capability reads as absent — which is exactly what was observed in game (2026-09-08): the bridge printed
+-- heartbeats and wrote no file although the sandbox does provide `io` (LuaSandbox.cpp
+-- InitializeIOForSandbox). A free name in this chunk resolves through the sandbox
+-- environment, which is the only lookup that answers the question being asked.
+local function globalIs(get, wanted)
+    local ok, v = pcall(get)
+    if not ok then return false end
+    return type(v) == wanted
+end
+
+Protocol.caps = {}
+
+function Protocol.detectCapabilities()
+    local c = {}
+    -- The plain Lua half. `io` is expected to be here: CET 1.10 "stripped ImGui, json, io and
+    -- dofile and such from console sandbox" — from the CONSOLE sandbox, while mods keep them
+    -- with all pathing relative to the mod's own folder (CET Nexus changelog, version 1.10).
+    -- The `io.open` check of 2026-09-08 was typed in the console, so it tested the half that was
+    -- deliberately stripped and says nothing about this one.
+    c.io = globalIs(function() return io end, "table")
+    c.ioOpen = c.io and (type(io.open) == "function")
+    -- Added for mods in CET 1.9.2 (CET Nexus changelog), so this is expected to be true and
+    -- the in-house decoder below is the fallback, not the plan. Only `decode` matters here;
+    -- encoding stays ours, because nothing attests how CET's `json.encode` orders keys or
+    -- distinguishes an empty array from an empty object, and the result's `bytes` framing
+    -- depends on the exact string.
+    c.json = globalIs(function() return json end, "table") and (type(json.decode) == "function")
+    c.os = globalIs(function() return os end, "table")
+    c.osTime = c.os and (type(os.time) == "function")
+    -- "os.remove and os.rename were not working properly" was fixed in CET 1.12.0 (CET Nexus
+    -- changelog), so a result can be committed by rename instead of being read half-written.
+    c.osRename = c.os and (type(os.rename) == "function")
+    c.math = globalIs(function() return math end, "table")
+    Protocol.caps = c
+    Protocol.detectRttiCapabilities()
+    return Protocol.caps
+end
+
+--- The RTTI-dependent half, re-run on the first tick.
+---
+--- CET 1.14: `GetMod()` and RTTI-dependent types are only available AFTER onInit (CET Nexus
+--- changelog, version 1.14). Nothing here CALLS any of them — `globalIs` reads a global by name and
+--- a `type()` test, never an invocation — but a global that is not bound yet reads as absent,
+--- so onInit's answer would be a lie by omission. `Protocol.tick` runs this once more on its
+--- first frame, and the capability line the heartbeat carries is the corrected one.
+function Protocol.detectRttiCapabilities()
+    local c = Protocol.caps
+    c.TweakDB = globalIs(function() return TweakDB end, "table") or globalIs(function() return TweakDB end, "userdata")
+    c.Cron = globalIs(function() return Cron end, "table")
+    c.Observe = globalIs(function() return Observe end, "function")
+    c.GetMod = globalIs(function() return GetMod end, "function")
+    c.Game = globalIs(function() return Game end, "table") or globalIs(function() return Game end, "userdata")
+    return c
+end
+
+--- `math` is not used by either shipped mod, so it is not attested either. These two locals
+--- are the whole dependency, and both have a pure-Lua fallback.
+local function floorNum(n)
+    if type(math) == "table" and type(math.floor) == "function" then return math.floor(n) end
+    if n >= 0 then return n - (n % 1) end
+    local t = n - (n % 1)
+    if t > n then t = t - 1 end
+    return t
+end
+
+local function absNum(n)
+    if n < 0 then return -n end
+    return n
+end
+
+-- ---------------------------------------------------------------------------
+-- Logging (`print("[ModWright] …")` breadcrumbs; the prefix used here is the
+-- `[ModWrightBridge]` one the mod folder is named for, so a log grep finds only this mod)
+-- ---------------------------------------------------------------------------
+-- `print(...)` is the console output used by shipped CET mods.
+
+-- `print` reaches the console; observed in game, it never reached the mod's own log file
+-- (`ModWrightBridge.log` stayed empty across three launches). CET gives each mod an
+-- `spdlog` table bound to that file (CET changelog 1.9.1: "you can also use spdlog to print
+-- in your log"; LuaSandbox.cpp InitializeLoggerForSandbox), so the same line goes there too
+-- when the global exists, which is what makes the banner recoverable from disk.
+function Protocol.log(msg)
+    local line = Protocol.LOG_PREFIX .. " " .. tostring(msg)
+    pcall(function() print(line) end)
+    pcall(function()
+        if type(spdlog) == "table" and type(spdlog.info) == "function" then spdlog.info(line) end
+    end)
+    return line
+end
+
+function Protocol.err(where, msg)
+    return Protocol.log("ERROR [" .. tostring(where) .. "] " .. tostring(msg))
+end
+
+--- Wrap a callback so a raw error can never escape into a CET event handler. Shipped
+--- mods wrap every engine call this way.
+function Protocol.guarded(where, fn)
+    return function(...)
+        local ok, e = pcall(fn, ...)
+        if not ok then Protocol.err(where, e) end
+        return ok
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- JSON encoding (see the header note for why this is not the `json` global)
+-- ---------------------------------------------------------------------------
+
+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` rather than `%z`: `%z` is gone in Lua 5.2+ and the lint step 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 == 1 / 0 or n == -1 / 0 then return "null" end               -- +/-inf without math.huge
+    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; these
+        -- files are diffed, and in log-only mode read by eye.
+        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 handles reach this encoder only after probes.lua has
+    -- coerced them. Anything else is REPORTED, never guessed at — an engine object silently
+    -- encoded as "{}" would read as a successful probe with no evidence.
+    return encodeString("<unencodable:" .. t .. ">")
+end
+
+--- Encode a value as compact JSON. Never throws; always returns a string. The output has no
+--- newline in it anywhere, which is what lets `io.open(path, "w")` (text mode on Windows)
+--- write exactly `#json` bytes — see `Protocol.writeFile`.
+function Protocol.encode(value, maxDepth)
+    local ok, out = pcall(function()
+        return encodeValue(value, 1, {}, maxDepth or 12)
+    end)
+    if ok and type(out) == "string" then return out end
+    return '{"encodeError":' .. encodeString(tostring(out)) .. "}"
+end
+
+-- ---------------------------------------------------------------------------
+-- JSON decoding: the `json` global when it exists, otherwise the decoder below
+-- ---------------------------------------------------------------------------
+-- The in-house decoder handles exactly what the Request and Marker schemas
+-- contain: objects, arrays, strings (with the six short escapes and \uXXXX), numbers,
+-- true/false/null. It is deliberately strict — a trailing comma or an unquoted key is an
+-- error, not a guess — because the alternative to a parse failure here is executing a
+-- request nobody wrote.
+
+local decodeValueAt
+
+local function skipWs(s, i)
+    while true do
+        local c = s:sub(i, i)
+        if c == " " or c == "\t" or c == "\r" or c == "\n" then i = i + 1 else return i end
+    end
+end
+
+local function utf8FromCodepoint(cp)
+    if cp < 0x80 then return string.char(cp) end
+    if cp < 0x800 then
+        return string.char(0xC0 + floorNum(cp / 0x40), 0x80 + (cp % 0x40))
+    end
+    return string.char(
+        0xE0 + floorNum(cp / 0x1000),
+        0x80 + (floorNum(cp / 0x40) % 0x40),
+        0x80 + (cp % 0x40))
+end
+
+local SHORT_ESCAPES = {
+    ['"'] = '"', ["\\"] = "\\", ["/"] = "/",
+    b = "\b", f = "\f", n = "\n", r = "\r", t = "\t",
+}
+
+local function decodeStringAt(s, i)
+    -- i points at the opening quote.
+    local out = {}
+    i = i + 1
+    while true do
+        local c = s:sub(i, i)
+        if c == "" then return nil, i, "unterminated string" end
+        if c == '"' then return table.concat(out), i + 1, nil end
+        if c == "\\" then
+            local e = s:sub(i + 1, i + 1)
+            local short = SHORT_ESCAPES[e]
+            if short then
+                out[#out + 1] = short
+                i = i + 2
+            elseif e == "u" then
+                local hex = s:sub(i + 2, i + 5)
+                if not hex:match("^%x%x%x%x$") then return nil, i, "bad \\u escape" end
+                local cp = tonumber(hex, 16)
+                -- Surrogate halves are passed through as U+FFFD rather than pair-decoded:
+                -- nothing in a request id, nonce, probe kind or TweakDB path is outside the
+                -- BMP, and inventing a pair decoder would be untested code on a path that
+                -- never runs.
+                if cp >= 0xD800 and cp <= 0xDFFF then cp = 0xFFFD end
+                out[#out + 1] = utf8FromCodepoint(cp)
+                i = i + 6
+            else
+                return nil, i, "unknown escape \\" .. tostring(e)
+            end
+        else
+            out[#out + 1] = c
+            i = i + 1
+        end
+    end
+end
+
+local function decodeNumberAt(s, i)
+    local body = s:match("^%-?%d+%.?%d*[eE]?[%+%-]?%d*", i)
+    if body == nil or body == "" then return nil, i, "bad number" end
+    local n = tonumber(body)
+    if n == nil then return nil, i, "bad number: " .. body end
+    return n, i + #body, nil
+end
+
+decodeValueAt = function(s, i, depth)
+    if depth > 32 then return nil, i, "nesting too deep" end
+    i = skipWs(s, i)
+    local c = s:sub(i, i)
+    if c == "" then return nil, i, "unexpected end of input" end
+
+    if c == "{" then
+        local obj = {}
+        i = skipWs(s, i + 1)
+        if s:sub(i, i) == "}" then return obj, i + 1, nil end
+        while true do
+            i = skipWs(s, i)
+            if s:sub(i, i) ~= '"' then return nil, i, "object key must be a string" end
+            local key, ni, e = decodeStringAt(s, i)
+            if e then return nil, ni, e end
+            i = skipWs(s, ni)
+            if s:sub(i, i) ~= ":" then return nil, i, "expected ':' after object key" end
+            local val
+            val, i, e = decodeValueAt(s, i + 1, depth + 1)
+            if e then return nil, i, e end
+            obj[key] = val
+            i = skipWs(s, i)
+            local d = s:sub(i, i)
+            if d == "," then i = i + 1
+            elseif d == "}" then return obj, i + 1, nil
+            else return nil, i, "expected ',' or '}' in object" end
+        end
+    end
+
+    if c == "[" then
+        local arr = {}
+        i = skipWs(s, i + 1)
+        if s:sub(i, i) == "]" then return Protocol.array(arr), i + 1, nil end
+        while true do
+            local val, e
+            val, i, e = decodeValueAt(s, i, depth + 1)
+            if e then return nil, i, e end
+            arr[#arr + 1] = val
+            i = skipWs(s, i)
+            local d = s:sub(i, i)
+            if d == "," then i = i + 1
+            elseif d == "]" then return Protocol.array(arr), i + 1, nil
+            else return nil, i, "expected ',' or ']' in array" end
+        end
+    end
+
+    if c == '"' then return decodeStringAt(s, i) end
+    if s:sub(i, i + 3) == "true" then return true, i + 4, nil end
+    if s:sub(i, i + 4) == "false" then return false, i + 5, nil end
+    if s:sub(i, i + 3) == "null" then return nil, i + 4, nil end
+    if c == "-" or c:match("%d") then return decodeNumberAt(s, i) end
+    return nil, i, "unexpected character " .. string.format("%q", c)
+end
+
+--- Which decoder this bridge is using, reported in the heartbeat's capability line.
+Protocol.decoderName = "in-house"
+
+--- Decode a JSON document. Returns nil on any failure — a request that does not parse is
+--- never half-applied.
+function Protocol.decode(raw)
+    if type(raw) ~= "string" or raw == "" then return nil end
+    if Protocol.caps.json then
+        local ok, v = pcall(function() return json.decode(raw) end)
+        if ok and type(v) == "table" then return v end
+        -- The global exists but did not answer: fall through to the in-house decoder rather
+        -- than reporting the request as unreadable.
+    end
+    local ok, value, _, e = pcall(function()
+        local v, i, err = decodeValueAt(raw, 1, 1)
+        return v, i, err
+    end)
+    if not ok then return nil end
+    if e ~= nil then return nil end
+    if type(value) ~= "table" then return nil end
+    return value
+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: every `io` call in this bridge is here, and every one is pcall-guarded
+-- ---------------------------------------------------------------------------
+-- UNVERIFIED (nothing attests CET's `io` for a mod). If `io` is absent or
+-- `io.open` refuses every candidate, `Protocol.transport` becomes "log" and nothing below is
+-- ever called again.
+
+--- Open a file, or return nil plus the error string `io.open` gave. Never throws.
+local function tryOpen(path, mode)
+    if not Protocol.caps.ioOpen then return nil, "io.open is not available in this CET sandbox" end
+    local ok, f, e = pcall(function() return io.open(path, mode) end)
+    if not ok then return nil, "io.open threw: " .. tostring(f) end
+    if f == nil then return nil, tostring(e) end
+    return f, nil
+end
+
+--- Read a whole file as bytes. "rb" so a Windows text-mode read can never drop a byte the
+--- marker's `bytes` counted: ModWright writes the request pretty-printed (arm.ts:74), so it
+--- DOES contain newlines and the framing check is only exact in binary mode.
+function Protocol.readFile(relPath)
+    local f, e = tryOpen(relPath, "rb")
+    if f == nil then return nil, e end
+    local raw
+    local ok = pcall(function() raw = f:read("*a") end)
+    pcall(function() f:close() end)
+    if not ok or type(raw) ~= "string" then return nil, "read failed" end
+    return raw, nil
+end
+
+--- Write a whole file. Mode "w" and not "wb" on purpose: it is the mode the
+--- original console check used, so what the bridge does is exactly what that console line
+--- proved. Safe because `Protocol.encode` never emits a newline, so text-mode translation
+--- has nothing to translate and `#json` stays the true byte count.
+function Protocol.writeFile(relPath, content)
+    local f, e = tryOpen(relPath, "w")
+    if f == nil then return false, e end
+    local ok = pcall(function() f:write(content) end)
+    pcall(function() f:close() end)
+    if not ok then return false, "write failed" end
+    return true, nil
+end
+
+--- Write, then commit by rename — for the result file only.
+---
+--- "os.remove and os.rename were not working properly" was FIXED in CET 1.12.0 (CET Nexus
+--- changelog), so a result can be written to a `.tmp` sibling and moved into place, which
+--- closes the window where ModWright could read a result file the bridge is still writing.
+--- This does NOT replace the marker: the completeness test is the `done` file's
+--- `bytes` against the result's real byte length, that is what the Node side checks, and it
+--- stays exactly as it was. This only makes the torn window smaller on installs where the
+--- rename works. When `os.rename` is missing or refuses, the plain write is used and the
+--- marker catches what it always caught.
+function Protocol.writeFileCommitted(relPath, content)
+    if not Protocol.caps.osRename then return Protocol.writeFile(relPath, content) end
+    local tmpPath = relPath .. ".tmp"
+    local okWrite, e = Protocol.writeFile(tmpPath, content)
+    if not okWrite then return false, e end
+    -- `os.rename` returns true on success, or nil plus a message; whether CET resolves ITS
+    -- paths relative to the mod folder the way it does `io.open`'s is not stated anywhere, so
+    -- this is attempted, not assumed.
+    local okCall, renamed = pcall(function() return os.rename(tmpPath, relPath) end)
+    if okCall and renamed then return true, nil end
+    -- The rename did not take: fall back to writing in place, and clean up the temp file so a
+    -- half-written `.tmp` is not left beside a good result to confuse a human reading the
+    -- folder.
+    local okDirect, directErr = Protocol.writeFile(relPath, content)
+    pcall(function() os.remove(tmpPath) end)
+    if not okDirect then return false, directErr end
+    return true, nil
+end
+
+--- Absolute-path-free: everything is relative to whatever directory CET resolves `io.open`
+--- against, which is the whole point of discovery.
+function Protocol.path(name)
+    return (Protocol.writeRootPrefix or "") .. name
+end
+
+-- ---------------------------------------------------------------------------
+-- Write-root discovery
+-- ---------------------------------------------------------------------------
+
+--- Try each candidate prefix with `io.open(candidate, "w")`, keep the first that succeeds,
+--- and record every failure string. On total failure the transport becomes log-only and each
+--- result is printed as `[MODWRIGHT-RESULT] <json>` for `triage_logs` to recover
+--- (src/surfaces/cyberpunk2077/surface.ts's `cet` log source).
+function Protocol.discoverWriteRoot()
+    Protocol.writeRootErrors = {}
+    Protocol.writeRootPrefix = nil
+    Protocol.transport = "log"
+    Protocol.writeRoot = "log-only"
+
+    if not Protocol.caps.ioOpen then
+        Protocol.writeRootErrors[#Protocol.writeRootErrors + 1] =
+            "io.open is not available in this CET sandbox (type(io) = " .. type(io) .. "); no candidate was tried"
+        return false
+    end
+
+    for _, prefix in ipairs(Protocol.WRITE_ROOT_CANDIDATES) do
+        local candidate = prefix .. Protocol.FILES.heartbeat
+        local f, e = tryOpen(candidate, "w")
+        if f ~= nil then
+            -- Prove it is writable, not merely openable: an opened-but-unwritable handle
+            -- would strand every result with no error anywhere.
+            local wrote = pcall(function() f:write("") end)
+            pcall(function() f:close() end)
+            if wrote then
+                Protocol.writeRootPrefix = prefix
+                Protocol.writeRoot = candidate
+                Protocol.transport = "file"
+                return true
+            end
+            Protocol.writeRootErrors[#Protocol.writeRootErrors + 1] =
+                'io.open("' .. candidate .. '", "w") opened but f:write failed'
+        else
+            Protocol.writeRootErrors[#Protocol.writeRootErrors + 1] =
+                'io.open("' .. candidate .. '", "w") failed: ' .. tostring(e)
+        end
+    end
+    return false
+end
+
+-- ---------------------------------------------------------------------------
+-- Time
+-- ---------------------------------------------------------------------------
+-- Howard Hinnant's civil-calendar algorithms in pure Lua, so the ISO format never depends on
+-- an `os.date` the CET sandbox may not have.
+
+local function daysFromCivil(y, m, d)
+    if m <= 2 then y = y - 1 end
+    local era = floorNum(y / 400)
+    local yoe = y - era * 400
+    local mp = m + ((m > 2) and -3 or 9)
+    local doy = floorNum((153 * mp + 2) / 5) + d - 1
+    local doe = yoe * 365 + floorNum(yoe / 4) - floorNum(yoe / 100) + doy
+    return era * 146097 + doe - 719468
+end
+
+local function civilFromDays(z)
+    z = z + 719468
+    local era = floorNum(z / 146097)
+    local doe = z - era * 146097
+    local yoe = floorNum((doe - floorNum(doe / 1460) + floorNum(doe / 36524) - floorNum(doe / 146096)) / 365)
+    local y = yoe + era * 400
+    local doy = doe - (365 * yoe + floorNum(yoe / 4) - floorNum(yoe / 100))
+    local mp = floorNum((5 * doy + 2) / 153)
+    local d = doy - floorNum((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
+
+function Protocol.isoFromEpoch(seconds)
+    if type(seconds) ~= "number" then return nil end
+    seconds = floorNum(seconds)
+    local days = floorNum(seconds / 86400)
+    local rem = seconds - days * 86400
+    local y, m, d = civilFromDays(days)
+    local h = floorNum(rem / 3600)
+    local mi = floorNum((rem % 3600) / 60)
+    local s = rem % 60
+    return string.format("%04d-%02d-%02dT%02d:%02d:%02dZ", y, m, d, h, mi, floorNum(s))
+end
+
+--- Parse an ISO 8601 UTC timestamp to epoch seconds. ModWright writes
+--- `Date#toISOString()`, 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 rather
+--- than silently misread as UTC.
+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
+
+--- Epoch seconds now, or nil when the bridge has no clock at all.
+--- `os.time()` is UNVERIFIED in the CET sandbox — nothing on disk uses `os` — so it is
+--- feature-detected and pcall-guarded, and its absence is a reported capability, not a crash.
+function Protocol.epochSeconds()
+    if Protocol.caps.osTime then
+        local ok, t = pcall(function() return os.time() end)
+        if ok then
+            local n = tonumber(t)
+            if n and n > 1000000000 then
+                Protocol.clockSource = "os.time"
+                return floorNum(n)
+            end
+        end
+    end
+    if Protocol.clockAnchorEpoch ~= nil then
+        return floorNum(Protocol.clockAnchorEpoch + (Protocol.uptime - Protocol.clockAnchorUptime))
+    end
+    return nil
+end
+
+--- Adopt a request's `issuedAt` as the wall-clock anchor when the sandbox has no clock of
+--- its own. Only ever called for a request the bridge WATCHED ARRIVE (see pollOnce), so the
+--- anchor comes from a file ModWright wrote seconds ago rather than from an unknown past.
+function Protocol.adoptClock(issuedAt)
+    if Protocol.caps.osTime then return false end
+    if Protocol.clockAnchorEpoch ~= nil then return false end
+    local secs = Protocol.parseIso(issuedAt)
+    if secs == nil then return false end
+    Protocol.clockAnchorEpoch = secs
+    Protocol.clockAnchorUptime = Protocol.uptime
+    Protocol.clockSource = "adopted-from-request-issuedAt"
+    Protocol.log("no wall clock in this sandbox; adopted the request's issuedAt (" ..
+        tostring(issuedAt) .. ") as the clock anchor")
+    return true
+end
+
+--- Current time as an ISO 8601 UTC string. Falls back to a Unix-epoch offset — a real,
+--- parseable timestamp that reads as 1970, which is the honest signal that this bridge does
+--- not know what time it is.
+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 (os.time is absent from this CET sandbox and no request had a parseable issuedAt); " ..
+            "every timestamp in this result is Unix epoch + bridge uptime"
+    end
+    return Protocol.isoFromEpoch(floorNum(Protocol.uptime)) or "1970-01-01T00:00:00Z"
+end
+
+-- ---------------------------------------------------------------------------
+-- Heartbeat
+-- ---------------------------------------------------------------------------
+
+--- The `bridge` block shared by heartbeats and results (`bridgeInfoSchema`, .strict()).
+function Protocol.info()
+    return {
+        name = Protocol.BRIDGE_NAME,
+        version = Protocol.BRIDGE_VERSION,
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        context = Protocol.context,
+    }
+end
+
+--- The capability block, as one line of `writeRootErrors`.
+---
+--- WHY IT RIDES THERE AND NOT IN A KEY OF ITS OWN: `bridgeHeartbeatSchema`
+--- (src/core/bridge/types.ts) is `.strict()`, and poll.ts/status.ts DISCARD a heartbeat that
+--- fails to parse. A top-level `capabilities` key would therefore turn every heartbeat this
+--- bridge writes into "no heartbeat found" on the ModWright side — the exact failure the
+--- capability block exists to diagnose. `writeRootErrors` is `z.array(z.string()).optional()`
+--- and is already the field that explains why the write root is what it is, so the line goes
+--- there, machine-readably: `capabilities: {json object of booleans}`. The same block is
+--- returned as real booleans in `cp2077.bridge.io`'s evidence, where `evidence` is
+--- `z.record(z.unknown())` and nothing is lost.
+function Protocol.capabilityLine()
+    local c = Protocol.caps
+    return "capabilities: " .. Protocol.encode({
+        io = c.ioOpen == true,
+        json = c.json == true,
+        TweakDB = c.TweakDB == true,
+        Cron = c.Cron == true,
+        Observe = c.Observe == true,
+        os = c.osTime == true,
+        math = c.math == true,
+        GetMod = c.GetMod == true,
+        requestDecoder = Protocol.decoderName,
+        clockSource = Protocol.clockSource,
+        transport = Protocol.transport,
+        moduleLoader = Protocol.loaderUsed,
+    })
+end
+
+--- Build the heartbeat table (`bridgeHeartbeatSchema`, .strict() — every key below is in it,
+--- and no key that is not).
+function Protocol.heartbeat()
+    local hb = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        bridge = Protocol.info(),
+        at = Protocol.isoNow(),
+        uptimeMs = floorNum(Protocol.uptime * 1000),
+        state = Protocol.state,
+        writeRoot = Protocol.writeRoot,
+    }
+    local errs = Protocol.array({ Protocol.capabilityLine() })
+    for _, e in ipairs(Protocol.writeRootErrors) do errs[#errs + 1] = e end
+    hb.writeRootErrors = errs
+    if Protocol.lastRequestId then hb.lastRequestId = Protocol.lastRequestId end
+    if Protocol.lastResultId then hb.lastResultId = Protocol.lastResultId end
+    return hb
+end
+
+--- Write (or, in log-only mode, print) one heartbeat.
+function Protocol.writeHeartbeat()
+    local json_ = Protocol.encode(Protocol.heartbeat())
+    if Protocol.transport == "file" then
+        local ok, e = Protocol.writeFile(Protocol.path(Protocol.FILES.heartbeat), json_)
+        if not ok then
+            -- The root worked at load and does not now. Say so once per occurrence and keep
+            -- the bridge alive; the next discovery happens only on reload, by design (a
+            -- write root that changes under a running game is not a case anything attests).
+            Protocol.err("heartbeat", "write to " .. Protocol.path(Protocol.FILES.heartbeat) ..
+                " failed: " .. tostring(e))
+        end
+        return
+    end
+    pcall(function() print(Protocol.HEARTBEAT_TAG .. " " .. json_) end)
+end
+
+-- ---------------------------------------------------------------------------
+-- Results: result first, `done` marker second
+-- ---------------------------------------------------------------------------
+
+--- `bytes` is `#json` — Lua's byte length of the exact string handed to `f:write`, which is
+--- what poll.ts compares against `Buffer.byteLength(resultRaw, "utf8")`. Nothing may be
+--- appended to `json` after this point (no trailing newline).
+---
+--- LOG-ONLY MODE: the same two payloads are printed instead, on one line each, tagged
+--- `[MODWRIGHT-RESULT]` and `[MODWRIGHT-DONE]`. `bytes` still counts the result JSON, so a
+--- line recovered from the CET log can be checked for truncation exactly the way the file
+--- transport checks it (CET's log is known to cut the previous run's last line mid-write —
+--- src/surfaces/cyberpunk2077/surface.ts's `cet` log source notes).
+function Protocol.writeResult(result)
+    local json_ = Protocol.encode(result)
+    local probeCount = 0
+    if type(result.probes) == "table" then probeCount = #result.probes end
+    local done = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        id = result.id,
+        nonce = result.nonce,
+        bytes = #json_,
+        probeCount = probeCount,
+    }
+    local doneJson = Protocol.encode(done)
+
+    if Protocol.transport == "file" then
+        -- Committed by rename where CET 1.12.0's fixed `os.rename` allows it; the `done`
+        -- marker below is still the protocol's completeness proof.
+        local okResult, e = Protocol.writeFileCommitted(Protocol.path(Protocol.resultFile(result.id)), json_)
+        if not okResult then
+            Protocol.err("writeResult", "result file write failed for " .. tostring(result.id) ..
+                " (" .. tostring(e) .. "); the done marker is deliberately NOT written, so ModWright " ..
+                "retries rather than reading a partial file. The result follows on one line:")
+            pcall(function() print(Protocol.RESULT_TAG .. " " .. json_) end)
+            pcall(function() print(Protocol.DONE_TAG .. " " .. doneJson) end)
+            return false
+        end
+        local okDone = Protocol.writeFile(Protocol.path(Protocol.doneFile(result.id)), doneJson)
+        Protocol.log(string.format("result %s written (%d bytes, %d probes, done marker %s)",
+            tostring(result.id), #json_, probeCount, okDone and "ok" or "FAILED"))
+        return okDone
+    end
+
+    pcall(function() print(Protocol.RESULT_TAG .. " " .. json_) end)
+    pcall(function() print(Protocol.DONE_TAG .. " " .. doneJson) end)
+    Protocol.log(string.format("result %s printed to the log (%d bytes, %d probes) — log-only mode, " ..
+        "recover it with triage_logs", tostring(result.id), #json_, probeCount))
+    return true
+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 disarm then result.disarm = disarm end
+    return result
+end
+
+--- One `skipped` ProbeResult, used for every probe of a refused request (a refused request 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)
+    Protocol.log("REFUSED request " .. tostring(request.id) .. " (" .. reason .. "): " .. tostring(detail))
+    Protocol.writeHeartbeat()
+end
+
+-- ---------------------------------------------------------------------------
+-- Running a request
+-- ---------------------------------------------------------------------------
+-- CET attests exactly one timer: `dt` accumulated in onUpdate (the common CET pattern).
+-- There is no WaitForRealtime here and no `Cron` (unverified), so `settleSeconds` — the
+-- console hazard, "the weapon drops into the holstered pose while you type", 2.0 s by
+-- default for pose/anim/equipment reads — is served by carrying the run across onUpdate
+-- frames in this little state machine.
+
+--- Begin an accepted request. Probes are not sampled yet: the settle delay runs first.
+function Protocol.beginRun(request)
+    local settle = 0
+    local windowSeconds = 0
+    if type(request.window) == "table" then windowSeconds = tonumber(request.window.seconds) or 0 end
+
+    local run = {
+        request = request,
+        results = {},
+        errors = {},
+        startedAt = nil,
+        settleRemaining = 0,
+        elapsed = 0,
+        windowSeconds = windowSeconds,
+    }
+    run.startedAt = Protocol.isoNow(run)
+
+    for _, probe in ipairs(request.probes) do
+        local s = tonumber(probe.settleSeconds) or 0
+        if s > settle then settle = s end
+    end
+    run.settleRemaining = settle
+    run.budget = settle + Protocol.WATCHDOG_SLACK_SECONDS
+
+    if windowSeconds > 0 then
+        run.errors[#run.errors + 1] =
+            "window.seconds = " .. tostring(windowSeconds) .. " was ignored: no CET listener API is attested by any " ..
+            "source on disk, so this bridge cannot observe. Every probe was sampled once, after the settle delay."
+    end
+
+    Protocol.run = run
+    Protocol.state = "running"
+    Protocol.lastRequestId = tostring(request.id)
+    Protocol.consumed[tostring(request.nonce)] = true
+    Protocol.writeHeartbeat()
+
+    Protocol.log(string.format("ARMED request %s: %d probe(s), settle %ss, allowMutate=%s",
+        tostring(request.id), #request.probes, tostring(settle), tostring(request.allowMutate == true)))
+    if settle > 0 then
+        Protocol.log("settling " .. tostring(settle) .. "s before the first sample — THE CONSOLE MUST BE CLOSED " ..
+            "for any pose, animation or equipment read")
+    end
+end
+
+--- Sample every probe and write the result. Called from `tick` once the settle delay is up.
+function Protocol.finishRun(run)
+    local request = run.request
+    for i, probe in ipairs(request.probes) do
+        local res
+        if run.results[i] ~= nil then
+            res = run.results[i]
+        else
+            local ok, out = pcall(function() return Protocol.dispatcher.run(probe, request, run) end)
+            if ok and type(out) == "table" then
+                res = out
+            else
+                Protocol.err("probe", tostring(out))
+                res = {
+                    id = tostring(probe.id or ("probe-" .. i)),
+                    kind = tostring(probe.kind or "?"),
+                    status = "error",
+                    observed = nil,
+                    evidence = {},
+                    error = "dispatch failed: " .. tostring(out),
+                    ranAt = Protocol.isoNow(),
+                }
+            end
+        end
+        run.results[i] = res
+    end
+
+    local result = Protocol.buildResult(request, run.startedAt, run.results, run.errors, nil)
+    Protocol.run = nil
+    Protocol.state = "idle"
+    Protocol.writeResult(result)
+    Protocol.lastResultId = tostring(request.id)
+    Protocol.writeHeartbeat()
+    return result
+end
+
+-- ---------------------------------------------------------------------------
+-- Polling and arming
+-- ---------------------------------------------------------------------------
+
+--- One poll. Reads the marker and the request, applies every arming check in the
+--- protocol's order, and either refuses IN WRITING or starts the run.
+---
+--- ARMING WITHOUT A CLOCK. The protocol makes `armedUntil` the guarantee that an armed bridge
+--- never fires in normal play (hazard 2). With `os.time` absent that check cannot be
+--- evaluated directly, so a second, weaker but attested guarantee stands in for it: the
+--- bridge remembers whether a request file was ALREADY THERE at its first poll after load. A
+--- request that was already on disk is refused `expired` — it could be weeks old. A request
+--- that appeared while this session was running was written by ModWright seconds ago, so its
+--- `issuedAt` is adopted as the clock anchor and `armedUntil` is evaluated from there. That
+--- is the whole difference the missing clock makes.
+function Protocol.pollOnce()
+    if Protocol.run ~= nil then return end
+    if Protocol.transport ~= "file" then return end
+
+    local markerRaw = Protocol.readFile(Protocol.path(Protocol.FILES.requestMarker))
+    local requestRaw = Protocol.readFile(Protocol.path(Protocol.FILES.request))
+
+    if not Protocol.firstPollDone then
+        Protocol.firstPollDone = true
+        if requestRaw ~= nil and requestRaw ~= "" then
+            local pre = Protocol.decode(requestRaw)
+            if type(pre) == "table" and pre.nonce ~= nil then
+                Protocol.preexistingNonce = tostring(pre.nonce)
+                Protocol.log("a request file was already present at the first poll (nonce " ..
+                    Protocol.preexistingNonce .. "); it is treated as possibly stale")
+            end
+        end
+    end
+
+    if markerRaw == nil or markerRaw == "" then return end
+    if requestRaw == nil or requestRaw == "" then return end
+    local marker = Protocol.decode(markerRaw)
+    if type(marker) ~= "table" 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 protocol consumes the nonce
+    -- precisely so a refusal is not rewritten on every poll.
+    if Protocol.consumed[reqNonce] then 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
+    -- about to become valid, so a mismatch must be STABLE across two polls (>= 1 s apart)
+    -- before it is called a real 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 then
+            Protocol.pendingMismatch = nil
+            Protocol.consumed[mkNonce] = true
+            Protocol.refuse(request, "nonce-mismatch",
+                string.format("marker names id=%s nonce=%s; request names id=%s nonce=%s (stable across two polls, so not a torn write)",
+                    mkId, mkNonce, reqId, reqNonce))
+        else
+            Protocol.pendingMismatch = key
+        end
+        return
+    end
+    Protocol.pendingMismatch = nil
+
+    -- Byte length. A disagreement is the half-written case, which has no `disarm.reason` in
+    -- the protocol's enum 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
+            Protocol.log(string.format("request %s still incomplete after %d polls: marker says %s bytes, file is %d",
+                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",
+            string.format("this bridge speaks protocolVersion %d; the request says %s and its marker says %s. Re-run `bridge stage`, then `deploy --variant withBridge`.",
+                Protocol.PROTOCOL_VERSION, tostring(request.protocolVersion), tostring(marker.protocolVersion)))
+        return
+    end
+
+    if tostring(request.game) ~= "cyberpunk2077" then
+        Protocol.refuse(request, "wrong-game",
+            "this is the Cyberpunk 2077 CET bridge; the request names game=" .. tostring(request.game))
+        return
+    end
+
+    if type(request.probes) ~= "table" or #request.probes == 0 then
+        Protocol.refuse(request, "protocol-mismatch", "the request carries no probes")
+        return
+    end
+
+    -- armedUntil, and the no-clock substitute described above.
+    local wasPreexisting = (Protocol.preexistingNonce ~= nil and Protocol.preexistingNonce == reqNonce)
+    if not Protocol.caps.osTime and Protocol.clockAnchorEpoch == nil then
+        if wasPreexisting then
+            Protocol.refuse(request, "expired",
+                "this CET sandbox has no wall clock (os.time is absent) and this request file was already on disk when " ..
+                "the bridge loaded, so its armedUntil cannot be shown to be in the future. Re-arm with `bridge arm` " ..
+                "while the game is running, and it will be honoured.")
+            return
+        end
+        Protocol.adoptClock(tostring(request.issuedAt or ""))
+    end
+
+    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: " .. tostring(request.armedUntil))
+        return
+    end
+    local nowSecs = Protocol.epochSeconds()
+    if nowSecs == nil then
+        -- No clock and no anchor: honouring an expiry that cannot be evaluated would break
+        -- the one guarantee arming exists to give.
+        Protocol.refuse(request, "expired",
+            "the bridge has no wall clock (os.time is absent) and the request's issuedAt did not parse, so it cannot " ..
+            "prove the request is still armed")
+        return
+    end
+    if nowSecs >= untilSecs then
+        Protocol.refuse(request, "expired",
+            string.format("armedUntil %s has passed (bridge clock %s, source %s)",
+                tostring(request.armedUntil), tostring(Protocol.isoFromEpoch(nowSecs)), Protocol.clockSource))
+        return
+    end
+
+    Protocol.beginRun(request)
+end
+
+--- Arm from a JSON string typed at the console. The one way to drive the bridge in log-only
+--- mode, where there is no request file to read. Every arming check above still applies
+--- except the two that need a file (marker framing and byte length).
+function Protocol.armFromString(raw)
+    if Protocol.run ~= nil then return nil, "a run is already in progress" end
+    local request = Protocol.decode(raw)
+    if type(request) ~= "table" then return nil, "that is not a JSON object this bridge can decode" end
+    if tonumber(request.protocolVersion) ~= Protocol.PROTOCOL_VERSION then
+        return nil, "protocolVersion must be " .. Protocol.PROTOCOL_VERSION
+    end
+    if tostring(request.game) ~= "cyberpunk2077" then return nil, "game must be cyberpunk2077" end
+    if type(request.probes) ~= "table" or #request.probes == 0 then return nil, "the request carries no probes" end
+    if request.id == nil or request.nonce == nil then return nil, "id and nonce are required" end
+    if Protocol.consumed[tostring(request.nonce)] then return nil, "that nonce has already been consumed" end
+    Protocol.adoptClock(tostring(request.issuedAt or ""))
+    Protocol.beginRun(request)
+    return true, nil
+end
+
+-- ---------------------------------------------------------------------------
+-- The loop (a 1.0 s accumulator in onUpdate, the common CET pattern)
+-- ---------------------------------------------------------------------------
+
+--- Called from init.lua's onUpdate handler with the frame delta. Never throws.
+function Protocol.tick(dt)
+    dt = tonumber(dt) or 0
+    if dt < 0 then dt = 0 end
+    Protocol.uptime = Protocol.uptime + dt
+
+    -- CET 1.14: `GetMod()` and RTTI-dependent types are only available after onInit (CET
+    -- Nexus changelog, version 1.14). The first frame is the earliest point at which asking
+    -- about them gives a true answer, so the capability line is corrected here — once.
+    if not Protocol.rttiRechecked then
+        Protocol.rttiRechecked = true
+        pcall(Protocol.detectRttiCapabilities)
+    end
+
+    local run = Protocol.run
+    if run ~= nil then
+        run.elapsed = run.elapsed + dt
+        if run.settleRemaining > 0 then
+            run.settleRemaining = run.settleRemaining - dt
+        end
+        if run.settleRemaining <= 0 then
+            Protocol.finishRun(run)
+        elseif run.elapsed > run.budget then
+            run.errors[#run.errors + 1] = string.format(
+                "the bridge watchdog fired after %.1fs (settle %.1fs + %.1fs slack); probes were sampled at that point",
+                run.elapsed, run.budget - Protocol.WATCHDOG_SLACK_SECONDS, Protocol.WATCHDOG_SLACK_SECONDS)
+            Protocol.finishRun(run)
+        end
+    end
+
+    Protocol.pollAcc = Protocol.pollAcc + dt
+    if Protocol.pollAcc >= Protocol.POLL_SECONDS then
+        Protocol.pollAcc = 0
+        Protocol.guarded("poll", Protocol.pollOnce)()
+    end
+
+    if Protocol.transport == "file" then
+        Protocol.hbAcc = Protocol.hbAcc + dt
+        if Protocol.hbAcc >= Protocol.HEARTBEAT_SECONDS then
+            Protocol.hbAcc = 0
+            Protocol.guarded("heartbeat", Protocol.writeHeartbeat)()
+        end
+    else
+        Protocol.logHbAcc = Protocol.logHbAcc + dt
+        if Protocol.logHbAcc >= Protocol.LOG_HEARTBEAT_SECONDS then
+            Protocol.logHbAcc = 0
+            Protocol.guarded("heartbeat", Protocol.writeHeartbeat)()
+        end
+    end
+end
+
+--- Feature-detect, discover the write root, and announce both. Called once from onInit.
+function Protocol.init(opts)
+    Protocol.dispatcher = opts.dispatcher
+    Protocol.loaderUsed = opts.loaderUsed or "?"
+    Protocol.detectCapabilities()
+    Protocol.decoderName = Protocol.caps.json and "json.decode" or "in-house"
+    if Protocol.caps.osTime then Protocol.clockSource = "os.time" end
+
+    local ok = Protocol.discoverWriteRoot()
+    if ok then
+        Protocol.log("write root: " .. Protocol.writeRoot .. " (io.open succeeded on candidate " ..
+            tostring(Protocol.writeRootPrefix == "" and "1" or Protocol.writeRoot) .. ")")
+    else
+        Protocol.log("NO WRITABLE CANDIDATE — log-only mode. Every result is printed as one " ..
+            Protocol.RESULT_TAG .. " line; recover it with triage_logs.")
+        for _, e in ipairs(Protocol.writeRootErrors) do Protocol.log("  " .. e) end
+    end
+    Protocol.log(Protocol.capabilityLine())
+    Protocol.writeHeartbeat()
+    return Protocol
+end
+
+return Protocol