sots-engine/docs/S-standalone.md

src/app — the standalone, and exactly how far it is from the byte-match

Lane S2, 2026-09-08. Branch wip/standalone.

The campaign's north star is a functional reimplementation, and the first milestone that makes it falsifiable is:

the standalone loads a save, runs one strategic turn, and writes an autosave that byte-matches what the original produces from the same state.

This document says what sots_turn does today, what it deliberately does not do, and what stands between it and that byte-match. The short answer is on the first line of the metric: 14 of the 44 turn-driver phases are modelled, 7 of them commit anything, and the reference turn closes 5 of 209 diverging leaves. Everything below is the detail behind those numbers.

---

1. What it does end to end, today

$ sots_turn SAVE --roundtrip --phases --out POST.sav --metric metric.json

1. Loads the save through mars::stream::read_save_file — the engine's own reader, the one with 100 % named coverage on all eleven saves in the corpus.
2. Proves the foundation with --roundtrip: re-serialises the untouched parse and compares byte for byte against the inflated stream. If that fails, nothing after it means anything, so the run stops.
3. Walks the whole published phase order of all three drivers — the host steps, then StrategyServer::ProcessTurn's 32 phases, with ServerPlayer::ProcessTurn's 12 nested in at phase 13, then OnAllCombatDone_Tail's 37 — running what we hold and printing what we do not.
4. Writes the post-turn state back through mars::stream::write_save + gzip.
5. Emits a completion metric as JSON for the campaign dashboard.

It reads no game data. The save path is an argument; the test reads $SOTS_SAVES_DIR and skips cleanly when it is unset. No .sav is in this repo and none is written into it.

2. The design decision that matters: blocked phases do not commit

Several phases are ones whose formula is verified and whose inputs are not modelled. The budget roll-up is the type case: ComputeBudget compared clean over 4,284 live calls, but one of its inputs is the money output of each owned system, and that needs the population → base-output term the colony model explicitly declares unresolved.

Running such a phase and writing its result would be worse than not running it. It replaces a leaf that may currently agree with the oracle by construction with one that is confidently wrong, and the divergence count then measures how much code we ran rather than how much we know. So a blocked phase is evaluated, reported, and not written unless the operator passes --commit-blocked.

This is not theoretical. S31's player-status restore was implemented and committed in the first version of this lane; the comparison tool immediately reported two regressed leaves on the turn2 → turn3 pair — two Player.Status words that agreed with the oracle before the turn and disagreed after it. The phase writes 1; the file carries 4; a writer between the phase and the autosave is unaccounted. S31 is now blocked, and the measured fact is recorded in its catalog note rather than papered over.

The same reasoning governs the generator. The turn consumes roughly 18–20 words that nothing here models, so the advanced state would be wrong in a different way from the untouched state. The untouched state at least tells the truth. --commit-rng exists for the day the ledger closes.

3. The phase catalog

src/app/phase_catalog.{h,cpp} is the roadmap and the ledger at once. Every phase of every driver is in it whether or not it is implemented, with one of five statuses:

status	meaning	commits?
verified	implemented here and compared against the live game	yes
implemented	implemented from an instruction-verified reading, not yet compared live	yes
partial	part implemented and committed, part stubbed; the note says which	yes, the part
blocked	formula held, an input is not modelled	no (unless forced)
stub	a named no-op	no

Nothing is verified. That is deliberate: in this table verified means "compared against the live game", and lane S2 holds no VM. app_test_catalog asserts verified == 0 so the claim cannot drift upward by accident.

3.1 Current state

