fruix-bootstrap/docs/PLAN_5.md

Plan 5: split Fruix bootstrap from canonical Fruix

This plan turns the boundary from docs/bootstrap.md into a concrete migration sequence.

The intended end state is:

• fruix-bootstrap prepares a plain FreeBSD host to act as a Fruix builder
• fruix is the canonical repo/channel for:
  • packages
  • systems
  • installers
  • deployment
  • node lifecycle
• a booted Fruix system no longer depends on fruix-bootstrap

Primary goal

Reach the point where a plain FreeBSD machine can:

1. use fruix-bootstrap to become a Fruix builder
2. use that builder to evaluate a pinned fruix checkout or revision
3. build a Fruix artifact from fruix
   • installer ISO
   • VM image
   • system closure
4. boot or install that artifact
5. continue operating using only fruix

Guiding rules

1. fruix is the only canonical home for long-lived Fruix logic.
2. fruix-bootstrap may wrap fruix, but should not fork it.
3. If a booted Fruix node should understand it, it belongs in fruix.
4. Bootstrap-only foreign-host glue belongs in fruix-bootstrap.
5. Prefer temporary wrappers over duplicated logic.

What should move to fruix first

These are the highest-priority items to live in fruix, because they define the product rather than the bootstrap path.

1. Package definitions

Move first:

• modules/fruix/packages/...

Why:

• package definitions are canonical Fruix content
• they are part of the future channel story
• booted Fruix systems should use these directly

2. FreeBSD system model and system artifact logic

Move early:

• modules/fruix/system/freebsd/model.scm
• modules/fruix/system/freebsd/source.scm
• modules/fruix/system/freebsd/build.scm
• modules/fruix/system/freebsd/render.scm
• modules/fruix/system/freebsd/media.scm
• modules/fruix/system/freebsd/utils.scm
• modules/fruix/system/freebsd/executor.scm
• the thin facade modules/fruix/system/freebsd.scm

Why:

• these define what a Fruix system is
• they define build/promotion/deploy behavior
• they must remain stable across bootstrap and post-bootstrap operation

3. Fruix CLI semantics

Move early:

• scripts/fruix.scm
• the long-lived CLI behavior it implements

Why:

• command semantics belong to Fruix, not bootstrap
• installed nodes should match the host CLI model

4. Installed-node lifecycle logic

Move early:

• node helper/module tree logic
• build
• build-base
• deploy
• reconfigure
• status
• switch
• rollback

Why:

• these are core Fruix product actions after first boot

5. Installer and future TUI installer

Move early and keep there:

• installer environment logic
• installer ISO logic
• future TUI installer application

Why:

• the installer is a Fruix product artifact
• Fruix should be able to rebuild its own installer

6. Metadata formats

Move early and treat as canonical:

• system generation metadata
• deployment metadata
• promoted native-build result metadata
• any future Fruix revision/pin metadata

Why:

• metadata is part of Fruix identity
• bootstrap should consume these formats, not redefine them

What can temporarily remain in fruix-bootstrap

These items are allowed to remain here while the split is in progress.

1. Bootstrap wrapper entrypoints

Examples:

• shell wrappers that locate the pinned fruix checkout
• shell wrappers that set GUILE_LOAD_PATH, GUILE_PREFIX, etc.
• entrypoints that invoke the real Fruix CLI from the foreign host

These should become thin wrappers around fruix, not alternate implementations.

2. Foreign-host dependency bring-up

Examples:

• locating or building Guile
• locating or building Shepherd support pieces
• preparing the host environment so the Fruix CLI can run

This is bootstrap territory.

3. Foreign-host validation harnesses

Examples:

• tests for plain-FreeBSD -> Fruix-builder bring-up
• tests that validate local bootstrap assumptions
• docs for first-time setup on vanilla FreeBSD

These stay useful here even after most Fruix logic moves out.

4. Temporary compatibility glue

Examples:

• wrappers that still point from bootstrap into ../fruix
• temporary environment shims needed while the split settles

These are acceptable if they are clearly transitional and do not redefine Fruix semantics.

What should not remain in fruix-bootstrap

Do not let this repo become a second home for:

• canonical package definitions
• canonical system semantics
• deployment semantics
• installer semantics
• long-lived metadata definitions
• installed-node behavior after first boot

If bootstrap needs those capabilities, it should invoke them from fruix.

Proposed migration sequence

