# Fruix plan and package model notes

This document captures the current Fruix direction for package identity, base
artifacts, ports integration, installer/product milestones, and a few open
issues discovered during current work.

## Current package model

Fruix currently has three practical lanes.

### 1. FreeBSD base artifacts

These are the packages that represent FreeBSD base/system pieces:

- kernel
- world
- runtime slice
- bootloader slice
- headers / SDK slice

Today there are two forms.

#### A. Host-staged bootstrap/prototype packages

Examples:

- `freebsd-kernel`
- `freebsd-userland`
- `freebsd-runtime`
- `freebsd-bootloader`
- `freebsd-rc-scripts`
- `freebsd-networking`
- `freebsd-openssh`

These use `copy-build-system` and stage files from the current host system.
They are useful for bootstrap, recovery, and validating the Fruix store/system
model before all artifacts are built natively by Fruix.

#### B. Native Fruix-built base artifacts

Examples:

- `freebsd-native-kernel`
- `freebsd-native-world`
- `freebsd-native-runtime`
- `freebsd-native-bootloader`
- `freebsd-native-headers`

These use `freebsd-kernel-build-system` or `freebsd-world-build-system` and are
built from a declared `freebsd-base`, which itself points at a declared
`freebsd-source`.

This is the real long-term direction.

### 2. FreeBSD ports-style packages

Examples today:

- `freebsd-gmake`
- `freebsd-bash`
- `freebsd-autotools`
- `freebsd-openssl`
- `freebsd-zlib`
- `freebsd-nodejs`
- `freebsd-npm`
- `freebsd-ripgrep`
- `freebsd-tmux`
- `freebsd-neovim`

These are currently hand-written host-staged packages that mostly repackage
host-installed files from `/usr/local` into Fruix store objects.

They are useful as a bootstrap path, but they are still host-dependent and can
fail when the builder host does not have the exact expected files installed.

### 3. Other Fruix packages

Long term, packages that are not part of FreeBSD base or directly mirrored from
Ports should just become normal Fruix packages.

This should not be treated as a special "Guix compatibility" category forever.
The likely end state is simply:

- Fruix has its own package model
- packages may be inspired by, imported from, or rewritten from Guix packages
- but they become normal Fruix packages with Fruix-native metadata and build
  policy

## Naming direction

Current names reflect history:

- `freebsd-*` usually means host-staged/bootstrap/prototype packages
- `freebsd-native-*` means Fruix-native built base artifacts

That naming is likely backwards for the long term.

### Proposed future rename

When the native path is complete enough to become the canonical path:

- rename `freebsd-native-*` -> `freebsd-*`
- rename current host-staged/bootstrap packages to something like:
  - `freebsd-bootstrap-*`
  - or `freebsd-host-staged-*`

Recommendation:

- do **not** rename immediately while both paths are still actively in use
- first finish the native base path and make it the default serious workflow
- then do a compatibility transition with aliases/deprecation

That keeps user-facing names aligned with the intended product identity:

- `freebsd-*` should mean the real Fruix-managed thing
- bootstrap/prototype packages should say so explicitly

## Replacement plan already visible in the code

The current host-staged replacement order already suggests the intended
migration:

1. first-wave
   - `freebsd-kernel`
   - `freebsd-bootloader`
2. second-wave
   - `freebsd-runtime`
   - `freebsd-libc`
   - `freebsd-userland`
   - `freebsd-rc-scripts`
3. third-wave
   - `freebsd-networking`
   - `freebsd-openssh`
4. fourth-wave
   - `freebsd-kernel-headers`
   - `freebsd-clang-toolchain`
5. fifth-wave
   - development/user packages like:
     - `freebsd-gmake`
     - `freebsd-autotools`
     - `freebsd-openssl`
     - `freebsd-zlib`
     - `freebsd-nodejs`
     - `freebsd-ripgrep`
     - `freebsd-neovim`
     - etc.

The broad strategy should remain:

- bootstrap with host-staged packages
- move base/system pieces to native Fruix builds from declared source
- then replace brittle host-staged development/profile/package layers

## FreeBSD version/base story

Fruix already has the core abstractions needed to build arbitrary declared
FreeBSD bases:

- `freebsd-source`
- `freebsd-base`
- `freebsd-native-kernel-for`
- `freebsd-native-world-for`
- `freebsd-native-runtime-for`
- `freebsd-native-bootloader-for`
- `freebsd-native-headers-for`

That means Fruix can already express things like:

