fruix-bootstrap/docs/PROGRESS.md

Progress

This file is now intentionally compact.

Detailed chronological history through Phase 18.2 has been archived at:

• docs/reports/progress-log-through-phase18-2-freebsd.md

For a broader narrative summary, see:

• docs/PROG_SUMMARY.md

Current status

Fruix currently has:

• declarative system modeling on FreeBSD
• content-addressed system closures under /frx/store
• native FreeBSD base artifacts in /frx/store
• declarative FreeBSD source objects and source materialization
• source-driven native base builds from materialized source snapshots
• side-by-side source revisions and boot validation
• a host-driven non-interactive install path:
  • fruix system install
• a bootable Fruix-managed installer environment:
  • fruix system installer
• a bootable Fruix-managed installer ISO:
  • fruix system installer-iso
• an explicit installed-system generation layout under:
  • /var/lib/fruix/system
• explicit installed-system retention roots under:
  • /frx/var/fruix/gcroots
• a validated installed-system generation switch/rollback workflow via:
  • fruix system status
  • fruix system switch
  • fruix system rollback
• a validated separate in-system development environment overlay via:
  • /run/current-system/development-profile
  • /run/current-development
  • /usr/local/bin/fruix-development-environment
• a validated separate in-system build environment overlay via:
  • /run/current-system/build-profile
  • /run/current-build
  • /usr/local/bin/fruix-build-environment
  • /usr/include -> /run/current-system/build-profile/usr/include
  • /usr/share/mk -> /run/current-system/build-profile/usr/share/mk
• a validated host-initiated native base-build path inside a Fruix-managed guest via:
  • real XCP-ng boot of a development-enabled Fruix system
  • in-guest buildworld / buildkernel
  • staged installworld / distribution / installkernel
• a validated controlled guest self-hosted native base-build prototype via:
  • /usr/local/bin/fruix-self-hosted-native-build
  • result roots under /var/lib/fruix/native-builds
  • in-guest source recovery from current-system metadata
• a validated promotion path that turns native-build result roots into first-class Fruix store objects via:
  • fruix native-build promote
  • /frx/store/...-fruix-native-world-...
  • /frx/store/...-fruix-native-kernel-...
  • /frx/store/...-fruix-native-headers-...
  • /frx/store/...-fruix-native-bootloader-...
  • /frx/store/...-fruix-native-build-result-...
• an explicit executor model for native base builds with current executor kinds:
  • host
  • ssh-guest
  • self-hosted
• end-to-end validated staged-result-plus-promotion paths for executor policies:
  • ssh-guest
  • self-hosted
• system declarations that can now consume a promoted native-build result bundle directly via:
  • promoted-native-build-result
  • operating-system-from-promoted-native-build-result
• a real XCP-ng boot validation of a system materialized from a promoted native-build result identity
• installed systems that now carry their own canonical declaration inputs and bundled Fruix node CLI sources
• a real XCP-ng validation of in-node:
  • fruix system build
  • fruix system build-base
  • fruix system reconfigure
  • fruix system rollback
• local installed-node promotion of native-base results into the node's own /frx/store
• a real XCP-ng validation of host-driven:
  • fruix system deploy onto an installed Fruix node with reboot and rollback preserved

Validated boot modes still are:

• freebsd-init+rc.d-shepherd
• shepherd-pid1

The validated Phase 18 installation work currently uses:

• freebsd-init+rc.d-shepherd

Latest completed achievement

2026-04-06 — Fruix now has a real host-driven deploy command for installed nodes

Fruix now supports a validated host-driven:

• fruix system deploy

workflow on the approved real XCP-ng path.

Highlights:

• the main Fruix CLI now supports deploying either:
  • a declaration file, or
  • an already built /frx/store/...-fruix-system-... closure onto a remote Fruix node over SSH
• deploy now:
  • builds or resolves the selected closure locally
  • computes the recursive store closure from .references
  • transfers only missing store items to the target
  • runs remote fruix system switch
  • can reboot the target and wait for SSH to return
• the installed helper surface was bumped again and now also accepts:
  • fruix system deploy ...
• a real bug in the shared store-hash helper was fixed while validating this path:
  • sha256-string now uses a fresh temporary path rather than a fixed /tmp/fruix-system-hash.txt

Validation:

• PASS postphase20-system-deploy-xcpng

Reports:

• docs/reports/postphase20-system-deploy-freebsd.md
• docs/system-deployment-workflow.md
• docs/GUIX_DIFFERENCES.md

2026-04-06 — Installed Fruix nodes can now build and promote native base results locally

Installed Fruix nodes now support a validated local:

• fruix system build-base

workflow on the approved real XCP-ng path.

Highlights:

• the installed helper at /usr/local/bin/fruix now supports:
  • fruix system build-base [--jobs COUNT] [--store DIR]
• installed nodes can now:
  • run the strict build-profile-based native base-build helper locally
  • stage the mutable result under /var/lib/fruix/native-builds/...
  • promote that result into immutable node-local /frx/store/... objects
• operating-system-from-promoted-native-build-result now accepts:
  • #:build-packages so build-capable installed nodes can be declared directly from promoted native-base identities