Milestone 1: make fruix-bootstrap call fruix

Goal:

• this repo stops being the canonical implementation and becomes a launcher/bootstrap layer

Deliverables:

• define a pinned fruix checkout input for bootstrap
  • initially a local path such as ../fruix is acceptable
• bootstrap wrappers invoke Fruix modules/scripts from that checkout
• package/system logic is no longer edited here as the primary source of truth

Success signal:

• running the bootstrap entrypoint clearly uses ../fruix as the canonical Fruix source

Milestone 2: move canonical modules into fruix

Goal:

• all long-lived package/system logic lives in fruix

Deliverables:

• modules/fruix/packages/... live in fruix
• modules/fruix/system/... live in fruix
• scripts/fruix.scm lives in fruix
• this repo only wraps/invokes those files

Success signal:

• the same Fruix code is used both:
  • from a foreign host via bootstrap
  • from a booted Fruix node

Milestone 3: record a pinned Fruix identity in artifacts

Goal:

• built artifacts know which Fruix revision produced them

Deliverables:

• define minimal Fruix identity metadata, such as:
  • checkout path for local development
  • git commit when available
  • optional dirty/clean marker
• record that identity in:
  • image metadata
  • installer metadata
  • deployed generation metadata
  • installed-node metadata

Success signal:

• a system can answer: “which Fruix revision built me?”

Milestone 4: first self-contained Fruix install from bootstrap

Goal:

• prove that bootstrap is needed only to create the first Fruix artifact

Deliverables:

• from plain FreeBSD + bootstrap, build either:
  • a Fruix installer ISO, or
  • a Fruix VM image
• boot/install the resulting system
• validate that the running Fruix node can perform post-boot actions using fruix only:
  • fruix system build
  • fruix system build-base
  • fruix system reconfigure
  • fruix system deploy
  • fruix system rollback

Success signal:

• no runtime dependence on the bootstrap checkout is required after first boot

Milestone 5: build the first TUI installer in fruix

Goal:

• the user-facing installation experience is defined by Fruix itself

Deliverables:

• minimal text/TUI installer application in fruix
• built into the Fruix installer environment / installer ISO
• opinionated input surface, for example:
  • target disk
  • hostname
  • root SSH key or password
  • optional operator user
  • optional profile/template selection
• generated declaration and install metadata recorded by Fruix

Success signal:

• bootstrap builds the installer, but Fruix defines the installer behavior

First split-validation milestone

The first major proof should be this:

Bootstrap builds Fruix, then Fruix continues alone

Concretely:

1. start from plain FreeBSD
2. use fruix-bootstrap to create a Fruix builder
3. point it at pinned ../fruix
4. build a Fruix VM image or installer ISO from fruix
5. boot the resulting Fruix system
6. on the running Fruix system, perform at least:
   • fruix system build
   • fruix system reconfigure
   • fruix system rollback
7. verify none of those steps need the bootstrap checkout

This is the first meaningful architectural victory of the split.

Recommended immediate tasks

1. add a bootstrap configuration variable for the pinned Fruix checkout
   • initially defaulting to ../fruix
2. change bootstrap wrappers to load Fruix code from that checkout
3. stop treating this repo as the canonical edit location for Fruix modules
4. move package/system/CLI logic into fruix
5. add minimal Fruix revision metadata recording to built artifacts
6. then proceed to the Fruix-defined TUI installer

Temporary practical compromises

The split does not require perfection on day one.

Temporarily acceptable:

• local-path pinning to ../fruix
• wrapper scripts in bootstrap that export environment variables for Fruix
• some bootstrap-era host assumptions while the builder path stabilizes

Not acceptable long-term:

• duplicated package definitions in both repos
• duplicated system semantics in both repos
• booted Fruix nodes depending on bootstrap logic to keep operating

Open questions to resolve later

These do not block the boundary itself:

• exact Fruix channel/lock file format
• exact user-facing upgrade policy
• binary publication/substitution design
• local jail executor for native base builds

Those are important, but they should be built on top of the split rather than baked into the boundary prematurely.

Summary

The migration priority is:

1. make bootstrap a thin launcher for pinned fruix
2. move canonical logic into fruix
3. record Fruix identity in artifacts
4. prove a booted Fruix node can continue without bootstrap
5. build the TUI installer in fruix

If this plan is followed, fruix-bootstrap stays small and generic, while fruix becomes the real long-term system source of truth.