From cb84fd91709956bd63079b56ecc8339d7fa5a744 Mon Sep 17 00:00:00 2001 From: Michal Dengusiak Date: Tue, 20 Oct 2026 11:11:21 +0200 Subject: [PATCH 1/2] docs: installed-build samCommit/runnerCommit hold the SAM_Deploy revision (S06) Owner-accepted S06 limitation: document that SAM_Deploy installer builds report the SAM_Deploy build revision in both fields, how to recover the repository revisions from its gitlinks, and that existing records keep their meaning. Co-Authored-By: Claude Opus 5.5 --- docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md | 50 +++++++++++++++++++ docs/benchmark/SCHEMA.md | 18 ++++++- 2 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md diff --git a/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md b/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md new file mode 100644 index 0000000..1a12499 --- /dev/null +++ b/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md @@ -0,0 +1,50 @@ +# S06 - revision fields in installer builds (PR record) + +This PR is a documentation-only part of roadmap S06 (`SAM/documentation/SIMULATION_ROADMAP_Q4_2026.md`). +- Branch: `docs/s06-installed-build-provenance`, targeting `sow/2026-Q4` (base `68eded00`). +- Related PRs: SAM-BIM/SAM_Deploy#66 (the S06 installed candidate) and SAM-BIM/SAM_OpenStudio#32. +- Merge needs owner approval. `PROJECT_PROGRESS.md` is not touched; it gets a closeout only after the merge. + +## Status +Ready for owner review. The owner decided on 2026-10-20 to accept the installer-build provenance limitation as an +explicitly documented S06 exception. New repository stamping is not to be implemented. + +## Work completed +`SCHEMA.md` now covers installer builds. Its provenance table and a new section, "Revision fields in installer builds", +state the following: +- In a SAM_Deploy installer build without overrides, `samCommit` and `runnerCommit` hold the **SAM_Deploy build + revision**, because every assembly carries the SAM_Deploy commit as its InformationalVersion metadata. +- The field alone does not tell the two kinds of revision apart. The installer stamp does: it is + `...0+`, which SAM_UI records in `application.sourceRevisionOf`. +- The actual revisions come from the pinned gitlinks: `git ls-tree SAM SAM_Tas SAM_OpenStudio`. +- Existing documents keep their meaning. Developer runs with `SAM_COMMIT` (S05 and earlier) hold repository revisions. + No historical value is redefined. + +## Evidence +On the S06 installed candidate (SAM_Deploy `717533c`, hosted installer run #227, genuine install), both producers reported +`samCommit` = `runnerCommit` = `717533c`. The gitlinks of `717533c` give SAM `df27563b`, SAM_Tas `e84aeff6` and +SAM_OpenStudio `1f4bf60c`. Evidence is in SAM_Deploy#66, `evidence/s06-20261020/runs/x3-installer-both-embedded/`. + +## Decisions and assumptions +- This is documentation only. The schema version, the validators and the producers are unchanged. A field naming the + revision kind, or per-repository stamping, would be a separate schema or build change. +- The S06 provenance check is recorded as an **accepted limitation**, not as PASS. + +## Files changed +- `docs/benchmark/SCHEMA.md` +- `docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md` (this record) + +## Validation +- The diff touches only these two documentation files. +- The `#revision-fields-in-installer-builds` and `#version-and-compatibility-policy` anchors resolve to headings in `SCHEMA.md`. +- The producers' resolution order was checked against `Program.cs` in SAM_Tas (`benchmark/SAM.Analytical.Tas.Benchmark.Cli`) + and SAM_OpenStudio (`benchmark/SAM.Analytical.OpenStudio.Benchmark`). +- The stamp format was checked against SAM_Deploy `installer.yml` "Compute SAMVersion". +- Hosted CI: see the PR description. + +## Unresolved +None for this PR. SAM_Deploy's `SAM_Validation` gitlink stays at `68eded00`: this change ships no binary. + +## Next step +Owner review and merge. Then the SAM_Validation `PROJECT_PROGRESS.md` closeout, a docs-only `[skip ci]` commit with the +merge SHA. diff --git a/docs/benchmark/SCHEMA.md b/docs/benchmark/SCHEMA.md index 1fecca8..85586c5 100644 --- a/docs/benchmark/SCHEMA.md +++ b/docs/benchmark/SCHEMA.md @@ -26,8 +26,8 @@ Unknown fields do not change the meaning of known fields. A writer must not emit | `sourceFileHash` | string or null | SHA-256 of the exact input model-file bytes; null only when failure prevents hashing | | `canonicalModelHash` | string or null | SHA-256 of the canonical SAM representation; null only when failure prevents canonicalization | | `canonicalizationVersion` | string | Semantic version of the canonicalization rules | -| `samCommit` | string | SAM source revision used for the run | -| `runnerCommit` | string | Producer repository revision used for the run | +| `samCommit` | string | SAM source revision used for the run; in a SAM_Deploy installer build, the SAM_Deploy build revision (see [Revision fields in installer builds](#revision-fields-in-installer-builds)) | +| `runnerCommit` | string | Producer repository revision used for the run; in a SAM_Deploy installer build, the SAM_Deploy build revision (same section) | | `engine` | object | Engine kind, display name, engine version, and SDK version | | `route` | string | Exact route identifier; routes are never inferred from engine kind | | `weather` | object | Portable identity plus exact-file SHA-256 | @@ -43,6 +43,20 @@ Hashes use `sha256:` followed by 64 lowercase hexadecimal characters. `sourceFil For a successful run, both model hashes and the weather hash are required. A failure document may use `null` only for a hash that could not be computed, and must explain the reason in `warnings` or `notes`. `canonicalizationVersion` is required on every document, including failures: a document that could not compute a canonical hash must still declare which rules it would have used. Canonicalization rules must remove non-semantic ordering and formatting variation without removing model content that can affect simulation; they are specified in full under [Canonical model hashing](#canonical-model-hashing). +### Revision fields in installer builds + +Accepted limitation (owner decision, roadmap S06, 2026-10-20). The producers resolve `samCommit` and `runnerCommit` in this order: +1. the `--sam-commit` / `--runner-commit` argument; +2. the `SAM_COMMIT` / `RUNNER_COMMIT` environment variable; +3. the `+` build metadata of the InformationalVersion, of `SAM.Analytical` for `samCommit` and of the producer's own assembly for `runnerCommit`. + +A SAM_Deploy installer build stamps every assembly with the SAM_Deploy commit it was built from. So a producer run from an installed build, without overrides, writes that **SAM_Deploy build revision** into both fields, not the SAM or producer repository revision. The field alone does not say which kind of revision it holds. A SAM_Deploy installer build is recognisable by its stamp: version `...0+` on the producer and SAM assemblies, which SAM_UI's run manifest records in `application.sourceRevisionOf`. + +To recover the actual source revisions, read the gitlinks that the SAM_Deploy revision pins: +`git ls-tree SAM SAM_Tas SAM_OpenStudio` in `SAM-BIM/SAM_Deploy`. The SAM entry gives `samCommit`; SAM_Tas gives the Tas producer's `runnerCommit`, and SAM_OpenStudio the OpenStudio producer's. + +Existing documents keep their meaning and are not rewritten. Developer-built runs that set `SAM_COMMIT` (S05 and earlier), and runs whose producers resolved a local Git revision, record repository revisions. Per-repository stamping of installer builds is not implemented. Changing these fields' meaning, or adding a field that names the revision kind, is a schema change under the [version policy](#version-and-compatibility-policy). + Engine fields are: | Field | Type | Meaning | From ed7a878a993f2052d39d7ee9ba257b25aad40d3b Mon Sep 17 00:00:00 2001 From: Michal Dengusiak Date: Tue, 20 Oct 2026 11:46:45 +0200 Subject: [PATCH 2/2] docs: correct where the installer stamp is recorded in the run manifest (S06) Review fix: provenance.application.sourceRevisionOf is explanatory text. The full stamp is in entryAssembly.informationalVersion and components[].informationalVersion; sourceRevision holds the extracted SHA. Verified against the committed genuine-installer manifests. Co-Authored-By: Claude Opus 5.5 --- docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md | 15 ++++++++++++--- docs/benchmark/SCHEMA.md | 6 +++++- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md b/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md index 1a12499..1ecca97 100644 --- a/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md +++ b/docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md @@ -14,8 +14,13 @@ explicitly documented S06 exception. New repository stamping is not to be implem state the following: - In a SAM_Deploy installer build without overrides, `samCommit` and `runnerCommit` hold the **SAM_Deploy build revision**, because every assembly carries the SAM_Deploy commit as its InformationalVersion metadata. -- The field alone does not tell the two kinds of revision apart. The installer stamp does: it is - `...0+`, which SAM_UI records in `application.sourceRevisionOf`. +- The field alone does not tell the two kinds of revision apart. The installer stamp does: the InformationalVersion + `...0+`. SAM_UI's run manifest records it under `provenance.application`: + - the full stamp in `entryAssembly.informationalVersion` and each `components[].informationalVersion`; + - the extracted SHA in `sourceRevision`. + + `sourceRevisionOf` is explanatory text only. (Corrected after review: an earlier head, `cb84fd9`, said the stamp was + in `sourceRevisionOf`.) - The actual revisions come from the pinned gitlinks: `git ls-tree SAM SAM_Tas SAM_OpenStudio`. - Existing documents keep their meaning. Developer runs with `SAM_COMMIT` (S05 and earlier) hold repository revisions. No historical value is redefined. @@ -24,6 +29,9 @@ state the following: On the S06 installed candidate (SAM_Deploy `717533c`, hosted installer run #227, genuine install), both producers reported `samCommit` = `runnerCommit` = `717533c`. The gitlinks of `717533c` give SAM `df27563b`, SAM_Tas `e84aeff6` and SAM_OpenStudio `1f4bf60c`. Evidence is in SAM_Deploy#66, `evidence/s06-20261020/runs/x3-installer-both-embedded/`. +The committed genuine-installer manifests (x1 `box.tas-run.json`, x2 `openstudio-run.json`, x3 `engine-comparison-run.json`) +record `provenance.application.sourceRevision` = `717533c`. Their `entryAssembly.informationalVersion` and every +`components[].informationalVersion` are `2026.4.227.0+717533c`. Their `sourceRevisionOf` is the explanatory sentence. ## Decisions and assumptions - This is documentation only. The schema version, the validators and the producers are unchanged. A field naming the @@ -40,7 +48,8 @@ SAM_OpenStudio `1f4bf60c`. Evidence is in SAM_Deploy#66, `evidence/s06-20261020/ - The producers' resolution order was checked against `Program.cs` in SAM_Tas (`benchmark/SAM.Analytical.Tas.Benchmark.Cli`) and SAM_OpenStudio (`benchmark/SAM.Analytical.OpenStudio.Benchmark`). - The stamp format was checked against SAM_Deploy `installer.yml` "Compute SAMVersion". -- Hosted CI: see the PR description. +- The manifest field names and values were checked against the committed SAM_Deploy#66 manifests listed under Evidence. +- Hosted CI: `cb84fd9` passed Build (Windows) (SAM_Validation run 39398892361) and spdx. Later heads: see the PR description. ## Unresolved None for this PR. SAM_Deploy's `SAM_Validation` gitlink stays at `68eded00`: this change ships no binary. diff --git a/docs/benchmark/SCHEMA.md b/docs/benchmark/SCHEMA.md index 85586c5..3538298 100644 --- a/docs/benchmark/SCHEMA.md +++ b/docs/benchmark/SCHEMA.md @@ -50,7 +50,11 @@ Accepted limitation (owner decision, roadmap S06, 2026-10-20). The producers res 2. the `SAM_COMMIT` / `RUNNER_COMMIT` environment variable; 3. the `+` build metadata of the InformationalVersion, of `SAM.Analytical` for `samCommit` and of the producer's own assembly for `runnerCommit`. -A SAM_Deploy installer build stamps every assembly with the SAM_Deploy commit it was built from. So a producer run from an installed build, without overrides, writes that **SAM_Deploy build revision** into both fields, not the SAM or producer repository revision. The field alone does not say which kind of revision it holds. A SAM_Deploy installer build is recognisable by its stamp: version `...0+` on the producer and SAM assemblies, which SAM_UI's run manifest records in `application.sourceRevisionOf`. +A SAM_Deploy installer build stamps every assembly with the SAM_Deploy commit it was built from. So a producer run from an installed build, without overrides, writes that **SAM_Deploy build revision** into both fields, not the SAM or producer repository revision. The field alone does not say which kind of revision it holds. A SAM_Deploy installer build is recognisable by its stamp: the InformationalVersion `...0+` on the producer and SAM assemblies. SAM_UI's run manifest records it under `provenance.application`: +- the full stamp in `entryAssembly.informationalVersion` and in each `components[].informationalVersion`; +- the extracted revision in `sourceRevision`. + +`sourceRevisionOf` is explanatory text that says where `sourceRevision` comes from; it is not a revision or a stamp. To recover the actual source revisions, read the gitlinks that the SAM_Deploy revision pins: `git ls-tree SAM SAM_Tas SAM_OpenStudio` in `SAM-BIM/SAM_Deploy`. The SAM entry gives `samCommit`; SAM_Tas gives the Tas producer's `runnerCommit`, and SAM_OpenStudio the OpenStudio producer's.