fruix/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 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`

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 — Native build executor model introduced and validated across two executor policies

Fruix now has an explicit executor model for native base builds, and the same staged-result-plus-promotion flow is validated across both host-initiated guest execution and guest self-hosted execution.

Highlights:

- native base-build placement is now modeled as executor policy rather than as separate unrelated paths
- current executor kinds are:
  - `host`
  - `ssh-guest`
  - `self-hosted`
- guest result roots now carry explicit executor metadata instead of only an ad hoc executor string
- both validated executor paths now converge on the same Fruix-native flow:
  - stage mutable results under `/var/lib/fruix/native-builds/<run-id>`
  - emit promotion metadata with shared provenance/build-policy/artifact shape
  - promote immutable identities into `/frx/store/...`
- the `ssh-guest` path now also stages promotable native-build result roots rather than only temporary build directories under `/var/tmp`
- the host can now promote both executor paths through the same command:
  - `fruix native-build promote RESULT_ROOT`

Validation:

- `PASS phase20-host-initiated-native-build-xcpng`
- `PASS phase20-host-initiated-native-build-store-promotion-xcpng`
- `PASS phase20-self-hosted-native-build-xcpng`
- `PASS phase20-native-build-store-promotion-xcpng`

Reports:

- `docs/system-deployment-workflow.md`
- `docs/GUIX_DIFFERENCES.md`
- `docs/reports/phase20-development-environment-freebsd.md`
- `docs/reports/phase20-host-initiated-native-builds-freebsd.md`
- `docs/reports/phase20-self-hosted-native-builds-freebsd.md`
- `docs/reports/phase20-native-build-store-promotion-freebsd.md`
- `docs/reports/phase20-native-build-executor-model-freebsd.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:

- extend the shared executor/result model from validated `ssh-guest` and `self-hosted` paths to the `host` path as well
- decide how much of result import/promotion should remain host-side versus become a more integrated Fruix action
- determine whether executor selection should become part of a higher-level Fruix native-build/deployment command surface

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

It is now:

- how should Fruix expose executor selection, execution policy, and result promotion as one coherent operator-facing workflow?