fruix/docs/reports/phase8-system-image-freebsd.md

Phase 8.2: Image generation integrated with the Fruix system definition layer

Date: 2026-04-01

Summary

This step moves bhyve-image generation out of a detached shell-only path and into the declarative Fruix FreeBSD system-composition module.

Added files:

• tests/system/materialize-phase8-system-image.scm
• tests/system/run-phase8-system-image.sh

Updated file:

• modules/fruix/system/freebsd.scm

Validation command

Run command:

METADATA_OUT=/tmp/phase8-system-image-metadata.txt \
./tests/system/run-phase8-system-image.sh

What changed in the system layer

The FreeBSD system module now exports image-oriented operations including:

• operating-system-image-spec
• materialize-bhyve-image

The integrated image path now:

1. starts from a declarative Fruix operating-system object
2. materializes the system closure under /frx/store
3. materializes a rootfs from that closure
4. stages the closure and its reference closure into rootfs/frx/store
5. builds:
   • esp.img
   • root.ufs
   • disk.img
6. stores the resulting image artifact as a content-addressed store item under /frx/store

Observed results

Observed metadata included:

• image_store_path=/frx/store/...-fruix-bhyve-image-fruix-freebsd
• disk_image=/frx/store/...-fruix-bhyve-image-fruix-freebsd/disk.img
• closure_path=/frx/store/...-fruix-system-fruix-freebsd
• raw_sha256=ac57d4c694ea3cf6b1bd24be48982090a6cfcfa301d052c1f903636a46f2d56e
• image_size_bytes=335578624
• store_item_count=13
• esp_fstype=msdosfs
• root_fstype=ufs
• run_current_system_target=/frx/store/...-fruix-system-fruix-freebsd
• boot_loader_target=/run/current-system/boot/loader
• rc_conf_target=/run/current-system/etc/rc.conf
• rc_script_target=/run/current-system/usr/local/etc/rc.d/fruix-shepherd
• image_generation_mode=declarative-system-layer

Important findings

• image generation is now a direct output of the Fruix FreeBSD system-definition layer rather than an external follow-up script around Phase 7 artifacts
• the resulting image artifact is itself stored under /frx/store, preserving the project’s store-centered composition story as the work moves from closures to VM images
• rerunning materialize-bhyve-image for the same operating-system description produced the same image store path, which is the current prototype proof that the declarative system object can drive image generation end-to-end
• the integrated image still passes the same static boot-structure checks used in Phase 8.1:
  • GPT layout
  • EFI partition contents
  • UFS root partition
  • serial-console loader configuration
  • run/current-system topology

Conclusion

Phase 8.2 is satisfied on the current FreeBSD prototype track:

• a single declarative Fruix operating-system description can now drive image generation end-to-end
• the result is a bhyve-oriented raw image artifact stored under /frx/store
• Phase 8 as a whole is now complete on the active FreeBSD amd64 prototype path