sots-re/findings/subsystems/turncommands-capture.md

# The command stream, captured and bound to the autosave it produced

Lane CB, 2026-09-08. Guest **VM146** (`sots-re-win10-146`, 192.168.10.146), build
`cb2-20260908T2251Z`, worktree `wip/cb` off `main` `4f25f1e`. Predictions committed before the
instrument changed: `sots-engine` `docs/CB-predictions.md` (commit `4457249`, before
`ai_orders.cpp` was touched; the seed addendum at `c3d95dd`, before the turn-1 runs).

Paired with lane **RB**, which builds `sots_turn --turn-commands <blocks>`. This document is the
input side. Captures live in `verify/results/turncommands/`; raw logs in
`verify/results/shim/aiorders/cb-*.txt`.

---

## 0. Lead

**The canonical pair is captured and it binds.** `ref-turn2.sav` + one End Turn, with the block
dump installed, wrote `(Autosave EndTurn).sav` = `bb4fd9ac89f41e3b…` (66,732 B) and
`(Autosave).sav` = `978041acd168b56e…` (67,219 B) — **both byte-identical to the published
determinism oracle and to this lane's own `hooks=off` control taken on the same guest through the
same click path**. So the stream and the autosave come from the same run, and the instrument did
not change the turn it recorded. `(Autosave).sav` is byte-identical to `turn3-state.sav`, which is
the file lane RB's replay has to reproduce.

`verify/results/turncommands/cb-turn2to3.json` carries, for that one run:

* the **complete block set** — 8 block slots, 6 gates and all 27 lists each, with every element;
* the **three heap payloads no previous capture could read** — list 8's route, list 10's counted
  vector, list 23's `Population` body;
