[michaldengusiak]

Roadmap S04 - Stable canonical simulation snapshot (SAM documentation/SIMULATION_ROADMAP_Q4_2026.md, Phase A, finding F7 of #239). SAM_UI only; SAM_Validation's canonical JSON v1 and canonicalizationVersion are unchanged. Record: documentation/S04-StableCanonicalSnapshot-PR.md.

Base sow/2026-Q4 4d7f5bd8. Independent of S03 (#242). Validated content SHA 29ca1d1a, after the independent-review fixes; the first content was 0594e708. Record/evidence-only commits: bbc8a19d, 420b71dd, b19b80ab.

Problem (from real evidence)

• Session to session. Two frozen snapshots of the same box model, from two sessions, differ only in the Guid/ActiveGuid of the default "3D View" in SAM.Analytical.UI → UI Geometry Settings. The window regenerates that view on every open. As a result, four real S01b Both runs of one model carry four different canonicalModelHash values.
• Build to build. Once the view state is removed, the emptied UI set's GUID is the assembly's module version id, which changes with every SAM_UI build.

Fix

• FreezeAnalyticalModel writes the model's JSON without UI Geometry Settings.
  • The SAM.Analytical.UI set is dropped too, but only if it is empty, including an already-empty one.
  • The JSON is written exactly as Core.Convert.ToFile writes it, so a model with no view state gives the same bytes as before.
  • This is the snapshot that both Both producers hash and that OpenStudio Simulation converts.
• The open model is never changed.
• The OpenStudio result model gets back a copy of the view state. The copy is taken at freeze time and attached inside a try/catch, so it never changes the run's outcome.
• No geometry, construction, schedule, weather, design-day, option or conversion changes.

Validation (local)

• Full SAM.Analytical.UI.WPF.Tests 2874/2874 PASS on 29ca1d1a: 2860 existing plus 14 new in CanonicalSnapshotTests, on the Part O multizone fixture, with each model saved and reopened as the window does. (2873/2873 on 0594e708.)

  • A: the same model opened twice gives the same hash.
  • B: different UI GUIDs, or another build's set GUID, give the same hash.
  • C: each engineering edit changes the hash.
  • D/E: two Both runs get identical snapshots, and each manifest's hash equals its file's.
  • F: the result model keeps the freeze-time view state; the real OpenStudio run test checks this too.
  • G: the source model is not changed.

• Mutation checks, all caught:

  Mutation	Tests failed
  Pre-S04 snapshot	7
  Every UI set dropped	1
  Emptied set kept	2
  Already-empty set kept	1
  Result-model view state not restored	1

• Real producers (documentation/evidence/s04-20261019/):

  • Two sessions with different view GUIDs both gave snapshot 0c30db14….
  • benchmark-tas and benchmark-openstudio both reported canonicalModelHash 05c1e334….
  • The 4 historical S01b snapshots (two app builds, 4 pre-S04 hashes) re-freeze to the same values.

• Real ribbon (S05 rehearsal, draft S05 preflight - rehearsal only, NOT acceptance (docs/evidence) #244, local S03+S04 integration build): three separate app sessions of Run Simulation > Both (explicit ×2, embedded) all gave 0c30db14… / 05c1e334….

Independent review

A separate regression review of the combined S03+S04 diff found two S04 defects, both fixed in 29ca1d1a:

• Medium: the result-model view state was read from the live model at the end of a worker-thread run, unguarded, so it could turn a successful run into Failed. It is now copied at freeze time and attached inside a try/catch.
• Low: an already-empty UI set was kept. It is now dropped.

Notes

• Historical B1a documents keep their session-dependent hashes; new ones are stable.
• The Both evidence used a manual SAM_COMMIT for the developer-built producers (see S03: automatic run provenance for Tas, OpenStudio and Both #242).

Integration with merged S03 (2026-10-20)

S03 (#242) merged first as 1e460bbe. 3bbba54b merges sow/2026-Q4 (56e67d09) into this branch, keeping both the S04 and S03 blocks in OpenStudioSimulationTests.RealRun_…; its code tree equals the earlier local integration tree 8aafcb06 (only PROJECT_PROGRESS.md differs, from the base).

• Local full SAM.Analytical.UI.WPF.Tests on 3bbba54b: run 1 2925/2926 (one S03 test timed out on ProgressWindowHost's 5 s shutdown join under load and reported Cancelled; pre-existing fail-safe, recorded), run 2 2926/2926 PASS.
• The local SAM�uild predates SAM#212 (F1); hosted CI builds dependencies from source. Details in the record.
• dac1e540 is record-only.

Final PR head: see the latest checks below (updated at merge).

🤖 Generated with Claude Code