Skip to content

docs: installed-build samCommit/runnerCommit hold the SAM_Deploy revision (S06) #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaldengusiak merged 2 commits into from
Oct 20, 2026
Merged

docs: installed-build samCommit/runnerCommit hold the SAM_Deploy revision (S06) #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cb84fd9
docs: installed-build samCommit/runnerCommit hold the SAM_Deploy revi…
michaldengusiak Oct 20, 2026
ed7a878
docs: correct where the installer stamp is recorded in the run manife…
michaldengusiak Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/benchmark/S06-INSTALLED-PROVENANCE-PR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# 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: the InformationalVersion
`<year>.<quarter>.<run>.0+<revision>`. 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_Deploy revision> 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/`.
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
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".
- 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.

## Next step
Owner review and merge. Then the SAM_Validation `PROJECT_PROGRESS.md` closeout, a docs-only `[skip ci]` commit with the
merge SHA.
22 changes: 20 additions & 2 deletions docs/benchmark/SCHEMA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -43,6 +43,24 @@ 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 `+<revision>` 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: the InformationalVersion `<year>.<quarter>.<run>.0+<SAM_Deploy revision>` 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_Deploy revision> 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 |
Expand Down
Loading