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?