modwright 0.1.0

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

@@ -0,0 +1,74 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / ProbesClient.lua — the CLIENT-context dispatch table.
+--
+-- There is exactly one client row, `bg3.client.loaded`, and the client bootstrap is
+-- "client heartbeat + client probes only". This file is that table, and it
+-- is deliberately tiny: API.md §"Client / Server States" says the two Lua states "are
+-- completely separated from each other and cannot access the internal state of each other",
+-- and the protocol has exactly ONE request file and ONE result file per request id — so
+-- if the client also polled and wrote results, the two states would race over the same
+-- files. The client therefore never polls and never writes a result. It writes only
+-- `ModWright_hb_client.json`, and the SERVER's `bg3.client.loaded` handler
+-- (Probes.lua) relays what it finds there.
+--
+-- Everything this row captures — `stage`, `seVersion`, `gameVersion` —
+-- fits inside the heartbeat schema the client already writes (`gameState`,
+-- `bridge.runtimeVersion`, `bridge.gameVersion`), so no new file is invented for it. A
+-- future client probe needing anything else needs a protocol change, not a workaround.
+--
+-- ============================================================================
+-- Ext API used in this file
+-- ============================================================================
+-- 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.
+-- (The marker this mirrors is the client marker of a shipped SE mod, which writes
+--  `{ stage, seVersion = Ext.Utils.Version(), gameVersion = Ext.Utils.GameVersion() }`.)
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+local Protocol = Ext.Require("ModWrightBridge/Protocol.lua")
+
+local ProbesClient = {}
+
+--- Set by BootstrapClient so the marker can name the registration point it was produced at,
+--- the way a shipped mod's marker distinguishes "bootstrap" from "SessionLoaded".
+ProbesClient.stage = "bootstrap"
+
+-- MODWRIGHT-PROBE-TABLE-BEGIN
+ProbesClient.handlers = {
+
+    -- attested(engine). The shipped precedent is a client-state marker written with
+    -- Ext.IO.SaveFile that proves SE enumerated the mod without loading a save ("main menu is
+    -- enough; no save needed").
+    ["bg3.client.loaded"] = {
+        run = function()
+            local marker = { loaded = true, stage = ProbesClient.stage }
+            local okV, v = pcall(function() return Ext.Utils.Version() end)
+            if okV and v ~= nil then marker.seVersion = tostring(v) end
+            local okG, g = pcall(function() return Ext.Utils.GameVersion() end)
+            if okG and g ~= nil then marker.gameVersion = tostring(g) end
+            local gs = Protocol.gameState()
+            if gs ~= nil then marker.gameState = gs end
+            return { status = "pass", observed = marker, evidence = marker }
+        end,
+    },
+
+}
+-- MODWRIGHT-PROBE-TABLE-END
+
+--- Run one client probe by kind. Never throws.
+function ProbesClient.run(kind)
+    local h = ProbesClient.handlers[tostring(kind)]
+    if h == nil or h.run == nil then
+        return { status = "unsupported", observed = nil, evidence = { kind = tostring(kind) },
+                 error = "no handler for probe kind \"" .. tostring(kind) .. "\" in the client dispatch table" }
+    end
+    local ok, res = pcall(h.run)
+    if ok and type(res) == "table" then return res end
+    Log.err("client-probe:" .. tostring(kind), res)
+    return { status = "error", observed = nil, evidence = {}, error = tostring(res) }
+end
+
+return ProbesClient