sots-engine/docs/L4-ai-orders.md

L4 — the AI command block, live

Companion to docs/L4-predictions.md (written and committed before the module existed) and to sots-re/findings/subsystems/ai-order-capture.md (the full report, with the raw logs).

What was added

src/shim/hooks/ai_orders.{h,cpp} — two instruments behind three config keys.

aiorders=on installs exactly one detour: a register-transparent entry stub on Game::StrategySim::ApplyTurnCommandBatch. That function takes (blocks, n) as stack arguments and multiplies n by 0x1b4 to make its end pointer, so at its entry every player's submitted TurnCommands block is complete, in memory, at a known stride. One hook there dumps the whole turn's command traffic: six gates, twenty-seven list lengths and 48 bytes per element, per block.

aiprobes=all adds sixteen entry counters in lane H's asm-stub style, in their own table so probe_entry.cpp's set is untouched and probes= still means what it meant. Row 0 is StrategyAIAgent::RunTaskList, and its stub is hand-written: it reads that function's pass stack argument into a global before tail-jumping, so every later probe hit is attributed to a pass. That is the difference between counting entries and measuring the two-pass model.

aiorders.out=<path> — the dump goes to its own file as well as shim.log.

Both halves are separately switchable so they can be given separate rule-19 controls. In the end they did not need to be: the full seventeen-detour configuration reproduced the campaign's published End-Turn oracle byte for byte, on a guest (VM145) that had never been checked against it.

What it found

Full account in the findings document. The three that change this repo:

1. The AI submits a list-23 element every turn. Lists 17–27 had never been populated by any workload, so the free half of ListAdvancesModCount was read from the instruction stream and nothing else. It is now exercised twice and both turns still cost the measured 12.
2. Ids in AI commands are client-allocated. The build order names design 18 and the fleet order names fleet 34 — neither exists in the input save, and the other new design that turn (a monster faction's, made server-side) took 1712 from the save's master counter. Two id spaces; the small one travels in the command. OrderClient does not model id allocation and now has a named reason to.
3. Pass 0 emits nothing, measured from the output. All three pass-1-gated exits were entered in both passes in equal numbers, and the block carries one copy of each element. OrderClient's EnterTaskPass gate is confirmed.

Tests

tests/game_ai/test_live_blocks.cpp — 44 checks, both captured blocks rebuilt through the public OrderClient API from the dumped values, asserting the list profile, the element values, the gate counts and the ModCount total for each turn, plus a two-sided check that the list-23 element is free while a list-16 element is not.

It is deliberately a separate binary from test_orders.cpp. That file is the record of what static reading predicted before any of this ran, and it stays that way; this one is the record of what the game did. The agreement between them is evidence only while the two stay independent.

Two placeholder ids in test_orders.cpp were corrected in place from the capture (the AI fleet order names fleet 34 with a hop to 272, not fleet 1744; the three research targets are techIds 144/90/288). Rule 11: a wrong id in a test is how a wrong id spreads.

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-l4, DIST=/srv/re-lab/shim/dist-l4) — 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 (1,209 entries). This lane's fragment is lane-l4.json, nine entries: eight IAITask::Execute bodies and the list-16 order method. Nine other entries in the regenerated header belong to concurrent lanes' fragments and came along with the merge, as the per-lane fragment mechanism intends.

One thing that did not work, recorded because it costs a run

The turn-1 workload (turn1-state.sav + one End Turn) is not reproducible. Three runs produced three different post-turn autosaves, differing in exactly one field: the research target of the one AI player that owns nothing. Every other byte — ids, designs, fleets, ModCount — is identical. determinism-oracle.md verifies the oracle for the ref-turn2 workload and only for that one; this lane is the first to run the turn-1 workload more than once, and it is now on the record that a byte comparison on that workload is a comparison against noise.