sots-engine/docs/CB-capture.md

# CB — the capture instrument, and what it measured

Lane CB, 2026-09-08. Guest VM146, build `cb2-20260908T2251Z`. Predictions and their outcomes are in
`docs/CB-predictions.md`; the RE-side write-up, the captures and the raw logs are in `sots-re`
(`findings/subsystems/turncommands-capture.md`, `verify/results/turncommands/`).

This document is the engine-side record: what changed in the shim, and the two facts the change
bought that a replayer needs.

---

## 1. What changed

Three additions to lane L4's `src/shim/hooks/ai_orders.cpp`, and nothing else. L4's design point is
kept unchanged: **the instrument reads element bytes, not element types**, and the typing happens
offline in `sots-re/tools/turncommands_capture.py`, so a corrected record costs a re-parse instead
of a rebuild, a redeploy and a turn. That paid for itself twice in one session — see §4.

| key | default | what |
|---|---|---|
| `aiorders.words=<N>` | 12 | the element window, ≤ 64. List 1's `ShipDesignDef` puts its name past 48 bytes. |
| `aiorders.deep=on\|off` | off | follow the heap: `{_Myfirst,_Mylast,_Myend}` and MSVC `std::string` shapes inside the window. |
| `aiseed=off\|log\|pin` + `aiseed.values=<netid>=<hex>,…` | off | read — or **replace** — the fourth stack argument of `Game::StrategyApp::RunAI`. |

`aiorders=on aiprobes=off` is still one detour; `aiseed=` adds a second. Configs:
`shim.cfg.cboff` (the control, installs nothing), `shim.cfg.cbcapture`, `shim.cfg.cbtrap`,
`shim.cfg.cbpin`.

**Three payloads in the canonical block are behind pointers** — list 8's route, list 10's counted
vector, list 23's `Population` body. Without `deep` they are **absent**, not empty, and a fleet
move with no route reads exactly like a fleet move that goes nowhere. That is why `aicfg words= deep=`
is printed into every capture: a reader must never have to guess which of the two it is looking at.

## 2. `aiseed=pin` is an intervention, not an instrument, and is logged as one

Every call logs `observed`, `used` and `pinned`, so a pinned run says so in its own capture and can
never be read as a natural one.

It exists because of a control problem, not a curiosity. `turn1-state → turn2` has an outcome set
of size k > 1: three lanes ran it with `hooks=off` and got three different files. On such a workload
**no single un-instrumented run is a control**, and an instrumented run agreeing with one of them 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. Pinning removes the only per-process input and makes a control possible.

It worked, three times over. Three processes on that save, each drawing its own three natural seeds
(nine distinct words in all), two of them pinned to the first's, produced **one** autosave
(`d59bb9f2fd0eb535…`) with identical gates — including player 512's research target `282`, the value
that varies — and identical element records. Two runs agreeing on a `k > 1` workload is a `1/k`
coincidence; three is `1/k²`.

## 3. What a replayer needs from this, in one place

* **The seeds are part of the stream.** `game/ai` is a deterministic function of
  (save, per-client seed). A capture without them records the AI's answer with no record of its
  input.
* **Element sizes, measured** (not read): list 3 = 4 words; list 5 = 8; list 8 = 1 + vector;
  list 10 = 2 + vector; list 14 = 2 words **+ one byte**; list 23 = 1 + vptr + vector. Established
  by comparing two runs that wrote byte-identical autosaves — a word that differs between them is
  not a word the applier reads — and agreeing with the writer's own instruction stream on all six.
* **List 14's bool is one byte.** The other three bytes of its word are heap garbage that differs
  run to run. Compare the byte, not the word.
* **List 3's element is stored backwards** relative to its wire order. Per-list, not a rule.

## 4. Two records corrected, one of them mine

**Lane L4's list-23 reading, twice.** `Population{vptr, vector(24 B), −1}` has no trailing int —
the word after the vector differs between two runs whose autosaves are byte-identical, so it is an
allocator cookie. And the body is **not** turn-dependent: five of its six words are the same on
turn 1 and turn 2, and the sixth is a per-process pointer.

**My own list-5 record, found by lane RB while consuming the capture.** The element is dumped in
*memory* order and its memory field order is not its wire order; **memory member 1 is wire member
`SRsc`**, six members unread. RB's first replay predicted zero regressions and got two. The record
is now **dropped** rather than relabelled: the values ship as `rates_memory_order_{u32,f32}` with
`wire: null`, and the `.tcb` emits the seven `?` tokens RB's own converter emits, so a replayer
refuses rather than guesses. A missing field is honest; a mislabelled one propagates — and it would
have propagated inside the artefact that is meant to outlive the adapter that read it.

That is the capture/replay pairing doing its job in both directions, which is the argument for
having run the two lanes together.

## 5. Gates

Run as separate commands (rule 13).

* `tools/clean_room_check.sh` — **OK**
* host `ctest --preset host` — **55/55**
* CT111 shim cross-build (`/srv/re-lab/build/sots-engine-cb`, `DIST=/srv/re-lab/shim/dist-cb`), on a
  **freshly extracted tree with `build-shim` removed** (rule 24) — **exit 0**, exports 66 names
  identical to the real `binkw32.dll`

The generated header was **regenerated** from `sots-re/ghidra/addresses.json` plus every
`ghidra/addresses.d/*.json` fragment (rule 14), never hand-resolved — the merge of lane L4's
instrument conflicted there and regeneration is what resolved it. **This lane adds no addresses**:
it used `StrategySim_ApplyTurnCommandBatch` and `StrategyApp_RunAI`, both already carried by lanes
A2 and AI1, so there is no `addresses.d/lane-cb.json` and there should not be one.