fruix/docs/reports/phase17-side-by-side-source-revisions-freebsd.md

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:

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:

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:

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.