# Phase 12.1: deployment provenance and diagnostic metadata for the current FreeBSD pipeline

Date: 2026-04-02

## Goal

Before starting native FreeBSD base builds from `/usr/src`, the current host-staged pipeline needed better provenance and easier diagnosis.

The specific targets for this subphase were:

- record which host-side FreeBSD base inputs were used for a generated closure/image
- make the closure itself carry that provenance
- distinguish host-staged FreeBSD base stores from Fruix-built runtime stores
- improve the validation harnesses so later failures are easier to investigate

## Implementation

### 1. Closure-level provenance files

`modules/fruix/system/freebsd.scm` now generates and stores two explicit metadata files in the system closure:

- `metadata/host-base-provenance.scm`
- `metadata/store-layout.scm`

These record:

- host `freebsd-version -kru`
- host `uname -a`
- `/usr/src` path
- `/usr/src` git revision/branch when available
- `newvers.sh` SHA256 as a stable source-tree identifier fallback
- exact host-staged FreeBSD base store paths used by the closure
- exact Fruix runtime store paths used by the closure
- selected init mode

This makes the generated closure self-describing instead of requiring ad hoc host inspection.

### 2. `fruix system` metadata became more explicit

`scripts/fruix.scm` now emits additional machine-readable metadata for both:

- `fruix system build`
- `fruix system image`

New fields include:

- `host_base_store_count`
- `host_base_stores`
- `fruix_runtime_store_count`
- `fruix_runtime_stores`
- `host_base_provenance_file`
- `store_layout_file`
- `host_freebsd_version`
- `host_uname`
- `usr_src_git_revision`
- `usr_src_git_branch`
- `usr_src_newvers_sha256`

This gives later harnesses and operators a clean way to identify exactly what kind of system/image was produced.

### 3. Validation harnesses now assert provenance availability

Updated harnesses:

- `tests/system/run-phase7-system-closure.sh`
- `tests/system/run-phase8-system-image.sh`

They now validate that provenance fields are present and that the generated closure contains the new metadata files.

### 4. Runtime-diagnostic capture was expanded in the VM harnesses

Updated harnesses:

- `tests/system/run-phase9-xcpng-boot.sh`
- `tests/system/run-phase11-shepherd-pid1-xcpng.sh`
- `tests/system/run-phase11-shepherd-pid1-qemu.sh`

These now collect additional guest-side diagnostic tails where available, including:

- `shepherd-bootstrap.out`
- `shepherd.log`
- recent `dmesg`

This does not change the boot architecture, but it improves post-failure visibility.

### 5. Host-side validation became more stable

The host-side closure/image harnesses now force:

- `GUILE_AUTO_COMPILE=0`

when invoking `fruix` under `sudo env`.

This avoided a misleading one-time validation drift caused by mixed compiled/source host state during back-to-back reproducibility checks immediately after source edits.

## Validation

### Phase 7 system closure

Passing run:

- `PASS phase7-system-closure`
- workdir: `/tmp/phase12-1b-closure-1775157039`

Key new metadata included:

```text
host_base_store_count=8
fruix_runtime_store_count=3
host_base_provenance_file=/frx/store/.../metadata/host-base-provenance.scm
store_layout_file=/frx/store/.../metadata/store-layout.scm
host_freebsd_version=15.0-STABLE
usr_src_newvers_sha256=d6f6e9ab352d3f6281e788c78a63ac311ab7a3a4bb5dfc0016ed0aadb90b5d9d
```

### Phase 8 system image

Passing run:

- `PASS phase8-system-image`
- workdir: `/tmp/phase12-1b-image-1775157039`

Key new metadata included:

```text
host_base_store_count=8
fruix_runtime_store_count=3
host_base_provenance_file=/frx/store/.../metadata/host-base-provenance.scm
store_layout_file=/frx/store/.../metadata/store-layout.scm
host_freebsd_version=15.0-STABLE
host_uname=FreeBSD fruixdev 15.0-STABLE ...
```

### Harness validation

Syntax-checked successfully:

- `tests/system/run-phase9-xcpng-boot.sh`
- `tests/system/run-phase11-shepherd-pid1-xcpng.sh`
- `tests/system/run-phase11-shepherd-pid1-qemu.sh`

## Assessment

This subphase does not replace the host-staged FreeBSD base model yet.  Instead, it makes that transitional model much easier to reason about.

Generated systems/images now answer the key questions directly:

- which FreeBSD base inputs came from the host?
- which runtime artifacts came from Fruix-built Guile/Shepherd outputs?
- what `/usr/src` identity was available at build time?
- where should an operator look first when the VM boot/runtime path misbehaves?

That is sufficient to support the next hardening step and then the later move toward native FreeBSD world/kernel artifacts in `/frx/store`.

## Next recommended step

Proceed to Phase 12.2:

- improve runtime/operator diagnostics inside the guest itself
- reduce the remaining noisy boot rough edges where the fixes are small and local
- keep the validated deployment path stable while preparing for native base-build work