sots-re/findings/subsystems/system-visibility-prediction.md

Prediction: the visibility phase, before it is built

Lane E3, 2026-09-08. Written and committed before the engine change exists (rule 2). Model: findings/subsystems/system-visibility-record.md.

Baseline, measured on sots-engine main 0592104 this morning:

turn1-state -> turn2-state   204 leaf differences
turn2-state -> turn3-state   103 leaf differences

The model, as three rules

1. T17 RecordObservation. For every player p and system s with s.AFlags & (1 << p.PlyrIdx): set NVE[p] = { EPid = p's handle id, ETS = frame, Eid = the encounter id at s }. frame is the post-increment frame, i.e. the turn number the autosave carries. Entries are ordered by PlyrIdx ascending (a std::map). Nothing is ever erased.
2. T21 SetExploredBy. s.EFlags |= s.AFlags.
3. S29 ltis. If s.AFlags != 0 then s.ltis = frame.

Eid is taken from an existing NVE entry when the system already has one (the field it mirrors is fixed for the life of the game); otherwise from a fleet at the system with FtEnc != 0; otherwise -1.

AFlags is read from the save, not recomputed. Justification, and it is checkable: neither reference pair moves an AFlags leaf, so the loaded value is the value the phase would see.

Predicted leaves closed

turn1-state -> turn2-state (the 32-leaf target)

Eight systems — 64 Hyperion, 112 Gamma Cephei, 288 Ke'Dolarra, 304 Koa'Vo, 336 Kaa'Vaalu, 400 Markab, 448 Kea'Pono, 480 Ko'Rorkor — are exactly the systems with AFlags != 0.

leaves	rule	count
Sys[*]/NVE count 0 -> 1	1	8
Sys[*]/EPid only-in-B	1	8
Sys[*]/ETS only-in-B	1	8
Sys[*]/Eid only-in-B	1	8
the brief's target		32
Sys[*]/EFlags 0 -> {16,128,16,16,16,16} on 64, 304, 336, 400, 448, 480	2	6
Sys[*]/ltis 1 -> 2 on all eight	3	8
total predicted closed		46

Predicted EPid values, per system, in order: 528, 16, 32, 576, 528, 528, 528, 528. Predicted Eid values: 5, -1, -1, -1, 3, 3, 4, 4. Predicted ETS: 2 everywhere.

Expected result: 204 -> 158, closed 46, regressed 0.

turn2-state -> turn3-state

The entries already exist, so only their stamps move.

leaves	rule	count
Sys[*]/ETS 2 -> 3 on the same eight	1	8
Sys[*]/EFlags	2	0 (already equal to AFlags)
Sys[*]/ltis 2 -> 3 on the same eight	3	8
total predicted closed		16

Expected result: 103 -> 87, closed 16, regressed 0.

EPid and Eid must be re-emitted unchanged; if either moves, the model has regressed a leaf that agreed by construction, and that is a failure of rule 3, not a rounding detail.

Falsification

Each of these is a way the model is wrong and the symptom that would show it.

• The gate is VFlags, not AFlags. On both reference pairs VFlags == AFlags on every system, so the pairs cannot separate them. The discriminator already in the corpus is zuul-turn23-fleet23.sav Bismol: VFlags = 2, AFlags = 0, ETS frozen at 22 while the save is turn 23. A VFlags model refreshes it to 23. Symptom: a host test that replays Bismol's row fails. That test is written.
• The gate is EFlags. Same corpus discriminator: Bismol has EFlags = 2.
• ETS is the sighting turn, set once, not refreshed. Then turn2 -> turn3 closes 0 of its 8, and the eight ETS 2 -> 3 leaves stay. Symptom: pair 2 closes 8 instead of 16.
• Eid is re-derived from the fleet every turn rather than parked on the system. Invisible on this corpus — no encounter fleet dies in it. Symptom: none available; that is why §8 of the model doc names the workload instead of claiming the rule.
• The Eid test is FtFlg & 0x10, not FtEnc != 0. Invisible on this corpus; the six encounter fleets agree on both. Symptom: none available.
• EPid is the player index, not the handle id. Then all eight EPid leaves regress to 0..7 instead of closing. Symptom: 8 closed becomes 8 regressed, and the run's closed count drops to 38 / 16.
• The map is ordered by insertion, not by key. Invisible: every system in the corpus has exactly one entry. Symptom: none available; the ordering is asserted from the container type, and §8 names the two-empire-contact workload that would exercise it.
• ltis is not the frame but something that merely equals it here. ltis is 1 at turn 1 and 2 at turn 2 on the same systems, which is consistent with a great many counters. The reading is a 41-byte function body; if it is wrong the 8 ltis leaves regress rather than close.
• The phase runs before the frame increment. Then every stamp is one low and 24 leaves regress across the two pairs.

What the model deliberately does not write

• NVO.TShn (10 leaves per pair). Its gate is not AFlags — Spica has AFlags == 0 and TShn still moves. Formula not held; evaluated and reported, not written (lane S2's rule).
• rcex (6 leaves per pair). Unexplained.
• NVs / PlayerView. Count 0 on both reference pairs; the PlayerView refresh loop is a separate phase and no leaf of it diverges on either pair.

---

Measured

Run after the build, against the prediction above, which was committed in 55ea86f before any engine file existed. Engine branch wip/visibility, host ctest 46/46, clean-room OK, shim cross-built on CT111 with exports byte-identical.

pair	baseline	after	closed	regressed
turn1-state -> turn2-state	204	158	46	0
turn2-state -> turn3-state	103	87	16	0

Closed, by leaf name — the prediction's table, line for line:

turn1 -> turn2   EPid 8   ETS 8   Eid 8   NVE 8   (= the brief's 32)   ltis 8   EFlags 6
turn2 -> turn3   ETS 8    ltis 8

tools/standalone_report.py's own numbers, whose baseline is the do-nothing distance from the input save rather than from main, are 209 -> 158 (closed 51, regressed 0) and 108 -> 87 (closed 21, regressed 0); the five-leaf difference in each is what main had already closed.

Three pairs the model was never fitted to

Rule 2's strong form. None of these was looked at while the model was being built; the human-* pair is a different game on a different map with a different species mix.

pair	baseline	after	closed	regressed
human-turn2-orders -> human-turn3-noderoute	353	311	42 (21 ETS, 21 ltis)	0
zuul-turn15-orders -> zuul-turn16-noderoute	276	264	12 (6 ETS, 6 ltis)	0
zuul-turn16-noderoute -> zuul-turn17-orders2	341	329	12 (6 ETS, 6 ltis)	0

128 leaves closed across five pairs, 0 regressed.

The falsification that mattered

The AFlags-vs-VFlags case is the one the reference pairs could not decide, and it is decided. Running the engine on zuul-turn23-fleet23.sav reproduces the freeze on the save itself: every observed system's stamp moves to 24 and Bismol's — sticky mask 2, explored mask 2, active mask 0 — stays at 22, in both ETS and ltis. A VFlags or EFlags model moves it to 24. That row is also a host test (tests/game_sim/test_visibility.cpp, test_bismol_freeze), which asserts the freeze and asserts what the wrong gate would have produced, so a later edit that swaps the mask fails loudly rather than quietly agreeing with the five pairs above.

None of the other falsification cases fired. The remaining ones — the two Eid derivations and the map ordering — are exactly the ones the section marked "symptom: none available", and they are still not settled; §8 of the model doc names the workloads.