162 lines
4.8 KiB
Markdown
162 lines
4.8 KiB
Markdown
# 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
|