sots-engine/docs/EV-events.md

# EV — posting events into the save's turn bucket (P11)

Roadmap item 5. The engine already **models** the event log (`game/events`: turn-bucketed
storage, per-bucket dedup, the `FLT_MAX` position sentinel, the `act == 0 && no subject && no
position -> 2` rule). What was missing is that the standalone never wrote any of it into the
save it produces. This lane wires that up for the one event a turn on the reference pair
actually posts that the standalone can compute, and reports the rest as blocked with the
blocker named.

Nothing here carries the game's displayed text. The engine holds `EVENTSUM_*` / `EVENTMSG_*`
keys only; the text is resolved at run time through a lookup the caller supplies, which the
standalone builds from the operator's own installed string table (`--data`).

---

## 1. What a turn actually posts (measured, whole corpus)

Not derived — read out of the eleven saves in `verify/results/saves` with the state-checksum
tree. Only two players in any corpus save ever hold an event at all: the human (`PlyrIdx 0`)
and the one AI empire that owns colonies (`PlyrIdx 1`). Every other player's `EvNxID` is 0 on
every save, including the two AI shadow empires that *do* pick research targets.

**Reference pair `turn1-state.sav -> turn2-state.sav` — the whole turn posts two events:**

| player | bucket | id | image | act | loc |
|---|---|---|---|---|---|
| 0 (human) | `EvTurn=2` | 1 | `EVENT_NO_RESEARCH` | 1 | 0 |
| 1 (AI) | `EvTurn=2` | 1 | `EVENT_SHIPS_BUILT` | 0 | 288 |

**Pair 2 `turn2-state.sav -> turn3-state.sav` — three:**

| player | bucket | id | image | act | loc |
|---|---|---|---|---|---|
| 0 | `EvTurn=3` | 2 | `EVENT_NO_RESEARCH` | 1 | 0 |
| 1 | `EvTurn=3` | 2 | `EVENT_SHIPS_BUILT` | 0 | 288 |
| 1 | `EvTurn=3` | 3 | `EVENT_RESEARCH_OVERBUDGET` | 1 | 0 |

