modwright 0.1.0

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

@@ -0,0 +1,1104 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / probes.lua — the CET dispatch table. One entry per row of
+-- the probe catalogue, keyed by the row's `id`, carrying that row's
+-- EXACT status word, and nothing else: probes are data rather than new Lua,
+-- so a test plan can never ship fresh script into the game.
+--
+-- ============================================================================
+-- THE RULE THAT SHAPES EVERY HANDLER HERE
+-- ============================================================================
+-- The catalogue marks half these rows `unverified`, and an `unverified` row is one where NOTHING ON
+-- DISK attests the call. So a handler whose call is missing returns `error` with a message
+-- naming what was missing and which check settles it. It never returns `pass`, and
+-- it never lets the absence propagate as a Lua error into CET's onUpdate.
+--
+-- Attestation words used below:
+--   attested(engine)  a shipped CET mod on disk makes this exact call
+--   attested(doc)     a CyberEngineTweaks wiki page names this exact call
+--   unverified        no page and no mod on disk makes it; a console check confirms or contradicts it
+--   not designed      the catalogue's `cp2077.loot.roll`: answered `unsupported`, always
+-- Each is copied into the probe result's `evidence.attestation` with its citation, so the
+-- provenance of an answer travels with the answer.
+--
+-- ============================================================================
+-- Engine calls used in this file (source quoted above each first use)
+-- ============================================================================
+--   Game.GetPlayer()                                wiki/Script-tutorial.md §"Regular handles";
+--                                                   shipped CET mods
+--   Game.GetTransactionSystem():GetItemInSlot(...)  shipped CET mods
+--   TweakDBID.new(name)                             shipped CET mods
+--   ItemID.GetTDBID(w:GetItemData():GetID())        shipped CET mods
+--   Game.GetDynamicEntitySystem():GetTaggedIDs(t)   shipped CET mods
+--   Game.FindEntityByID(id)                         shipped CET mods
+--   ent:FindComponentByName(name)                   shipped CET mods
+--   ent:GetWorldPosition() / GetWorldOrientation()  shipped CET mods
+--   Game.AddToInventory(item, qty)                  wiki/Console.md §"Specificity";
+--                                                   wiki/ConsoleCommands.md:25
+--   GetMod("ModWrightBridge")                       knowledge fact cp2077.process.cet-mods-sandboxed
+--                                                   (verified, 2.31, observed in game 2026-08-16)
+--   TweakDB:GetRecord / TweakDB:GetFlat             observed in the CET console on
+--                                                   2026-09-08 (see the rows below).
+--
+-- MUTATION. Two rows have effect `mutate`: `cp2077.inventory.add`, and `cp2077.lua.eval`
+-- (added 2026-09-11). They are the two handlers in this
+-- file with `mutates = true`, and `Probes.run` refuses to call a mutating handler unless the
+-- request set `allowMutate: true` AND the kind is one of those two ids. Because the gate keys
+-- off `mutates` and not off the request's own effect word, a request that mislabelled either
+-- kind as `read` is refused just the same. Every other handler reads.
+
+local Probes = {}
+
+--- Wired by init.lua so this module needs no loader of its own.
+local Protocol = nil
+
+function Probes.init(protocol)
+    Protocol = protocol
+    return Probes
+end
+
+-- ---------------------------------------------------------------------------
+-- Shared helpers
+-- ---------------------------------------------------------------------------
+
+local function params(probe)
+    if type(probe.params) == "table" then return probe.params end
+    return {}
+end
+
+local function ok(observed, evidence)
+    return { status = "pass", observed = observed, evidence = evidence or {} }
+end
+
+local function failed(msg, observed, evidence)
+    return { status = "fail", observed = observed, evidence = evidence or {}, error = msg }
+end
+
+local function errored(msg, evidence)
+    return { status = "error", observed = nil, evidence = evidence or {}, error = msg }
+end
+
+--- The one message shape every `unverified` row uses when its call is simply not there.
+local function absent(what, confirmStep)
+    return errored(what .. " is not available in this CET sandbox, and no source on disk attests it. " ..
+        "This row stays `unverified` until " .. confirmStep .. " confirms or contradicts it; it is reported " ..
+        "as an error rather than a pass so nothing downstream reads a missing call as a measurement.")
+end
+
+--- An attested call whose global is nonetheless not visible from this sandbox. Distinct
+--- from `absent`: the call is known to work (seen from the console, 2026-09-08), so a
+--- missing global here is an environment difference to report, never a reason to call
+--- the row unverified. The old `absent` wording was once read as a
+--- refusal and re-verified by hand; the evidence now names the type seen.
+local function missingAttested(what, call, evidence)
+    evidence = evidence or {}
+    evidence.globalType = what
+    return errored(what .. " is not visible from this mod sandbox, although " .. call ..
+        " is attested from the CET console (2026-09-08). Record the type seen here and compare " ..
+        "with a direct console call in the same session; this is an environment finding, not an " ..
+        "unverified probe.", evidence)
+end
+
+--- Is a global present, without calling it?
+-- Globals are read by NAME through a closure, never through `_G`: a CET mod's environment
+-- is a fresh table falling back to a whitelisted globals copy without `_G`
+-- (CyberEngineTweaks/src/scripting/Sandbox.cpp:9, LuaSandbox.cpp whitelist), so `_G[name]`
+-- is always nil in here. Observed in game: the heartbeat, which detects by
+-- name, said GetMod true while this helper said nil. Same fix as protocol.lua's globalIs.
+local GLOBAL_GETTERS = {
+    io = function() return io end,
+    GetMod = function() return GetMod end,
+    Game = function() return Game end,
+    TweakDB = function() return TweakDB end,
+}
+
+local function have(name)
+    local get = GLOBAL_GETTERS[name]
+    if not get then return false, "unlisted" end
+    local okG, v = pcall(get)
+    if not okG then return false, "nil" end
+    local t = type(v)
+    return (t == "table" or t == "userdata" or t == "function"), t
+end
+
+--- Turn an engine value into something `Protocol.encode` can carry. Engine handles are
+--- `userdata`; `tostring` is the only thing attested to work on one (shipped mods
+--- print `tostring(...)` of engine values), so that is what is recorded.
+local function coerce(v)
+    local t = type(v)
+    if t == "nil" or t == "string" or t == "number" or t == "boolean" then return v end
+    if t == "table" then
+        local out = {}
+        for k, val in pairs(v) do
+            local kt = type(k)
+            if kt == "string" or kt == "number" then
+                local vt = type(val)
+                if vt == "string" or vt == "number" or vt == "boolean" then out[k] = val
+                else out[k] = tostring(val) end
+            end
+        end
+        return out
+    end
+    return tostring(v)
+end
+
+--- `table.pack` is 5.2+, and this file is kept inside the 5.1-compatible subset the two
+--- shipped CET mods use (README.md "Lua checking"; nothing on disk pins which dialect CET
+--- runs). So pack by hand: `select("#", ...)` counts the values including nils, which
+--- `#{...}` cannot. Returns (count, table).
+local function packResults(...)
+    return select("#", ...), { ... }
+end
+
+--- Read a Vector4-like handle's x/y/z. Shipped CET mods do exactly this
+--- (`pos.x + dx, pos.y + dy, pos.z + dz`), so the field access is attested.
+local function xyz(v)
+    if v == nil then return nil end
+    local out
+    local okR = pcall(function()
+        out = { x = tonumber(v.x), y = tonumber(v.y), z = tonumber(v.z) }
+    end)
+    if not okR or out == nil or out.x == nil then return nil end
+    return out
+end
+
+--- Read a quaternion handle's i/j/k/r. Shipped CET mods read `q.i, q.j, q.k, q.r`.
+local function quat(q)
+    if q == nil then return nil end
+    local out
+    local okR = pcall(function()
+        out = { i = tonumber(q.i), j = tonumber(q.j), k = tonumber(q.k), r = tonumber(q.r) }
+    end)
+    if not okR or out == nil or out.i == nil then return nil end
+    return out
+end
+
+--- `Game.GetPlayer()` — wiki/Script-tutorial.md §"Regular handles" ("we can only get the
+--- handle of the `player` by calling the global function `Game.GetPlayer()`");
+--- shipped CET mods call it the same way (`if not Game.GetPlayer() then return end`).
+local function player()
+    local p
+    local okP = pcall(function() p = Game.GetPlayer() end)
+    if okP and p ~= nil then return p end
+    return nil
+end
+
+--- `Game.GetDynamicEntitySystem():GetTaggedIDs(tag)` — a shipped CET mod
+--- (`local des = Game.GetDynamicEntitySystem()` … `des:GetTaggedIDs(tag) or {}`).
+local function taggedIds(tag)
+    local ids
+    local okT, e = pcall(function()
+        local des = Game.GetDynamicEntitySystem()
+        ids = des:GetTaggedIDs(tag) or {}
+    end)
+    if not okT then return nil, tostring(e) end
+    if type(ids) ~= "table" then return nil, "GetTaggedIDs returned " .. type(ids) end
+    return ids, nil
+end
+
+--- `Game.FindEntityByID(id)` — shipped CET mods
+--- (`return Game.FindEntityByID(lightID)`).
+local function entityById(id)
+    local ent
+    local okE, e = pcall(function() ent = Game.FindEntityByID(id) end)
+    if not okE then return nil, tostring(e) end
+    return ent, nil
+end
+
+--- `Game.GetTransactionSystem():GetItemInSlot(player, TweakDBID.new(slot))` —
+--- as shipped CET mods do. Returns (itemObject|nil, err).
+local function itemInSlot(slot)
+    local p = player()
+    if p == nil then return nil, "Game.GetPlayer() returned nil — load a save first" end
+    local item
+    local okI, e = pcall(function()
+        item = Game.GetTransactionSystem():GetItemInSlot(p, TweakDBID.new(slot))
+    end)
+    if not okI then return nil, tostring(e) end
+    return item, nil
+end
+
+--- `ItemID.GetTDBID(w:GetItemData():GetID())` — as shipped CET mods do.
+local function itemTdbid(item)
+    local tdbid
+    local okT, e = pcall(function() tdbid = ItemID.GetTDBID(item:GetItemData():GetID()) end)
+    if not okT then return nil, tostring(e) end
+    return tdbid, nil
+end
+
+--- Resolve the `entityRef` parameter shared by the entity rows.
+---
+--- A BARE ENTITY-ID STRING CANNOT BE RESOLVED. `Game.FindEntityByID` is attested
+--- (shipped mods) but only ever with an id handed back by the engine — nothing on disk
+--- attests any call that turns a string back into an EntityID, so asking for one is answered
+--- with an error naming the three forms that DO work rather than a guess:
+---   entityRef = "$player"                      the player (Game.GetPlayer)
+---   entityRef = "$equipped", params.slot = "…" the item in an equipment slot
+---   params.tag = "…" (+ optional params.index) the nth dynamic entity carrying that tag
+--- Returns (entity, describe, err).
+local function resolveEntity(p)
+    local ref = p.entityRef and tostring(p.entityRef) or nil
+
+    if p.tag ~= nil then
+        local tag = tostring(p.tag)
+        local ids, e = taggedIds(tag)
+        if ids == nil then return nil, nil, "GetTaggedIDs(\"" .. tag .. "\") failed: " .. tostring(e) end
+        local index = tonumber(p.index) or 1
+        if #ids == 0 then
+            return nil, nil, "no dynamic entity carries the tag \"" .. tag .. "\" right now — " ..
+                "stream the location in (stand at the marker) and re-run"
+        end
+        if ids[index] == nil then
+            return nil, nil, "params.index " .. tostring(index) .. " is out of range: " .. #ids ..
+                " entit" .. ((#ids == 1) and "y" or "ies") .. " carry the tag \"" .. tag .. "\""
+        end
+        local ent, e2 = entityById(ids[index])
+        if ent == nil then
+            return nil, nil, "Game.FindEntityByID resolved nothing for tag \"" .. tag .. "\" #" ..
+                tostring(index) .. (e2 and (": " .. e2) or " (the entity may still be streaming in)")
+        end
+        return ent, { via = "tag", tag = tag, index = index, taggedCount = #ids }, nil
+    end
+
+    if ref == "$player" then
+        local pl = player()
+        if pl == nil then return nil, nil, "Game.GetPlayer() returned nil — load a save first" end
+        return pl, { via = "$player" }, nil
+    end
+
+    if ref == "$equipped" then
+        local slot = p.slot and tostring(p.slot) or nil
+        if slot == nil then return nil, nil, 'entityRef "$equipped" needs params.slot, e.g. "AttachmentSlots.WeaponRight"' end
+        local item, e = itemInSlot(slot)
+        if item == nil then
+            return nil, nil, "nothing is in slot " .. slot .. (e and (": " .. e) or " — equip the item by hand first")
+        end
+        return item, { via = "$equipped", slot = slot }, nil
+    end
+
+    return nil, nil,
+        "cannot resolve entityRef " .. tostring(ref) .. ": nothing on disk attests a call that turns an entity-id " ..
+        'string back into an EntityID. Use params.tag (+ params.index), entityRef "$player", or entityRef ' ..
+        '"$equipped" with params.slot.'
+end
+
+--- `ent:FindComponentByName(name)` — a shipped CET mod
+--- (`return ent:FindComponentByName("SomeGlow")`). Returns (found, err).
+local function componentPresent(ent, name)
+    local comp
+    local okC, e = pcall(function() comp = ent:FindComponentByName(name) end)
+    if not okC then return nil, tostring(e) end
+    return comp ~= nil, nil
+end
+
+--- The component sweep shared by `cp2077.entity.components`, `cp2077.interaction.present`
+--- and the appearance differential. Returns (foundArray, mapTable, errArray).
+local function sweepComponents(ent, names)
+    local found = Protocol.array({})
+    local map = {}
+    local errs = Protocol.array({})
+    for _, raw in ipairs(names) do
+        local name = tostring(raw)
+        local present, e = componentPresent(ent, name)
+        if present == nil then
+            map[name] = "error"
+            errs[#errs + 1] = name .. ": " .. tostring(e)
+        else
+            map[name] = present
+            if present then found[#found + 1] = name end
+        end
+    end
+    return found, map, errs
+end
+
+-- ---------------------------------------------------------------------------
+-- The dispatch table (in table order)
+-- ---------------------------------------------------------------------------
+-- MODWRIGHT-PROBE-TABLE-BEGIN
+Probes.handlers = {
+
+    -- Row 1 — **unverified**. "Where can the bridge write?" `io.open(rel, "w")` over the
+    -- write-root candidate list; nothing attests CET's `io` for a mod. Confirmed or
+    -- contradicted by the discovery result. The discovery itself already ran at onInit; this row
+    -- reports it rather than re-running it, so a test plan cannot flap the transport mid-run.
+    ["cp2077.bridge.io"] = {
+        attestation = "unverified",
+        citation = "write-root discovery — no source attests CET's io for a mod",
+        effect = "read",
+        run = function()
+            local present, t = have("io")
+            local evidence = {
+                writeRoot = Protocol.writeRoot,
+                writeRootPrefix = Protocol.writeRootPrefix,
+                transport = Protocol.transport,
+                candidates = Protocol.array({}),
+                failures = Protocol.array({}),
+                capabilities = {
+                    io = Protocol.caps.ioOpen == true,
+                    json = Protocol.caps.json == true,
+                    TweakDB = Protocol.caps.TweakDB == true,
+                    Cron = Protocol.caps.Cron == true,
+                    Observe = Protocol.caps.Observe == true,
+                    os = Protocol.caps.osTime == true,
+                    math = Protocol.caps.math == true,
+                    GetMod = Protocol.caps.GetMod == true,
+                },
+                requestDecoder = Protocol.decoderName,
+                clockSource = Protocol.clockSource,
+                moduleLoader = Protocol.loaderUsed,
+                typeOfIo = t,
+            }
+            for i, prefix in ipairs(Protocol.WRITE_ROOT_CANDIDATES) do
+                evidence.candidates[i] = prefix .. Protocol.FILES.heartbeat
+            end
+            for i, e in ipairs(Protocol.writeRootErrors) do evidence.failures[i] = e end
+
+            if not present then
+                return errored("io is absent from this CET sandbox (type(io) = " .. t .. "): the bridge is in " ..
+                    "log-only mode and every result is printed as a [MODWRIGHT-RESULT] line. This is " ..
+                    "recorded as `cp2077.bridge.io` CONTRADICTED.", evidence)
+            end
+            if Protocol.transport == "file" then
+                return ok(Protocol.writeRoot, evidence)
+            end
+            return failed("io exists but every write-root candidate refused a write; the bridge is in log-only mode",
+                Protocol.writeRoot, evidence)
+        end,
+    },
+
+    -- Row 2 — attested(engine). "The bridge mod is loaded and console-reachable":
+    -- `registerForEvent("onInit", …)` and a returned table for `GetMod("ModWrightBridge")` —
+    -- knowledge fact cp2077.process.cet-mods-sandboxed (status `verified`, "2.31",
+    -- observed in game 2026-08-16, "console access is via GetMod(\"ModName\"), and each mod's init.lua
+    -- must return a table"); shipped CET mods follow the same shape.
+    ["cp2077.mod.loaded"] = {
+        attestation = "attested(engine)",
+        citation = "knowledge cp2077.process.cet-mods-sandboxed (verified 2.31); shipped CET mods register onInit and return a table",
+        effect = "read",
+        run = function()
+            local hb = Protocol.heartbeat()
+            local evidence = { heartbeat = hb }
+            local present, t = have("GetMod")
+            if not present then
+                -- Reaching this handler already proves the mod is loaded; only the CONSOLE
+                -- half of the row is unanswerable, and that is said rather than assumed.
+                evidence.getModAvailable = false
+                evidence.note = "this handler ran, so the mod is loaded; GetMod is " .. t ..
+                    " here, so console reachability could not be checked from inside the sandbox — " ..
+                    'run `print(tostring(GetMod("ModWrightBridge")))` in the console to confirm'
+                return ok(true, evidence)
+            end
+            local mod
+            local okM, e = pcall(function() mod = GetMod("ModWrightBridge") end)
+            evidence.getModAvailable = true
+            if not okM then
+                evidence.getModError = tostring(e)
+                return ok(true, evidence)
+            end
+            evidence.getModReturned = (mod ~= nil) and type(mod) or "nil"
+            evidence.exposes = Protocol.array({})
+            if type(mod) == "table" then
+                for k in pairs(mod) do evidence.exposes[#evidence.exposes + 1] = tostring(k) end
+                table.sort(evidence.exposes)
+            end
+            if mod == nil then
+                return failed('GetMod("ModWrightBridge") returned nil even though this handler is running — ' ..
+                    "the mod folder name and the GetMod argument must match", false, evidence)
+            end
+            return ok(true, evidence)
+        end,
+    },
+
+    -- Row 3 — attested(engine). "A player exists (i.e. in a save, not the menu)".
+    ["cp2077.player.present"] = {
+        attestation = "attested(engine)",
+        citation = "wiki/Script-tutorial.md §\"Regular handles\"; shipped CET mods",
+        effect = "read",
+        run = function()
+            local present, t = have("Game")
+            if not present then
+                return absent("the `Game` global (type " .. t .. ")", "a console check")
+            end
+            local p = player()
+            local evidence = { handle = p ~= nil and tostring(p) or nil }
+            if p == nil then
+                return failed("Game.GetPlayer() returned nil — the game is at the menu, or no save is loaded",
+                    false, evidence)
+            end
+            return ok(true, evidence)
+        end,
+    },
+
+    -- Row 4 — attested(engine). "Which TweakDB item is in a slot".
+    -- PRECONDITION: the item is equipped BY HAND, and the console hazard means
+    -- the console must be CLOSED while this samples (the weapon drops to the holstered pose
+    -- while you type). Give the probe settleSeconds: 2.0.
+    ["cp2077.item.equipped"] = {
+        attestation = "attested(engine)",
+        citation = "shipped CET mods (GetItemInSlot, ItemID.GetTDBID)",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if p.slot == nil then
+                return errored('params.slot is required, e.g. "AttachmentSlots.WeaponRight"')
+            end
+            local slot = tostring(p.slot)
+            local evidence = {
+                slot = slot,
+                precondition = "the item must be equipped by hand and THE CONSOLE MUST BE CLOSED while this samples " ..
+                    "(the console hazard); use settleSeconds: 2.0",
+            }
+
+            local item, e = itemInSlot(slot)
+            if item == nil then
+                if e ~= nil then return errored("GetItemInSlot failed: " .. e, evidence) end
+                return failed("nothing is in slot " .. slot, nil, evidence)
+            end
+            local tdbid, e2 = itemTdbid(item)
+            if tdbid == nil then
+                return errored("ItemID.GetTDBID(item:GetItemData():GetID()) failed: " .. tostring(e2), evidence)
+            end
+            local observed = tostring(tdbid)
+            evidence.tdbid = observed
+
+            -- `expect` handled here, not by the generic comparator: shipped CET mods
+            -- compare TDBIDs as `tdbid == TweakDBID.new(name)`, and the string form of a
+            -- TweakDBID is not attested to equal the record path it was built from. So an
+            -- `eq`/`ne` against a string is answered with the ATTESTED comparison.
+            if type(probe.expect) == "table" and type(probe.expect.value) == "string"
+                and (probe.expect.op == "eq" or probe.expect.op == "ne") then
+                local want = probe.expect.value
+                local same
+                local okC, e3 = pcall(function() same = (tdbid == TweakDBID.new(want)) end)
+                if not okC then
+                    return errored("TweakDBID.new(\"" .. want .. "\") comparison failed: " .. tostring(e3), evidence)
+                end
+                evidence.expect = { op = probe.expect.op, value = want, note = "TweakDBID.new equality (the comparison shipped CET mods use)" }
+                local pass = (probe.expect.op == "eq") and same or (not same)
+                return {
+                    status = pass and "pass" or "fail",
+                    observed = observed,
+                    evidence = evidence,
+                    expectHandled = true,
+                    error = (not pass) and ("slot " .. slot .. " holds " .. observed .. ", not " .. want) or nil,
+                }
+            end
+
+            return ok(observed, evidence)
+        end,
+    },
+
+    -- Row 5 — attested(doc) FOR THE CALL ONLY. "Give an item (**mutate**)".
+    -- `Game.AddToInventory(itemString, quantityString)` — wiki/Console.md §"Specificity"
+    -- ('if one wants to call `AddToInventory` they would call `Game.AddToInventory("ItemName", 1)`')
+    -- and wiki/ConsoleCommands.md:25, whose body is `WIP`: the RETURN VALUE IS UNDOCUMENTED.
+    -- The row's rule: the call's return is recorded but never trusted.
+    -- Preconditions: `allowMutate: true` and a disposable save.
+    ["cp2077.inventory.add"] = {
+        attestation = "attested(doc) for the call; success is NOT read from its return",
+        citation = "wiki/Console.md §\"Specificity\"; wiki/ConsoleCommands.md:25 (body: WIP)",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            if p.item == nil then return errored("params.item is required") end
+            local item = tostring(p.item)
+            -- ConsoleCommands.md:25 names the parameters `itemString, quantityString`, while
+            -- Console.md's example passes the number 1. The string form is what the signature
+            -- says, so that is what is sent, and both are recorded.
+            local qty = tostring(p.qty or p.quantity or 1)
+            local evidence = {
+                item = item,
+                qty = qty,
+                signature = "Game.AddToInventory(itemString, quantityString) — ConsoleCommands.md:25",
+                returnTrusted = false,
+                note = "PASS here means only that the call was invoked without a Lua error. The wiki body for this " ..
+                    "command is `WIP`, so its return value is undocumented and is recorded verbatim without being " ..
+                    "interpreted. Pair this row with a following read probe (cp2077.item.equipped, or a TweakDB " ..
+                    "read) to learn whether anything actually happened.",
+            }
+            local present = have("Game")
+            if not present then return absent("the `Game` global", "a console check") end
+            local ret
+            local okA, e = pcall(function() ret = Game.AddToInventory(item, qty) end)
+            if not okA then
+                return errored("Game.AddToInventory(\"" .. item .. "\", \"" .. qty .. "\") raised: " .. tostring(e), evidence)
+            end
+            evidence.returnValue = coerce(ret)
+            evidence.returnType = type(ret)
+            return ok(true, evidence)
+        end,
+    },
+
+    -- Added 2026-09-11 so that the console lines once pasted by hand
+    -- (`Game.AddToInventory(...)`, `TweakDB:GetRecord(...)`, `GetMod(...).where()`) run
+    -- through ModWright. Same shape as the BG3 handler: `return <code>` first, the bare chunk
+    -- as the fallback, pcall, every return value coerced, the encoded result capped at
+    -- `maxBytes` (default 16 KB). Marked `mutates = true` and listed in MUTATING_KINDS: the
+    -- bridge cannot know what a chunk does, so it never runs one without allowMutate. The gate
+    -- below keys off THIS flag rather than the effect word on the request, so a request that
+    -- labelled this kind `read` is skipped exactly like one labelled `mutate`.
+    -- Status unverified: nothing here has run in a game, so whether a CET mod's environment
+    -- exposes a Lua loader at all is the first thing a launch settles.
+    ["cp2077.lua.eval"] = {
+        attestation = "unverified",
+        citation = "added 2026-09-11 so console lines run through ModWright",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            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, and this is the half that matters here: this file stays in the
+            -- 5.1 subset, and in 5.1 `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`, ignored by 5.1's
+            -- `loadstring`.
+            local loader = loadstring or load
+            if loader == nil then
+                return errored("no Lua loader (loadstring/load) is exposed to this mod", { code = code })
+            end
+            -- Observed on the first launch of this kind (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
+            -- 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 ok(observed, { code = code, form = form, returnCount = returnCount, bytes = bytes, truncated = truncated })
+        end,
+    },
+
+    -- Row 6 — attested(engine). "Find dynamic entities by tag".
+    ["cp2077.entity.tagged"] = {
+        attestation = "attested(engine)",
+        citation = "shipped CET mods (GetDynamicEntitySystem/GetTaggedIDs, FindEntityByID)",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if p.tag == nil then return errored("params.tag is required") end
+            local tag = tostring(p.tag)
+            local ids, e = taggedIds(tag)
+            local evidence = { tag = tag, precondition = "loaded save, player near the entity (it must be streamed in)" }
+            if ids == nil then
+                return errored("Game.GetDynamicEntitySystem():GetTaggedIDs(\"" .. tag .. "\") failed: " .. tostring(e), evidence)
+            end
+            local list = Protocol.array({})
+            local resolved = 0
+            for i, id in ipairs(ids) do
+                local ent, e2 = entityById(id)
+                if ent ~= nil then resolved = resolved + 1 end
+                list[i] = { id = tostring(id), resolved = ent ~= nil, error = e2 }
+            end
+            evidence.ids = list
+            evidence.resolvedCount = resolved
+            evidence.taggedCount = #ids
+            if #ids == 0 then
+                return failed("no dynamic entity carries the tag \"" .. tag .. "\" right now", 0, evidence)
+            end
+            return ok(#ids, evidence)
+        end,
+    },
+
+    -- Row 7 — attested(engine) FOR THE CALL; the component NAMES to ask for are per-case
+    -- and **unverified**, which is why `params.names` is required and never defaulted.
+    ["cp2077.entity.components"] = {
+        attestation = "attested(engine) for the call; the component names asked for are unverified (per-case)",
+        citation = "shipped CET mods (ent:FindComponentByName)",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if type(p.names) ~= "table" or #p.names == 0 then
+                return errored("params.names must be a non-empty array of component names. There is no default: " ..
+                    "the names are per-case and unverified, so guessing one would manufacture evidence.")
+            end
+            local ent, describe, e = resolveEntity(p)
+            if ent == nil then return errored(e, { resolve = describe }) end
+
+            local found, map, errs = sweepComponents(ent, p.names)
+            local evidence = {
+                resolve = describe,
+                asked = Protocol.array(p.names),
+                byName = map,
+                errors = errs,
+                precondition = "the entity must be streamed in",
+            }
+            if #errs > 0 then
+                return errored("FindComponentByName failed for " .. #errs .. " name(s): " .. table.concat(errs, "; "), evidence)
+            end
+            if #found == 0 then
+                return failed("none of the " .. #p.names .. " named components is on this entity", found, evidence)
+            end
+            return ok(found, evidence)
+        end,
+    },
+
+    -- Row 8 — attested(engine) FOR ITEM OBJECTS (shipped mods read these off the drawn
+    -- weapon); **unverified** for a sector-placed prop, which a
+    -- `GetTaggedIDs`/`GetWorldPosition` console line settles. The attestation reported in the
+    -- evidence therefore depends on HOW the entity was resolved.
+    ["cp2077.entity.transform"] = {
+        attestation = "attested(engine) for item objects; unverified for a sector-placed prop",
+        citation = "shipped CET mods (GetWorldPosition/GetWorldOrientation on an item object)",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            local ent, describe, e = resolveEntity(p)
+            if ent == nil then return errored(e, { resolve = describe }) end
+
+            local evidence = { resolve = describe, precondition = "the entity must be streamed in" }
+            if describe.via == "tag" then
+                evidence.attestationForThisCall = "unverified — this is a sector-placed/dynamic prop, not the item " ..
+                    "object shipped CET mods read; a console line is the confirmation"
+            else
+                evidence.attestationForThisCall = "attested(engine) — shipped CET mods read these off an item object"
+            end
+
+            local pos, orient
+            local okP, e1 = pcall(function() pos = ent:GetWorldPosition() end)
+            if not okP then return errored("ent:GetWorldPosition() raised: " .. tostring(e1), evidence) end
+            local okO, e2 = pcall(function() orient = ent:GetWorldOrientation() end)
+            if not okO then evidence.orientationError = tostring(e2) end
+
+            local position = xyz(pos)
+            local orientation = quat(orient)
+            evidence.position = position
+            evidence.orientation = orientation
+            evidence.positionRaw = (position == nil) and tostring(pos) or nil
+            if position == nil then
+                return failed("GetWorldPosition returned something with no readable x/y/z: " .. tostring(pos), nil, evidence)
+            end
+            return ok(position, evidence)
+        end,
+    },
+
+    -- Row 9 — **unverified**. The acceptance-regression differential: tagged -> components
+    -- -> transform, compared against a recorded good baseline.
+    --
+    -- READ THIS BEFORE TRUSTING THIS ROW.
+    -- The observed failure is "a wrong/unresolvable name spawns an INVISIBLE entity"; nothing on disk
+    -- attests a visibility predicate in CET Lua, so this probe CANNOT answer "is it visible". It
+    -- answers "does this entity carry the same components in the same place as the baseline", and
+    -- acceptance pairs it with a manual row ("stand at the marker; is the case drawn?").
+    --
+    -- With no `params.baseline` it is a CAPTURE, and says so with status `skipped` rather than
+    -- reporting a pass it did not earn.
+    ["cp2077.entity.appearance"] = {
+        attestation = "unverified (composite; see the comment above the row)",
+        citation = "composed of cp2077.entity.tagged + .components + .transform; see the comment above the row for the failure mode",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if p.tag == nil then return errored("params.tag is required (the sector node's tag)") end
+            if type(p.names) ~= "table" or #p.names == 0 then
+                return errored("params.names must be the candidate component-name list to probe; the " ..
+                    "names are per-case and unverified, so this row never invents one")
+            end
+            local tag = tostring(p.tag)
+
+            local ids, e = taggedIds(tag)
+            local evidence = {
+                tag = tag,
+                baselineId = p.baselineId and tostring(p.baselineId) or nil,
+                caveat = "this row cannot answer \"is it visible\": no visibility predicate is attested in CET Lua. " ..
+                    "Pair it with the manual row \"stand at the marker; is the case drawn?\".",
+                precondition = "player within streaming range; baseline captured on a known-good build",
+            }
+            if ids == nil then return errored("GetTaggedIDs(\"" .. tag .. "\") failed: " .. tostring(e), evidence) end
+            evidence.taggedCount = #ids
+            if #ids == 0 then
+                return failed("nothing carries the tag \"" .. tag .. "\" — the entity did not spawn, or is not streamed in",
+                    nil, evidence)
+            end
+
+            local index = tonumber(p.index) or 1
+            local ent, e2 = entityById(ids[index])
+            if ent == nil then
+                return errored("Game.FindEntityByID resolved nothing for \"" .. tag .. "\" #" .. tostring(index) ..
+                    (e2 and (": " .. e2) or ""), evidence)
+            end
+
+            local found, map = sweepComponents(ent, p.names)
+            local pos
+            pcall(function() pos = ent:GetWorldPosition() end)
+            local capture = {
+                components = found,
+                byName = map,
+                position = xyz(pos),
+                taggedCount = #ids,
+            }
+            evidence.capture = capture
+
+            local baseline = p.baseline
+            if type(baseline) ~= "table" then
+                return {
+                    status = "skipped",
+                    observed = capture,
+                    evidence = evidence,
+                    error = "no params.baseline was supplied, so no differential was computed. This row is a " ..
+                        "DIFFERENTIAL: record `evidence.capture` from a known-good build as the baseline and re-run " ..
+                        "with params.baseline set to it.",
+                }
+            end
+
+            local baseComponents = {}
+            if type(baseline.components) == "table" then
+                for _, n in ipairs(baseline.components) do baseComponents[tostring(n)] = true end
+            end
+            local missing, extra = Protocol.array({}), Protocol.array({})
+            for _, n in ipairs(found) do
+                if not baseComponents[n] then extra[#extra + 1] = n end
+            end
+            for n in pairs(baseComponents) do
+                if map[n] ~= true then missing[#missing + 1] = n end
+            end
+            table.sort(missing)
+
+            local moved = nil
+            local basePos = baseline.position
+            if type(basePos) == "table" and capture.position ~= nil then
+                local dx = (tonumber(basePos.x) or 0) - capture.position.x
+                local dy = (tonumber(basePos.y) or 0) - capture.position.y
+                local dz = (tonumber(basePos.z) or 0) - capture.position.z
+                moved = { dx = dx, dy = dy, dz = dz }
+                local tol = tonumber(p.positionTolerance) or 0.05
+                moved.withinTolerance = (dx * dx + dy * dy + dz * dz) <= (tol * tol)
+                moved.tolerance = tol
+            end
+            evidence.diff = { missingComponents = missing, extraComponents = extra, position = moved }
+            evidence.baseline = { components = Protocol.array(baseline.components or {}), position = basePos }
+
+            if #missing > 0 or #extra > 0 then
+                return failed("the component list differs from the baseline (" .. #missing .. " missing, " .. #extra ..
+                    " extra); that is the appearance regression's signature when the position is unchanged",
+                    capture, evidence)
+            end
+            if moved ~= nil and moved.withinTolerance == false then
+                return failed("components match the baseline but the entity moved beyond the tolerance", capture, evidence)
+            end
+            return ok(capture, evidence)
+        end,
+    },
+
+    -- Row 10. `TweakDB:GetRecord(id)`, not attested by any page or mod on disk, but observed
+    -- to work from the CET console (2026-09-08):
+    --   print(tostring(TweakDB:GetRecord("Items.Preset_Example")))
+    ["cp2077.tweakdb.record"] = {
+        attestation = "attested(engine)",
+        citation = "observed in the CET console (2026-09-08): TweakDB:GetRecord(id) returned userdata",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if p.id == nil then return errored("params.id is required, e.g. \"Items.Preset_Example\"") end
+            local id = tostring(p.id)
+            local evidence = { id = id, call = "TweakDB:GetRecord(id)" }
+            local present, t = have("TweakDB")
+            if not present then return missingAttested("`TweakDB` (type " .. t .. ")", "TweakDB:GetRecord", evidence) end
+            local rec
+            local okR, e = pcall(function() rec = TweakDB:GetRecord(id) end)
+            if not okR then
+                return errored("TweakDB:GetRecord(\"" .. id .. "\") raised: " .. tostring(e) ..
+                    " — the call itself is attested (observed 2026-09-08); this is an error for this id or this session, not an unverified call", evidence)
+            end
+            evidence.returnType = type(rec)
+            evidence.returnValue = (rec ~= nil) and tostring(rec) or nil
+            if rec == nil then
+                return failed("no TweakDB record with id \"" .. id .. "\"", false, evidence)
+            end
+            return ok(true, evidence)
+        end,
+    },
+
+    -- Row 11. `TweakDB:GetFlat(id)`, same standing as row 10.
+    --   print(tostring(TweakDB:GetFlat("Items.Preset_Example.displayName")))
+    ["cp2077.tweakdb.flat"] = {
+        attestation = "attested(engine)",
+        citation = "observed in the CET console (2026-09-08): TweakDB:GetFlat(id) returned a LocKey",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            if p.id == nil then return errored("params.id is required, e.g. \"Items.Preset_Example.displayName\"") end
+            local id = tostring(p.id)
+            local evidence = { id = id, call = "TweakDB:GetFlat(id)" }
+            local present, t = have("TweakDB")
+            if not present then return missingAttested("`TweakDB` (type " .. t .. ")", "TweakDB:GetFlat", evidence) end
+            local flat
+            local okF, e = pcall(function() flat = TweakDB:GetFlat(id) end)
+            if not okF then
+                return errored("TweakDB:GetFlat(\"" .. id .. "\") raised: " .. tostring(e) ..
+                    " — the call itself is attested (observed 2026-09-08); this is an error for this id or this session, not an unverified call", evidence)
+            end
+            evidence.returnType = type(flat)
+            local value = coerce(flat)
+            evidence.value = value
+            if flat == nil then
+                return failed("no TweakDB flat with id \"" .. id .. "\"", nil, evidence)
+            end
+            return ok(value, evidence)
+        end,
+    },
+
+    -- Row 12 — **unverified (name)**. "An interaction component is on the entity" — the
+    -- call is `cp2077.entity.components`, but "the *name* is not attested anywhere on disk",
+    -- so the name must come from the request and is never guessed at here.
+    ["cp2077.interaction.present"] = {
+        attestation = "unverified (the interaction component's NAME is attested nowhere on disk)",
+        citation = "shipped CET mods for the call; the component name itself is unattested",
+        effect = "read",
+        run = function(probe)
+            local p = params(probe)
+            local names = p.names
+            if type(names) ~= "table" or #names == 0 then
+                if p.name ~= nil then names = { p.name } end
+            end
+            if type(names) ~= "table" or #names == 0 then
+                return errored("params.names (or params.name) is required: NO interaction component name is attested " ..
+                    "by any source on disk, so this row will not guess one. Supply the candidate name(s) you " ..
+                    "want probed, and record the answer as the confirmation.")
+            end
+            local ent, describe, e = resolveEntity(p)
+            if ent == nil then return errored(e, { resolve = describe }) end
+
+            local found, map, errs = sweepComponents(ent, names)
+            local evidence = {
+                resolve = describe,
+                asked = Protocol.array(names),
+                byName = map,
+                errors = errs,
+                caveat = "the component NAME is unverified: an absent result may mean the interaction is missing OR " ..
+                    "that this is the wrong name for it. Only a name confirmed in the field promotes this row.",
+            }
+            if #errs > 0 then
+                return errored("FindComponentByName failed: " .. table.concat(errs, "; "), evidence)
+            end
+            if #found == 0 then
+                return failed("none of the named interaction components is on this entity", found, evidence)
+            end
+            return ok(found, evidence)
+        end,
+    },
+
+    -- Row 13 — **not designed.** "Loot table produced an item": no attested call exists
+    -- on disk. It stays a `manual` row until a confirmation step lands
+    -- one, so this kind is implemented as a permanent `unsupported`, which is the status
+    -- reserved for a kind the bridge cannot answer.
+    ["cp2077.loot.roll"] = {
+        attestation = "not designed",
+        citation = "the catalogue's last row — no attested call exists on disk",
+        effect = "read",
+        run = function()
+            return {
+                status = "unsupported",
+                observed = nil,
+                evidence = {
+                    designStatus = "not designed",
+                    remedy = "keep this as a `manual` test-plan row (\"kill the enemy; did the item drop?\") until a " ..
+                        "confirmation step lands an attested call. Nothing in CET on disk reads a loot roll.",
+                },
+                error = "cp2077.loot.roll is not designed: no attested call exists on disk. It stays a manual row.",
+            }
+        end,
+    },
+}
+-- MODWRIGHT-PROBE-TABLE-END
+
+-- ---------------------------------------------------------------------------
+-- Dispatch
+-- ---------------------------------------------------------------------------
+
+--- Attach the row's status word and citation, apply `expect`, and stamp the result.
+function Probes.finalize(probe, handler, out)
+    local status = out.status or "pass"
+    local evidence = out.evidence
+    if type(evidence) ~= "table" then evidence = {} end
+    if handler ~= nil then
+        evidence.attestation = handler.attestation
+        evidence.citation = handler.citation
+    end
+
+    if not out.expectHandled and (status == "pass" or status == "fail") and type(probe.expect) == "table" then
+        local verdict, note = Probes.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
+
+local function deepEqual(a, b)
+    if type(a) ~= "table" or type(b) ~= "table" then return a == b end
+    return Protocol.encode(a) == Protocol.encode(b)
+end
+
+local function containsValue(observed, value)
+    if observed == nil then return false end
+    local needle = tostring(value)
+    if type(observed) == "string" then return observed:find(needle, 1, true) ~= nil end
+    if type(observed) == "table" then
+        for _, v in pairs(observed) do
+            if type(v) == "table" then
+                if containsValue(v, value) then return true end
+            elseif tostring(v) == needle then
+                return true
+            end
+        end
+        return Protocol.encode(observed):find(needle, 1, true) ~= nil
+    end
+    return tostring(observed) == needle
+end
+
+--- The `expect` block: `{ op: "eq"|"ne"|"gte"|"lte"|"contains"|"absent", value }`.
+--- Returns "pass"|"fail"|"error" plus a short note for `evidence.expect`.
+function Probes.evaluateExpect(observed, expect)
+    if type(expect) ~= "table" or expect.op == nil then return nil, nil end
+    local op = tostring(expect.op)
+    local value = expect.value
+
+    if op == "eq" then
+        return deepEqual(observed, value) and "pass" or "fail", "eq"
+    elseif op == "ne" then
+        return (not deepEqual(observed, value)) and "pass" or "fail", "ne"
+    elseif op == "gte" or op == "lte" then
+        local a, b = tonumber(observed), tonumber(value)
+        if a == nil or b == nil then
+            return "error", op .. " needs two numbers; observed=" .. tostring(observed)
+        end
+        if op == "gte" then return (a >= b) and "pass" or "fail", "gte" end
+        return (a <= b) and "pass" or "fail", "lte"
+    elseif op == "contains" then
+        return containsValue(observed, value) and "pass" or "fail", "contains"
+    elseif op == "absent" then
+        local empty = (observed == nil) or (observed == false) or (observed == "")
+        if not empty and type(observed) == "table" then empty = (next(observed) == nil) end
+        return empty and "pass" or "fail", "absent"
+    end
+    return "error", "unknown expect op: " .. op
+end
+
+--- The ids allowed to mutate anything: the inventory row it always had, and
+--- (since 2026-09-11) the eval row. Named
+--- as a constant so the gate below reads as the rule it enforces.
+Probes.MUTATING_KINDS = { ["cp2077.inventory.add"] = true, ["cp2077.lua.eval"] = true }
+
+--- Run one probe. NEVER throws: one probe failing can never abort the batch, and a handler
+--- that raises is reported as `error` with the raised message.
+function Probes.run(probe, request, runCtx)
+    local kind = tostring(probe.kind or "")
+    local handler = Probes.handlers[kind]
+
+    if handler == nil then
+        return Probes.finalize(probe, nil, {
+            status = "unsupported",
+            observed = nil,
+            evidence = { kind = kind, context = "cet" },
+            error = "no handler for probe kind \"" .. kind .. "\" in the CET dispatch table (the catalogue lists every id it knows)",
+        })
+    end
+
+    -- The `observe` effect: a listener is armed and the human performs the action.
+    -- No CET listener API is attested by any source on disk (`Observe` is a CET extra that
+    -- nothing here can vouch for), so an observe probe is `unsupported`, not a silent read.
+    if tostring(probe.effect or "read") == "observe" then
+        return Probes.finalize(probe, handler, {
+            status = "unsupported",
+            observed = nil,
+            evidence = { effect = "observe", ObserveAvailable = Protocol.caps.Observe == true },
+            error = "this bridge cannot observe: no CET listener API is attested by any source on disk. Use a " ..
+                "`read` probe with settleSeconds, or a manual test-plan row.",
+        })
+    end
+
+    -- THE MUTATION GATE (keyed on the capability tiers).
+    -- Two conditions, both required: the kind is one of the ids with effect `mutate`, and
+    -- the request was granted the `session` tier (Protocol.grantsTier, which still honours the
+    -- retired `allowMutate: true` alias for one release).
+    local wantsMutation = (handler.mutates == true) or (tostring(probe.effect or "read") == "mutate")
+    if wantsMutation then
+        if Probes.MUTATING_KINDS[kind] ~= true then
+            return Probes.finalize(probe, handler, {
+                status = "skipped",
+                observed = nil,
+                evidence = { effect = "mutate", kind = kind },
+                error = "the probe declares effect \"mutate\" but " .. kind .. " is a read-only row in the catalogue. " ..
+                    "The only kinds this bridge lets mutate anything are cp2077.inventory.add and cp2077.lua.eval.",
+            })
+        end
+        if not Protocol.grantsTier(request, "session") then
+            return Probes.finalize(probe, handler, {
+                status = "skipped",
+                observed = nil,
+                evidence = { effect = "mutate", tier = "session", granted = false },
+                error = "effect is \"mutate\" (session tier) and the request was not granted the \"session\" tier. " ..
+                    "Grant it via bridge.policy mode: workbench, grant: [\"session\"], or the retired " ..
+                    "allowMutate: true alias.",
+            })
+        end
+    end
+
+    local okRun, out = pcall(handler.run, probe, request, runCtx)
+    if okRun and type(out) == "table" then return Probes.finalize(probe, handler, out) end
+    Protocol.err("probe:" .. kind, out)
+    return Probes.finalize(probe, handler, {
+        status = "error",
+        observed = nil,
+        evidence = { kind = kind },
+        error = tostring(out),
+    })
+end
+
+--- Every kind this bridge answers, sorted — printed by `m.help()` and counted in the banner.
+function Probes.kinds()
+    local out = {}
+    for k in pairs(Probes.handlers) do out[#out + 1] = k end
+    table.sort(out)
+    return out
+end
+
+return Probes