sots-engine/docs/P-events-wiring.md

P — wiring the event posts into ours

Lane E recovered the event API and landed src/game/events/ as a pure module. Lane R's guarded recapture then made the missing post precise: TechTree::ProcessResearch exits 1 with exactly one divergent field,

side.events.after.v.next_id  [exact]  orig={"t":"i32","v":4}  ours={"t":"i32","v":3}

on a call where the arithmetic reproduces perfectly (node[144].progress 2879→5768, flag 1→2, the single RNG draw identical). This lane closes that field.

It takes lane E's option (a), count-only. The game's EventStorage::PostEvent is never called and no live byte is written; ours posts into its own sots::events::EventStorage and writes the resulting counts into the scratch copy of the owner's storage header. That is what makes it safe to put near the VM, and it is also the honest limit of what it proves.

---

1. What changed

file	change
src/game/events/research_events.{h,cpp}	PostResearchPassEvents — the events one ProcessResearch call raises, as a pure function of the per-node outcomes; KeylessEventText() for a caller with no string table
src/shim/hooks/event_inputs.{h,cpp} (new lib shim_events)	the live↔model adapter: scan a Game::EventStorage before the original runs, seed the model from it, write the counts back into a scratch header
src/shim/hooks/research.{h,cpp}	the wiring, the observed_techs region, the new args, the rewritten Coverage
tests/game_events/test_events.cpp	6 new cases on the pass driver (the three call shapes lane R captured, plus dedup and the keyless lookup)
tests/shim_events/unit_tests.cpp (new)	10 cases on the adapter, driven on a byte buffer laid out with the real offsets
include/generated/sots_addresses.h	regenerated from sots-re ghidra/addresses.json (386 → 396 entries)

tools/clean_room_check.sh — OK. Host ctest — 33/33 passed (was 32/32; shim_events_unit is new). Both run as separate commands. The shim TU itself is syntax-checked only (g++ -std=c++17 -Wall -Wextra -fsyntax-only, clean): there is no MinGW i686 cross toolchain on this box, so tools/build-shim.sh still has to run on CT111 before any deploy.

New binary facts (via addresses.json → tools/gen_addresses.py, never hand-edited)

Read out of TechTree::SetResearched (0x00581e10) by this lane, plus one from lane R's guard:

ServerPlayer_off_ObservedTechs (0x274) · TechNode_off_TurnAvailable (0x20) · TechNode_off_TurnResearched (0x24) · TechNode_off_Order (0x28) · TechNode_off_Children (0x04) · TechEdge_off_CostRP (0x1c) · TechEdge_off_ChildDef (0x40) · TechTree_off_OrderCounter (0x20) · TechTree_SetResearched_flag_Force (0x2) · TechTree_SetResearched_flag_Silent (0x4)

The last one settles a question the count depends on. SetResearched invokes the owner callback as vft+0x10(def, (flags >> 2) & 1), so bit 2 of its flags argument is OnTechResearched's silent. ProcessResearch calls SetResearched(def, 2), so silent is false and the completion event is posted. That was previously an inference from an event count; it is now read off the instruction stream.

---

2. How the count model works, and why each piece is there

The scan is taken before the original

In compare mode ours runs after the original (hook.h, run<true>). A scan of the event list taken inside ours would see the original's own freshly posted records — and the model would deduplicate against them, post nothing, and agree for exactly the wrong reason. So ScanEventStorage runs in describe_args, which hook.h calls immediately before regions() and before the original.

Ours posts into its own storage, seeded from the scan

SeedFromScan rebuilds the turn buckets (their EvTurn values, in order) and EvNxID, and leaves the buckets empty. Empty because the records' EvDsc/EvMsg are localized game text, which the engine must not carry.

That has one consequence, and it is measured rather than assumed. A post can only be deduplicated against a record already in the same turn bucket, and only a record with the same EvImg can ever match. So the scan counts the events in the current turn's bucket that carry one of the six research EvImg identifiers and reports it as the argument events_dedup_risk:

• events_dedup_risk = 0 → nothing in the bucket can collide with anything we post, and the count-only model is exact for that call.
• anything else → our id count is a lower bound, and the report says so instead of the reader having to guess.