**Order matters and is visible in the ids**: within player 1's turn-3 bucket the construction
event is id 2 and the research event is id 3, so the build pass posts **before** the research
pass. Ids are per player (`EvNxID` lives on the player's own storage), so no cross-player
order is observable and none is assumed.

The bucket's `EvTurn` is the **post-increment** turn: a turn run from a save at turn *N*
posts into bucket *N+1*. In the standalone that is `game.sim.frame` after `H00`.

Across the whole corpus the only other images seen are `EVENT_SHIPS_BUILT`,
`EVENT_RESEARCH_COMPLETE`, `EVENT_TECHS_UNLOCKED`, `EVENT_RESEARCH_OVERBUDGET`,
`EVENT_FLEET_ARRIVED`, `EVENT_FLEET_EXPLORED`, `EVENT_FLEET_MULTIPOINT_NONODE`,
`EVENT_LABACCIDENT_SMALL`, `EVENT_COLONY_NEWSETTLERS`, `EVENT_ENEMY_INCOMING_Human` and
`EVENT_NO_RESEARCH`. None of the tail's event phases (`T18`, `T21`, `T32`) fires on either
reference pair — measured, not assumed; on other corpus saves they clearly do.

## 2. The no-research condition, corrected

The standalone's condition was `no research target && at least one available tech`. That is
two thirds of the original's and it **over-fires by three players** on the reference pair.
The original's is three tests, all of which now have a name in `ghidra/addresses.json`:

1. `ResT == NULL` — no research target;
2. `TechTree::CollectResearchedTechs(out, turn, INT_MAX, sort=1)` came back **empty**, i.e.
   **no tech finished on this turn or later**;
3. `TechTree::FindFirstAvailableTech() != NULL`, i.e. at least one node is in state 2.

Test 2 was missing here and it is not decoration. `zuul-turn23-fleet23.sav` exercises it: the
human posts `EVENT_NO_RESEARCH` on turns 2..15, posts `EVENT_RESEARCH_COMPLETE` on turn 22
and **no** no-research event that turn, then posts `EVENT_NO_RESEARCH` again on turn 23. That
is exactly test 2 suppressing the event on the turn a tech landed.

Tests 2 and 3 are computable from the wire: a `TechState` row's `St` is the node state
(0 hidden, 1 parent researched, 2 available, 3 available and selected, 4 researched) and
`TAcq` is the turn it was researched.

Test 1 is **not** fully computable. `ResTNm` gives the target the save was written with, but
three of the four real players on the reference pair acquire a target *during* the turn, and
that is AI research selection (`game/ai`). The stand-in is the operator-supplied AI roster,
`--ai-player N`, which the standalone already carries for `T31`:

> **HYPOTHESIS (workload: the whole 11-save corpus).** An AI-controlled player that begins its
> turn with no research target acquires one before the no-research check, so it never posts
> `EVENT_NO_RESEARCH`. Support: across the corpus no AI player posts that event on any of
> roughly ninety player-turns, while the human posts it on every turn it has no target.
> Falsified by a single AI player-turn carrying the event.

So `P11` stays **blocked**, commits only under `--commit-blocked=P11`, and even then posts
nothing for a player the operator named as AI and nothing at all without a text table.

## 3. Prediction (written before the build; rule 2)

Baseline moved under this lane: `main` is now `eafbc5f` (lane T2). Re-measured with this
lane's own binary before any change: pair 1 **209 -> 131** (closed 78, regressed 0), pair 2
**108 -> 72** (closed 36, regressed 0). The brief's 209 -> 157 / 108 -> 86 predate T2. The
numbers below are against the re-measured baseline, so the lane's own contribution is
pair 1 **131 -> 127** and pair 2 **72 -> 69**.

**Run A — `--data <root> --ai-player 1 --ai-player 2 --ai-player 3 --commit-blocked=P11`.**

`P11` posts exactly one event, for player 0, into bucket `EvTurn = frame`:
`EvEID` 1 (pair 1) / 2 (pair 2), `EvDsc` and `EvMsg` from `EVENTSUM_NO_RESEARCH` /
`EVENTMSG_NO_RESEARCH`, `EvImg = "EVENT_NO_RESEARCH"`, `EvLoc = 0`,
`EvPos = {FLT_MAX, FLT_MAX, FLT_MAX}`, `EvAct = 1`, `EvCID = 0`; `EvNxID` 0 -> 2 (pair 1),
2 -> 3 (pair 2).

* pair 1: **closed 4, regressed 0** — `Events/EvNxID`, the empty-collection leaf
  `Events/Events/.`, the new count leaf `Events/Events/.[0]`, the new bucket
  `Events/Events/.[EvTurn=2]`.
* pair 2: **closed 3, regressed 0** — `Events/EvNxID`, `Events/Events/.[0]` (1 -> 2), the new
  bucket `Events/Events/.[EvTurn=3]`.

Player 1's four (pair 1) / three (pair 2) event leaves stay: they need `EVENT_SHIPS_BUILT`,
which needs a ship the turn builds, which needs an AI-generated build order — the same
blocker `B6` and `T36` already name.

**Run B — the control, no `--data`, no `--ai-player`, no `--commit-blocked`.** closed 0,
regressed 0; the phase reports the condition and posts nothing.

### Falsification

| # | if the model is wrong this way | symptom |
|---|---|---|
| F1 | the AI-picks-a-target hypothesis is wrong | with the roster supplied the event is missing for a player the oracle has one for; without it, four posts and roughly fifteen regressed leaves on pair 1 |
| F2 | the bucket turn is the input turn, not the incremented frame | the bucket lands at `EvTurn=1`; closed 1, regressed 2 |
| F3 | the position sentinel is written as `+inf` rather than `FLT_MAX` | bucket appears, `EvPos/.[0..2]` diverge; closed 3, regressed 3 |
| F4 | the `act == 0 -> 2` rule is applied where it should not be (`act` here is 1) | `EvAct` diverges; regressed 1 |
| F5 | the writer emits a trailing node on a record the engine synthesised rather than parsed | the post-turn save's coverage drops below the input's, visible in the report's `coverage` line |
| F6 | the "researched this turn" gate is wrong | no visible effect on either reference pair (nothing is researched on either turn); it would show as a spurious post on the turn a corpus save completes a tech |

Run B is the control for F1: it is the same code with the input withheld, and its over-fire
count is a direct measurement of how much of the phase the AI roster is carrying.