fruix/docs/reports/phase12-provenance-diagnostics-freebsd.md

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:

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:

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