# End-Turn determinism oracle — verified on the real game (2026-09-07)

Question: "load the same save, press End Turn, and the resulting autosave is byte-identical run to run"
(the Phase-2 verification oracle). Answer: **YES — byte-identical**, across five runs, in two separate
game processes, with and without an intervening manual save, and also identical to the autosave the
*original* (non-loaded, freshly created) game wrote in the earlier session.

## Verdict

**byte-identical.** No masking is needed for the End Turn oracle when both sides start from the same
save file. sha256 of `(Autosave).sav` after End Turn from `Autosave - turn2.sav` is
`978041acd168b56ed8eb3f5e42e78d5e70eae6e6517d75e659a5eb7ca3d60921` in every run (A–E) and equals the
`Autosave - turn3.sav` captured in the first session (different process, game created live, not loaded).

The only place bytes ever varied is **load → save round-trip of a *post-turn* autosave**: the game
resets a per-player `Status` int (4 → 0) on load, which also moves the derived top-level `Checksum`.
See "Round-trip stability" below for the canonicalization rule if a harness ever compares a loaded
`(Autosave).sav` against a re-save of it.

## Revalidated 2026-09-08 (lane H)

Lane N's End Turns overwrote the three autosave *contents* on VM140 (the file set was untouched).
Lane H regenerated the pair by the documented procedure — load `ref-turn2.sav` (`ab4ac2d7…`, verified
first), one End Turn, build `recap-7584bad-20260908T0615Z`, `hooks=trace` — and **both hashes below
reproduced exactly**: `(Autosave EndTurn).sav` 66,732 B `bb4fd9ac89f41e3b…`, `(Autosave).sav`
67,219 B `978041acd168b56e…`.

