modwright 0.1.0

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

@@ -0,0 +1,175 @@
+-- MODWRIGHT-BRIDGE-DO-NOT-SHIP
+--
+-- ModWrightBridge / Watch.lua — listeners for `effect: "observe"` probes
+-- (an observe probe registers its listener at arm time and is harvested when window.seconds
+-- elapses).
+--
+-- Why watching and not doing: `Osi.UseSpell` was observed to re-cast, move the caster and
+-- self-kill via an HP-cost passive, and was removed from the mod that used it. So "spell
+-- resolved" is reachable only by watching while the human casts — this bridge never calls
+-- an Osiris action and never forces a cast.
+--
+-- ============================================================================
+-- Ext API used in this file
+-- ============================================================================
+-- API.md §"Calling Lua from Osiris" / "Capturing Events/Calls":
+--   `Ext.Osiris.RegisterListener(name, arity, event, handler)`
+--   - `arity` is "the number of columns for DBs or the number of parameters (both IN and OUT)"
+--   - `event` is one of `before`, `after`, `beforeDelete`, `afterDelete`
+--   - "handler is a Lua function ... The function receives all parameters of the original DB/function."
+--   Example: `Ext.Osiris.RegisterListener("TurnEnded", 1, "after", function (characterGuid) ... end)`
+--   Arities this bridge is likely to be asked for (observed in game; wrong arity gives a
+--   silently dead listener): CastedSpell 5, StatusApplied 4, StatusRemoved 4,
+--   Died 1, KilledBy 4, UsingSpellOnTarget 6.
+-- API.md §"SE Events":
+--   `Ext.Events.<EVENT_NAME>:Subscribe(fun)` returning "a handler index that can be used to
+--   cancel the subscription later on", and `Ext.Events.<EVENT_NAME>:Unsubscribe(handlerId)`.
+--
+-- KNOWN LIMIT, stated rather than hidden: API.md documents `Unsubscribe` for `Ext.Events` but
+-- lists NO unregister for `Ext.Osiris.RegisterListener`. So an Osiris listener, once armed,
+-- lives until the Lua state is reloaded. This module therefore registers at most ONE engine
+-- listener per (name, arity) per Lua state and fans out to per-probe subscriber records that
+-- can be deactivated; repeated observe requests reuse the same registration instead of
+-- stacking a new dead closure on every run.
+
+local Log = Ext.Require("ModWrightBridge/Log.lua")
+local Protocol = Ext.Require("ModWrightBridge/Protocol.lua")
+
+local Watch = {}
+
+--- key "<name>/<arity>" -> { subscribers = { watchRecord, ... } }
+Watch.osirisRegistry = {}
+
+--- Capture one call's varargs as JSON-safe values. Osiris hands strings and numbers; anything
+--- else is stringified rather than dropped, and an actual nil becomes "<nil>" so the argument
+--- list keeps its positions (a hole would make the array encode short).
+local function captureArgs(n, ...)
+    local args = Protocol.array({})
+    for i = 1, n do
+        local v = select(i, ...)
+        local t = type(v)
+        if v == nil then
+            args[i] = "<nil>"
+        elseif t == "number" or t == "string" or t == "boolean" then
+            args[i] = v
+        else
+            args[i] = tostring(v)
+        end
+    end
+    return args
+end
+
+--- `match` is a map from 1-based argument position to an expected value. JSON object keys are
+--- strings, so both `match[i]` and `match[tostring(i)]` are honoured. GUID comparisons go
+--- through Protocol.normGuid, because Osiris hands the same
+--- entity as a bare UUID in some events and as a prefixed `Name_UUID` in others.
+local function rowMatches(match, args)
+    if type(match) ~= "table" then return true end
+    for k, want in pairs(match) do
+        local idx = tonumber(k)
+        if idx ~= nil then
+            local got = args[idx]
+            local a, b = tostring(got), tostring(want)
+            if a ~= b and Protocol.normGuid(a) ~= Protocol.normGuid(b) then
+                return false
+            end
+        end
+    end
+    return true
+end
+
+--- Arm (or join) an Osiris listener. Returns a watch record, or (nil, error string).
+function Watch.osiris(name, arity, match, limit)
+    if type(name) ~= "string" or name == "" then return nil, "params.name is required" end
+    local n = tonumber(arity)
+    if n == nil then
+        return nil, "params.arity is required and must be a number (a wrong arity gives a silently dead listener)"
+    end
+
+    local key = name .. "/" .. tostring(math.floor(n))
+    local reg = Watch.osirisRegistry[key]
+    if reg == nil then
+        reg = { subscribers = {} }
+        local ok, err = pcall(function()
+            Ext.Osiris.RegisterListener(name, math.floor(n), "after", Log.guarded("osiris:" .. key, function(...)
+                local argc = select("#", ...)
+                local args = captureArgs(argc, ...)
+                local at = Log.monotonic()
+                for _, w in ipairs(reg.subscribers) do
+                    if w.active and #w.rows < w.limit and rowMatches(w.match, args) then
+                        w.rows[#w.rows + 1] = { at = at, args = args }
+                    end
+                end
+            end))
+        end)
+        if not ok then
+            return nil, "Ext.Osiris.RegisterListener(\"" .. name .. "\", " .. tostring(n) .. ", \"after\", ...) failed: " .. tostring(err)
+        end
+        Watch.osirisRegistry[key] = reg
+        Log.info("armed Osiris listener " .. key .. " (after)")
+    end
+
+    local w = {
+        kind = "osiris",
+        key = key,
+        name = name,
+        arity = math.floor(n),
+        match = match,
+        limit = tonumber(limit) or 64,
+        rows = Protocol.array({}),
+        active = true,
+    }
+    reg.subscribers[#reg.subscribers + 1] = w
+    return w
+end
+
+--- Arm an `Ext.Events.<name>` subscription. Returns a watch record, or (nil, error string).
+--- Used for `bg3.event.damage`'s `EsvLuaBeforeDealDamage`, which is
+--- **unverified (event fields)**: it is NOT in API.md's event table, only used in a
+--- shipped SE mod. Hence the existence check below, and
+--- hence rows are dumped WHOLE rather than read through a field path nothing pins.
+function Watch.engineEvent(name, limit)
+    if type(name) ~= "string" or name == "" then return nil, "event name is required" end
+    local ev
+    pcall(function() ev = Ext.Events[name] end)
+    if ev == nil then
+        return nil, "Ext.Events." .. name .. " does not exist in this Script Extender build (it is not in API.md's event table either)"
+    end
+
+    local w = {
+        kind = "event",
+        name = name,
+        limit = tonumber(limit) or 10,
+        rows = Protocol.array({}),
+        active = true,
+        eventRef = ev,
+    }
+
+    local ok, handlerId = pcall(function()
+        return ev:Subscribe(Log.guarded("event:" .. name, function(e)
+            if not w.active then return end
+            if #w.rows >= w.limit then return end
+            local tbl = Protocol.dumpComponent(e, 6)
+            w.rows[#w.rows + 1] = { at = Log.monotonic(), event = tbl }
+        end))
+    end)
+    if not ok then
+        return nil, "Ext.Events." .. name .. ":Subscribe failed: " .. tostring(handlerId)
+    end
+    w.handlerId = handlerId
+    Log.info("armed engine event listener " .. name)
+    return w
+end
+
+--- Deactivate a watch. Engine-event subscriptions are unsubscribed (API.md documents it);
+--- Osiris subscribers are only deactivated, because API.md documents no unregister for them.
+function Watch.stop(w)
+    if type(w) ~= "table" then return end
+    w.active = false
+    if w.kind == "event" and w.eventRef ~= nil and w.handlerId ~= nil then
+        pcall(function() w.eventRef:Unsubscribe(w.handlerId) end)
+        w.eventRef = nil
+    end
+end
+
+return Watch

package/bridges/bg3-se/Mods/ModWrightBridge/meta.lsx

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<save>
+  <version major="4" minor="8" revision="0" build="500" />
+  <region id="Config">
+    <node id="root">
+      <children>
+        <node id="Conflicts" />
+        <node id="Dependencies" />
+        <node id="ModuleInfo">
+          <attribute id="Author" type="LSString" value="ModWright" />
+          <attribute id="CharacterCreationLevelName" type="FixedString" value="" />
+          <attribute id="Description" type="LSString" value="MODWRIGHT-BRIDGE-DO-NOT-SHIP. ModWright's author-only verification bridge: reads entity components and stats on request and writes the answers to the Script Extender folder. Never ship this with a mod." />
+          <attribute id="FileSize" type="uint64" value="0" />
+          <attribute id="Folder" type="LSString" value="ModWrightBridge" />
+          <attribute id="LobbyLevelName" type="FixedString" value="" />
+          <attribute id="MD5" type="LSString" value="" />
+          <attribute id="MainMenuBackgroundVideo" type="FixedString" value="" />
+          <attribute id="MenuLevelName" type="FixedString" value="" />
+          <attribute id="Name" type="FixedString" value="ModWrightBridge" />
+          <attribute id="NumPlayers" type="uint8" value="4" />
+          <attribute id="PhotoBooth" type="FixedString" value="" />
+          <attribute id="PublishHandle" type="uint64" value="0" />
+          <attribute id="StartupLevelName" type="FixedString" value="" />
+          <attribute id="Tags" type="LSString" value="" />
+          <attribute id="Type" type="FixedString" value="Add-on" />
+          <attribute id="UUID" type="FixedString" value="2f81bf4a-d9c7-43c5-a5e1-16c5e1d6fbc9" />
+          <attribute id="Version64" type="int64" value="36028797018963968" />
+          <children>
+            <node id="PublishVersion">
+              <attribute id="Version64" type="int64" value="36028797018963968" />
+            </node>
+            <node id="Scripts" />
+            <node id="TargetModes">
+              <children>
+                <node id="Target">
+                  <attribute id="Object" type="FixedString" value="Story" />
+                </node>
+              </children>
+            </node>
+          </children>
+        </node>
+      </children>
+    </node>
+  </region>
+</save>

package/bridges/bg3-se/README.md

@@ -0,0 +1,99 @@
+# bg3-se bridge
+
+The Baldur's Gate 3 Script Extender bridge: ModWright's author-only, read-only verification
+mod. It writes a heartbeat while loaded, polls for an armed request, runs the probes that
+request names, and writes a result plus a `done` marker. It is staged by
+`stageBridge(project, "baldursgate3")` (`src/core/bridge/stage.ts`) into
+`<project>/.modwright/bridge/bg3-se/`, and `deploy --variant withBridge` copies
+`Mods/ModWrightBridge` from there into the project's `loose` root
+(`Data/Mods/ModWrightBridge`).
+
+The protocol is implemented on the Node side in `src/core/bridge/`; the probe catalogue is
+the dispatch table in `Probes.lua`.
+
+## Module identity
+
+| | |
+|---|---|
+| Module UUID | `2f81bf4a-d9c7-43c5-a5e1-16c5e1d6fbc9` |
+| `Folder` / `Name` | `ModWrightBridge` |
+| `Version64` | `36028797018963968` (1.0.0.0) |
+| `ModTable` | `ModWrightBridge` |
+| `RequiredVersion` | `21` |
+
+The UUID is **fixed and published here**: it is generated once and never
+regenerated, because it is what a person pastes into a test profile's `modsettings.lsx`
+`ModuleShortDesc` and what `bg3.mod.active` would be asked about. `RequiredVersion: 21`
+matches the floor of a shipped SE mod rather than API.md's
+example 29, so the bridge never demands a newer extender than the mod under test; anything
+newer it wants (`Ext.Timer.ClockEpoch`, `Ext.Utils.GetCommandLineParams`) is `pcall`ed and
+degraded gracefully when absent. `Version64` is Larian's packed form
+(`major<<55 | minor<<47 | revision<<31 | build`), the same encoding other mods' meta.lsx files use.
+
+## protocolVersion
+
+**1** — the current value of `PROTOCOL_VERSION` in `src/core/bridge/types.ts`. The Lua
+defines the identical integer literal as `Protocol.PROTOCOL_VERSION`
+(`ScriptExtender/Lua/ModWrightBridge/Protocol.lua`): `protocolVersion` is an
+integer duplicated in the Lua and the Node constant, checked at arm time.
+`test/unit/bridge/bg3-lua-parity.test.ts` asserts the two literals agree.
+
+## The tree
+
+```
+bridges/bg3-se/
+  bridge.json                          # id, protocolVersion, version, file list, sha256s
+  README.md                            # this file
+  Mods/ModWrightBridge/
+    meta.lsx                           # Folder/Name/UUID/Version64
+    ScriptExtender/
+      Config.json                      # {"RequiredVersion":21,"ModTable":"ModWrightBridge","FeatureFlags":["Lua"]}
+      Lua/BootstrapServer.lua          # registration point (SessionLoaded + ResetCompleted)
+      Lua/BootstrapClient.lua          # client heartbeat + client probes only
+      Lua/ModWrightBridge/Protocol.lua      # io + marker framing + nonce + heartbeat + run orchestration
+      Lua/ModWrightBridge/Probes.lua        # server dispatch table (all 14 probe ids)
+      Lua/ModWrightBridge/ProbesClient.lua  # client dispatch table (bg3.client.loaded)
+      Lua/ModWrightBridge/Watch.lua         # observe-probe listeners
+      Lua/ModWrightBridge/Log.lua           # [ModWrightBridge] prints + rolling ModWright_log.json
+```
+
+`bridge.json`'s `files[]` carries a `sha256` per file: plain `sha256` over the file's raw
+bytes, hex, keyed by a POSIX path relative to this directory. `bridge stage` copies the tree
+verbatim and does **not** fill them in, and nothing in ModWright reads them yet — they exist
+so a staged or deployed copy can be compared against the source of truth by hand. Recompute
+them (and bump `version`) whenever a file here changes; `bridge.json` itself is excluded from
+its own list.
+
+## The content banner
+
+`BRIDGE_BANNER` in `src/core/bridge/types.ts` (`"MODWRIGHT-BRIDGE-DO-NOT-SHIP"`) appears,
+verbatim, in the **first line** of every `.lua` file here and in the module's `meta.lsx`
+description. This is what lets `bg3.history.bridge-never-ships`
+(`src/surfaces/baldursgate3/validators/bridge.ts`) catch a bridge file that reached a build
+output under a path that no longer says "ModWrightBridge" — e.g. flattened during packaging
+— not just one that still does. The validator reads only the first 1024 bytes, so the banner
+must stay on the first line: `bg3-lua-parity.test.ts` enforces that.
+
+## Checking the Lua
+
+No Lua parser is vendored. Syntax is checked with `luac -p` under Lua 5.1 and
+5.4 (every file here passes both as shipped); drift is checked by
+`test/unit/bridge/bg3-lua-parity.test.ts`, which reads the Lua as text and asserts the
+dispatch-table keys equal the catalogue's probe ids, that the `PROTOCOL_VERSION` literals
+agree, that `bridge.json` lists every shipped file, and that every `.lua` carries the banner.
+
+## What this bridge never does
+
+- No Osiris **action**, ever, and no forced cast: `Osi.UseSpell` was observed to re-cast,
+  move the caster and self-kill via an HP-cost passive. `observe` probes watch while the
+  human acts.
+- No Osiris **query** as a source of truth: the whole query set was observed returning
+  wrong/false on the tested build. Every read is an entity-component read. The
+  two deliberate exceptions — `Osi.GetMaxHitpoints` inside `bg3.osiris.health`, where the
+  query's unreliability *is* the measurement, and `Osi.GetHostCharacter()` to expand the
+  `"$host"` token — are named at the top of `Probes.lua` and stamped into probe evidence as
+  `hostResolvedVia`.
+- No `PersistentVars`, `ModVars` or `UserVars` writes (API.md §"Persistence":
+  "PersistentVars are deprecated and should not be used").
+- No file deletion or rename: `Ext.IO` has none, which is why a consumed
+  request is retired by an in-memory nonce plus the request's own `armedUntil`.

package/bridges/bg3-se/bridge.json

@@ -0,0 +1,68 @@
+{
+  "id": "bg3-se",
+  "game": "baldursgate3",
+  "protocolVersion": 1,
+  "version": "0.1.0",
+  "moduleUuid": "2f81bf4a-d9c7-43c5-a5e1-16c5e1d6fbc9",
+  "moduleFolder": "ModWrightBridge",
+  "requiredExtenderVersion": 21,
+  "banner": "MODWRIGHT-BRIDGE-DO-NOT-SHIP",
+  "deploy": {
+    "rootId": "loose",
+    "from": ".modwright/bridge/bg3-se/Mods/ModWrightBridge",
+    "into": "Mods/ModWrightBridge",
+    "variant": "withBridge",
+    "locked": false,
+    "backup": true,
+    "prune": [
+      "ModWrightBridge/**"
+    ],
+    "note": "The deploy target a shipped SE mod uses, verbatim: `bridge stage` adds it to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit. A deploy WITHOUT `--variant withBridge` prunes the folder back out, with backup."
+  },
+  "sha256": {
+    "algorithm": "sha256",
+    "encoding": "hex",
+    "over": "the file's raw bytes, unmodified",
+    "paths": "POSIX-separated, relative to bridges/bg3-se/",
+    "regenerate": "python3 -c \"import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())\" <path>",
+    "note": "Recomputed by hand whenever a file here changes; `bridge stage` (src/core/bridge/stage.ts) copies the tree verbatim and does not fill these in, and nothing in ModWright reads them yet. They exist so a staged or deployed copy can be compared against the source of truth by hand."
+  },
+  "files": [
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Config.json",
+      "sha256": "50bf2bf72fc7f84b7ab373e9ecf1455dd8032e034701d29b08990a1a0b34a057"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/BootstrapClient.lua",
+      "sha256": "3c867c190e9c0f091d06cff59b43acb5e6fbaa067f18c27d23f8b8d07e66e402"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/BootstrapServer.lua",
+      "sha256": "40ba495dc6ca17640b921620e83f62ffb72503294456c898936d47bbb6e2aa6c"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/Log.lua",
+      "sha256": "a0297f2d93175efce05638c5806baf126b025a26ac61f30abb936f3112822c9d"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/Probes.lua",
+      "sha256": "76ca8cd1ddc993bd0e8bdb40c55e21021d4245b686bda64d4a9f9bb9f7f2c0e0"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/ProbesClient.lua",
+      "sha256": "8769934b38702435fb8f36c561d5a257010f5cd58a342982dc0d285ed9946e0f"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/Protocol.lua",
+      "sha256": "ee62d070fd15ca818198c0403fdb659930fc04d1841c7fa1433e18d3abdd60ba"
+    },
+    {
+      "path": "Mods/ModWrightBridge/ScriptExtender/Lua/ModWrightBridge/Watch.lua",
+      "sha256": "8dc31ba46f6ab03e5804742292be46f8a8124259370fe33fbcdde96a6d17557d"
+    },
+    {
+      "path": "Mods/ModWrightBridge/meta.lsx",
+      "sha256": "ac6fd48f1dc547c3f95abd56c3bceb9252ebca258ef23c74a50c35138d5d24c7"
+    }
+  ]
+}