- FreeBSD 14.2 source
- a 14.2 base definition
- a 14.2 runtime/world/kernel artifact build

What is still missing is a polished user-facing workflow for this.

### Desired user-facing capability

Eventually Fruix should make this easy:

- build FreeBSD 14.2 runtime/world/kernel as first-class store objects
- assemble a runnable environment from those artifacts
- run tools like `ls` from that declared base/runtime cleanly

Today this is possible in principle through Scheme-level composition, but not
as a polished one-line CLI workflow.

## Ports strategy

A pragmatic path for Ports support is probably best.

### Phase 1: make them work first

Start with a simple path that fits Fruix reasonably well and actually works:

- repackage installed host Ports or pkg artifacts into Fruix store objects
- record provenance and host/source assumptions clearly
- keep them usable inside Fruix profiles and system closures

This is not perfect or fully reproducible, but it is practical.

### Phase 2: auto-package installed/pkg artifacts

Add a more automated import story for Ports-derived software, for example by:

- reading installed package metadata
- reading package file lists/manifests
- generating Fruix package definitions or manifests automatically

This would automate the current hand-written host-staged ports package pattern.

### Phase 3: source-built Ports under Fruix control

Longer term:

- build Ports in jails under Fruix executor policy
- import resulting artifacts into the Fruix store
- make them first-class Fruix package identities

This is a bigger project and should likely wait until the native base and
closure/image stories are more mature.

## Native build identity and executor model

These remain core product ideas.

### Native base builds should be first-class Fruix objects

Native build results should feel like real immutable Fruix identities:

- world
- kernel
- bootloader
- headers / SDK

Not just files in a temporary result area.

Desired model:

- staging/result roots are temporary build/result areas
- `/frx/store/...` remains the real immutable identity
- promoted native artifacts record:
  - executor
  - source identity
  - provenance
  - build policy

Status: **mostly implemented / in progress**.

Fruix already has native build result promotion and store objects, but the full
user-facing workflow still needs more polish.

### Executor model

The intended executor abstraction should cover the same declared build with
multiple execution backends:

- `host`
- `jail`
- `ssh-guest`
- `self-hosted`
- later maybe `remote-builder`

Desired mental model:

- same declared source
- same expected outputs
- same provenance shape
- executor is a policy choice, not an architecture fork

Status: **substantially in progress**.

We already have a real executor model and jail-backed execution is becoming a
first-class local primitive.

### Promotion step

Desired lifecycle:

1. build runs somewhere
2. result lands in a staging/result root
3. Fruix validates result shape and metadata
4. Fruix promotes successful results into store objects
5. system declarations consume promoted artifacts

Status: **mostly implemented / in progress**.

## Jails as the normal local isolation primitive

A strong Fruix-on-FreeBSD direction is to treat jails as the normal local build
and assembly isolation primitive.

Current progress:

- copy builds can run in jails
- native build commands can run in jails
- package profile materialization uses jailed merge policy
- system closure profile/development-profile/build-profile assembly uses jailed
  union-tree policy
- rootfs population helpers now run through the jailed helper path too
- image/installer/ISO assembly now records staged jail metadata and uses a
  dedicated assembly privileged policy surface
- install-time storage layout application is now executed as a rendered
  privileged helper script under that policy instead of many scattered host-side
  privileged calls
- remaining image resize and raw-file install attach/detach paths now also run
  through dedicated assembly privileged helper scripts, further shrinking the
  host-side privileged call surface
- network is disabled by default in these jailed paths
- union assembly mounts are now much smaller and omit host `/etc` and `devfs`
- direct block-device `system install` is now an explicit opt-in under the
  assembly policy instead of the default path

Next likely steps:

- keep pushing filesystem/image construction toward file-backed or jailed helper
  paths where practical
- decide whether any remaining assembly-time host assumptions should move behind
  an even narrower dedicated helper or runner boundary

## Runtime / development / build separation

Fruix should keep three layers conceptually distinct:

- runtime profile
- development profile
- build profile / build environment

The build layer should be:

- more sanitized
- more reproducible
- less interactive
- closer to the exact contract needed for buildworld/buildkernel and other
  reproducible builds

Status: **partially present**, but likely still needs clearer user-facing and
internal modeling.

## Installed systems as real Fruix nodes

Installed systems should increasingly feel like managed Fruix machines rather
than deployed images with helper scripts.

Desired node-local lifecycle:

