[michaldengusiak]

S06 supporting change: the OpenStudio CLI that runs is the one that matches the SDK

Roadmap S06 (SAM/documentation/SIMULATION_ROADMAP_Q4_2026.md). This is the supporting PR for the SAM_Deploy S06 smoke candidate (SAM-BIM/SAM_Deploy, branch feature/s06-installed-smoke-candidate). That candidate pins this branch's content commit 1f4bf60c through its SAM_OpenStudio gitlink.

Problem. With no explicit path, Query.OpenStudioCliPath() returned the first openstudio.exe on PATH. Neither SAM_UI's OpenStudio route nor benchmark-openstudio passes a path. So on the S05 laptop, models written by the in-process OpenStudio 3.10.0 SDK (EnergyPlus 25.1.0) could be run by ladybug_tools' 3.11.0 CLI (EnergyPlus 25.2.0), depending on PATH (S03 finding, SAM_UI#242).

Change (SAM.Core.OpenStudio/Query/OpenStudioCliPath.cs):

• The discovery order is unchanged.
• When more than one CLI is found, the first one whose --version equals the loaded SDK version is returned. Build metadata after + is ignored.
• If none matches, the first one found is returned, as before.
• An explicit path is never version-checked.
• Two new public helpers: the pure selection rule, and OpenStudioCliVersion (cached).
• Nothing else changes: SDK, runner, diagnostics, conversion and results are untouched.

Tests:

• 9 offline tests in benchmark/SAM.Analytical.OpenStudio.Benchmark.Tests/OpenStudioCliSelectionTests.cs, which is the project hosted CI runs.
• Local run: 51/51 passed.
• Mutation check: disabling the version match fails 4 of the 9 new tests.

The end-to-end check is in the SAM_Deploy S06 record: an installed candidate run with ladybug's 3.11 first on PATH.

Record: documentation/S06-OpenStudio-Cli-Selection-PR.md. Validated content SHA: 1f4bf60c. Record commit: 3082dc6.

Hosted checks at the final head 3082dc6 (record-only after 1f4bf60c): build ✅ and spdx ✅. Local: 51/51 benchmark tests passed again on 2026-10-20.

End to end (2026-10-20, genuine installer). The hosted SAM_Deploy installer (run #227, which pins 1f4bf60c) was installed into an isolated profile, and OpenStudio was then run from the real ribbon with ladybug's OpenStudio 3.11.0 first on PATH. The run used the 3.10.0 CLI (46a80a3d), which matches SDK 3.10.0 / EnergyPlus 25.1.0. The result was Succeeded. The raw comparison with S05 reports exactMatch: false (45/45 numbers, 24 differences), kept as measured. All 24 differences are 4 run-generated subsurface names. Each maps 1:1 through its host-panel reference (one aperture per panel in this fixture), with equal values (SAM_Deploy#66 runs/os-subsurface-mapping.txt). Evidence: SAM-BIM/SAM_Deploy#66, evidence/s06-20261020/runs/x2-installer-openstudio/.

Explicit CLI path behaves as before: it is returned without any version check (test ExplicitPath_IsUnchanged_AndNeverVersionChecked). Nothing in the ribbon or the producer sets it, so it was not exercised end to end.

Merge order: this PR first. Then SAM_Deploy#66 repins only its SAM_OpenStudio gitlink to this PR's exact merge commit (never a later closeout tip), reruns Validate and the installer, and merges after the owner's approval. The provenance labelling (SAM_Deploy#66 check 9) was settled by the owner on 2026-10-20 as "Not PASS: accepted limitation" (documented in SAM-BIM/SAM_Validation#16); it does not block this change.
Do not merge before owner review. After merge, the SAM_Deploy S06 gitlink must be repointed from 1f4bf60c to the merge commit.

🤖 Generated with Claude Code