[michaldengusiak]

Roadmap S03 - Run settings and version traceability (SAM documentation/SIMULATION_ROADMAP_Q4_2026.md, Phase A). SAM_UI only; no SAM_Validation schema change. Record: documentation/S03-RunProvenance-PR.md.

Base sow/2026-Q4 4d7f5bd8. Validated content SHA 87126efc (after the independent-review fixes; first content 29926a2f). 4efe93f4 and 2724f0c5 are record/evidence only.

What changes

• One shared provenance mechanism (Classes/Provenance/SimulationRunProvenance.cs), written into every Tas, OpenStudio and Both manifest as "provenance" (sam-ui.run-provenance/1):
  • Build: the build's own stamp (InformationalVersion + metadata, set by SAM_Deploy installers), never SAM_COMMIT or a Git HEAD; the SHA-256 of every SAM assembly the run used.
  • Tas: the registered TBD.Document server (TAS version, SHA-256).
  • OpenStudio: the SDK versions, the CLI that ran (SHA-256, version) and the EnergyPlus version from eplusout.err.
  • Both: each producer's binary, and what each producer reported in its B1a.
  • Weather: embedded or explicit, with its hash.
  • Design days and settings: the design-day source, and the settings actually handed to the engine.
  • An unknown item is "unknown" with its reason under provenance.unknown; no item is left blank.
• Tas only (Energy Simulation / Run Simulation > Tas) now writes <project>.tas-run.json beside the TBD on every outcome: Succeeded, Failed, Cancelled, Refused and a thrown exception. The Part O routes are unchanged.
• Unchanged: run status, exceptions, cancellation, outputs, settings, conversion, comparison, B1a and the other repositories. Pre-S03 manifest keys are kept (provenance is additive).

Validation (local)

• Full SAM.Analytical.UI.WPF.Tests: 2912/2912 PASS on 87126efc (2860 + 52 new: SimulationRunProvenanceTests 46, TasRunManifestTests 6). Earlier, 2910/2910 on 29926a2f. Focused set, including a real OpenStudio run: 107/107.

• Mutation checks, all caught:

  Mutation	Tests failed
  No Tas record	6
  SAM_COMMIT used as the revision	1
  "Embedded" decided by presence instead of content	3
  Status ignoring an exception	2
  Stale reasons kept	1
  Weather Guid kept in the content hash	1

• Real engines on the licensed laptop, through the SAM_UI code paths (documentation/evidence/s03-20261019/): Tas explicit and embedded; OpenStudio explicit and embedded; Both with and without SAM_COMMIT.

• Real-ribbon rehearsal on a local S03+S04 integration build (draft S05 preflight - rehearsal only, NOT acceptance (docs/evidence) #244): Tas success, Tas refusal and Both. Each tas-run.json / manifest matched what the engines did.

Independent review

A separate regression review of the combined S03+S04 diff confirmed no change to S03 status, exceptions or outputs. It led to three fixes in 87126efc:

• the weather content hash no longer includes the WeatherData's own Guid;
• the TAS COM server is looked up in both registry views;
• no stale reasons are left when a whole section becomes unknown.

The tests that set SAM_COMMIT now run in a non-parallel collection.

Findings / owner decisions

1. Both needs SAM_COMMIT when the producers are developer builds. Without it, both producers refuse their own B1a ($.provenance.samCommit) and the run fails; the evidence is included. This is existing producer behaviour, now recorded. SAM_UI cannot supply a verified value. It resolves with stamped producers (S06), or with a separate producer/SAM_Validation change. Decide: accept until S06?
2. OpenStudio CLI/SDK mismatch on this laptop. The in-process SDK is 3.10.0 (E+ 25.1.0), but the CLI that ran is ladybug_tools' 3.11.0 (E+ 25.2.0). This belongs to S06.
3. The Part O routes write no tas-run.json.

Merge order with S04 (#243)

The two PRs are independent. Both append assertions to OpenStudioSimulationTests.RealRun_…, so whichever merges second has one textual conflict: keep both blocks. A local integration merge resolved it that way and passed the full suite: 2926/2926.

Final PR head 2724f0c5: hosted Build (39328188434) PASS; SPDX (39328188446) PASS.

🤖 Generated with Claude Code