fruix/docs/reports/phase19-deployment-workflow-freebsd.md

Phase 19.1: canonical Fruix deployment workflow on FreeBSD

Date: 2026-04-04

Goal

Phase 19.1 is about turning Fruix's already-validated closure/image/install behavior into a clear operator-facing deployment story.

The verification target here is documentation clarity rather than a new low-level boot primitive.

The repo needed a single coherent explanation of how Fruix expects operators to:

• build a system closure
• materialize a rootfs or image
• install directly to an image or block device
• use the installer image and installer ISO paths
• roll forward to a candidate declaration
• roll back to an earlier declaration

Result

Phase 19.1 is complete.

The repository now documents a first-class Fruix deployment workflow in:

• docs/system-deployment-workflow.md

That document defines the current canonical command surface and explains how the already-existing validated paths fit together operationally.

What was documented

Canonical frontend

The documented user-facing frontend is now explicitly:

• ./bin/fruix system ...

This includes the currently supported deployment-oriented actions:

• build
• rootfs
• image
• install
• installer
• installer-iso

Canonical deployment model

The workflow document now defines Fruix's current deployment model as:

1. declare a system in Scheme
2. build the system closure in /frx/store
3. materialize the artifact appropriate to the target environment
4. boot or install that artifact
5. treat the resulting closure path and emitted provenance metadata as the deployment identity

Roll-forward and rollback semantics

The document makes explicit an important current design point:

• Fruix rollback is already real at the declaration/closure/deployment layer
• but it is not yet a first-class installed-system generation switch operation

So the documented rollback workflow today is:

• retain the earlier declaration
• rebuild or rematerialize it
• redeploy or reboot that earlier closure again

That matches what Fruix has already validated in earlier phases.

Platform-specific installer target-device detail

The workflow document also records the now-important target-device distinctions between validated environments:

• installer disk-image path under QEMU:
  • /dev/vtbd1
• installer ISO path under QEMU:
  • /dev/vtbd0
• installer ISO path under XCP-ng:
  • /dev/ada0

That makes the deployment story less harness-specific and more operator-explicit.

Why this satisfies Phase 19.1

Before this phase, Fruix already had the machinery for:

• building declarative system closures
• generating bootable images
• performing direct non-interactive installation
• booting a Fruix installer environment
• booting and installing from a Fruix installer ISO
• rollback-friendly redeploy of earlier declarations

What was missing was a repo-level explanation that unified those into a single operator workflow.

The new document closes that gap by connecting:

• Phase 10 command-surface work
• Phase 15 redeploy/rollback validation
• Phase 18 install and installer-media validation
• and the recent QEMU + XCP-ng installer ISO validation

Current boundaries now made explicit

The documentation intentionally records what Fruix has not solved yet:

• installed-system generation links
• explicit rollback targets and generation metadata
• a first-class switch or reconfigure command
• installed-system rollback as an in-place operator workflow
• GC-root management for installed systems

Those are left for later Phase 19 steps rather than being blurred into the current deployment story.

References to existing validation

The documented workflow rests on already-passing validation paths, including:

• PASS phase18-system-install
• PASS phase18-installer-environment
• PASS phase18-installer-iso
• PASS phase18-installer-iso-xcpng
• PASS phase15-base-rollback-qemu
• PASS phase15-base-rollback-xcpng

Conclusion

Phase 19.1 is now complete.

Fruix has a documented canonical deployment workflow for FreeBSD covering:

• build
• image generation
• direct install
• installer-media install
• roll-forward
• rollback by redeploying an earlier declaration

The next step is Phase 19.2:

• model installed-system generations, rollback targets, and deployment roots more explicitly.