re: EngineCtx field registry (engine-ctx.toml) + builder

Canonical source vm-map/engine-ctx.toml (35 documented ctx fields) +
engine_ctx_build.py (--build/--lint, unit-tested) -> build/engine-ctx.json
+ docs/engine-ctx-reference.md. Applied to Ghidra in the next task.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tools/engine_ctx_build.py

@@ -0,0 +1,85 @@
+"""Build the EngineCtx struct artifacts from vm-map/engine-ctx.toml (single source of truth).
+
+    py -3.11 -X utf8 tools/engine_ctx_build.py --build   # -> build/engine-ctx.json + docs/engine-ctx-reference.md
+    py -3.11 -X utf8 tools/engine_ctx_build.py --lint     # checks only (overlap / out-of-bounds / dup name / type)
+
+The struct is APPLIED to the Ghidra /v2 image via run_script_inline reading build/engine-ctx.json
+(see docs/superpowers/plans/2026-07-09-engine-ctx-struct.md). ctx = engine context (esi / thiscall this);
+the VM global bank G[...] is a separate space (vm-map/globals.toml), never added here.
+"""
+import json
+import sys
+import tomllib
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+TYPE_SIZES = {"int": 4, "uint": 4, "void*": 4}
+
+
+def load(toml_text):
+    d = tomllib.loads(toml_text)
+    fields = [{"offset": int(f["offset"]), "name": f["name"], "type": f["type"], "note": f.get("note", "")}
+              for f in d.get("field", [])]
+    fields.sort(key=lambda f: f["offset"])
+    return {"meta": d["meta"], "fields": fields}
+
+
+def lint(model):
+    errs, size = [], int(model["meta"]["size"])
+    seen_names, prev = {}, None
+    for f in model["fields"]:
+        sz = TYPE_SIZES.get(f["type"])
+        if sz is None:
+            errs.append(f"unknown type {f['type']!r} for {f['name']}")
+            sz = 4
+        if f["offset"] + sz > size:
+            errs.append(f"field {f['name']} @0x{f['offset']:x} out of bounds (size 0x{size:x})")
+        if f["name"] in seen_names:
+            errs.append(f"duplicate name {f['name']!r}")
+        seen_names[f["name"]] = True
+        if prev is not None and f["offset"] < prev["end"]:
+            errs.append(f"overlap: {f['name']} @0x{f['offset']:x} into {prev['name']} (ends 0x{prev['end']:x})")
+        prev = {"name": f["name"], "end": f["offset"] + sz}
+    return errs
+
+
+def emit_json(model):
+    return {"meta": model["meta"],
+            "fields": {hex(f["offset"]): {"name": f["name"], "type": f["type"]} for f in model["fields"]}}
+
+
+def emit_reference_md(model):
+    lines = ["# EngineCtx field reference", "",
+             "> Generated from `vm-map/engine-ctx.toml` by `tools/engine_ctx_build.py --build`. Do not edit.",
+             "", f"Struct `{model['meta']['struct_name']}`, size `0x{int(model['meta']['size']):x}`. "
+             "Applied to the Ghidra `/v2` image (dispatch-handler `this` = `EngineCtx *`).", "",
+             "| offset | name | type | note |", "|---|---|---|---|"]
+    for f in model["fields"]:
+        lines.append(f"| `0x{f['offset']:x}` | `{f['name']}` | `{f['type']}` | {f['note']} |")
+    return "\n".join(lines) + "\n"
+
+
+def main():
+    text = (REPO / "vm-map" / "engine-ctx.toml").read_text(encoding="utf-8")
+    model = load(text)
+    errs = lint(model)
+    if errs:
+        print("LINT ERRORS:")
+        for e in errs:
+            print("  " + e)
+        return 1
+    if "--lint" in sys.argv[1:]:
+        print(f"lint clean: {len(model['fields'])} fields")
+        return 0
+    if "--build" in sys.argv[1:]:
+        (REPO / "build" / "engine-ctx.json").write_text(
+            json.dumps(emit_json(model), indent=2) + "\n", encoding="utf-8")
+        (REPO / "docs" / "engine-ctx-reference.md").write_text(emit_reference_md(model), encoding="utf-8")
+        print(f"built {len(model['fields'])} fields -> build/engine-ctx.json + docs/engine-ctx-reference.md")
+        return 0
+    print(__doc__)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/test_engine_ctx.py

@@ -0,0 +1,61 @@
+"""Unit tests for the EngineCtx builder (tools/engine_ctx_build.py).
+
+Run: py -3.11 -X utf8 tools/test_engine_ctx.py   (plain runner, no pytest).
+"""
+import sys
+
+from engine_ctx_build import load, lint, emit_json
+
+FAILS = []
+
+
+def check(cond, msg):
+    if not cond:
+        FAILS.append(msg)
+        print("FAIL:", msg)
+    else:
+        print("ok:", msg)
+
+
+GOOD = ('[meta]\nstruct_name="EngineCtx"\nsize=0x1000\n'
+        '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote="x"\n'
+        '[[field]]\noffset=0x20\nname="b"\ntype="void*"\nnote="y"\n')
+
+
+def test_load_and_emit():
+    j = emit_json(load(GOOD))
+    check(j["fields"]["0x10"]["name"] == "a" and j["meta"]["struct_name"] == "EngineCtx",
+          "emit_json keys fields by hex offset + carries meta")
+
+
+def test_lint_clean():
+    check(lint(load(GOOD)) == [], "clean model lints with no errors")
+
+
+def test_lint_catches_overlap():
+    bad = ('[meta]\nstruct_name="E"\nsize=0x1000\n'
+           '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote=""\n'
+           '[[field]]\noffset=0x12\nname="b"\ntype="int"\nnote=""\n')   # 0x10+4 > 0x12 -> overlap
+    check(any("overlap" in e.lower() for e in lint(load(bad))), "lint flags overlapping fields")
+
+
+def test_lint_catches_oob_and_dupname():
+    bad = ('[meta]\nstruct_name="E"\nsize=0x14\n'
+           '[[field]]\noffset=0x10\nname="a"\ntype="int"\nnote=""\n'
+           '[[field]]\noffset=0x40\nname="a"\ntype="int"\nnote=""\n')   # 0x40 > size AND dup name
+    errs = lint(load(bad))
+    check(any("out of bounds" in e.lower() for e in errs) and any("duplicate" in e.lower() for e in errs),
+          "lint flags out-of-bounds offset and duplicate name")
+
+
+def main():
+    test_load_and_emit()
+    test_lint_clean()
+    test_lint_catches_overlap()
+    test_lint_catches_oob_and_dupname()
+    print("FAILURES:", len(FAILS))
+    return 1 if FAILS else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())