Phase 1: Minimal OpenStudio/EnergyPlus run from SAM_UI without disrupting Tas (gate G1, first PR) #229

Parent: #227

Goal

Add the smallest reliable path that runs a real OpenStudio/EnergyPlus simulation from SAM_UI, reusing the existing SAM_OpenStudio APIs and runner. Tas must keep working exactly as it does now.

Context

• SAM_UI has no OpenStudio path and no reference to SAM_OpenStudio. CI (.github/workflows/build.yml) does not clone or build SAM_OpenStudio.
• Reused from SAM_OpenStudio (netstandard2.0, OpenStudio NuGet 3.10.0):
  • AnalyticalModel.ToOpenStudioAsync(epw, outDir, convOpts, runOpts, run, IProgress<OpenStudioSimulationProgress>, CancellationToken) (SAM.Analytical.OpenStudio/Convert/ToOpenStudio/AnalyticalModel.cs:62);
  • OpenStudioRunOptions (UseUniqueRunDirectory, TimeoutSeconds, CliPath);
  • Query.OpenStudioCliPath;
  • result mapping into SAM result classes (docs/SAM_OPENSTUDIO_RESULT_MAPPING.md);
  • OpenStudioConversionResult.GetDiagnostics().
• EnergyPlus already runs as a separate openstudio.exe process under a Job Object, so cancel or timeout kills the whole process tree.

Scope

1. CI: add SAM_OpenStudio to the dependency clone and build order in build.yml after SAM. Its libraries depend only on SAM. Check that branch resolution falls back to sow/2026-Q4.
2. References in WPF/SAM.Analytical.UI.WPF:
   • HintPath to SAM_OpenStudio\build\SAM.{Core,Geometry,Analytical}.OpenStudio.dll;
   • PackageReference OpenStudio at the version SAM_OpenStudio pins;
   • System.Data.SQLite with its win-x64 native copy, following SAM_OpenStudio's csproj pattern and its net8.0-windows Grasshopper projects.
3. New Modify/SimulateOpenStudio.cs:
   • Serialise the current model to a snapshot JSON in the run folder and work on a copy.
   • Resolve weather: embedded model weather written to an EPW, or a file the user picks. Record which one was used.
   • Call ToOpenStudioAsync(..., run: true) on a background thread with progress and cancel.
   • Write results to the copy and save <name>_OpenStudio.json next to the run.
   • Show diagnostics and the run-folder path.
4. Ribbon command "Simulate (OpenStudio/EnergyPlus)" in AnalyticalWindow.xaml.cs next to Simulate() (~:2209). Existing Tas commands stay untouched.
5. Missing or wrong-version OpenStudio CLI: a clear diagnostic with no crash and no partial results written to the open model.
6. PR record document under documentation/, as AGENTS.md requires.

Out of scope

Parallel execution, a job framework, the standalone runner exe, Tas/OpenStudio comparison, input manifests, packaging in SAM_Deploy. The packaging risk (OpenStudio bindings and CLI must be shipped or installed) is recorded as a follow-up.

Depends on

None for the code. The SAM_OpenStudio sow/2026-Q4 build output must be available in CI.

Acceptance criteria

• The SAM_UI solution builds in CI with SAM_OpenStudio resolved from sow/2026-Q4. The build log shows which dependency branch was selected.
• On a Windows machine with OpenStudio 3.10, running the SAM_OpenStudio two-cell fixture (tests/resources/models/rawModel-WindowsWeatherDataDDYAdiabaticAirPanel.sam) from SAM_UI produces run/eplusout.sql with 0 severe/fatal errors, and results load into <name>_OpenStudio.json.
• The results in <name>_OpenStudio.json match benchmark-openstudio on the same model and EPW. They use the same code path, so the difference must be zero.
• The open model's existing results and the Tas workflow are unchanged. A unit test proves the snapshot/copy guarantee, and a manual Tas run before and after the change gives identical results.
• Cancel kills openstudio.exe and energyplus.exe, and nothing is written to the model.

Validation gate G1