That is a stronger result than a repeat, because the process is no longer the one this document
measured: nineteen template hooks and seven RNG entry-point detours are now installed instead of a
single asm stub, an x87 control-word module is present, and `SavedGames\` holds eight files rather
than four. The oracle survives all of it. Copies kept at
`verify/results/shim/probes/oracle-restore/h-oracle-{endturn,autosave}.sav`, and the same bytes were
put back on the VM as the three autosaves.

**Related, and it belongs next to the oracle:** lane H found that a MinHook detour on
**0x00893290** changes the game's output — same input save, `(Autosave).sav` 4 bytes different and
one generator word short (`findings/control-flow/tail-probes.md` §2). The un-instrumented game and
the lane-Z instrument agree; that one hook does not. **A behavioural harness must be checked against
the oracle, not only against itself.** The cheap standing check is: load
`verify/results/shim/tailrng/z2-endturn.sav`, one End Turn, expect
`(Autosave).sav` = `b2124798470d85ea86b0e9e4abfd9e23f3be73caa1115dd7614021be76305939`.

## Environment

* VM140 `sots-re-win10`, `C:\SOTS\Sword of the Stars.exe` GOG v1.8.1 (`ver.1.8.1 Wed Dec 13 03:38:31 2017`),
  DXVK 3.1 on Mesa lavapipe, windowed 1024x768 (see `Z:\saves\README.md` for the launch recipe).
* Phase-2 shim (`binkw32.dll` proxy, build `4a15301-20260907T2118Z`) deployed with `shim.cfg` `hooks=trace`
  — only hooks `Mars_Application_Initialize` and logs; it was loaded in both processes used here
  (`shim.log`: pid 3808 then pid 4384).
* Input save: `Z:\saves\Autosave - turn2.sav` (sha256 `ab4ac2d7…`, 66,739 B) copied to
  `C:\SOTS\SavedGames\ref-turn2.sav`. It is the *post-turn* autosave of turn 2 (state after End Turn #1
  completed): 2 players (`re` = Morrigi @ Gamma Cephei, `Fane Lao` = AI), 28 stars, game name `MyGameverify1`.
* The three autosaves the game had in `SavedGames\` before this work (turn 5-ish, 76 kB, from a later
  session) were moved to `pre-existing\` so the Load dialog only showed known files.
* UI driven with `recipe/click_helper.ps1` via the `SOTSUI` scheduled task; screenshots via `qm screendump`.

Click path per run (1024x768 window at 0,0):
main menu `Load Game` (512,536) → `Single Player` (512,290) → `OK` (551,523) → pick row → `OK` (682,624)
→ lobby `Launch` (511,663) → ~30 s load → strategy map "Turn 2", Imperial Savings 289,688 →
`End Turn` (100,714) → ~5 s → "Turn 3", Savings 532,369 → in-game menu (1000,714) → `Quit to Main Menu` (938,699) → `OK` (537,377).
Manual save: menu → `Save` (938,679) → type suffix into the pre-filled name → `Save` (773,234) → `OK` → `Done` (773,542).

## Runs

| Run | Process | Procedure | `(Autosave EndTurn).sav` | `(Autosave).sav` |
|---|---|---|---|---|
| A | pid 3808 (already running) | load `ref-turn2` → End Turn | `bb4fd9ac89f41e3b` 66,732 B | `978041acd168b56e` 67,219 B |
| B | pid 3808 (same process) | quit to menu → load `ref-turn2` → End Turn | `bb4fd9ac89f41e3b` | `978041acd168b56e` |
| C | **pid 4384 (game exited with code 0, relaunched via task `SOTS`)** | load `ref-turn2` → End Turn | `bb4fd9ac89f41e3b` | `978041acd168b56e` |
| D | pid 4384 | load `ref-turn2` → **manual save `MyGameverify1rtD`** → End Turn | `bb4fd9ac89f41e3b` | `978041acd168b56e` |
| E | pid 4384 | load `MyGameverify1verify1` (the Status=0 form) → **manual save `MyGameverify1rtE`** → End Turn | `bb4fd9ac89f41e3b` | `978041acd168b56e` |
| ref (first session, 16:03) | pid 6396-era, game created live, never loaded | End Turn #2 of the live game | `Autosave EndTurn - turn3.sav` = `bb4fd9ac89f41e3b` | `Autosave - turn3.sav` = `978041acd168b56e` |

Full hashes (`runX/sha256.txt`):

```
978041acd168b56ed8eb3f5e42e78d5e70eae6e6517d75e659a5eb7ca3d60921  (Autosave).sav            [turn-3 post-turn state]  runs A B C D E + first session
bb4fd9ac89f41e3bc0db2af08b18ce83417521ac4bcee695fc9fa6ce16e30948  (Autosave EndTurn).sav    [turn-2 pre-turn state]   runs A B C D E + first session
bb4fd9ac89f41e3bc0db2af08b18ce83417521ac4bcee695fc9fa6ce16e30948  MyGameverify1rtD.sav      manual save after loading ref-turn2 (run D)
bb4fd9ac89f41e3bc0db2af08b18ce83417521ac4bcee695fc9fa6ce16e30948  MyGameverify1rtE.sav      manual save after loading MyGameverify1verify1 (run E)
bb4fd9ac89f41e3bc0db2af08b18ce83417521ac4bcee695fc9fa6ce16e30948  MyGameverify1verify1.sav  manual save from the first session (turn 2)
ab4ac2d7e2977260a4de916f65c7ecc6dd5b0094dac4bb51241317232ea17ab4  ref-turn2.sav             input (= Z:\saves\Autosave - turn2.sav)
```

Inflated (gunzipped) streams are equally identical: `(Autosave).sav` → 609,080 B `17db7ed455357c4d…`,
`(Autosave EndTurn).sav` → 603,360 B `29f194dfcd932b93…`, `ref-turn2.sav` → 603,360 B `2fcf34ce4296b160…`.
The gzip container is deterministic too (header `1f8b 0800 00000000 00 0b`: MTIME=0, XFL=0, OS=11/NTFS,
no name/comment) — the compressed bytes match, not just the payload.

## What End Turn writes

On the transition to the new turn the game writes, in `C:\SOTS\SavedGames\` (all at the same second):

* `(Autosave EndTurn).sav` — the **pre-turn** state, i.e. the state at the moment End Turn was pressed.
  It is byte-identical to a manual save made on that turn.
* `(Autosave).sav` — the **post-turn** state (new turn number, RNG advanced, economy applied).
* `(Autosave Backup).sav` — the previous `(Autosave).sav`, rotated (only appears from the second End
  Turn in a process's SavedGames history; it is a rename, hash unchanged).

Nothing is written on Load or on Launch from the lobby. The Load dialog lists files by filename with the
in-file `GameName`, player count and `Turn`. Files in the first-session `Z:\saves\` were renamed copies of
these (`Autosave - turnN.sav` = `(Autosave).sav`, etc.).

No timestamp, save name, machine id or session salt is stored anywhere in the file: `MyGameverify1verify1`,
`MyGameverify1rtD`, `MyGameverify1rtE` and `(Autosave EndTurn)` — four different file names, three of
them written minutes apart in two processes — are one and the same byte sequence.

## Round-trip stability (load → save with no End Turn)

* Loading the **pre-turn / manual form** and saving immediately reproduces the loaded bytes exactly:
  `MyGameverify1verify1.sav` (`bb4fd9ac…`) → load → Save → `MyGameverify1rtE.sav` = `bb4fd9ac…`. **Stable.**
* Loading the **post-turn `(Autosave).sav` form** and saving immediately does *not* reproduce it:
  `ref-turn2.sav` (`ab4ac2d7…`, 66,739 B) → load → Save → `MyGameverify1rtD.sav` = `bb4fd9ac…` (66,732 B).
  The two inflated streams (603,360 B each) differ in exactly **5 bytes**:

```
inflated offset (1-based)   ref-turn2   re-save   field (save_reader --dump path)
      89                     0x64        0x54      Summary.Checksum  int  -1205790620 -> -1205790636   (delta 16 = 4 x 4)
  66291  (0x102e8+4)          4           0        Player[PlryName="re"].Status
 116067  (0x1c558+4)          4           0        Player[PlryName="Fane Lao"].Status
 177739  (0x2b640+4)          4           0        Player[PlryName="Singularity"].Status   (1st of two Singularity records)
 235567  (0x39824+4)          4           0        Player[PlryName="Singularity"].Status   (2nd)
