Advance and document the v0.10 save compatibility repair

[themuffinator]

Summary

• advance both CI workflows to the merged openQ4-game integration commit 09fa7e175efa5a5d819569ba577fd0e11c38a891
• preserve the GameLib modernization line while incorporating the reviewed save fix from Stabilize v0.10 save restoration across build profiles openQ4-game#7 through Integrate v0.10 save repair with the modernization line openQ4-game#8
• document the exact released v0.10 version-3 compatibility decoder
• explain the two absent player liquid-state fields and the optimized-build empty-physics-frame omission
• lock the complete legacy tuple, both SP/MP readers, source-declared frame ownership, and removal of linker-address comparisons in the engine's cross-repository v3 contract
• add player-facing 0.12 upgrade guidance and the retained issue ERROR: idRestoreGame::ReadSyncId: marker mismatch while reading ReadTrace at offset 696660 (got 0x00000034, expected 0x5934514f) #123 validation limits

Validation

• all 47 companion GameLib contracts (36 competitive plus 11 save/portability/presentation groups)
• standalone GameLib Windows x64 SP/MP build (488/488)
• integrated openQ4 Windows x64 engine/SP/MP/renderer build (1,200/1,200)
• all 14 companion integration checks across Linux x64/ARM64 GCC/Clang, Windows x64, and macOS ARM64/Intel x64
• python tools/tests/competitive_match_layer.py
• python tools/tests/savegame_v3_contract.py
• python tools/tests/savegame_pointer_width_safety.py
• python tools/tests/gamelibs_staging.py
• python tools/tests/validation_hardening.py
• python tools/tests/docs_link_integrity.py
• python tools/tests/release_tooling_safety.py
• python -m py_compile tools/tests/savegame_v3_contract.py
• python tools/validation/openq4_validate.py pr --dry-run --game-libs-repo E:\Repositories\openQ4-game
• git diff --check

Runtime evidence

• exact reporter v0.10 save passes its omitted physics frame and both later four-byte field boundaries, including the reported ReadTrace offset, before reaching the missing-mod GUI boundary; combined-modernization log SHA-256 CED470F16CD82A20453B9B5B276C1A0C453274803F9B5BF1E511D720D1D3E3CA
• fresh stock game/airdefense2 save/reload completes in active gameplay and exits normally; save SHA-256 9B3F94F1FAAC72F05C791DD7A253E980765A343FF4E1481EDD9D7D09A9C9015D, reload log SHA-256 2EACB7D643E01EC66F1180E3678AFA3F21E5CB5308B812FFD4DD1292D60CA31B, engine screenshot SHA-256 600D2E29DBCBE4C826CA11A686E0D04028E0FD06B87BAF236C16F5F7175EB74A
• the engine screenshot was visually reviewed and shows healthy restored gameplay rendering

The exact attached mod save next reaches a GUI identity mismatch because the attachment omits its HiDef mod GUI/assets. Issue #123 will remain open for reporter-side confirmation with the complete mod installation.

Related to #123.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 48696572a7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Advance the pinned GameLibs revision with this contract

The added check requires symbols introduced by the companion decoder change, but the checked commit-validation.yml and push-verification.yml still fetch openQ4-game revision 79c9d7d1e26952ffd8e5352f7d51b64ee08b9d82 before invoking this script. That older pinned source does not contain OPENQ4_SAVEGAME_V3_PRE_PLAYER_LIQUID_FIELDS_SNAPSHOTS, so snapshot_tuples() raises Missing snapshot array and makes the standard PR and push validation jobs fail. Advance both workflow pins to the companion revision containing the decoder as part of this cross-repository change.

AGENTS.md reference: AGENTS.md:L26-L27

Useful? React with 👍 / 👎.

[themuffinator]

Final validation is complete.

• The clean-tree local PR profile passed in 400.9 seconds.
• The integrated Windows x64 engine + SP/MP build passed all 1,200 build steps.
• The companion GameLib integration passed all 47 contract tests and all 488 standalone Windows x64 SP/MP build steps; all 14 GameLib PR Menu cursor handling #8 CI jobs also passed.
• The reporter's exact attached save now passes the original missing-idPhysics, two historical-field, and ReadTrace boundaries. The integrated rerun log SHA-256 is CED470F16CD82A20453B9B5B276C1A0C453274803F9B5BF1E511D720D1D3E3CA; it proceeds to the later expected HiDef GUI-layout mismatch because the attachment does not include the complete mod assets.
• The full root Commit Validation workflow passed, including Linux x64 ASan+UBSan, Windows x64, Linux ARM64, Wayland variants, macOS ARM64/Intel, and both universal2 assemblies. The separate Linux ARM64 cross-build also passed.

The four failures in the push-only macOS runtime-smoke matrix exactly match the four failures on current main run 33028426771. They are the inherited hosted-Apple OpenGL 2.1 / GLSL 130 optional-renderer startup limitation (including the Metal jobs' OpenGL fallback probe), not regressions introduced by this PR. There are no new or required-check failures.