sots-engine/docs
alex 39c01422f7 src/app: the standalone -- load a save, run a turn, write a save
`sots_turn` loads a save through the engine's own reader, walks the published
phase order of all three turn drivers, runs what we hold, prints what we do
not, and writes the result back through the engine's own writer.

The phase catalog carries all 32 + 12 + 37 phases whether or not they are
implemented, so an unimplemented phase is a named no-op that appears in the run
log rather than a silent absence. 14 of the 44 turn-driver phases are modelled,
7 commit anything, 2 of the 37 tail phases are modelled.

Modelled but NOT committed is a first-class state. A phase whose formula we hold
and whose inputs we do not is evaluated, reported, and left unwritten unless
--commit-blocked is passed. That distinction was earned: committing phase 31's
player-status restore regressed two leaves that had agreed with the oracle
before the turn, because the phase writes 1 and the file carries 4.

Measured against the game's own post-turn saves, leaves localised by
state_checksum.py with coverage proved by re-serialisation:

  turn1-state -> turn2-state   209 -> 204 diverging, closed 5, regressed 0
  turn2-state -> turn3-state   108 -> 103 diverging, closed 5, regressed 0

Two tests: app_catalog (the tables stay complete and nothing claims to be
verified against a live game) and app_turn (11 saves driven; an untouched load
re-serialises byte-identically, a turn leaves the file re-readable, and no
blocked or stub phase writes anything). Skips cleanly without SOTS_SAVES_DIR.

ctest 38/38, clean-room OK. src/shim untouched. docs/S-standalone.md has the
full gap list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ARBgSooAfokKUy6wKUKEyZ
2026-09-08 10:35:45 -04:00
..
B1.md b1: ComputeBudget hook + adapter; fix researchMoneyKept to be charged only with a research target; budget out-param is int[22] 2026-09-07 23:24:10 -04:00
B2.md b2 live: 3 completions compared 0 divergences; float32 confirmed on the game; RollResearchEvent RNG region added; xenotech block size bug fixed 2026-09-08 01:18:39 -04:00
B3.md b3 live results: 13/15 zero-divergence, RNG post-state 14/15; research target is state 3 (no decay); oracle gap = unposted overbudget event 2026-09-08 00:29:44 -04:00
B4.md b4 live: 36 calls 0 divergences, no colony RNG draws as predicted; fix 3 hook bugs (stale args, two-base StrategyServer, raw Ghidra offset) 2026-09-08 02:07:28 -04:00
E-events.md game/events: the player event log and the five research events 2026-09-08 02:45:57 -04:00
G-wire-schema.md A: type the AIAgent custom-data blocks; named coverage 98.0% -> 99.9% 2026-09-08 07:33:06 -04:00
game-data.md game/data: typed catalogs (weapons, sections, turrets, ids, tech tree, strings), cross_check; oracle 229k values 0 diffs 2026-09-07 17:55:08 -04:00
game-design.md game/design: assembly/fit/gating rules + derived stats on game/data; 127/127 designs, 197/197 DOpts, oracle-identical 2026-09-07 22:10:35 -04:00
game-effects.md b2: OnTechResearched hook + 10 effects-table corrections (float32, xenotech block size, no already-researched guard, sticky mask, AI bonus values) 2026-09-08 00:01:04 -04:00
game-sim.md b4: colony + movement hooks; 22 formula corrections (growth curve has no capacity term, range margin +0.05f, ties-to-even rounding); 3 verified signatures 2026-09-08 00:57:55 -04:00
harness-audit.md lane P: post the research events from ours (count-only), declare ObservedTech 2026-09-08 04:16:22 -04:00
M-movefleet.md movefleet: reproduce the original's float32 normalise; 8 of 45 live divergences -> 0 2026-09-08 03:50:04 -04:00
M0.md m0: binkw32 proxy shim, minhook, trace hook on Application::Initialize; build/deploy tooling 2026-09-07 17:22:15 -04:00
M1.md m1: GlobalConsts::LoadFile hook + game/config loader; trace 19 calls, compare 0 div, replace passes End-Turn oracle 2026-09-07 22:16:55 -04:00
M2.md m2: live verification results (weapons compare 0 div, oracle passes; section compare crash documented) 2026-09-07 23:52:50 -04:00
mars-parse.md mars/parse + mars/text: engine parity (Mars::Script tokenizer, first-wins keys, trailing-pair drop); oracles 1531/1531, 64/64 2026-09-07 18:10:18 -04:00
mars-rng.md mars::rng: the seven draw entry points, with their word costs 2026-09-08 09:59:05 -04:00
mars-stream.md mars/stream + mars/rng: Streamable reader/writer/shapes, MT19937; 3 real saves exact + byte-identical round-trip 2026-09-07 17:46:06 -04:00
mars-text.md mars/parse + mars/text: engine parity (Mars::Script tokenizer, first-wins keys, trailing-pair drop); oracles 1531/1531, 64/64 2026-09-07 18:10:18 -04:00
mars-vfs.md mars/vfs: gob ZIP reader + native override, miniz 3.1.2; oracle-verified 8352+2035 entries 2026-09-07 17:40:51 -04:00
P-events-wiring.md lane P: post the research events from ours (count-only), declare ObservedTech 2026-09-08 04:16:22 -04:00
R-recapture.md recapture: golden traces with guards on the live game 2026-09-08 03:04:34 -04:00
S-standalone.md src/app: the standalone -- load a save, run a turn, write a save 2026-09-08 10:35:45 -04:00
shim-trace.md shim: force and verify the x87 control word around the turn gate 2026-09-08 05:09:16 -04:00
T-turn-driver.md lane T merge fixups: name the roll-succeeded branch instead of its FUN_ id (clean-room); mark describe_i32 maybe_unused so the shim cross-builds 2026-09-08 08:13:39 -04:00
U-unlock.md U: live verification - 0 divergences on 35 calls, three workloads 2026-09-08 06:57:15 -04:00
V-eventlive.md V: live verification of lane P's event posting; the advance prediction held 2026-09-08 06:00:01 -04:00