```

  The other four `Player.Status` fields (Alien Menace, Peacekeeper Enforcer, Von Neumann, Independent
  Colony) are 0 in both. Interpretation: `Status=4` is the "turn ended / ready" flag the server leaves on the
  four turn-participating player records when it writes the post-turn autosave; loading a game clears it.
  `Summary.Checksum` moves by exactly the sum of the changed bytes (16), consistent with an additive
  checksum over the payload — treat it as **derived**, never as state.
  (`dumps/diff_ref-turn2_vs_EndTurn.txt`, `dumps/cmp_ref-turn2_vs_EndTurn.txt`.)

## Recommended canonicalization rule for the harness

1. **Oracle compare (End Turn):** compare `(Autosave).sav` and `(Autosave EndTurn).sav` **byte-for-byte**
   (sha256 of the file is enough; no inflate, no masking). Expected for the reference run from
   `Autosave - turn2.sav`: `(Autosave).sav` = `978041acd168b56e…`, `(Autosave EndTurn).sav` = `bb4fd9ac89f41e3b…`.
2. **If a re-implementation compares its output against a *loaded* post-turn autosave, or compares a
   pre-turn save with a post-turn one of the same turn**, canonicalize by masking exactly:
   * every `Player.Status` int (set to 0), and
   * `Summary.Checksum` (recompute, or ignore).
   Nothing else varies. Use `save_reader.py --dump` on the inflated stream; both fields are named as
   above at fixed paths.
3. Do not mask anything in the gzip container — it is deterministic (MTIME 0), so a container-level
   sha256 is a valid first-line check; inflate only to localize a mismatch.

## Files in this directory

* `runA/ … runE/` — the raw `SavedGames\` contents after each run, plus `sha256.txt`.
* `pre-existing/` — the three later-turn autosaves that were in `SavedGames\` before this work (moved aside).
* `dumps/` — `save_reader.py --dump` text of `ref-turn2` (input), `Autosave-EndTurn-turn2` and
  `Autosave-turn3` (outputs), plus the field diff and `cmp -l` of the round-trip pair.
* `inflated/` — gunzipped streams of the same three files.
* `screenshots/` — console captures of each run's loaded state / result / save dialogs.
* `hashes.txt` — sha256 of every `.sav` across all runs.

State left behind: the game is still running on VM140 (pid 4384, task `SOTS`, shim `hooks=trace`), sitting
on the turn-3 strategy map after run E; `C:\SOTS\SavedGames\` holds the run-E set (`ref-turn2.sav`,
`MyGameverify1*.sav`, the three `(Autosave*)` files).