From 390bfb248fcce53887416ed05c146f6ad022e5e6 Mon Sep 17 00:00:00 2001 From: Steffen Beyer Date: Fri, 3 Apr 2026 10:44:01 +0200 Subject: [PATCH] Document FreeBSD base self-hosting decision --- docs/PROGRESS.md | 55 ++++++++ docs/PROG_SUMMARY.md | 9 +- .../phase15-self-hosting-decision-freebsd.md | 120 ++++++++++++++++++ 3 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 docs/reports/phase15-self-hosting-decision-freebsd.md diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index da60d8b..257a98b 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -3624,3 +3624,58 @@ Current assessment: - side-by-side native base outputs in `/frx/store` - rollback to the earlier closure without mutating it in place - the remaining Phase 15 work is to document the evidence-based decision on whether self-hosted base builds should be the next step, or whether host-built native base artifacts should remain the near-term path while reproducibility/source acquisition improve + +## 2026-04-03 — Phase 15.3: decided not to pursue self-hosted base builds yet + +Completed work: + +- wrote the Phase 15.3 report: + - `docs/reports/phase15-self-hosting-decision-freebsd.md` +- updated the high-level summary: + - `docs/PROG_SUMMARY.md` +- recorded an evidence-based decision about the next architecture step after Phases 13–15 + +Decision: + +- do **not** pursue self-hosted FreeBSD base builds as the next immediate milestone +- keep the near-term path on: + 1. host-built native FreeBSD base artifacts from `/usr/src` + 2. storage in `/frx/store` + 3. stronger declarative source-tree/version selection and provenance + 4. tighter reproducibility around source inputs and build parameters +- only revisit guest self-hosting after those pieces are stronger + +Evidence used for the decision: + +- Fruix already builds native FreeBSD base artifacts from `/usr/src` into `/frx/store` +- Fruix already validates a host-base-free boot/runtime path composed from: + - `freebsd-native-kernel` + - `freebsd-native-bootloader` + - `freebsd-native-runtime` +- that path already boots on: + - local QEMU/UEFI/TCG + - the approved real XCP-ng VM/VDI path +- the FreeBSD base is now an explicit declarative input through `freebsd-base` +- Fruix now supports side-by-side declared base versions and rollback-friendly redeploy +- the most important remaining reproducibility gap is now source-tree selection/acquisition, not host-copy boot/runtime assembly +- environment constraints still argue for caution before a self-hosting pivot: + - local bhyve remains blocked under Xen due to missing nested VT-x exposure + - real validation still reuses a single approved XCP-ng VM/VDI pair + - XCP-ng storage permissions still prevent creating fresh VDIs on demand + +Current assessment: + +- Phase 15.3 is complete +- Phase 15 is fully complete +- Fruix now has: + - a host-base-free native FreeBSD boot/runtime path in `/frx/store` + - an explicit declarative FreeBSD base model + - side-by-side base-version coexistence in `/frx/store` + - rollback-friendly redeploy across declared base versions + - a documented decision to continue with host-built native base artifacts for now rather than jumping immediately to guest self-hosting + +Next recommended step: + +1. focus the next phase on making FreeBSD source-tree selection/acquisition more declarative and reproducible +2. keep improving provenance and source-input identity around the now-working native base path +3. revisit self-hosted base builds only after the source/reproducibility boundary is substantially stronger diff --git a/docs/PROG_SUMMARY.md b/docs/PROG_SUMMARY.md index 9d73a9f..d6e87da 100644 --- a/docs/PROG_SUMMARY.md +++ b/docs/PROG_SUMMARY.md @@ -17,6 +17,12 @@ Completed milestones include: - `freebsd-init+rc.d-shepherd` - `shepherd-pid1` - **Native runtime cleanup**: removed the guest runtime’s dependence on `/tmp/*-validate-install` compatibility-prefix symlinks for Guile, guile-extra, and Shepherd. The guest now boots and runs Guile/Shepherd from the store-backed runtime layout without those temporary aliases. +- **Native FreeBSD base artifacts**: replaced the validated host-copy boot/runtime path with native `/usr/src`-built artifacts in `/frx/store` for: + - `freebsd-native-kernel` + - `freebsd-native-bootloader` + - `freebsd-native-runtime` +- **Declarative FreeBSD base model**: the FreeBSD base is now an explicit system input via `freebsd-base`, not just an ambient property of the builder host. +- **Base upgrade story**: Fruix can now keep distinct declared base versions side by side in `/frx/store` and roll forward / back between them through the normal system deployment flow. ## Major pain points now behind us @@ -30,6 +36,7 @@ Completed milestones include: ## Major pain points still ahead - **True store-native runtime artifacts**: some historical build/install prefixes are still embedded in binaries and metadata. They are no longer required at runtime, but the local Guile/guile-extra/Shepherd build/install flow should still be moved to a genuinely store-native prefix from the start. +- **Source reproducibility for the FreeBSD base**: the next major boundary is no longer host-copy boot/runtime assets; it is making source-tree selection/acquisition more reproducible and less tied to a single ambient `/usr/src`. - **Boot-path simplification**: Fruix now supports both the legacy `freebsd-init+rc.d-shepherd` path and the more Guix-like `shepherd-pid1` path. We still need to decide whether Shepherd PID 1 becomes the preferred/default architecture. - **Reduce transitional FreeBSD glue**: more of the current bootstrap/activation/runtime setup should become cleaner and less prototype-specific over time. - **Tooling and platform constraints**: local bhyve remains blocked by missing nested virtualization under Xen, and XO permissions still prevent creating/importing new VDIs; current validation must keep reusing the approved VM/VDI path. @@ -37,4 +44,4 @@ Completed milestones include: ## Bottom line -Fruix has crossed the most important threshold: it is no longer just a collection of isolated FreeBSD experiments. It can now build declarative FreeBSD system artifacts, boot them on the real target VM, reach the network, serve SSH, run Shepherd as PID 1, and operate from `/frx` without depending on temporary runtime-prefix shims. The biggest remaining work is no longer “can this boot?” but “how cleanly and natively can we make the runtime and boot architecture from here?” +Fruix has crossed the most important threshold: it is no longer just a collection of isolated FreeBSD experiments. It can now build declarative FreeBSD system artifacts, boot them on the real target VM, reach the network, serve SSH, run Shepherd as PID 1, operate from `/frx` without depending on temporary runtime-prefix shims, build native FreeBSD base artifacts into `/frx/store`, and roll forward / back between declared base versions. The biggest remaining work is no longer “can this boot?” but “how reproducible and source-declarative can we make the native FreeBSD base path from here?” diff --git a/docs/reports/phase15-self-hosting-decision-freebsd.md b/docs/reports/phase15-self-hosting-decision-freebsd.md new file mode 100644 index 0000000..98cfb55 --- /dev/null +++ b/docs/reports/phase15-self-hosting-decision-freebsd.md @@ -0,0 +1,120 @@ +# Phase 15.3: decision on self-hosted FreeBSD base builds + +Date: 2026-04-03 + +## Question + +After Phases 13 through 15, should Fruix immediately pursue self-hosted FreeBSD base builds inside a Fruix-managed guest, or should it continue using the host builder while tightening source/reproducibility boundaries? + +## Current evidence + +What is now already true: + +- Fruix builds native FreeBSD base artifacts from `/usr/src` into `/frx/store` +- Fruix has validated a host-base-free boot/runtime path composed from: + - `freebsd-native-kernel` + - `freebsd-native-bootloader` + - `freebsd-native-runtime` +- that path boots locally under QEMU/UEFI and on the approved real XCP-ng VM/VDI +- the FreeBSD base is now an explicit declarative system input through `freebsd-base` +- Fruix can keep distinct declared base versions side by side in `/frx/store` +- Fruix can roll forward to a candidate base declaration and roll back to the earlier closure without mutating it in place + +So the main Guix-inspired value proposition is already present at the system-deployment layer: + +- declarative system descriptions +- content-addressed outputs +- side-by-side versions +- rollback-friendly closures + +## What is still not strong enough for self-hosting to be the best next step + +### 1. Source acquisition is still too host-local + +The native base path still depends on the host's local `/usr/src` tree as the source of truth. + +That means the next reproducibility win is not "build inside the guest" first; it is "make the source tree selection/acquisition more explicit and reproducible" first. + +### 2. The host-built path is already validated and useful + +The current host-built native base flow is not hypothetical anymore. It has already proven: + +- native artifacts in `/frx/store` +- host-base-free boot/runtime composition +- side-by-side closures +- rollback behavior + +That makes it the productive path to continue refining. + +### 3. Self-hosting would currently mix several problems at once + +Jumping to guest self-hosting now would combine: + +- source acquisition/reproducibility questions +- toolchain/profile maturity questions +- build-environment modeling questions +- large build-resource/runtime questions inside the guest +- deployment/debugging questions + +That would make failure analysis worse just after the project finally obtained a clean validated deployment path. + +### 4. Platform constraints still argue for caution + +Current operator/environment constraints still matter: + +- local bhyve remains blocked under Xen due to missing nested VT-x exposure +- real VM validation still reuses a single approved XCP-ng VM/VDI pair +- XCP-ng storage permissions still prevent creating fresh VDIs on demand + +Those constraints do not block the current host-built native-base path, but they do make an early self-hosting pivot less attractive. + +## Decision + +**Decision:** do **not** pursue self-hosted FreeBSD base builds as the next immediate milestone. + +The near-term direction should remain: + +1. continue building native FreeBSD base artifacts on the host +2. keep storing them in `/frx/store` +3. improve declarative source-tree/version selection and provenance +4. tighten reproducibility around source inputs and build parameters +5. only revisit self-hosting after those pieces are stronger + +## Why this is the right decision now + +This preserves the important architectural win already achieved: + +- Fruix, not ad hoc host copying, now defines the deployed FreeBSD base through declared store artifacts + +It also follows the same spirit as Guix generation/rollback semantics: the crucial user-facing property is not where the build happened first, but that the result is declarative, content-addressed, side-by-side, and rollback-friendly. + +At this point Fruix already has those properties for the FreeBSD base path. + +## Conditions for revisiting self-hosting later + +Self-hosted base builds should be reconsidered only after at least most of the following are true: + +- Fruix can select or acquire distinct FreeBSD source trees more reproducibly than a single ambient `/usr/src` +- the native development/toolchain side is modeled cleanly enough for a Fruix-managed build environment +- operator/deployment tooling can handle larger iterative validation loops without excessive friction +- there is a concrete benefit to guest-side base builds beyond what host-built store artifacts already provide + +## Recommended next focus after Phase 15 + +The next work should likely focus on improving the declared source/reproducibility boundary around the now-working native base path, rather than on guest self-hosting. + +A good next phase would be centered on things like: + +- declarative source-tree selection/acquisition for the FreeBSD base +- stronger provenance for declared source inputs +- cleaner rebuilds across multiple source trees or revisions +- continued refinement of deployment/generation management around the existing store-based base artifacts + +## Result + +Phase 15.3 is complete. + +The project now has an evidence-based decision: + +- **near-term path:** host-built native FreeBSD base artifacts in `/frx/store` +- **not yet:** self-hosted FreeBSD base builds inside the Fruix guest