- `fruix system build`
- `fruix system reconfigure`
- `fruix system upgrade`
- `fruix system build-base`
- `fruix system deploy`
- `status`
- `switch`
- `rollback`

Key requirement:

- no hidden dependence on a bootstrap checkout
- no hidden dependence on ambient host paths
- no hidden dependence on ad hoc bootstrap-only mechanics

Status: **partial / in progress**.

See also: `docs/plan_2.md` for the follow-on lifecycle plan focused on
node-local management, deploy hardening, and the later source/pin/upgrade path.

## Source / pin / update / lock workflow

Source provenance should not only be recorded after the fact; it should become
part of the operator workflow.

Desired lifecycle:

- source object
- pin/lock/update decision
- build result
- promoted base artifacts
- deployed system generation

This is very Fruix, but it does not have to be the first user-facing milestone.

Status: **mostly open**.

## Publication / substitutes / build once deploy many

Before scaling self-hosting too far, Fruix should have at least a minimal story
for:

- store export/import
- artifact publication
- fetch/substitute-like reuse
- trust/provenance verification

Goal:

- build once
- publish/store/export once
- deploy many

Status: **open**.

## Product/operator workflow

A good small canonical Fruix lifecycle is still a useful north star:

1. update/pin source inputs
2. build base artifacts
3. build system closure
4. publish/promote results
5. deploy/switch
6. rollback if needed

Fruix feels most like Fruix when the operator thinks in terms of:

- declared sources
- promoted base artifacts
- immutable system generations
- executor policy

and not in terms of raw `make buildworld` mechanics.

## fruix / fruix-bootstrap boundary

The contract should be:

### fruix-bootstrap

- foreign FreeBSD bring-up
- installer media
- host-side bootstrap/install/deploy helpers
- enough machinery to seed the first Fruix node onto disk

### fruix

- package definitions
- system definitions
- node CLI
- build/reconfigure/build-base/deploy logic
- future source/update/lock/publish/substitute logic

The installer should install a pinned Fruix revision, and after first boot the
node should move forward using Fruix itself, not the bootstrap repo.

Status: **needs to be made explicit**.

## Installer and pinned Fruix workflow

A near-term product milestone should remain:

- install a pinned Fruix onto a machine through a small TUI installer
- then have the booted node depend only on Fruix from there onward

Suggested phases:

### Phase A — establish source of truth

- define `fruix` vs `fruix-bootstrap`
- make installed systems point at pinned Fruix

### Phase B — guided installation

- TUI installer on the current installer ISO
- generate declaration + pin + install metadata
- boot into a usable Fruix node

### Phase C — operational usability

- ensure node-local lifecycle is complete enough
- add basic export/import or publish/fetch for artifacts

### Phase D — Fruix-native lifecycle

- source update/lock/compare
- later upgrade policy
- later substitutes/cache/trust refinement
- later deeper jail executor refinement

## Current open issues and recent lessons

### 1. Host-staged inputs are still brittle

Recent examples:

- unreadable host file inside `/etc/defaults` (`devfs.rules`) broke system build
  hashing until Fruix stopped staging the entire directory
- `freebsd-autotools` currently assumes host paths such as
  `/usr/local/share/autoconf2.72` exist

This reinforces the plan:

- host-staged packages are bootstrap tools
- they should not remain the canonical product identity forever

### 2. System build validation is still exposing host-assumption bugs

Recent validation has moved past one host-input bug only to reveal others.
This is useful and should continue:

- fix host-assumption bugs while bootstrap packages still exist
- keep pushing toward native-built base artifacts and less host dependence

### 3. Union-tree mount minimization is the right direction

Recent work reduced union/closure/profile assembly jail mounts to a much smaller
runtime surface.

That direction has now continued into:

- rootfs population helpers
- image/installer/ISO assembly under a dedicated privileged builder policy

The next refinement is to reduce the remaining privileged host-side surface
further, especially around final image/device manipulation.

## Summary

Short version:

- native base artifacts are the real Fruix direction
- current `freebsd-*` host-staged packages are bootstrap/prototype tools
- once the native path is complete enough, rename so the real Fruix-managed
  artifacts get the canonical `freebsd-*` names
- Ports should probably start with a simple "works first" integration path
  before aiming for full source-built ports under Fruix control
- packages imported or inspired from Guix should ultimately just become normal
  Fruix packages
- the product center of gravity should remain:
  - declared source identity
  - promoted immutable artifacts
  - FreeBSD-native execution/isolation
  - small opinionated operator workflows