• this validation keeps the current running system generation unchanged while producing a new promoted native-base identity for later declaration/deployment use

Validation:

• PASS postphase20-installed-node-build-base-xcpng

Reports:

• docs/reports/postphase20-installed-node-build-base-freebsd.md
• docs/system-deployment-workflow.md
• docs/GUIX_DIFFERENCES.md

2026-04-06 — Fruix now separates interactive development from strict native base-build environment

Fruix now has a more explicit three-layer model for build-capable FreeBSD systems:

• runtime profile
• development profile
• build profile

Highlights:

• <operating-system> now supports separate build-packages
• system closures can now materialize both:
  • development-profile
  • build-profile
• build-capable systems now expose:
  • /run/current-system/build-profile
  • /run/current-build
  • /usr/local/bin/fruix-build-environment
• canonical compatibility links for native base builds now come from the build profile:
  • /usr/include -> /run/current-system/build-profile/usr/include
  • /usr/share/mk -> /run/current-system/build-profile/usr/share/mk
• the new build helper intentionally clears development-shell variables such as:
  • MAKEFLAGS
  • CPPFLAGS
  • CFLAGS
  • CXXFLAGS
  • LDFLAGS
• the self-hosted native-build helper now uses this stricter build-helper contract instead of manually reconstructing that sanitization ad hoc
• promotion metadata for native-build results now records build-profile explicitly

Validation:

• PASS phase20-development-environment-xcpng
• PASS phase20-self-hosted-native-build-xcpng
• PASS phase20-native-build-store-promotion-xcpng
• PASS phase20-host-initiated-native-build-xcpng
• PASS phase20-host-initiated-native-build-store-promotion-xcpng

Representative validated metadata included:

• build_profile_guest=/run/current-system/build-profile
• build_profile=/run/current-system/build-profile
• helper_version=5
• executor_version=5

Report:

• docs/reports/postphase20-build-profile-separation-freebsd.md
• docs/system-deployment-workflow.md
• docs/GUIX_DIFFERENCES.md

2026-04-06 — Installed systems can now build and reconfigure themselves from local declaration state

Fruix-installed systems are now meaningfully closer to real Fruix nodes.

Highlights:

• system closures now carry canonical declaration metadata in:
  • metadata/system-declaration.scm
  • metadata/system-declaration-info.scm
  • metadata/system-declaration-system
• system closures now also carry bundled Fruix node CLI sources in:
  • share/fruix/node/scripts/fruix.scm
  • share/fruix/node/modules/...
  • share/fruix/node/guix/guix/build/utils.scm
• the installed helper at /usr/local/bin/fruix now supports:
  • fruix system build
  • fruix system reconfigure
  • fruix system status
  • fruix system switch
  • fruix system rollback
• no-argument in-node build and reconfigure now use the node's own embedded declaration inputs
• in-node Fruix builds now reuse the installed Guile/Shepherd runtime stores already referenced by the system instead of assuming host-only /tmp/... build prefixes
• the real XCP-ng validation proved the full installed-node flow:
  • boot current system
  • build from local declaration state
  • build a candidate declaration on-node
  • reconfigure into that candidate generation
  • reboot into the candidate generation
  • rollback
  • reboot back into the original generation

Validation:

• PASS postphase20-installed-node-build-reconfigure-xcpng

Reports:

• docs/reports/postphase20-promoted-native-base-declarations-freebsd.md
• docs/reports/postphase20-installed-node-management-freebsd.md
• docs/system-deployment-workflow.md
• docs/GUIX_DIFFERENCES.md

Recent major milestones

• 1d00907 — Add Fruix bootable installer environment
• 2517710 — Add non-interactive Fruix installation flow
• 02a02e3 — Document Fruix FreeBSD source policy
• 865012e — Boot Fruix from distinct FreeBSD source revisions
• 8150508 — Validate side-by-side FreeBSD source revisions
• 5cbf5b9 — Build native bases from materialized FreeBSD sources

Active constraints

• local bhyve remains blocked under Xen due to lack of nested VT-x exposure
• XO self-service creation is still not usable with the current token
• real XCP-ng validation must continue to use:
  • VM 90490f2e-e8fc-4b7a-388e-5c26f0157289
  • approved A/B VDIs:
    • 0f1f90d3-48ca-4fa2-91d8-fc6339b95743
    • 7061d761-3639-4bec-87f7-2ba1af924eaa
• local QEMU/TCG validation keeps conservative default SMP settings; QEMU_SMP remains overrideable

Next step

docs/PLAN_4.md currently ends at Phase 20.3, and that milestone sequence is now complete.

The next practical follow-up is now clearer:

• grow the installed-node command surface from validated build/build-base/deploy/reconfigure/rollback toward:
  • upgrade
• decide how executor policy, native-base promotion, and installed-node reconfiguration should compose in one operator-facing workflow
• turn the current local self-hosted build-base path into a cleaner first-class local executor story, with jail now the most promising next candidate
• determine how much of native-build request/promotion should remain explicit versus being absorbed into higher-level Fruix node actions

The immediate architectural direction is no longer just “can guest self-hosting work?”

It is now:

• how should Fruix expose real managed-node behavior across declaration inputs, native-base results, generation switching, and deployment actions?