# Phase 16.2: materialize declarative FreeBSD source inputs under Fruix control

Date: 2026-04-03

## Goal

Phase 16.2 moves from merely *describing* FreeBSD source inputs to actually *materializing* them under Fruix control.

The objective in this subphase was not yet to switch the native base build path away from ambient `/usr/src`.  Instead, it was to establish the missing fetch/materialization layer that later phases can consume.

That means Fruix now knows how to:

- fetch a Git-backed FreeBSD source declaration
- download and verify a `src.txz` declaration
- materialize the resulting source tree into `/frx/store`
- cache downloaded source state under `/frx/var/cache/fruix/freebsd-source`
- record stable source metadata for later native builds

## Implementation

### New source materializer in `modules/fruix/system/freebsd.scm`

Added:

- `materialize-freebsd-source`

and exported it for use by the Fruix CLI.

This materializer now supports all currently modeled source kinds:

- `local-tree`
- `git`
- `src-txz`

### Source artifacts are now first-class store objects

Materialized source outputs are now stored in paths of the form:

- `/frx/store/<hash>-freebsd-source-<name>`

Each source output contains:

- `tree/` or an auto-detected nested source root beneath it
- `.fruix-source`
- `.freebsd-source-info.scm`
- `.references`

The source info file records at least:

- declared source
- effective/resolved source
- materialized store path
- effective source root
- source tree SHA256
- cache path used to produce it

### Cache layout added under `/frx/var/cache/fruix/freebsd-source`

The new materializer caches downloaded source state under:

- `/frx/var/cache/fruix/freebsd-source/git/...`
- `/frx/var/cache/fruix/freebsd-source/archives/...`

Current behavior:

- Git sources use a cached bare repository
- `src.txz` sources use a cached archive file
- repeated materialization of the same resolved source identity reuses the same store output path

### Git source handling

Git materialization now:

- uses `https://git.FreeBSD.org/src.git`
- supports declarations by ref and/or commit
- fetches the selected ref/commit into a cached bare repository
- resolves refs to a concrete commit
- exports that commit into a store materialization

This means Fruix can now represent moving refs declaratively while still recording the exact resolved commit used for a given materialized source tree.

### `src.txz` source handling

`src.txz` materialization now:

- downloads the declared archive URL with `fetch`
- requires and verifies SHA256 for materialization
- extracts the archive into a store materialization
- records both the declared hash and the resulting source tree hash

For release archives, the canonical shorter URL form is now used in validation and documentation, for example:

- `https://download.freebsd.org/releases/amd64/15.0-RELEASE/src.txz`

rather than the longer doubled-architecture variant.

### Auto-detect the effective source root inside materialized trees

Git exports place the source tree directly at the materialized root.

Official `src.txz` archives instead unpack as:

- `usr/src/...`

inside the extracted directory tree.

To make this usable for later native builds, the materializer now auto-detects the effective source root and records it explicitly.  For example:

- Git materialization root:
  - `/frx/store/...-freebsd-source-stable15-git-ref/tree`
- `src.txz` materialization root:
  - `/frx/store/...-freebsd-source-release15-src-txz/tree/usr/src`

### New user-facing CLI command

Added a new user-facing command path in `scripts/fruix.scm`:

- `fruix source materialize SOURCE-FILE`

with options:

- `--source NAME`
- `--store DIR`
- `--cache DIR`
- `--help`

The command emits machine-readable metadata including:

- declared source fields
- materialized store path
- effective source root
- source tree hash
- cache path
- resolved Git commit if applicable
- verified archive hash if applicable

This gives Phase 16.2 an operator-usable entry point rather than limiting it to internal Scheme helpers.

### Validation tightened for archive-backed sources

`src-txz` source validation now requires:

- URL
- SHA256

This is the right reproducibility boundary for archive downloads.

## Guix comparison

This step continues to mirror the most useful Guix source boundary without copying it mechanically:

- Guix models source objects with `origin`
- Git-backed origins use `git-reference`