On the reference workload it should be 0 on every call (see §4).

The text stand-in preserves exactly the property dedup needs

KeylessEventText() resolves every string-table key to the bare format "%s", and the hook passes the node's own index as the substitution. So EvMsg is the node index and nothing else. That is not the game's text and must never be shown or serialized — but it preserves the one property the comparator cares about:

• two different nodes going over budget in the same turn get different EvMsg → both are kept, which is what the original does (their real messages differ by the tech name);
• the same node twice collapses to one id, which is also what the original does;
• an over-budget and a completion for the same node share EvMsg but differ in EvImg, which the comparator also tests → both are kept.

tests/game_events pins all three through this lookup.

Only compare mode writes

WriteBackCounts is called only when compare is set. In replace mode the region pointer is live game memory, and bumping EvNxID there without a serialized record behind it would corrupt the very save the oracle hashes — strictly worse than the missing event. Replace mode therefore still posts nothing, and the Coverage note says so.

---

3. What is verified, what is modelled by analogy, and what is not modelled

Verified from the instruction stream (lane E's read, plus this lane's read of 0x00581e10):

• EVENT_RESEARCH_OVERBUDGET fires iff the completion roll failed and !wasDone && nowDone. sim::ResearchStepResult::overbudgetEvent already computes exactly that, in the same branch that sets node.flag = 2 — the flag lane R confirmed on the game.
• One completion event fires on every completion reached from ProcessResearch, because silent = (flags >> 2) & 1 and ProcessResearch passes flags = 2.
• The posting rules themselves: dedup keys, act == 0 && !obj && !pos → 2, the FLT_MAX default, EvNxID starting at 0, the last-match bucket lookup, the prune off-by-one. All of lane E's, all unit-tested.

Modelled by analogy, and count-neutral: which of EVENT_RESEARCH_COMPLETE / _UNDERBUDGET is posted. The original splits on TechTree::GetProgressRatio(tree, def) against (double)0.8f; ours splits on ResearchStepResult::completedEarly, which is progress/cost against the same constant, computed by ProcessResearch itself two instructions earlier for the flag = 0 decision. They are very probably the same number, but this lane did not read GetProgressRatio (0x0057e950). It does not affect next_id: both branches post exactly one event. It would affect a text or EvImg comparison, and no region has one.

Not modelled — flagged, not guessed:

• EVENT_TECHS_UNLOCKED. Its trigger is pinned: SetResearched's second sweep sets state = 2 and stamps turnAvailable (only when it reads −1), and the tail loop at 0x00587ff4 collects state == 2 && turnAvailable == currentTurn. But evaluating it needs the child-unlock cascade, which ours deliberately does not run — B3 declared it out of scope and its writes land on live objects compare mode must not touch. PostResearchPassEvents therefore takes the unlock list as an input and is handed nullptr ("no list"), which is deliberately distinct from an empty list ("computed, and empty"). Predicted residual: next_id short by exactly 1 on every call that completes a tech. Guessing the trigger — "post it whenever something completed" — would score on this save and be wrong the first time a completion unlocks nothing.
• EVENT_TEMPERANCE. Posted from the same OnTechResearched call, but only when the completed tech is a temperance tech and the per-species sweep actually cured at least one addicted system. Neither input is available here, and no save in verify/ has addiction, so this has never been observed firing. The helper exists and is unit-tested; it is not driven.
• EVENT_NO_RESEARCH. Posted from ServerPlayer::ProcessTurn (0x0089168c), not from this hook. Out of scope by call site, not by omission.
• The text. EvDsc/EvMsg come from the game's string table. No region can see them, and none pretends to.

---

4. What the next VM run should show

This is a prediction, not a fishing trip. Run the existing shim.cfg.recapb3 recipe (ref-turn2.sav → Launch → End Turn) unchanged, then the five-End-Turn continuation.

4.1 The first End Turn — the headline

Game::TechTree::ProcessResearch: 3 calls, 3 compared, 0 divergent, tracecmp exit 0.

call	alloc	events.next_id orig	ours before this lane	ours now
0	{tech 144, 2889}, species 2	3 → 4	3 ✗	3 → 4 ✓
1	{90, 0}	0 → 0	0 ✓	0 ✓
2	{9, 0}	0 → 0	0 ✓	0 ✓