driver	phases	modelled	committed
host steps (outside the milestone's denominator)	2	2	2
StrategyServer::ProcessTurn	32	4	3
ServerPlayer::ProcessTurn	12	10	4
the milestone's denominator	44	14	7
OnAllCombatDone_Tail	37	2	1

3.2 What actually runs

Committed

phase	what it does
H00 BeginProcessTurn	advances the frame counter — the turn number the whole game displays
H01 SaveWriterInvariants	the summary's turn number is the frame counter; an identity that holds across the whole corpus
S00 SnapshotPreviousTurn	the modification-counter bump (the shadow-word snapshot is not modelled)
S11 SystemTurn	game::sim::ProcessColonyTurn, committing the parts that need neither the tuning table nor a carrying capacity
P07 ClearTimedResearchAccumulators	zeroes the three timed-research accumulators that are on the wire
P08 DecayRebellionOutputModifier	rebel AI only: −0.04f per turn, clamped to [1, 2]
P09 AccumulateTimedResearchBonuses	the timed research-bonus vector, iterated last → first, which is load-bearing because float addition is not associative
P10 ConsumeResearchRollPending	the strict 0.5f < progress/cost test and the in-branch flag clear
T00 IncrementModCount	the tail's own bump of the same counter

Evaluated and reported, not committed: P01 P02 P03 P05 P06 P11 S31 T31.

Everything else is a named no-op that prints itself in --phases.

3.3 One hypothesis, and how it is being tested

ProcessColonyTurn takes stable as an input — in the original it is a callee's verdict. The standalone's stand-in is owned && !abandoned && !destroyed, and it is labelled a hypothesis in the code and in the run log, because rule 6 says a path no evidence exercises is a hypothesis.

It is a testable one: stable drives the turns-developing counter, which is a named leaf. On the reference pair it judged 3 of 28 systems stable and closed exactly the 3 ntdev leaves the oracle moved. It then closed the same 3 on the turn2 → turn3 pair — a different workload, which is what makes it evidence about the model rather than about the recording. Six independent agreements, zero disagreements, is not proof, and it is written down as such.

4. The divergence report

Measured by sots-re/tools/standalone_report.py, which drives sots_turn over each consecutive-turn pair in the corpus and diffs the result against the game's own post-turn save using verify/state-checksum/state_checksum.py. That tool localises to named leaves and proves its own coverage by re-serialising the parse back to bytes, so nothing can hide from it.

Reference pair turn1-state.sav → turn2-state.sav (a real End Turn):

baseline (a standalone that does nothing)   209 leaves diverge
after one standalone turn                   204 leaves diverge
closed 5, regressed 0

Closed: /Summary/Turn, /Sim/Frame, and ntdev on Gamma Cephei, Ke'Dolarra and Koa'Vo. The second pair turn2 → turn3 closes the same five out of a baseline of 108, with zero regressions.

regressed is reported next to closed on purpose. A leaf that agreed before the turn and disagrees after it is a phase doing damage, and netting it off against the closures would hide exactly the failure this scaffold is built to catch.

4.1 Where the remaining 204 live

subsystem	leaves	what it is
/Sim/players	82	savings, bankruptcy limits, research state, the turn's event buckets, per-player AI bookkeeping
/Sim/systems	80	see below
/Sim/turnstats	24	the per-turn statistics archive — written by the tail's last phase
/Sim/SvSctOb	8	the script-object encounter tree
singletons	10	ModCount, RNG, Checksum, NMnx, cmbtid, the four id lists, NumFlts

The system side is not 80 unrelated facts. It is a handful of mechanisms:

• 32 leaves — one new nve record on each of 8 systems (NVE + EPid/ETS/Eid). One mechanism, eight repetitions: the per-player system-visibility record. Spine phase 24 or tail phase 21.
• 18 leaves — TShn and ltis moving 1 → 2 on 8–10 systems. Both look like per-turn counters and both are unattributed; nothing in the campaign names their writer. They are the cheapest measured candidates on the board and they are deliberately not implemented, because "it went up by one across one turn" is a hypothesis, not a reading.
• the rest: population growth, reputation, the output-rate re-normalisation, one new fleet.

The player side is dominated by three things: Sav (blocked behind the system-income term), the bankruptcy limits (blocked behind the same term), and the event buckets (blocked behind the localised event-text table).

5. What stands between this and the byte-match

In the order they must be solved, not in order of size.

1. The RNG ledger. 18–20 words are consumed per turn and none are modelled. The generator is saved state, so a byte-match is arithmetically impossible until every draw is attributed — including the two draw sites in the post-combat tail, which happen after the spine has finished and before the file is written. Lane I proved the search space closes (exactly 22 draw sites in the spine's 1,426-function closure, plus an image-wide scan for inlined draws); lane Z is measuring the attribution. Nothing in src/app can close this.
2. The population → output term. One unresolved formula blocks P01, P02, P05, P06 and T31 — that is 5 of the 44 phases and the single largest cluster of player-side leaves. It is the highest-value unresolved formula in the campaign for this milestone.
3. The post-combat tail. 37 phases, none implemented, and it is the driver the autosave is written from. turnstats, the bankruptcy limits, the observed-design records and the player reports all live there.
4. Summary.Checksum. Its algorithm is unknown. It is one leaf, and it is the last leaf: whatever it hashes, it cannot be right until everything it hashes is right.
5. The Player.Status writer. The phase writes 1, the file carries 4, a load resets to 0. Four leaves, and a small, self-contained question.

There is also a floating-point requirement that is already measured rather than assumed: intermediates must be held at 53 bits and narrowed to float32 only on store, with round-to-nearest. 24-bit precision and round-up each move named leaves on this very corpus. game::sim already follows that rule; anything added to src/app must too.

6. Tests

test	what it holds
app_catalog	the three tables are complete, contiguous, uniquely named, and 32 + 12 = 44; every non-stub carries a note; nothing claims to be verified
app_turn	over every save in $SOTS_SAVES_DIR: an untouched load re-serialises byte-identically; a turn leaves the file re-readable and re-serialisable; the modelled counters moved; no blocked or stub phase wrote anything; the generator is untouched by default. Skips cleanly when the variable is unset

7. What this lane did not do

• It did not run the game. Lane S2 holds no VM; every comparison here is against saves the game already wrote.
• It did not touch src/shim/, so no cross-build was required.
• It did not implement a phase on a guess. Two obvious "+1 per turn" system counters were left alone for exactly that reason, and they are named in §4.1 so the next lane can close them properly.