modwright 0.1.0

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

@@ -0,0 +1,375 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge — the Cyber Engine Tweaks entry point. This is ModWright's author-only
+-- verification bridge. It is never
+-- shipped in a mod: `cp2077.history.bridge-never-ships`
+-- (src/surfaces/cyberpunk2077/validators/bridge.ts) blocks a build whose output carries this
+-- folder or the banner on the first line above.
+--
+-- WHAT THIS MOD DOES, IN ONE PARAGRAPH: at load it feature-detects the sandbox and discovers
+-- where `io.open` can write; every 1 s it looks for an armed request file; when it finds one
+-- whose marker, nonce, protocol version, game and expiry all check out, it runs the probes
+-- that request names and writes a result followed by a `done` marker carrying the result's
+-- byte length. It READS. The single mutating call in the whole bridge
+-- (`Game.AddToInventory`, the one `mutate` row of the probe catalogue) runs only when the request sets
+-- `allowMutate: true`. If no write root exists it runs LOG-ONLY, printing each result as one
+-- `[MODWRIGHT-RESULT] <json>` line for `triage_logs` to recover.
+--
+-- ============================================================================
+-- Registration shape and its citations
+-- ============================================================================
+-- knowledge fact `cp2077.process.cet-mods-sandboxed` (status `verified`, "2.31", observed in game
+-- 2026-08-16): "cet mods run in a sandboxed lua environment; console access is via
+-- `GetMod(\"ModName\")`, and each mod's init.lua must return a table with methods that the
+-- console can call." That is why this file ends in a `return { … }` and why every console
+-- entry point is a field of it.
+--
+-- `registerForEvent("onUpdate", function(dt) … end)` with an accumulator is
+-- the common CET mod pattern:
+--     local timer = 0
+--     registerForEvent("onUpdate", function(dt)
+--         timer = timer + dt
+--         if timer < 3.0 then return end
+--         timer = 0
+-- and it is the ONLY timer attested for CET. `onInit` and `onShutdown` are registered the
+-- same way.
+--
+-- ============================================================================
+-- The module loader ladder (and why it is a ladder)
+-- ============================================================================
+-- The bridge is split into init.lua + protocol.lua + probes.lua. The CET mods surveyed had
+-- no second file, so the routes come from CET's own changelog rather than from a sibling
+-- on disk:
+--   * "All pathing is now relative to mod (breaking change, includes all io functions,
+--     dofile() and such included)", and require paths are separated with "/" rather than "."
+--     (CET Nexus changelog, version 1.10) — so `require("protocol")` resolves inside THIS
+--     mod's folder, and a dotted `require("ModWrightBridge.protocol")` is not a CET spelling.
+--   * `dofile` is deprecated as of 1.9.1 but still present, and mod-relative since 1.10 — so
+--     `dofile("protocol.lua")` is the last resort, and the older routes relative to bin/x64
+--     (`dofile("plugins/cyber_engine_tweaks/mods/.../protocol.lua")`) are gone: they describe
+--     pre-1.10 behaviour that no longer exists.
+-- Each route is still tried in turn inside `pcall`, and the one that worked is reported in the
+-- heartbeat's capability line and by `m.where()`. If every route fails the mod STILL returns a
+-- table — with `status()`, `where()` and `help()` that explain the failure — because a CET mod
+-- that returns nothing is unreachable from the console and cannot even be diagnosed.
+
+local BANNER = "MODWRIGHT-BRIDGE-DO-NOT-SHIP"
+local PREFIX = "[ModWrightBridge]"
+
+-- `print(...)` is the console output used by shipped CET mods.
+local function say(msg)
+    pcall(function() print(PREFIX .. " " .. tostring(msg)) end)
+end
+
+local loadErrors = {}
+
+--- Try one loader route. Returns the module table or nil.
+local function tryRoute(label, fn)
+    local okCall, mod = pcall(fn)
+    if okCall and type(mod) == "table" then return mod, label end
+    loadErrors[#loadErrors + 1] = label .. " -> " .. tostring(mod)
+    return nil, nil
+end
+
+--- Load one of this mod's own modules by its base name ("protocol" / "probes").
+local function loadModule(name)
+    local routes = {
+        -- Mod-relative, "/" not "." (CET Nexus changelog, version 1.10).
+        { 'require("' .. name .. '")', function() return require(name) end },
+        { 'require("ModWrightBridge/' .. name .. '")', function() return require("ModWrightBridge/" .. name) end },
+        -- Deprecated since 1.9.1, still present, mod-relative since 1.10.
+        { 'dofile("' .. name .. '.lua")', function() return dofile(name .. ".lua") end },
+    }
+    for _, route in ipairs(routes) do
+        local mod, label = tryRoute(route[1], route[2])
+        if mod ~= nil then return mod, label end
+    end
+    return nil, nil
+end
+
+local Protocol, protocolLoader = loadModule("protocol")
+local Probes, probesLoader = nil, nil
+if Protocol ~= nil then
+    Probes, probesLoader = loadModule("probes")
+end
+
+-- ---------------------------------------------------------------------------
+-- The degraded mod: every loader route failed
+-- ---------------------------------------------------------------------------
+-- Still a table, still console-reachable, and it says exactly what went wrong.
+if Protocol == nil or Probes == nil then
+    local missing = (Protocol == nil) and "protocol.lua" or "probes.lua"
+    say("FATAL: could not load " .. missing .. ". The bridge is loaded but INERT.")
+    for _, e in ipairs(loadErrors) do say("  " .. e) end
+    say('Run `GetMod("ModWrightBridge").where()` for this list again, and see the bridge README.')
+
+    local function report()
+        say("INERT: " .. missing .. " never loaded. Routes tried:")
+        for _, e in ipairs(loadErrors) do say("  " .. e) end
+        say("Fix: confirm all three .lua files are in " ..
+            "bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge/ and re-run `deploy --variant withBridge`. " ..
+            "Since CET 1.10 every path here is relative to that folder (CET Nexus changelog, version 1.10).")
+        return { loaded = false, missing = missing, errors = loadErrors }
+    end
+
+    registerForEvent("onInit", function()
+        say("onInit: inert (" .. missing .. " never loaded)")
+    end)
+
+    return {
+        banner = BANNER,
+        status = report,
+        where = report,
+        help = report,
+        probe = report,
+        arm = report,
+        run = report,
+    }
+end
+
+Probes.init(Protocol)
+
+-- ---------------------------------------------------------------------------
+-- Events
+-- ---------------------------------------------------------------------------
+
+local tickErrors = 0
+local TICK_ERROR_LIMIT = 20
+local loopDisabled = false
+
+-- `registerForEvent("onInit", …)` — the standard CET entry event.
+registerForEvent("onInit", function()
+    local okInit, e = pcall(function()
+        Protocol.init({
+            dispatcher = Probes,
+            loaderUsed = tostring(protocolLoader) .. " / " .. tostring(probesLoader),
+        })
+    end)
+    if not okInit then
+        say("FATAL in onInit: " .. tostring(e))
+        return
+    end
+    -- The banner: what loaded, at which protocol version, with how many
+    -- probe kinds, and where it can write.
+    say(string.format(
+        "loaded — bridge %s, protocolVersion %d, %d probe kinds, transport %s, write root %s",
+        Protocol.BRIDGE_VERSION, Protocol.PROTOCOL_VERSION, #Probes.kinds(),
+        Protocol.transport, Protocol.writeRoot))
+    if Protocol.transport == "file" then
+        say(string.format("polling %s every %ss; heartbeat %s every %ss",
+            Protocol.path(Protocol.FILES.request), tostring(Protocol.POLL_SECONDS),
+            Protocol.path(Protocol.FILES.heartbeat), tostring(Protocol.HEARTBEAT_SECONDS)))
+    else
+        say("LOG-ONLY MODE: no candidate write root accepted a write, so there is no request file to poll and no " ..
+            "heartbeat file to write. Results are printed as " .. Protocol.RESULT_TAG .. " lines and the heartbeat as " ..
+            "a " .. Protocol.HEARTBEAT_TAG .. " line every " .. tostring(Protocol.LOG_HEARTBEAT_SECONDS) .. "s. " ..
+            "Arm by hand with m.arm(<json string>) or m.probe(kind, paramsJson).")
+    end
+    say("console: local m = GetMod(\"ModWrightBridge\") — then m.help(), m.where(), m.status()")
+end)
+
+-- `registerForEvent("onUpdate", function(dt) … end)` with a dt accumulator —
+-- the common CET pattern. The accumulators themselves live in Protocol.tick.
+registerForEvent("onUpdate", function(dt)
+    if loopDisabled then return end
+    local okTick, e = pcall(function() Protocol.tick(dt) end)
+    if okTick then
+        tickErrors = 0
+        return
+    end
+    tickErrors = tickErrors + 1
+    say("ERROR in onUpdate (" .. tickErrors .. "/" .. TICK_ERROR_LIMIT .. "): " .. tostring(e))
+    if tickErrors >= TICK_ERROR_LIMIT then
+        loopDisabled = true
+        say("onUpdate disabled after " .. TICK_ERROR_LIMIT .. " consecutive errors, so it cannot flood " ..
+            "cyber_engine_tweaks.log. Reload the mod from the CET UI once the cause is fixed.")
+    end
+end)
+
+-- `registerForEvent("onShutdown", …)` — the standard CET shutdown event.
+registerForEvent("onShutdown", function()
+    pcall(function()
+        -- A final heartbeat with `state: "unloaded"` would be natural. That word is NOT in
+        -- `bridgeHeartbeatStateSchema` (src/core/bridge/types.ts: "idle"|"running"|"disarmed"),
+        -- and a heartbeat that fails the strict schema is DISCARDED by poll.ts/status.ts —
+        -- ModWright would report "no heartbeat found" and blame the write root. So the state
+        -- stays "idle" and the shutdown is recorded in `writeRootErrors`, which is a string
+        -- array the schema does accept.
+        Protocol.state = "idle"
+        Protocol.writeRootErrors[#Protocol.writeRootErrors + 1] =
+            "shutdown: the bridge was unloaded at " .. tostring(Protocol.isoNow()) ..
+            "; this heartbeat is final and will not advance until the mod loads again"
+        Protocol.writeHeartbeat()
+        say("onShutdown: final heartbeat written (state idle, shutdown noted in writeRootErrors)")
+    end)
+end)
+
+-- ---------------------------------------------------------------------------
+-- The console table (drivable by hand via local b = GetMod("ModWrightBridge"))
+-- ---------------------------------------------------------------------------
+
+local consoleSeq = 0
+
+local function nextConsoleId()
+    consoleSeq = consoleSeq + 1
+    -- `id` must match ModWright's `[a-z0-9-]{8,64}` and `nonce` its 16 hex characters, so a
+    -- console-driven result file is shaped exactly like an armed one.
+    return string.format("console-%06d", consoleSeq),
+           string.format("%08x%08x", (consoleSeq * 2654435761) % 4294967296, consoleSeq)
+end
+
+--- m.status() — the heartbeat, as a table, printed as JSON.
+local function statusFn()
+    local hb = Protocol.heartbeat()
+    say("status: " .. Protocol.encode(hb))
+    return hb
+end
+
+--- m.where() — everything about the transport, in words.
+local function whereFn()
+    say("transport   : " .. Protocol.transport .. (Protocol.transport == "file" and "" or "  (LOG-ONLY)"))
+    say("write root  : " .. tostring(Protocol.writeRoot))
+    say("prefix      : " .. tostring(Protocol.writeRootPrefix))
+    say("candidates  :")
+    for i, prefix in ipairs(Protocol.WRITE_ROOT_CANDIDATES) do
+        local candidate = prefix .. Protocol.FILES.heartbeat
+        local mark = (Protocol.writeRoot == candidate) and "  <== IN USE" or ""
+        say(string.format("  %d. %s%s", i, candidate, mark))
+    end
+    if #Protocol.writeRootErrors > 0 then
+        say("failures    :")
+        for _, e in ipairs(Protocol.writeRootErrors) do say("  " .. e) end
+    end
+    say("files       : " .. Protocol.path(Protocol.FILES.request) .. ", " ..
+        Protocol.path(Protocol.FILES.requestMarker) .. ", " .. Protocol.path(Protocol.resultFile("<id>")) ..
+        ", " .. Protocol.path(Protocol.doneFile("<id>")))
+    say("loader      : " .. tostring(Protocol.loaderUsed))
+    say(Protocol.capabilityLine())
+    if #loadErrors > 0 then
+        say("loader routes that failed:")
+        for _, e in ipairs(loadErrors) do say("  " .. e) end
+    end
+    return {
+        transport = Protocol.transport,
+        writeRoot = Protocol.writeRoot,
+        writeRootPrefix = Protocol.writeRootPrefix,
+        writeRootErrors = Protocol.writeRootErrors,
+        capabilities = Protocol.caps,
+        loader = Protocol.loaderUsed,
+    }
+end
+
+--- m.probe(kind, paramsJson, settleSeconds) — run ONE probe by hand.
+---
+--- `paramsJson` is a JSON object as a STRING, e.g.
+---   m.probe("cp2077.item.equipped", '{"slot":"AttachmentSlots.WeaponRight"}', 2)
+--- `settleSeconds` (optional) stages the probe through the normal run machinery so you can
+--- CLOSE THE CONSOLE before it samples — which the console hazard requires for any
+--- pose, animation or equipment read. With no settle it samples immediately, while the
+--- console is open, and the result says so.
+---
+--- `allowMutate` is always FALSE here: the one mutating row of the probe catalogue is never fired by an
+--- accidental console line. Use m.arm(<json>) with "allowMutate": true when you mean it.
+local function probeFn(kind, paramsJson, settleSeconds)
+    if kind == nil then
+        say('usage: m.probe("cp2077.player.present") or m.probe("cp2077.tweakdb.record", \'{"id":"Items.Preset_Example"}\', 2)')
+        return nil
+    end
+    local p = {}
+    if paramsJson ~= nil and paramsJson ~= "" then
+        local decoded = Protocol.decode(tostring(paramsJson))
+        if type(decoded) ~= "table" then
+            say("could not decode paramsJson — it must be a JSON OBJECT in a string, e.g. '{\"tag\":\"MyModTag\"}'")
+            return nil
+        end
+        p = decoded
+    end
+
+    local id, nonce = nextConsoleId()
+    local settle = tonumber(settleSeconds) or 0
+    local probe = {
+        id = "console",
+        kind = tostring(kind),
+        context = "cet",
+        effect = "read",
+        params = p,
+        settleSeconds = settle,
+    }
+    local request = {
+        protocolVersion = Protocol.PROTOCOL_VERSION,
+        id = id,
+        nonce = nonce,
+        issuedAt = Protocol.isoNow(),
+        armedUntil = Protocol.isoNow(),
+        game = "cyberpunk2077",
+        allowMutate = false,
+        probes = { probe },
+    }
+
+    if settle > 0 then
+        Protocol.beginRun(request)
+        say("staged: CLOSE THE CONSOLE now — the probe samples in " .. tostring(settle) ..
+            "s and the result is written as " .. Protocol.resultFile(id))
+        return id
+    end
+
+    local res = Probes.run(probe, request, nil)
+    say("probe " .. tostring(kind) .. ": " .. Protocol.encode(res))
+    if res.status == "pass" or res.status == "fail" then
+        say("NOTE: sampled with the console OPEN. For any pose, animation or equipment read pass a settle, " ..
+            "e.g. m.probe(\"" .. tostring(kind) .. "\", " ..
+            (paramsJson and ("'" .. tostring(paramsJson) .. "'") or "nil") .. ", 2)")
+    end
+    return res
+end
+
+--- m.arm(jsonString) — hand the bridge a whole request as a JSON string. The only way to
+--- drive a full request in log-only mode, and the way to set `allowMutate`.
+local function armFn(raw)
+    if raw == nil then
+        say('usage: m.arm(\'{"protocolVersion":1,"id":"by-hand-01","nonce":"0123456789abcdef",' ..
+            '"issuedAt":"2026-09-08T12:00:00Z","armedUntil":"2026-09-08T12:10:00Z","game":"cyberpunk2077",' ..
+            '"allowMutate":false,"probes":[{"id":"p1","kind":"cp2077.player.present","context":"cet",' ..
+            '"effect":"read","params":{}}]}\')')
+        return nil
+    end
+    local okArm, e = Protocol.armFromString(tostring(raw))
+    if not okArm then
+        say("arm refused: " .. tostring(e))
+        return nil
+    end
+    say("armed by hand; the result will be " .. (Protocol.transport == "file" and "written" or "printed") .. " shortly")
+    return true
+end
+
+--- m.run() — poll once, right now, instead of waiting for the next accumulator tick.
+local function runFn()
+    Protocol.guarded("console-run", Protocol.pollOnce)()
+    say("polled " .. Protocol.path(Protocol.FILES.request) .. "; state = " .. Protocol.state)
+    return Protocol.state
+end
+
+local function helpFn()
+    say("ModWrightBridge " .. Protocol.BRIDGE_VERSION .. " (protocolVersion " .. Protocol.PROTOCOL_VERSION .. ")")
+    say("  m.status()                          heartbeat as JSON")
+    say("  m.where()                           transport, write root, candidates, capabilities")
+    say("  m.probe(kind, paramsJson, settle)   run one probe (never mutates)")
+    say("  m.arm(jsonString)                   hand it a whole request (this is where allowMutate lives)")
+    say("  m.run()                             poll for a request file right now")
+    say("probe kinds:")
+    for _, k in ipairs(Probes.kinds()) do say("  " .. k) end
+    return Probes.kinds()
+end
+
+-- knowledge fact cp2077.process.cet-mods-sandboxed: "each mod's init.lua must return a table
+-- with methods that the console can call" (shipped mods return `{}` or a table of
+-- named functions — this is that shape).
+return {
+    banner = BANNER,
+    status = statusFn,
+    where = whereFn,
+    probe = probeFn,
+    arm = armFn,
+    run = runFn,
+    help = helpFn,
+}