Also on call 0, and these are the fields that say the model is right for the right reason:

• turn = 3. If it is not 3, nothing below is trustworthy: the whole post lands in the wrong bucket. (ModCount at *(int*)(*(char**)(player+8) + 8).)
• events_turn_bucket_exists = true — the turn-3 bucket already holds EVENT_SHIPS_BUILT. This is what keeps events.turns at 2 and turns_bytes at 0x30 on both sides. If it comes back false, our post creates a bucket the original did not and turns_bytes diverges by 0x18 — which would mean turn is wrong, not that the model is.
• events_next_id_in = 3, events_in_turn_bucket = 1, events_dedup_risk = 0.
• events_scan_truncated must be absent. Its presence means a vector header did not parse and every event number in the record is unreliable.
• node[144].progress 2879 → 5768 and flag 1 → 2 on both sides, rng identical — unchanged from lane R's capture. If any of those regressed, the events wiring broke something it should not have touched.
• observed_techs.bytes unchanged on all three calls: turn 1 of ref-turn2 contains no tech completion, so nothing appends.

Calls 1 and 2 are other players with empty event lists (EvNxID = 0). WriteBackCounts must leave their scratch header byte-identical — the "no-op" case is unit-tested.

4.2 The five-turn continuation — expected to still diverge, by a known amount

Lane R warns that anything past the first End Turn is a run, not the run (from turn 4 the AI picks a different target). Treat the call ids as indicative and the shape as the prediction:

call	what happens	orig next_id	ours now	residual
0	over budget	4	4	none
3	completion	7	6	1 = EVENT_TECHS_UNLOCKED
6	rolled, failed, no cost crossing	8	8	none
9	completion	12	11	1 = EVENT_TECHS_UNLOCKED
12	rolled, failed	14	14	none
all others	zero-spend	0	0	none

So tracecmp should still exit 1 on the five-turn run, with exactly two divergent calls instead of three, and both remaining divergences off by exactly 1 in next_id. Any other number is new information: off by 2 means the completion event is not firing either; off by −1 means we posted something the original did not.

4.3 What the guard should stop saying

observed_techs is now a Result region, so its bytes are excluded from the player guard's undeclared-write scan. Expect the guard's span count on the two completion calls to drop by the player+0x274/0x278/0x27c entries (lane R saw 3 spans on call 3 and 1 on call 9) and those offsets to appear in the diff instead. That is the conversion, not a regression.

4.4 The measurement to take while you are there

On a completion call, observed_techs.bytes grows by exactly one element. That delta is sizeof(ObservedTech), which nothing in the project has pinned. On disk the element is {int otnF; int otnL; int odet; string otch; int owith} (confirmed in turn3-state.sav — the otch string holds the tech's name, e.g. WEP_RedLas), so a by-value element should measure 0x2c or 0x30 and a vector<ObservedTech*> would measure 4. Write the answer into addresses.json; the entry there currently says explicitly that it is not pinned.

---

5. Open

• sizeof(ObservedTech) and its append call site. It is somewhere under the OnTechResearched callback (both guards see it, which only bounds it to that subtree); it is not in OnTechResearched's own decompilation, and a constant search for 0x274 finds only unrelated objects, so it is reached through a lea displacement in a callee. §4.4 measures the stride without finding the site.
• TechTree::GetProgressRatio (0x0057e950) — the COMPLETE/UNDERBUDGET split is analogy until it is read.
• The unlock cascade. It is now fully decompiled (see the sots-re note), so EVENT_TECHS_UNLOCKED is implementable — but it belongs to whichever lane takes SetResearched, because modelling it means ours starts writing child state / turn_available / cost_rp, which B3 declared out of scope.
• EventStorage::PruneOldTurns still has never run: the reference saves are at turn ≤ 7 and the window is 50. The model reproduces the off-by-one and the unit tests pin it; nothing has measured it.
• Option (b) — delegating to the game's own PostEvent so the text and the save hash match — is untouched and remains the only path that can prove EvDsc/EvMsg. It changes VM behaviour and is deliberately not wired here.