Fruix's source materializer now plays a similar role for FreeBSD-specific source inputs:

- local tree snapshots
- FreeBSD Git refs/commits
- official `src.txz` archives

The key preserved idea is the same: source identity should become an explicit, recorded, materialized input rather than ambient host state.

## New files

Added:

- `tests/system/phase16-git-freebsd-source.scm.in`
- `tests/system/phase16-txz-freebsd-source.scm.in`
- `tests/system/run-phase16-source-materialization.sh`

## Validation

Passing run:

- `PASS phase16-source-materialization`
- workdir:
  - `/tmp/fruix-phase16-source-materialization.QGuXi1`

### Git validation

Validated a Git declaration:

- name:
  - `stable15-git-ref`
- URL:
  - `https://git.FreeBSD.org/src.git`
- ref:
  - `stable/15`

Resolved/materialized result:

```text
materialized_source_store=/frx/store/dd1cc6b5ffa95b4d0c0f269522d5739da05e0f4ae81b1b314221d28b49d1981f-freebsd-source-stable15-git-ref
materialized_source_root=/frx/store/dd1cc6b5ffa95b4d0c0f269522d5739da05e0f4ae81b1b314221d28b49d1981f-freebsd-source-stable15-git-ref/tree
materialized_source_tree_sha256=d0d8e085d913a511d7fa1ba410040eb697a4cef800f354a092c65249ab3c4eb4
materialized_source_cache_path=/frx/var/cache/fruix/freebsd-source/git/9d432c47301c356bd2cede3400de40870e0b541b276888e34c68b882b9b894c7.git
materialized_source_commit=332708a606f6bf0841c1d4a74c0d067f5640fe89
```

The harness also confirmed:

- repeated materialization returned the same store path
- the cached Git repository exists
- the materialized tree contains:
  - `Makefile`
  - `sys/conf/newvers.sh`

### `src.txz` validation

Validated an archive declaration:

- name:
  - `release15-src-txz`
- URL:
  - `https://download.freebsd.org/releases/amd64/15.0-RELEASE/src.txz`
- SHA256:
  - `83c3e8157b6d7afcae57167fda75693bf1e5f581ca149a6ecb2d398b71bdfab0`

Resolved/materialized result:

```text
materialized_source_store=/frx/store/2e7857fb2c067b32acb482d048b8d1c2eeffdecd213108b3b0a4b2a87d56bc68-freebsd-source-release15-src-txz
materialized_source_root=/frx/store/2e7857fb2c067b32acb482d048b8d1c2eeffdecd213108b3b0a4b2a87d56bc68-freebsd-source-release15-src-txz/tree/usr/src
materialized_source_tree_sha256=afbe26f2213a19685fc2c3b875d26fab67e2cfcd605716cc66f669dabeaf7572
materialized_source_cache_path=/frx/var/cache/fruix/freebsd-source/archives/64ac7cc7d27435406995d63ef0b87ed0c485ce953ee8e9126127ca8f2a451d98-src.txz
materialized_source_sha256=83c3e8157b6d7afcae57167fda75693bf1e5f581ca149a6ecb2d398b71bdfab0
```

The harness also confirmed:

- repeated materialization returned the same store path
- the cached archive exists
- the effective materialized source root was detected as `tree/usr/src`
- that root contains:
  - `Makefile`
  - `sys/conf/newvers.sh`

### Regression check

Also re-ran:

- `PASS phase16-declarative-source-build`

This confirmed the new source materialization work did not break the earlier Phase 16.1 declarative source model path.

## Result

Phase 16.2 is complete.

Fruix can now fetch or materialize declared FreeBSD source inputs into `/frx/store` with cache-backed provenance under `/frx/var/cache/fruix/freebsd-source`.

The next step is now clear and narrower:

- teach native FreeBSD kernel/world/runtime builds to consume these materialized source artifacts instead of ambient `/usr/src`

That will be the real handoff from source acquisition to source-driven native base builds.