* the **three AI client seeds** (lane L1's per-process words), `0x9dfad635` / `0xb482b2d8` /
  `0xfb81e993` for net ids 32 / 496 / 512;
* the **input save and both output autosaves**, with sizes, sha256s, and the oracle comparison.

Two things this lane did not expect to produce and did:

1. **The creation turn made reproducible.** `turn1-state → turn2` is the workload three lanes ran
   and got three different files from. With the AI client seeds **pinned** to the values an earlier
   run observed, a *different process* reproduced that run's command block — including the research
   pick that varies — and its autosave **byte for byte**. Lane L1's mechanism confirmed from the
   other end; details in §4.
2. **An independent, empirical measurement of every element's size**, from two runs on two guests
   that wrote byte-identical autosaves. Any element word that differs between them cannot be a word
   the applier reads. The measured sizes agree with the record sizes read from the writer's
   instruction stream on all six lists — two methods, no disagreement.
3. **Two corrections to lane L4's list-23 reading**, and one to my own list-5 record — the latter
   found by lane RB while consuming this capture, which is the pairing working as intended.

---

## 1. What the canonical stream is

`turn2-state.sav` (`ab4ac2d7…`, 66,739 B) → one End Turn → `turn3-state.sav` (`978041ac…`).

Batch `seq=2`, `n=8` blocks at stride 0x1b4. Slots 0–3 carry player ids **16, 32, 496, 512**; slots
4–7 carry `playerId = 0` with uninitialised gate payloads (lane L4's P1 falsifier, reproduced).
**Every one of the four real players has the research-rate gate set** and no other gate; no
research-target gate is set on this turn by anybody.

Only player 32 emits commands:

| list | n | wire record, as captured |
|---|---:|---|
| 3 build | 1 | `{ordinal 2, designId 18, systemId 288, 0}` |
| 5 system rates | 1 | `{systemId 288, 0, 1.0f, 0, 0, 0, 0, 0}` |
| 8 fleet move | 1 | `{fleetId 34, nHops 1, [272]}` |
| 10 | 1 | `{systemId 288, fleetId 34, count 1, [1728]}` |
| 14 fleet task | 2 | `{34, 0, true}` and `{34, 1, true}` |
| 23 population | 1 | `{systemId 288, vptr, 24-byte body}` |

The three rows in bold type below are new; everything else reproduces lane L4 exactly, from a
different guest and a different build, which is worth stating as the corroboration it is.

**P3a held. The route is system 272.** Lane L4 could not read it and recorded that
`turn3-state.sav`'s waypoint says 272 without being able to prove the command said so. It does.
The waypoint in the output save and the route in the input command are the same id, so a replayer
needs to carry only one.

**P3b half-held, and the falsified half is the useful one.** List 10's counted vector holds one
value, **1728** — a *master-counter* id (a multiple of 16), **not** a small client-allocated one in
the 18/34 space. So the client allocates the fleet (34) and the design (18) out of its own small
counter but names the ship out of the server's. Lane L4's open question — "the client id counter is
not located, and 18 and 34 differ by 16, the master stride" — now has a boundary: **the two id
spaces coexist inside a single element**, and whatever the client counter is, it is not what names
ships. That is a sharper statement of the hole than the one L4 left, and it is still a hole.

**P3c half-held, and the falsified half is a better answer.** List 23's body is 24 bytes, as
predicted: `[0x00bd8d50, 1, 2, <ptr>, 1000000000, 0]`. The first word is a vftable pointer in the
same neighbourhood as the element's own, so this is **one 24-byte polymorphic object**, not six
ints, and the `1000000000` is population-shaped.

I predicted it would **differ between the turn-1 and turn-2 workloads**, on the strength of lane
L4's `+1` / `−1` trailing. It does not. Captured on both turns, **five of the six words are
identical** and the only one that moves is word 3, a heap pointer:

```
turn2 -> 3   [12422480, 1, 2, 0x3369f4c8, 1000000000, 0]
turn1 -> 2   [12422480, 1, 2, 0x343ba3e8, 1000000000, 0]
```

So the `+1`/`−1` that made it look turn-dependent was the noise word outside the element (§2), and
the payload itself is the same on every turn anyone has captured. It is still **not named** — this
lane says what bytes it carries and nothing more (rule 6) — but a replayer is not going to be
caught out by it on these two workloads.

---

## 2. The element sizes, measured rather than read

Lane L4 dumped a fixed 12-word window; this lane's is configurable and was run at 32. A wide window
runs off the end of a small heap node into the next one, and the words past the record are
**neighbouring heap**, not zero. That is a nuisance and it is also an instrument:

**Two runs of the same turn, on two different guests, both of which wrote byte-identical autosaves
(`bb4fd9ac` / `978041ac`). Any element word that differs between them cannot be a word the applier
reads.**

| list | stable prefix, L4 (VM145) vs CB (VM146) | record size from the writer | agree? |
|---|---:|---:|---|
| 3 build | 4 words | 4 | yes |
| 5 system rates | 8 words | 8 | yes |
| 8 fleet move | 1 + vector | 1 + 3 | yes |
| 10 | 2 + vector | 2 + 3 | yes |
| 14 fleet task | 2 words + **one byte** | 2 + bool | yes |
| 23 population | 1 + vptr + vector | 1 + 1 + 3 | yes |

Two consequences worth having:

**List 14's third field is one byte, and the other three bytes of its word are garbage.** The two
runs read `0x00B5B601` and `0x01138601` — same low byte, different upper three, which look like the
low bytes of a heap pointer. A replayer that compares the whole word will find a difference that is
not there.

**Correction to `ai-order-capture.md` §0: list 23's element has no trailing int.** Lane L4 recorded
`Population{vptr, vector(24 B), −1}` on turn 2→3 and `{…, 1}` on turn 1→2, and read those as a
field. This lane's turn-2 run reads **`0x0035765f`** in that slot — a value that also appears
mid-element in list 8 in L4's own log, i.e. an allocator cookie. Two runs, byte-identical outputs,
different value: it is not a field. The `+1`/`−1` L4 saw was heap noise that happened to look like
a signed flag, which is exactly why a wide window is worth having and exactly why the campaign
types elements offline instead of in the instrument.

---

## 3. The seeds

Lane L1 found each AI client's generator is seeded with a fresh per-process 32-bit word. This lane
records them next to the block, because **the seeds are part of the stream**: with them, the capture
is a reproducible pair; without them it is the AI's answer with no record of its input.

`Game::StrategyApp::RunAI` is entered **three times per process on a save load**, once per AI
client, and the fourth stack argument is the seed. On the canonical run:

| call | net id | seed |
|---:|---:|---|
| 1 | 32 | `0x9dfad635` |
| 2 | 496 | `0xb482b2d8` |
| 3 | 512 | `0xfb81e993` |

The net ids are the same four-value set the block slots carry (16 is the human and gets no client),
so a seed binds to a block by net id with no ambiguity.

### 3.1 One instrument defect, caught by its own coverage line

The first attempt reported `MH_ERROR_ALREADY_CREATED`: the trace framework installs **its own**
template hook on `RunAI` (that is L1's probe), and MinHook refuses a second detour on one target.
The module printed

```
COVERAGE: aiseed hook NOT INSTALLED -- the capture will carry NO seeds, and an absent seed list
means the instrument failed, not that the clients were unseeded
```

and that line is the only reason the run was not published with a silently empty seed list. It is
method rule 1 doing exactly the job it was written for. The fix is a config line
(`hook.Game::StrategyApp::RunAI=off`), and the detour count is unchanged: one instrument on that
function, not two.

---

## 4. The creation turn, and the control that had to be built

`turn1-state.sav` + one End Turn is the turn three AI players each **choose** a research target.
Three lanes have run it and got three different autosaves; the campaign's oracle does not extend to
it. This lane ran it three times.

### 4.1 Run C3, unpinned — and a fifth value for the tie set

The block reproduces lane L4's turn-1 block exactly: player 32 emits lists `{1:1, 3:1, 5:1, 23:1}`
with `{ordinal 1, designId 18, systemId 288, 0}`, and the three AI players set research-target
gates. **The design's name is read directly for the first time** — `"Honor Lance"`, short-string
optimised inside the list-1 element, recovered by the string scanner at word 2.

The targets are **144 / 90 / 282** for players 32 / 496 / 512. The first two are lane L4's values.
**282 is new.** L4 measured 288 for player 512; lane L5 named four outcomes by tech name. So the
outcome set for that one decision has at least one more member than anyone has enumerated, and
Rung C's "k = 6, all six nameable" claim is **not yet closed** — this run did not land inside the
named set as an id, and nobody has mapped 282 to a name. That is the honest status.

The autosave is `d59bb9f2fd0eb535…` (66,746 B) — which is exactly the file lane L5's own
`hooks=off` run produced. Two lanes, two processes, same outcome, by chance.

### 4.2 Runs C5a and C5b, pinned — the creation turn IS reproducible

C5a and C5b are C3 re-run with `aiseed=pin` set to the three seeds **C3 itself observed**. Each is a
separate process; each drew its own three natural seeds, all different from C3's and from each
other's, and each had them overwritten before the client constructor saw them.

| | C3 (unpinned) | C5a (pinned) | C5b (pinned) |
|---|---|---|---|
| natural seeds drawn | `e70a4703` / `0c63ca36` / `372be4df` | `227235b9` / `762d125e` / `9d77d4e6` | `be649c5c` / `2200dbd2` / `d418f3f8` |
| seeds **used** | its own | **C3's** | **C3's** |
| research targets 32 / 496 / 512 | 144 / 90 / **282** | 144 / 90 / **282** | 144 / 90 / **282** |
| all six gates, all four blocks | — | **identical** | **identical** |
| element records (lists 1, 3, 5, 23) | — | **identical** | **identical** |
| `(Autosave).sav` | `d59bb9f2fd0eb535…` | **`d59bb9f2fd0eb535…`** | **`d59bb9f2fd0eb535…`** |

**The workload that three lanes could not reproduce is reproducible once the seeds are pinned —
three processes, nine distinct natural seeds, one autosave.** Lane L1's mechanism is confirmed from
the other end: the seed is *the* per-process input, and `game/ai` is a deterministic function of
(save, per-client seed). Rung B's input is a **closed** record — save + seeds + block — not a log of
something that happened once.

Two runs agreeing on a `k > 1` workload is a `1/k` coincidence; three is `1/k²`, about 3 % at lane
L4's k = 6. That is the reason the third run was worth the eight minutes.

The single difference anywhere in the decoded stream is **word 3 of list 23's unnamed `Population`
body** — `876301736`, `245`, `61179324` across the three. By the argument of §2 (runs whose
autosaves are byte-identical cannot differ in a word the applier reads) that word is noise, now on
three data points rather than two. Localising it is exactly what a control on a `k > 1` workload
is *for*, and it did not exist before this lane could pin.

---

## 5. Rule 19, and the control that does not exist without pinning

**On the canonical pair the control is real.** `hooks=off` on VM146 reproduced both oracle hashes
(run C0), and the instrumented run reproduced them again (run C1). That pair is a valid rule-19
control because the workload is deterministic: there is one right answer and both runs gave it.

**On `turn1-state` there is no such thing as a single-run control, and this lane will not pretend
otherwise.** Three lanes have run `hooks=off` on that save and got three different files. With an
outcome set of size k, an instrumented run agreeing with one un-instrumented run is a **1/k
coincidence**; at lane L4's k = 6 that is a 17 % chance of a clean bill of health that means
nothing. A control on that workload requires the seeds *pinned*, which removes the only
per-process input. That is what the `aiseed=pin` mode exists for.

---

## 6. The capture format, for lane RB

`verify/results/turncommands/<run>.json`, written by `tools/turncommands_capture.py` from the
run's `shim.aiorders.txt` plus the run's own saves. Version 1.

```
capture_version, lane, guest, build, captured_utc
instrument   { words, deep, seed, pins, detours }     -- the run is self-describing
workload, note
binding {
  input    { file, bytes, sha256 }
  outputs  [ { file, bytes, sha256, path, oracle_sha256, matches_oracle } ]
  control_run
}
ai_seeds  [ { call, netId, observed, used, pinned } ]
list_size_self_check { mismatches, note }
batches [ { seq, n, blocks_va, stride, blocks: [ {
    index, playerId,
    gates { researchRate, researchTarget, researchBoost, group4, group5, civilianRatios },
    list_sizes [27],
    lists [ { list, member_offset, size, elements: [ {
        index, node_va,
        raw_words [...],                      <- GROUND TRUTH
        vectors   [ { at_word, first_va, capacity, count, words, truncated } ],
        strings   [ { at_word, sso, len, text } ],
        decoded   { record, <named fields>, wire [...], record_words }
    } ] } ] } ] } ]
```

Rules for consuming it, in order of how much they cost to get wrong:

1. **`raw_words` is the ground truth. `decoded` is a typing.** If they ever disagree, `raw_words`
   wins, and the fix belongs in the tool, not in the replayer.
2. **Use `decoded.wire`** — it is the values in the order the writer emits them, with the counted
   vectors already spliced in as `count` followed by elements. It is what a replayer feeds the
   applier.
3. **`record_words` says how much of `raw_words` is the element.** Everything past it is the next
   heap node. The window is deliberately wider than any record.
4. **A `vectors` entry at a word offset no record names is noise** and must be ignored. The
   follower is a shape test on a wide window and it fires on coincidences; every genuine payload in
   this capture sits at the word index its record predicts (list 8 `w1`, list 10 `w2`, list 23
   `w2`), and the decoder reads only those.
5. **`binding.outputs` is what makes the capture checkable.** A capture with no outputs, or whose
   hashes are not the ones the run produced, cannot be used for a byte-match and the tool writes a
   `WARNING` into the file saying so.
6. **`instrument.deep` must be `1`.** With `deep=0` the heap payloads are *absent*, not empty, and
   the tool writes `WARNING_INCOMPLETE`. A fleet move with no route is not a fleet move with a
   route of length zero.
7. **List 3's element is stored backwards in memory** relative to its wire order. The tool handles
   it; anyone reading `raw_words` directly must.

---

## 7. Coverage, stated as loudly as the result (rule 15)

* **Six of twenty-seven lists** have ever carried an element, in this capture or any other: 1, 3,
  5, 8, 10, 14, 23 (seven, counting list 1 on the turn-1 workload). Lists 2, 4, 6, 7, 9, 11–22,
  24–27 are empty in every block of every run. **A replayer's handling of those twenty is untested
  by this lane and must be labelled as such** — including list 7, colonize, which lane Q typed from
  a *human* orders save and which no AI capture has ever exercised.
* **One of six gates** is set on the canonical pair (research rate). Two on the turn-1 workload
  (rate and target). Gates 4, 5 and 6 have never been observed set by anything.
* **One AI player with anything to do**, on a 28-star board with no contact: no colonise, no
  invade, no raid, no diplomacy, no combat, no trade route, no spy program.
* **The `Population` body and list 10's payload are carried, not named.** This lane reports their
  bytes and declines to say what they mean.
* The element-size measurement rests on **two runs**. Two is enough to show a word is *unstable*;
  it is not enough to show a word is *stable*, and the stable prefixes above are therefore upper
  bounds on noise, not proofs of a record. They agree with the writer's own instruction stream,
  which is the second, independent leg.


---

### 7.1 Two planned runs that were not made, and why

* **C2, the `ModCount` trap set** (`watch=on` alongside the block dump). Planned as a second,
  independent check on the stream — predicted 10 bumps on the canonical turn, attributed per EIP.
  **Not run.** Lane RB got there first from the other side: replaying this capture puts
  `/Sim/ModCount` on **24 exactly with zero residual** on the canonical pair, which is a stronger
  statement than a trap multiset would have been (it checks the *arithmetic over the whole stream*,
  not the *sites*). The trap run would still add one thing nothing else has — per-EIP attribution,
  which would say *which handler* pays, not just that the total is right — and it remains a cheap
  hour for whoever wants it. `shim.cfg.cbtrap` is built and staged.
* **C4, a second unpinned turn-1 run.** Planned to give P5's "two streams differing in exactly one
  word". **Superseded.** The pinned pair answers the same question and answers it better: an
  unpinned pair shows that two runs *can* differ, while the pinned triple shows *what makes them
  differ* and removes it. P5 as written is unresolved and should stay on the board that way — this
  lane has one unpinned turn-1 stream, not two.

## 8. The guest, left as found (and one thing that was not preserved)

VM146 stopped, `binkw32.dll` restored to lane L5's build (md5 `F8DFC4AE…`, verified equal to
`C:\SOTS\shimdist-l5\binkw32.dll`), `shim.cfg` back to `hooks=off`, `SavedGames` at eight files
so the Load-dialog row geometry is unchanged.

**Not preserved:** the two autosaves that were in `SavedGames` when this lane took the guest.
`cbdeploy.ps1` deletes them before every run — deliberately, so that a run which writes none is
distinguishable from one that rewrites them, and so the dialog lists a constant six files. The
autosaves now present are run **C5b's** outputs (`a3f9dc4b…` / `d59bb9f2…`), both of which are
recorded byte-for-byte in `verify/results/saves/`. They are scratch files every lane's deploy script
deletes anyway, and nothing in the campaign depends on them, but the deletion was not announced in
advance and is recorded here rather than left for someone to notice.

Left in place for the next lane: `C:\SOTS\shimdist-cb` (build `cb-final-20260908T2320Z` plus the
four `shim.cfg.cb*` variants) and `C:\SOTS\cb\` (`cbdeploy.ps1`, `cbstep.ps1`, `cbgrab.ps1`,
`cbrun.ps1`, and the five collected run directories). The WSL-side drivers are in
`verify/harness/cb/`.