Validate side-by-side FreeBSD source revisions

2026-04-03 19:44:26 +02:00
parent 5cbf5b90ed
commit 8150508676
6 changed files with 763 additions and 1 deletions
--- a/docs/reports/phase17-side-by-side-source-revisions-freebsd.md
+++ b/docs/reports/phase17-side-by-side-source-revisions-freebsd.md
@@ -0,0 +1,141 @@
+# Phase 17.1: side-by-side FreeBSD source revisions in `/frx/store`
+
+Date: 2026-04-03
+
+## Goal
+
+Phase 17.1 verifies that Fruix can treat FreeBSD source revisions the same way it already treats other declarative inputs:
+
+- as explicit inputs,
+- as side-by-side store objects,
+- and as drivers of distinct native base outputs.
+
+The key question was no longer whether Fruix could materialize a source tree at all. Phase 16 already established that.
+
+The question here was stricter:
+
+- can two distinct FreeBSD source inputs coexist,
+- can they both drive native base builds,
+- and can they do so even when the user-facing base version label is the same?
+
+That last point matters because it proves the result is driven by source identity rather than by an arbitrary version-string rename.
+
+## Implementation
+
+Added two Phase 17 operating-system templates:
+
+- `tests/system/phase17-git-source-operating-system.scm.in`
+- `tests/system/phase17-txz-source-operating-system.scm.in`
+
+These model two distinct source identities:
+
+- a Git source with both:
+  - ref: `stable/15`
+  - pinned commit: `332708a606f6bf0841c1d4a74c0d067f5640fe89`
+- an official release archive source:
+  - `https://download.freebsd.org/releases/amd64/15.0-RELEASE/src.txz`
+  - sha256:
+    - `83c3e8157b6d7afcae57167fda75693bf1e5f581ca149a6ecb2d398b71bdfab0`
+
+Added validation harness:
+
+- `tests/system/run-phase17-source-coexistence.sh`
+
+## Validation design
+
+The harness builds three times:
+
+1. Git-backed system build
+2. `src.txz`-backed system build
+3. Git-backed rebuild
+
+The Git and `src.txz` systems intentionally share the same:
+
+- base name:
+  - `source-side-by-side`
+- base version label:
+  - `15.0-source-side-by-side`
+
+while differing only in their declared source/release metadata.
+
+This means distinct outputs cannot be explained away by a version-label rename.
+
+The harness verifies:
+
+- Git rebuild stability when the Git source is pinned by commit
+- distinct closure paths for Git vs `src.txz`
+- distinct materialized source store paths
+- distinct native kernel/bootloader/runtime store paths
+- zero host-base stores in both builds
+- one materialized source store in each closure
+- correct closure metadata for:
+  - declared source
+  - materialized source
+  - materialized source store count/path
+- correct native build info for:
+  - kernel
+  - runtime
+- effective source roots:
+  - Git: `.../tree`
+  - `src.txz`: `.../tree/usr/src`
+- the continued separation between:
+  - declared transitional `source-root`
+  - actual materialized source root used by the native build
+
+## Results
+
+Passing validation:
+
+- `PASS phase17-source-coexistence`
+
+Observed side-by-side closures:
+
+```text
+git_closure=/frx/store/d6cbcc76f57fa9c392a80fe20e7499f7a837aab4fb96ea056e624cde95bc70c8-fruix-system-fruix-freebsd
+git_closure_rebuild=/frx/store/d6cbcc76f57fa9c392a80fe20e7499f7a837aab4fb96ea056e624cde95bc70c8-fruix-system-fruix-freebsd
+txz_closure=/frx/store/02268e19930facb32e12b6ec191f2e5704d1e81033baf3637a889ad15924ff88-fruix-system-fruix-freebsd
+base_version_label=15.0-source-side-by-side
+same_base_version_label_distinct_sources=ok
+```
+
+Observed source identities:
+
+```text
+git_source_kind=git
+git_source_ref=stable/15
+git_source_commit=332708a606f6bf0841c1d4a74c0d067f5640fe89
+git_materialized_source_store=/frx/store/c9928605fa906b90a600dafeebe5005dd18ad3b8e62b7111d9d13ad60ee56490-freebsd-source-stable15-side-a
+git_materialized_source_root=/frx/store/c9928605fa906b90a600dafeebe5005dd18ad3b8e62b7111d9d13ad60ee56490-freebsd-source-stable15-side-a/tree
+
+txz_source_kind=src-txz
+txz_source_url=https://download.freebsd.org/releases/amd64/15.0-RELEASE/src.txz
+txz_source_sha256=83c3e8157b6d7afcae57167fda75693bf1e5f581ca149a6ecb2d398b71bdfab0
+txz_materialized_source_store=/frx/store/5eaeff5c6c55a95b6531d9cf2e1824cd4368d81c614608426bee1a5d2a664dc5-freebsd-source-release15-side-b
+txz_materialized_source_root=/frx/store/5eaeff5c6c55a95b6531d9cf2e1824cd4368d81c614608426bee1a5d2a664dc5-freebsd-source-release15-side-b/tree/usr/src
+```
+
+Observed native base outputs for the same version label:
+
+```text
+git_native_base_stores=/frx/store/4b615431ec25c500a3bf0ed70ce39e2ebf4f584994a53756268e4383962bc86b-freebsd-native-kernel-15.0-source-side-by-side,/frx/store/3a5a0b2b88b4757cf9cb4e3040f992d8fdb5bd9a7f1b186da983854cd95392c5-freebsd-native-bootloader-15.0-source-side-by-side,/frx/store/177f78e7f2932986a380187eb09dc34cc2cd9a146c5ed1fe1f00aae15ddf78d9-freebsd-native-runtime-15.0-source-side-by-side
+
+txz_native_base_stores=/frx/store/0c5141a86fa9c1974102f2bd8766eb3ab787b97dcccb71f17d80aefbe8ed4f3e-freebsd-native-kernel-15.0-source-side-by-side,/frx/store/3de6592f50a735d8461662cb393fc413325ce24ded45d4bb494525896f8cb5eb-freebsd-native-bootloader-15.0-source-side-by-side,/frx/store/46d256305198ee7d745b9032c71085aba97d55fdf7a0d3d2017dd4455173205d-freebsd-native-runtime-15.0-source-side-by-side
+```
+
+Those outputs differ only by content-address prefix, not by the human-readable version suffix. That is exactly the property Phase 17.1 needed.
+
+## Key observation
+
+A moving Git ref by itself is not a reproducibility boundary. For the reproducible half of this validation, the Git source was pinned by commit while still retaining its `stable/15` ref metadata.
+
+This fits the intended Fruix model:
+
+- refs are useful selectors,
+- commits are the stable Git identity boundary,
+- archive SHA256 values are the stable `src.txz` identity boundary.
+
+## Result
+
+Phase 17.1 is complete.
+
+Fruix can now hold at least two distinct FreeBSD source revisions side by side in `/frx/store` and build distinct native FreeBSD base artifacts from them, even when the visible base version label is kept the same.