fruix/docs/reports/phase14-native-boot-assets-freebsd.md

Phase 14.1: validated native FreeBSD boot assets without host-copied /boot

Date: 2026-04-03

Goal

The goal of Phase 14.1 was to stop relying on the host-staged freebsd-bootloader package for the validated boot path.

Phase 13 had already proved that Fruix could boot with:

• native kernel
• native world
• host-staged bootloader only

Phase 14.1 moved the remaining boot assets onto the native side as well.

Approach

Before introducing a cleaner package split, Fruix first reused the already-built native world output as the source of boot assets.

The Phase 14.1 operating-system template now uses:

• #:kernel freebsd-native-kernel
• #:bootloader freebsd-native-world
• #:base-packages (list freebsd-native-world)

That means the validated image now gets both:

• runtime files
• loader/boot assets

from the native /usr/src-built world output already staged in /frx/store.

This is slightly redundant at the model layer, but it is a clean way to prove the architectural point first:

• the boot path no longer needs host-copied /boot/... material

Additional QEMU harness fix

During repeated local validation, the existing QEMU PID1 harness was found to boot the raw store image directly from /frx/store.

That meant each local boot mutated the supposedly immutable image artifact and could leave the filesystem dirty for later runs.

To avoid that, tests/system/run-phase11-shepherd-pid1-qemu.sh now copies the built raw image to a temporary writable workdir file before launching QEMU:

• source image remains in /frx/store
• QEMU now writes to boot-disk.img in the workdir

This keeps the store image stable across repeated local boots.

New files

Added:

• tests/system/phase14-native-boot-pid1-operating-system.scm.in
• tests/system/run-phase14-native-boot-qemu.sh
• tests/system/run-phase14-native-boot-xcpng.sh

These wrappers reuse the proven PID1 boot harnesses and assert the new boundary:

• host_base_store_count=0
• native kernel present
• native world present
• boot assets come from native world

Validation

Local QEMU / UEFI / TCG

Passing run:

• PASS phase14-native-boot-qemu
• workdir: /tmp/phase14-1-qemu2-1775188371

Confirmed:

native_base_store_count=2
host_base_store_count=0
shepherd_pid=1
sshd_status=running
native_boot_assets=freebsd-native-world
native_base_boot=ok

Real XCP-ng VM

Passing run:

• PASS phase14-native-boot-xcpng
• workdir: /tmp/phase14-1-xcpng-1775188701

Confirmed:

vm_id=90490f2e-e8fc-4b7a-388e-5c26f0157289
vdi_id=0f1f90d3-48ca-4fa2-91d8-fc6339b95743
guest_ip=192.168.213.62
native_base_store_count=2
host_base_store_count=0
shepherd_pid=1
sshd_status=running
compat_prefix_shims=absent
guile_module_smoke=ok
native_boot_assets=freebsd-native-world
native_base_boot=ok

Result

Phase 14.1 is complete.

For the validated boot path, Fruix no longer depends on a host-copied freebsd-bootloader store item.

The currently validated native boot boundary is now:

• native kernel
• native world providing boot assets
• native world providing runtime
• Fruix runtime stores for Guile/Shepherd

That is already enough to say the image no longer relies on host-copied kernel/boot material.

Next step

Phase 14.2 should remove the remaining model redundancy by introducing a clearer native runtime slice, so the booted guest reaches ready state using an explicit native runtime output rather than reusing the broader native world output for both boot and runtime roles.