modwright 0.1.0

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

@@ -0,0 +1,1038 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / Probes.lua — the SERVER-context dispatch table. One entry per probe
+-- row of the bridge's probe catalogue, keyed by the row's `id`, and nothing else: probes are
+-- data rather than new Lua precisely because an SE `reset` degrades Osiris, so the probe
+-- list can never be shipped as fresh script.
+--
+-- THE RULE THAT SHAPES EVERY HANDLER HERE (the headline engine finding, observed in game):
+-- in the tested SE build, every Osiris QUERY function returns wrong/false for the entities
+-- probed: Osi.HasPassive, Osi.HasActiveStatus, Osi.IsEnemy, Osi.GetDistanceTo, Osi.IsDead,
+-- Osi.IsPlayer and others are not to be trusted. So every read below is
+-- an ENTITY COMPONENT read, no probe forces a cast, and no Osiris ACTION is ever called.
+--
+-- There are exactly TWO Osiris calls in this file, both deliberate and both named here so a
+-- reviewer never has to hunt for them:
+--   1. `Osi.GetMaxHitpoints(host)` inside `bg3.osiris.health` — where the query's
+--      unreliability IS the measurement. The degradation detector is
+--      `Osi.GetMaxHitpoints(host)` disagreeing with `Ext.Entity.Get(host).Health.MaxHp`.
+--   2. `Osi.GetHostCharacter()` to resolve the `"$host"` parameter token used by the
+--      converted test rows. It returns an identity, not a truth value; API.md's own helper
+--      `_C()` is defined as `Ext.Entity.Get(Osi.GetHostCharacter())`, and it is not among
+--      the queries observed to return junk. Every probe that uses it records
+--      `hostResolvedVia` in its evidence so the provenance travels with the answer.
+--
+-- ============================================================================
+-- Ext API used in this file (heading + signature above each first use)
+-- ============================================================================
+-- API.md §"Stats - `Ext.Stats`" / "Ext.Stats.GetStats(type: string): string[]"
+-- API.md §"Stats Objects" / "Ext.Stats.Get(stat, [level], [warnOnError]): StatEntry"
+-- API.md §"Reading stat attributes"
+-- API.md §"Mod info - `Ext.Mod`" / "IsModLoaded(modGuid)", "GetLoadOrder()", "GetMod(modGuid)"
+-- API.md §"Entity class - `Ext.Entity`" / "Entity:GetAllComponentNames() : string[]"
+-- API.md §"Saving the console output to a file" (the attested `Ext.Entity.Get("<uuid>")` call)
+-- API.md §"Utils - `Ext.Utils`" / "Common methods"
+-- (Ext.IO / Ext.Json / Ext.Timer citations live in Protocol.lua, Ext.Osiris in Watch.lua.)
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+local Protocol = Ext.Require("ModWrightBridge/Protocol.lua")
+local Watch = Ext.Require("ModWrightBridge/Watch.lua")
+
+local Probes = {}
+
+--- One-shot dump bookkeeping, so the serialized container is dumped on first miss
+--- literally on first miss and not on every poll of a long test plan.
+Probes.dumped = {}
+
+--- API.md §"Ext.Stats.GetStats(type: string): string[]" lists thirteen supported types, but the
+--- installed extender (runtime 32, observed in game 2026-09-09) answers four of them
+--- with `bg3se::lua::stats::FetchStatEntries(): Unknown stats entry type: <type>` on the console
+--- (SpellSet, EquipmentSet, ItemGroup, NameGroup) and returns nothing for them, so they are left
+--- out here rather than raising a warning on every stat probe. A stat of one of those types
+--- is not reachable through this probe; say so in the row instead of listing the type.
+local STAT_TYPES = {
+    "StatusData", "SpellData", "PassiveData", "Armor", "Weapon", "Character", "Object",
+    "TreasureTable", "TreasureCategory",
+}
+
+local HOST_TOKEN = "$host"
+
+-- ---------------------------------------------------------------------------
+-- Shared helpers
+-- ---------------------------------------------------------------------------
+
+local function params(probe)
+    if type(probe.params) == "table" then return probe.params end
+    return {}
+end
+
+local function fail(msg, evidence)
+    return { status = "fail", observed = nil, evidence = evidence or {}, error = msg }
+end
+
+local function errored(msg, evidence)
+    return { status = "error", observed = nil, evidence = evidence or {}, error = msg }
+end
+
+--- Turn any engine value into something the encoder can carry.
+local function coerce(v)
+    local t = type(v)
+    if t == "nil" then return nil end
+    if t == "string" or t == "number" or t == "boolean" then return v end
+    local tbl = Protocol.dumpComponent(v, 4)
+    if tbl ~= nil then return tbl end
+    return tostring(v)
+end
+
+--- `table.pack` is 5.2+, and both bridge trees are kept inside the 5.1-compatible subset that
+--- the `luac -p` pass (5.1 and 5.4) and bridges/*/README.md describe. So pack by
+--- hand: `select("#", ...)` counts the values including nils, which `#{...}` cannot.
+--- Returns (count, table).
+local function packResults(...)
+    return select("#", ...), { ... }
+end
+
+--- Resolve a guid parameter, expanding the `"$host"` token. Returns (guid, err, viaOsiris).
+local function resolveGuid(raw)
+    if raw == nil then return nil, "params.guid is required" end
+    local s = tostring(raw)
+    if s ~= HOST_TOKEN then return s, nil, false end
+    local ok, host = pcall(function() return Osi.GetHostCharacter() end)
+    if ok and host ~= nil and tostring(host) ~= "" then
+        return tostring(host), nil, true
+    end
+    return nil, "could not resolve \"$host\": Osi.GetHostCharacter() returned " .. tostring(host), true
+end
+
+--- Try the normalised UUID first, then the raw string, because Osiris hands the same
+--- entity in two different forms (a pattern proven in a shipped mod).
+local function getEntity(guid)
+    local e
+    pcall(function() e = Ext.Entity.Get(Protocol.normGuid(guid)) end)
+    if e == nil then pcall(function() e = Ext.Entity.Get(guid) end) end
+    return e
+end
+
+--- Read one named component off an entity and flatten it. Returns (table, blob, err).
+local function readComponent(guid, componentName)
+    local e = getEntity(guid)
+    if e == nil then
+        return nil, nil, "Ext.Entity.Get returned nil for " .. tostring(guid) .. " (entity not in the current session?)"
+    end
+    local raw
+    local ok = pcall(function() raw = e[componentName] end)
+    if not ok or raw == nil then
+        return nil, nil, "entity " .. tostring(guid) .. " has no readable ." .. componentName .. " component"
+    end
+    local tbl, blob = Protocol.dumpComponent(raw, 6)
+    if tbl == nil and blob == nil then
+        return nil, nil, "." .. componentName .. " could not be flattened by Ext.Json.Stringify{IterateUserdata=true}"
+    end
+    return tbl, blob, nil
+end
+
+--- Best-effort structural search used by the two rows whose field shape is
+--- NOT pinned. Collects (a) any value stored under a key equal to `needle` and (b) any
+--- table that carries `needle` as one of its own scalar values. Capped, depth-limited, and
+--- always reported alongside the whole dump so the reader can see what was searched.
+local function findNamed(node, needle, out, path, depth)
+    if depth > 8 or type(node) ~= "table" or #out >= 16 then return end
+    for k, v in pairs(node) do
+        local kp = path .. "/" .. tostring(k)
+        if tostring(k) == needle then
+            out[#out + 1] = { path = kp, value = coerce(v) }
+        end
+        if type(v) == "table" then
+            local names = false
+            for _, v2 in pairs(v) do
+                if type(v2) ~= "table" and tostring(v2) == needle then names = true end
+            end
+            if names then out[#out + 1] = { path = kp, value = coerce(v) } end
+            findNamed(v, needle, out, kp, depth + 1)
+        end
+    end
+end
+
+--- Sample the ActionResources component for one named resource. Returns
+--- (matches|nil, dumpTable, err). `matches` is nil when the resource could not be located —
+--- never a zero that would read as "the resource is empty".
+local function sampleResource(guid, resourceName)
+    local tbl, _, err = readComponent(guid, "ActionResources")
+    if tbl == nil then return nil, nil, err end
+    if resourceName == nil then return nil, tbl, nil end
+    local out = {}
+    findNamed(tbl, tostring(resourceName), out, "", 1)
+    if #out == 0 then return nil, tbl, nil end
+    return Protocol.array(out), tbl, nil
+end
+
+--- Status presence via the StatusContainer blob search (search the serialized blob for the
+--- id), the path that actually worked in game once Osi.HasActiveStatus was proven
+--- false-for-present.
+local function statusPresent(guid, statusId)
+    local tbl, blob, err = readComponent(guid, "StatusContainer")
+    if tbl == nil and blob == nil then return nil, nil, err end
+    local hit = false
+    if type(blob) == "string" and blob:find(tostring(statusId), 1, true) then hit = true end
+    return hit, tbl, nil
+end
+
+-- ---------------------------------------------------------------------------
+-- The dispatch table. Keys are the probe ids, verbatim.
+-- Each entry has `run` (read/mutate), and optionally `arm` + `harvest` (observe).
+-- test/unit/bridge/bg3-lua-parity.test.ts reads the keys back out of this block.
+-- ---------------------------------------------------------------------------
+-- MODWRIGHT-PROBE-TABLE-BEGIN
+Probes.handlers = {
+
+    -- attested(doc). API.md §"Ext.Stats.Get(stat, [level], [warnOnError]): StatEntry" —
+    -- "Returns the specified stats entry as an object for easier manipulation."
+    ["bg3.stat.exists"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.name == nil then return errored("params.name is required") end
+            local name = tostring(p.name)
+
+            local entry
+            -- warnOnError = false: a deliberate existence check must not spam the SE log.
+            pcall(function() entry = Ext.Stats.Get(name, nil, false) end)
+            local present = entry ~= nil
+
+            local searched = Protocol.array({})
+            if p.type ~= nil then
+                searched[1] = tostring(p.type)
+            else
+                for i, t in ipairs(STAT_TYPES) do searched[i] = t end
+            end
+
+            local foundIn = Protocol.array({})
+            for _, t in ipairs(searched) do
+                local names
+                pcall(function() names = Ext.Stats.GetStats(t) end)
+                if type(names) == "table" then
+                    for _, n in pairs(names) do
+                        if tostring(n) == name then
+                            foundIn[#foundIn + 1] = t
+                            break
+                        end
+                    end
+                end
+            end
+
+            return {
+                status = (present or #foundIn > 0) and "pass" or "fail",
+                observed = present,
+                evidence = { name = name, entryPresent = present, foundInTypes = foundIn, typesSearched = searched },
+            }
+        end,
+    },
+
+    -- attested(doc). API.md §"Reading stat attributes": "Stat attributes can be retrieved by
+    -- reading the appropriate property of the StatEntry object" — `local useCosts = spell.UseCosts`.
+    -- "If the stat entry doesn't have the specified attribute ... nil is returned."
+    ["bg3.stat.fields"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.name == nil then return errored("params.name is required") end
+            if type(p.fields) ~= "table" then return errored("params.fields must be an array of field names") end
+            local name = tostring(p.name)
+
+            local entry
+            pcall(function() entry = Ext.Stats.Get(name, nil, false) end)
+            if entry == nil then
+                return fail("no stats entry named \"" .. name .. "\"", { name = name })
+            end
+
+            local values = {}
+            local missing = Protocol.array({})
+            local unreadable = Protocol.array({})
+            for _, f in ipairs(p.fields) do
+                local key = tostring(f)
+                local v
+                local ok = pcall(function() v = entry[key] end)
+                if not ok then
+                    unreadable[#unreadable + 1] = key
+                elseif v == nil then
+                    missing[#missing + 1] = key
+                else
+                    values[key] = coerce(v)
+                end
+            end
+
+            return {
+                status = (#missing == 0 and #unreadable == 0) and "pass" or "fail",
+                observed = values,
+                evidence = { name = name, values = values, missing = missing, unreadable = unreadable },
+            }
+        end,
+    },
+
+    -- unverified (testplan/registry.ts). Observed in game (2026-09-10):
+    -- Ext.Template.GetTemplate(mapKey) called live at the console returns nil for a loose
+    -- Public/<Mod>/RootTemplates/*.lsx, and the full template object (with readable Name/
+    -- TemplateType/FileName fields, per a console dump) once the identical
+    -- node was converted to a sibling .lsf. That console call is attested; this handler,
+    -- reached only through the bridge, has not itself run yet — see knowledge fact
+    -- bg3.items.roottemplates.loose-lsx-in-roottemplates-is-not-loaded-a-separate-lsf-is.
+    ["bg3.template.exists"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.mapKey == nil then return errored("params.mapKey is required") end
+            local mapKey = tostring(p.mapKey)
+
+            -- Same convention every other handler uses for a required Ext.* call: pcall it,
+            -- never let one bad probe take Osiris down with it. A wholly missing `Ext.Template`
+            -- global (not expected in a real SE build, but reported like any other missing
+            -- precondition rather than guessed past) short-circuits before the call.
+            if Ext.Template == nil then return errored("Ext.Template is not available in this build") end
+
+            -- The pcall's own result is checked here, unlike `bg3.stat.exists`'s, and
+            -- deliberately: a `fail` from THIS probe is read as "the template did not reach the
+            -- engine", the exact signal the RootTemplates `.lsx` defect produces. A call that
+            -- raised instead of returning nil is a different fact entirely, and reporting it as
+            -- `fail` would send a reader hunting a packaging bug that is not there. `error` says
+            -- "this probe could not answer"; `fail` says "the answer is no".
+            local template
+            local ok, err = pcall(function() template = Ext.Template.GetTemplate(mapKey) end)
+            if not ok then
+                return errored("Ext.Template.GetTemplate(\"" .. mapKey .. "\") raised: " .. tostring(err), { mapKey = mapKey })
+            end
+            if template == nil then
+                return { status = "fail", observed = false, evidence = { present = false, mapKey = mapKey } }
+            end
+
+            local name, templateType, fileName
+            pcall(function() name = coerce(template.Name) end)
+            pcall(function() templateType = coerce(template.TemplateType) end)
+            pcall(function() fileName = coerce(template.FileName) end)
+
+            return {
+                status = "pass",
+                observed = true,
+                evidence = { present = true, mapKey = mapKey, name = name, templateType = templateType, fileName = fileName },
+            }
+        end,
+    },
+
+    -- attested(doc). API.md §"Mod info - `Ext.Mod`" / "IsModLoaded(modGuid)": "Returns whether
+    -- the module with the specified GUID is loaded."; "GetMod(modGuid)" whose `Info: ModuleInfo`
+    -- "includes fields such as Name, Author, Description, Directory, ModuleUUID, and ModVersion";
+    -- "GetLoadOrder()": "Returns the list of loaded module UUIDs in the order they're loaded in."
+    ["bg3.mod.active"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.uuid == nil then return errored("params.uuid is required") end
+            local uuid = tostring(p.uuid)
+
+            local loaded
+            pcall(function() loaded = Ext.Mod.IsModLoaded(uuid) end)
+
+            local modName, modVersion
+            pcall(function()
+                local m = Ext.Mod.GetMod(uuid)
+                if m ~= nil and m.Info ~= nil then
+                    modName = coerce(m.Info.Name)
+                    modVersion = coerce(m.Info.ModVersion)
+                end
+            end)
+
+            local index
+            pcall(function()
+                local order = Ext.Mod.GetLoadOrder()
+                if type(order) == "table" then
+                    local i = 0
+                    for _, u in pairs(order) do
+                        i = i + 1
+                        if Protocol.normGuid(tostring(u)) == Protocol.normGuid(uuid) then index = i end
+                    end
+                end
+            end)
+
+            return {
+                status = (loaded == true) and "pass" or "fail",
+                observed = loaded == true,
+                evidence = { uuid = uuid, loaded = loaded == true, modName = modName,
+                             modVersion = modVersion, loadOrderIndex = index },
+            }
+        end,
+    },
+
+    -- attested(doc). API.md §"Entity:GetAllComponentNames() : string[]" — "Returns all engine
+    -- component types (native C++ class names) that the entity has." Its printed sample is a
+    -- name-keyed map, so both shapes are accepted below rather than assuming one.
+    ["bg3.entity.components"] = {
+        run = function(probe)
+            local p = params(probe)
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return errored(err) end
+
+            local e = getEntity(guid)
+            if e == nil then return fail("Ext.Entity.Get returned nil for " .. guid, { guid = guid }) end
+
+            local raw
+            local ok = pcall(function() raw = e:GetAllComponentNames() end)
+            if not ok or type(raw) ~= "table" then
+                return errored("Entity:GetAllComponentNames() failed or returned a non-table for " .. guid, { guid = guid })
+            end
+
+            local names = Protocol.array({})
+            for k, v in pairs(raw) do
+                if type(k) == "string" then names[#names + 1] = k else names[#names + 1] = tostring(v) end
+            end
+            table.sort(names)
+
+            return {
+                status = (#names > 0) and "pass" or "fail",
+                observed = names,
+                evidence = { guid = guid, componentCount = #names, components = names,
+                             hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil },
+            }
+        end,
+    },
+
+    -- attested(engine). Active status -> e.StatusContainer (search the serialized blob for
+    -- the id); proven in a shipped mod.
+    -- Osi.HasActiveStatus is NOT used: it was observed to return false for a present status.
+    -- Precondition worth reading before believing a miss: console `AddBoosts`
+    -- do not survive save/load, so test on a fresh save.
+    ["bg3.entity.status"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.status == nil then return errored("params.status is required") end
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return errored(err) end
+            local statusId = tostring(p.status)
+
+            local hit, tbl, readErr = statusPresent(guid, statusId)
+            if hit == nil then return fail(readErr, { guid = guid, status = statusId }) end
+
+            local evidence = {
+                guid = guid, status = statusId, hit = hit,
+                readVia = "e.StatusContainer, searched as a serialized blob",
+                hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil,
+            }
+            -- The serialized container is attached on the first miss only.
+            local dumpKey = "status/" .. guid
+            if not hit and not Probes.dumped[dumpKey] then
+                Probes.dumped[dumpKey] = true
+                evidence.statusContainer = tbl
+            end
+
+            return { status = hit and "pass" or "fail", observed = hit, evidence = evidence }
+        end,
+    },
+
+    -- attested(engine). `e.PassiveContainer.Passives[].Passive.PassiveId`, a path walked by
+    -- a shipped mod.
+    ["bg3.entity.passive"] = {
+        run = function(probe)
+            local p = params(probe)
+            if p.passive == nil then return errored("params.passive is required") end
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return errored(err) end
+            local wanted = tostring(p.passive)
+
+            local tbl, blob, readErr = readComponent(guid, "PassiveContainer")
+            if tbl == nil and blob == nil then return fail(readErr, { guid = guid, passive = wanted }) end
+
+            local ids = Protocol.array({})
+            if type(tbl) == "table" and type(tbl.Passives) == "table" then
+                for _, row in ipairs(tbl.Passives) do
+                    local id
+                    if type(row) == "table" and type(row.Passive) == "table" then id = row.Passive.PassiveId end
+                    if id ~= nil then ids[#ids + 1] = tostring(id) end
+                end
+            end
+
+            local hit = false
+            for _, id in ipairs(ids) do
+                if id == wanted then hit = true end
+            end
+            local viaBlob = false
+            if not hit and type(blob) == "string" and blob:find(wanted, 1, true) then
+                hit = true
+                viaBlob = true
+            end
+
+            return {
+                status = hit and "pass" or "fail",
+                observed = hit,
+                evidence = { guid = guid, passive = wanted, passives = ids, hit = hit,
+                             matchedViaBlobSearch = viaBlob,
+                             hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil },
+            }
+        end,
+    },
+
+    -- attested(engine). `e.Classes` -> `.Classes[].ClassUUID/.SubClassUUID/.Level`; an
+    -- entity probe in a shipped mod proved the shape and field names:
+    -- { Classes = { { ClassUUID=..., Level=12, SubClassUUID=... } } }.
+    ["bg3.entity.class"] = {
+        run = function(probe)
+            local p = params(probe)
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return errored(err) end
+
+            local tbl, _, readErr = readComponent(guid, "Classes")
+            if tbl == nil then return fail(readErr, { guid = guid }) end
+
+            local rows = Protocol.array({})
+            local src = (type(tbl) == "table" and type(tbl.Classes) == "table") and tbl.Classes or nil
+            if src ~= nil then
+                for _, c in ipairs(src) do
+                    if type(c) == "table" then
+                        rows[#rows + 1] = {
+                            ClassUUID = c.ClassUUID ~= nil and tostring(c.ClassUUID) or nil,
+                            SubClassUUID = c.SubClassUUID ~= nil and tostring(c.SubClassUUID) or nil,
+                            Level = tonumber(c.Level),
+                        }
+                    end
+                end
+            end
+
+            return {
+                status = (#rows > 0) and "pass" or "fail",
+                observed = rows,
+                evidence = { guid = guid, classes = rows, component = tbl,
+                             hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil },
+            }
+        end,
+    },
+
+    -- **unverified (shape)**. The component's existence is attested by API.md's
+    -- own Entity:GetAllComponentNames() sample output ("eoc::ActionResourcesComponent"), but
+    -- the FIELD SHAPE is not documented anywhere. So this probe dumps the whole component
+    -- and reports a best-effort structural match, and says so in its evidence. One console
+    -- dump of the component on a live character settles it and promotes this row (and
+    -- bg3.boost.freecast with it) to attested.
+    ["bg3.entity.resource"] = {
+        run = function(probe)
+            local p = params(probe)
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return errored(err) end
+
+            local matches, tbl, readErr = sampleResource(guid, p.resource)
+            if tbl == nil then return fail(readErr, { guid = guid, resource = p.resource and tostring(p.resource) or nil }) end
+
+            local evidence = {
+                guid = guid,
+                resource = p.resource ~= nil and tostring(p.resource) or nil,
+                shapeUnverified = true,
+                shapeNote = "bg3.entity.resource is unverified (shape); confirm with a console dump of ActionResources on a live character and pin the SpellSlot path",
+                hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil,
+            }
+            local dumpKey = "resource/" .. guid
+            if not Probes.dumped[dumpKey] then
+                Probes.dumped[dumpKey] = true
+                evidence.component = tbl
+            end
+
+            if p.resource == nil then
+                return { status = "pass", observed = tbl, evidence = evidence }
+            end
+            if matches == nil then
+                evidence.component = tbl
+                return errored("could not locate resource \"" .. tostring(p.resource) ..
+                    "\" inside the ActionResources dump; the field shape is unverified; dump ActionResources at the console to pin it", evidence)
+            end
+            evidence.matches = matches
+            return { status = "pass", observed = matches, evidence = evidence }
+        end,
+    },
+
+    -- **unverified** (depends on bg3.entity.resource). The acceptance regression for a
+    -- free-cast boost: with the toggle ON, a leveled non-cantrip cast must consume no spell
+    -- slot. Sampled before/after ONE player cast inside the window and corroborated by the
+    -- toggle status (params.status); the cast is performed by the human (a forced
+    -- Osi.UseSpell was observed to re-cast, move the caster and self-kill via the toggle's
+    -- HP charge).
+    -- Precondition, observed in game: a toggled-off passive's OnCast functors never
+    -- fire, so a probe run with the toggle OFF reports `skipped`, never `pass`.
+    ["bg3.boost.freecast"] = {
+        run = function(probe)
+            return errored("bg3.boost.freecast is an observe probe: send it with effect \"observe\" and a window.seconds long enough for one cast")
+        end,
+        arm = function(probe)
+            local p = params(probe)
+            local guid, err, viaOsiris = resolveGuid(p.guid)
+            if guid == nil then return { error = err } end
+            local resource = p.resource ~= nil and tostring(p.resource) or "SpellSlot"
+            local statusId = p.status ~= nil and tostring(p.status) or "FREECAST_STATUS"
+
+            local before, dump, readErr = sampleResource(guid, resource)
+            local toggled, _, toggleErr = statusPresent(guid, statusId)
+            local watch, watchErr = Watch.osiris("CastedSpell", 5, { [1] = guid }, 32)
+
+            return {
+                guid = guid, resource = resource, statusId = statusId,
+                before = before, beforeDump = dump, readErr = readErr,
+                toggled = toggled, toggleErr = toggleErr, watch = watch, watchErr = watchErr,
+                hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil,
+            }
+        end,
+        harvest = function(probe, runCtx, armed)
+            if type(armed) ~= "table" or armed.error then
+                return errored(tostring(armed and armed.error or "arm state missing"))
+            end
+            local after, afterDump = sampleResource(armed.guid, armed.resource)
+            local casts = (armed.watch ~= nil) and armed.watch.rows or Protocol.array({})
+            Watch.stop(armed.watch)
+
+            local evidence = {
+                guid = armed.guid, resource = armed.resource, status = armed.statusId,
+                overclockToggledOn = armed.toggled,
+                overclockReadError = armed.toggleErr,
+                before = armed.before, after = after,
+                beforeComponent = armed.beforeDump, afterComponent = afterDump,
+                casts = casts, castCount = #casts,
+                shapeUnverified = true,
+                hostResolvedVia = armed.hostResolvedVia,
+                watchError = armed.watchErr,
+            }
+
+            if armed.watchErr ~= nil then
+                return errored("could not watch CastedSpell: " .. tostring(armed.watchErr), evidence)
+            end
+            if armed.toggled ~= true then
+                local why = "precondition unmet: " .. tostring(armed.statusId) ..
+                    " is not on the character; a toggled-off passive's OnCast functors never fire."
+                if armed.toggleErr ~= nil then
+                    why = "could not read the toggle status: " .. tostring(armed.toggleErr)
+                end
+                return { status = "skipped", observed = nil, evidence = evidence, error = why }
+            end
+            if #casts == 0 then
+                return { status = "skipped", observed = nil, evidence = evidence,
+                         error = "no CastedSpell row for this caster inside the window; the human did not cast (the bridge never forces one)" }
+            end
+            if armed.before == nil or after == nil then
+                return errored("the SpellSlot path inside ActionResources could not be read before and/or after the cast; " ..
+                    "the component shape is unverified; dump ActionResources at the console to pin it", evidence)
+            end
+
+            local unchanged = (Protocol.encode(armed.before) == Protocol.encode(after))
+            evidence.unchanged = unchanged
+            return {
+                status = unchanged and "pass" or "fail",
+                observed = unchanged,
+                evidence = evidence,
+                error = (not unchanged) and "the spell-slot resource changed across the cast: the free-cast boost did not apply" or nil,
+            }
+        end,
+    },
+
+    -- attested(doc). API.md §"Capturing Events/Calls":
+    -- `Ext.Osiris.RegisterListener(name, arity, event, handler)`. Arity must be exact or the
+    -- listener is silently dead (observed in game).
+    ["bg3.event.watch"] = {
+        run = function(probe)
+            return errored("bg3.event.watch is an observe probe: send it with effect \"observe\" and a window.seconds")
+        end,
+        arm = function(probe)
+            local p = params(probe)
+            local match = type(p.match) == "table" and p.match or nil
+            if type(match) == "table" then
+                -- Expand "$host" inside the match map so a plan row can watch the host without
+                -- knowing its GUID.
+                for k, v in pairs(match) do
+                    if tostring(v) == HOST_TOKEN then
+                        local g = resolveGuid(HOST_TOKEN)
+                        if g ~= nil then match[k] = g end
+                    end
+                end
+            end
+            local w, err = Watch.osiris(p.name, p.arity, match, tonumber(p.limit) or 64)
+            return { watch = w, error = err, name = p.name, arity = p.arity, match = match }
+        end,
+        harvest = function(probe, runCtx, armed)
+            if type(armed) ~= "table" then return errored("arm state missing") end
+            if armed.error ~= nil then return errored(tostring(armed.error), { name = armed.name, arity = armed.arity }) end
+            local rows = armed.watch.rows
+            Watch.stop(armed.watch)
+            return {
+                status = (#rows > 0) and "pass" or "fail",
+                observed = rows,
+                evidence = { name = tostring(armed.name), arity = tonumber(armed.arity),
+                             match = armed.match, rowCount = #rows, rows = rows,
+                             timebase = "Ext.Timer.MonotonicTime() milliseconds" },
+            }
+        end,
+    },
+
+    -- **unverified (event fields)**. `Ext.Events.EsvLuaBeforeDealDamage:Subscribe` is NOT in
+    -- API.md's event table — it is attested only by use in a shipped SE mod, and the field
+    -- paths inside the event are not pinned. Rows are therefore dumped WHOLE (the first
+    -- <=10 raw events) and any `filter` is applied as a substring test over the dump, labelled as such.
+    ["bg3.event.damage"] = {
+        run = function(probe)
+            return errored("bg3.event.damage is an observe probe: send it with effect \"observe\" and a window.seconds")
+        end,
+        arm = function(probe)
+            local p = params(probe)
+            local w, err = Watch.engineEvent("EsvLuaBeforeDealDamage", tonumber(p.limit) or 10)
+            return { watch = w, error = err, filter = type(p.filter) == "table" and p.filter or nil }
+        end,
+        harvest = function(probe, runCtx, armed)
+            if type(armed) ~= "table" then return errored("arm state missing") end
+            if armed.error ~= nil then return errored(tostring(armed.error)) end
+            local rows = armed.watch.rows
+            Watch.stop(armed.watch)
+
+            local kept = Protocol.array({})
+            if armed.filter == nil then
+                for i, r in ipairs(rows) do kept[i] = r end
+            else
+                for _, r in ipairs(rows) do
+                    local blob = Protocol.encode(r.event)
+                    local all = true
+                    for _, want in pairs(armed.filter) do
+                        if blob:find(tostring(want), 1, true) == nil then all = false end
+                    end
+                    if all then kept[#kept + 1] = r end
+                end
+            end
+
+            return {
+                status = (#kept > 0) and "pass" or "fail",
+                observed = kept,
+                evidence = {
+                    event = "EsvLuaBeforeDealDamage",
+                    fieldPathsUnverified = true,
+                    fieldPathsNote = "the field paths inside this event are not pinned; rows are dumped whole",
+                    filter = armed.filter,
+                    filterMode = "plain substring over the whole dumped event, because no field path is pinned",
+                    captured = #rows, matched = #kept, rows = kept,
+                },
+            }
+        end,
+    },
+
+    -- attested(doc/repo). The degradation detector is `Osi.GetMaxHitpoints(host)` vs
+    -- `Ext.Entity.Get(host).Health.MaxHp` disagreeing, after a mid-session `reset` degrades
+    -- Osiris (Osi queries return junk). This is the ONE probe
+    -- that calls an Osiris query on purpose: the query IS the thing being measured.
+    ["bg3.osiris.health"] = {
+        run = function(probe)
+            local p = params(probe)
+            local guid, err, viaOsiris = resolveGuid(p.guid ~= nil and p.guid or HOST_TOKEN)
+            if guid == nil then return errored(err) end
+
+            local osiRaw
+            pcall(function() osiRaw = Osi.GetMaxHitpoints(guid) end)
+
+            local ecsRaw
+            local e = getEntity(guid)
+            if e ~= nil then
+                pcall(function() ecsRaw = e.Health.MaxHp end)
+            end
+
+            local a, b = tonumber(osiRaw), tonumber(ecsRaw)
+            local agree = (a ~= nil and b ~= nil and a == b)
+
+            return {
+                status = agree and "pass" or "fail",
+                observed = agree,
+                evidence = {
+                    guid = guid,
+                    osiGetMaxHitpoints = (a ~= nil) and a or tostring(osiRaw),
+                    entityHealthMaxHp = (b ~= nil) and b or tostring(ecsRaw),
+                    agree = agree,
+                    resetCompletedSeenThisState = Protocol.osirisDegraded,
+                    detector = "Osi.GetMaxHitpoints(host) vs Ext.Entity.Get(host).Health.MaxHp disagreeing",
+                    hostResolvedVia = viaOsiris and "Osi.GetHostCharacter" or nil,
+                },
+                error = (not agree) and
+                    "Osiris disagrees with the ECS read: this Lua state is degraded (a mid-session `reset`). A save reload (F8) is the only clean fix; `reset` reloads Lua only." or nil,
+            }
+        end,
+    },
+
+    -- attested(doc). API.md §"Utils" / "Common methods": `Ext.Utils.GetGameState()`,
+    -- `Ext.Utils.GameVersion(): string?`, `Ext.Utils.Version(): int32`,
+    -- `Ext.Utils.GetCommandLineParams(): string[]` (whose documented sample output contains
+    -- "--skip-launcher"); the argv is after-the-fact evidence that the game was launched the
+    -- confirmed way, since ModWright never launches it. Reports the fixture, never assumes it.
+    -- bg3.lua.eval: console lines that used to be pasted by hand
+    -- (`_D(Ext.Stats.Get(...))`, `Osi.TemplateAddTo(...)`, `Ext.Mod.GetMod(...).Info.Directory`)
+    -- run through ModWright instead. One expression or chunk, compiled with the state's own
+    -- `loadstring`/`load` (`return <code>` first, the bare chunk as the fallback), run under
+    -- pcall, every return value coerced like any other probe's evidence, and the encoded result
+    -- capped at `maxBytes` (default 16 KB) so one careless `Ext.Entity.Get(...)` cannot flood
+    -- the result file. Registered with effect "mutate" and never anything weaker: the bridge
+    -- cannot know what a chunk does. Protocol's arm gate skips a `mutate` probe unless the
+    -- request set allowMutate — but that gate reads the effect word the REQUEST carries, so the
+    -- handler refuses outright when that word is anything but "mutate" (below).
+    -- Status unverified: nothing here has run in a game, so whether this state exposes a Lua
+    -- loader at all is the first thing a launch settles.
+    ["bg3.lua.eval"] = {
+        run = function(probe)
+            -- THE GATE, handler side. Protocol.lua's arm phase skips a probe when
+            -- `effect == "mutate" and request.allowMutate ~= true`; a request that labelled this
+            -- kind "read" (or "observe", which falls through to one sample at harvest time) would
+            -- therefore reach this handler with no allowMutate anywhere in the request. The
+            -- catalogue gives this kind effect `mutate`, so the handler enforces that rather than
+            -- trusting the label on the request file.
+            local effect = tostring(probe.effect or "read")
+            if effect ~= "mutate" then
+                return {
+                    status = "skipped",
+                    observed = nil,
+                    evidence = { effect = effect, kind = "bg3.lua.eval" },
+                    error = "bg3.lua.eval is a mutate-effect probe: send it with effect \"mutate\" and " ..
+                        "allowMutate: true. It never runs under a weaker effect, because the bridge cannot " ..
+                        "know what a chunk does.",
+                }
+            end
+            local p = params(probe)
+            if type(p.code) ~= "string" or p.code == "" then
+                return errored("params.code (a Lua expression or chunk) is required")
+            end
+            local code = p.code
+            -- The catalogue bounds maxBytes at 1..65536 (registry.ts); a request file is not the
+            -- catalogue, so an out-of-range value falls back to the default rather than
+            -- truncating the answer to nothing.
+            local maxBytes = tonumber(p.maxBytes) or 16384
+            if maxBytes < 1 or maxBytes > 65536 then maxBytes = 16384 end
+            -- `loadstring` first: wherever it exists the state is 5.1-era, and there `load`
+            -- takes a reader FUNCTION, not a string. 5.2+ drops `loadstring` and `load` takes
+            -- the string. The third argument ("t": text chunks only, never a binary chunk) is
+            -- honoured by 5.2+'s `load` and ignored by 5.1's `loadstring`.
+            local loader = loadstring or load
+            if loader == nil then
+                return errored("no Lua loader (loadstring/load) is exposed in this state", { code = code })
+            end
+            -- Observed in game (2026-09-11, BG3): the extender's loader rejected a chunk name as its second argument
+            -- ("bad argument #2 to 'loader' (table expected, got string)"), so the
+            -- code is the only argument passed; the loader's own defaults apply.
+            local fn, compileErr = loader("return " .. code)
+            local form = "expression"
+            if fn == nil then
+                fn, compileErr = loader(code)
+                form = "chunk"
+            end
+            if fn == nil then
+                return errored("does not compile: " .. tostring(compileErr), { code = code })
+            end
+            local n, results = packResults(pcall(fn))
+            if not results[1] then
+                return errored("raised: " .. tostring(results[2]), { code = code, form = form })
+            end
+            -- `coerce` maps nil to nil, so a nil among several returned values drops out of this
+            -- array instead of holding its place: `returnCount`, not `#observed`, is the
+            -- authority on how many values the chunk returned.
+            local values = {}
+            for i = 2, n do values[#values + 1] = coerce(results[i]) end
+            local returnCount = n - 1
+            local observed = values[1]
+            if returnCount > 1 then observed = values end
+            -- Truncation keeps a RAW PREFIX of the encoded JSON, as a plain Lua string. It is
+            -- deliberately not valid JSON on its own: the result writer re-encodes `observed`
+            -- with Protocol.encode, which escapes it into one JSON string literal, so the
+            -- result file stays parseable and the reader sees exactly how far the value got.
+            local encoded = Protocol.encode(observed)
+            local bytes = type(encoded) == "string" and #encoded or nil
+            local truncated = false
+            if bytes ~= nil and bytes > maxBytes then
+                observed = string.sub(encoded, 1, maxBytes)
+                truncated = true
+            end
+            return {
+                status = "pass",
+                observed = observed,
+                evidence = { code = code, form = form, returnCount = returnCount, bytes = bytes, truncated = truncated },
+            }
+        end,
+    },
+
+    ["bg3.precondition.report"] = {
+        run = function(probe, runCtx)
+            local report = {
+                gameState = Protocol.gameState(),
+                seVersion = nil,
+                gameVersion = nil,
+                commandLine = Protocol.commandLine(),
+                osirisDegraded = Protocol.osirisDegraded,
+                bridgeUptimeMs = math.max(0, Log.monotonic() - Protocol.loadedAtMs),
+            }
+            local okV, v = pcall(function() return Ext.Utils.Version() end)
+            if okV and v ~= nil then report.seVersion = tostring(v) end
+            local okG, g = pcall(function() return Ext.Utils.GameVersion() end)
+            if okG and g ~= nil then report.gameVersion = tostring(g) end
+
+            local host, hostErr = resolveGuid(HOST_TOKEN)
+            report.host = host
+            report.hostError = hostErr
+            report.hostResolvedVia = "Osi.GetHostCharacter"
+
+            if host ~= nil then
+                local classProbe = { id = "host-classes", kind = "bg3.entity.class", params = { guid = host } }
+                local ok, res = pcall(function() return Probes.handlers["bg3.entity.class"].run(classProbe) end)
+                if ok and type(res) == "table" then
+                    report.hostClasses = res.observed
+                    report.hostClassStatus = res.status
+                else
+                    report.hostClassError = tostring(res)
+                end
+            end
+
+            return { status = "pass", observed = report, evidence = report }
+        end,
+    },
+
+    -- attested(engine), RELAYED. The client row; its citation is Ext.IO.SaveFile called from
+    -- BootstrapClient.lua, the client-state marker pattern of a shipped SE mod.
+    --
+    -- The two Lua states cannot see each other (API.md §"Client / Server States": the 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 id —
+    -- so having both states poll and write the same result would race. The client therefore
+    -- writes only its own heartbeat (ModWright_hb_client.json) and this server-side handler
+    -- relays it. Every field the row reports is carried there: `stage` is the client's
+    -- Ext.Utils.GetGameState(), `seVersion` its bridge.runtimeVersion, `gameVersion` its
+    -- bridge.gameVersion. One case this arrangement cannot cover: a client state that never loads
+    -- leaves no heartbeat to relay, which the handler reports as a failure.
+    ["bg3.client.loaded"] = {
+        run = function(probe)
+            local raw = Protocol.load(Protocol.FILES.heartbeatClient)
+            if raw == nil or raw == "" then
+                return fail("no " .. Protocol.FILES.heartbeatClient .. " in the Script Extender folder: the client bridge state never loaded",
+                    { file = Protocol.FILES.heartbeatClient })
+            end
+            local hb = Protocol.decode(raw)
+            if type(hb) ~= "table" then
+                return errored("could not parse " .. Protocol.FILES.heartbeatClient, { file = Protocol.FILES.heartbeatClient })
+            end
+
+            local marker = {
+                loaded = true,
+                stage = hb.gameState,
+                seVersion = (type(hb.bridge) == "table") and hb.bridge.runtimeVersion or nil,
+                gameVersion = (type(hb.bridge) == "table") and hb.bridge.gameVersion or nil,
+            }
+
+            -- Freshness, using the same 15 s window as HEARTBEAT_FRESH_MS in
+            -- src/core/bridge/locate.ts, so "the client is loaded" never rests on a heartbeat
+            -- left behind by an earlier launch.
+            local ageSeconds
+            local nowSecs = Protocol.epochSeconds()
+            local atSecs = Protocol.parseIso(tostring(hb.at or ""))
+            if nowSecs ~= nil and atSecs ~= nil then ageSeconds = nowSecs - atSecs end
+
+            local evidence = {
+                file = Protocol.FILES.heartbeatClient,
+                marker = marker,
+                clientHeartbeatAt = hb.at,
+                clientState = hb.state,
+                ageSeconds = ageSeconds,
+                relayed = true,
+                relayNote = "read from the client heartbeat by the server state; the two Lua states are fully separated (API.md §\"Client / Server States\")",
+            }
+
+            if ageSeconds ~= nil and ageSeconds > 15 then
+                return { status = "fail", observed = marker, evidence = evidence,
+                         error = ("the client heartbeat is %ds old (>15s): the client bridge state is not running now"):format(ageSeconds) }
+            end
+            return { status = "pass", observed = marker, evidence = evidence }
+        end,
+    },
+
+}
+-- MODWRIGHT-PROBE-TABLE-END
+
+-- ---------------------------------------------------------------------------
+-- Dispatch (Probes.run(probe) looks `kind` up in a fixed table; an unknown kind is
+-- "unsupported"; every handler is pcall-wrapped following the guarded-callback pattern of a
+-- shipped SE mod, whose reason — a bad error path leaves Osiris returning junk — applies
+-- here exactly)
+-- ---------------------------------------------------------------------------
+
+--- Wrap a handler's return into a ProbeResult (`probeResultSchema`, .strict()) and apply the
+--- probe's `expect` block.
+function Probes.finalize(probe, out)
+    local status = out.status or "pass"
+    local evidence = out.evidence
+    if type(evidence) ~= "table" then evidence = {} end
+
+    if (status == "pass" or status == "fail") and type(probe.expect) == "table" then
+        local verdict, note = Protocol.evaluateExpect(out.observed, probe.expect)
+        if verdict ~= nil then
+            status = verdict
+            evidence.expect = { op = tostring(probe.expect.op), value = probe.expect.value, note = note }
+        end
+    end
+
+    local res = {
+        id = tostring(probe.id or "?"),
+        kind = tostring(probe.kind or "?"),
+        status = status,
+        observed = out.observed,
+        evidence = evidence,
+        ranAt = Protocol.isoNow(),
+    }
+    if out.error ~= nil then res.error = tostring(out.error) end
+    return res
+end
+
+--- Run one read/mutate probe. Never throws: one probe failing can never abort the batch.
+function Probes.run(probe, runCtx)
+    local kind = tostring(probe.kind or "")
+    local h = Probes.handlers[kind]
+    if h == nil or h.run == nil then
+        return Probes.finalize(probe, {
+            status = "unsupported",
+            observed = nil,
+            evidence = { kind = kind, context = Protocol.context },
+            error = "no handler for probe kind \"" .. kind .. "\" in the " .. Protocol.context .. " dispatch table",
+        })
+    end
+    local ok, res = pcall(h.run, probe, runCtx)
+    if ok and type(res) == "table" then return Probes.finalize(probe, res) end
+    Log.err("probe:" .. kind, res)
+    return Probes.finalize(probe, { status = "error", observed = nil, evidence = { kind = kind }, error = tostring(res) })
+end
+
+--- Arm one observe probe. Returns the arm state handed back to `harvest`.
+function Probes.arm(probe, runCtx)
+    local kind = tostring(probe.kind or "")
+    local h = Probes.handlers[kind]
+    if h == nil then
+        return { unsupported = true, kind = kind }
+    end
+    if h.arm == nil then
+        return { noArm = true, kind = kind }
+    end
+    local ok, state = pcall(h.arm, probe, runCtx)
+    if ok then return state end
+    Log.err("probe-arm:" .. kind, state)
+    return { error = tostring(state), kind = kind }
+end
+
+--- Harvest one observe probe at the end of the window.
+function Probes.harvest(probe, runCtx, armed)
+    local kind = tostring(probe.kind or "")
+    local h = Probes.handlers[kind]
+
+    if type(armed) == "table" and armed.unsupported then
+        return Probes.finalize(probe, {
+            status = "unsupported", observed = nil, evidence = { kind = kind },
+            error = "no handler for probe kind \"" .. kind .. "\" in the " .. Protocol.context .. " dispatch table",
+        })
+    end
+
+    if h ~= nil and h.harvest ~= nil then
+        local ok, res = pcall(h.harvest, probe, runCtx, armed)
+        if ok and type(res) == "table" then return Probes.finalize(probe, res) end
+        Log.err("probe-harvest:" .. kind, res)
+        return Probes.finalize(probe, { status = "error", observed = nil, evidence = { kind = kind }, error = tostring(res) })
+    end
+
+    -- A read-only kind sent with effect "observe": sample it once, at the end of the window,
+    -- and say so rather than pretending a listener watched anything.
+    local res = Probes.run(probe, runCtx)
+    if type(res.evidence) == "table" then
+        res.evidence.observeNote = "this probe kind has no observe handler; it was sampled once at the end of the window"
+    end
+    return res
+end
+
+return Probes