fruix/docs/reports/phase13-native-base-model-freebsd.md

Phase 13.1: model FreeBSD world and kernel as native Fruix build artifacts

Date: 2026-04-02

Goal

Phase 13 begins the Option B pivot from host-copy FreeBSD base packages toward builder-produced FreeBSD base artifacts in /frx/store.

This first subphase focused on the modeling and package/materialization layer:

• define native Fruix package objects for FreeBSD kernel and world outputs
• make their output identity depend on /usr/src and explicit build parameters
• teach the system metadata to distinguish host-staged base stores from native base stores

The purpose of this step was not yet to prove a full boot from those new outputs. It was to land the description and materialization model that Phase 13.2 can exercise concretely.

Implementation

1. Added native package definitions in modules/fruix/packages/freebsd.scm

New package objects:

• freebsd-native-kernel
• freebsd-native-world

New predicate:

• freebsd-native-build-package?

The native packages are intentionally FreeBSD-specific and currently parameterized with:

• source-root => /usr/src
• target => amd64
• target-arch => amd64
• kernconf => GENERIC
• make-flags =>
  • __MAKE_CONF=/dev/null
  • SRCCONF=/dev/null
  • SRC_ENV_CONF=/dev/null
  • MK_DEBUG_FILES=no
  • MK_TESTS=no

The first native world artifact also carries an explicit runtime-oriented prune list:

• usr/share/doc
• usr/share/examples
• usr/share/info
• usr/share/man
• usr/tests

That keeps the first native world target narrower and aligned with the current boot/runtime goal.

2. Added native build-system support in modules/fruix/system/freebsd.scm

materialize-freebsd-package now understands three classes of package build system:

• copy-build-system
• freebsd-world-build-system
• freebsd-kernel-build-system

For the native FreeBSD path, the materializer now records identity from:

• /usr/src
• explicit build parameters
• the selected kernel configuration

The /usr/src source identity is currently represented by an mtree-based tree digest using:

• type
• link
• size
• mode
• sha256digest

The kernel configuration is also hashed explicitly via its resolved KERNCONF path.

The code now has dedicated helpers for:

• native source identity
• native build-root identity
• buildworld/buildkernel stamp handling
• staged installworld/installkernel materialization
• writing native build metadata beside the resulting store outputs

3. Store-layout metadata now separates native and host-staged base stores

The closure metadata and CLI metadata now distinguish:

• host_base_stores
• native_base_stores
• fruix_runtime_stores

This is important for the architecture transition: a system can now say explicitly which parts of its FreeBSD base still come from transitional host-copy packages and which parts come from native /usr/src-driven artifacts.

4. Merged output trees now skip private dotfile metadata

The profile/tree merge logic now ignores private dotfile metadata in store outputs. This keeps internal build metadata files from leaking into the merged runtime tree when native base outputs start being consumed by real system closures.

Validation

Package/model load

Verified that the package/system modules still load after the native build-model additions, and that the new native package objects are present.

Observed output included:

freebsd-kernel-build-system
#t

for:

• freebsd-native-kernel build-system lookup
• freebsd-native-build-package? freebsd-native-world

Existing closure path regression check

To make sure the modeling work did not break the already validated host-copy path, re-ran:

• tests/system/run-phase7-system-closure.sh

Passing run:

• PASS phase7-system-closure
• workdir: /tmp/phase13-1-closure-1775164392

This confirmed that the existing FreeBSD system closure path still works while the new native base model is being introduced.

Assessment

Phase 13.1 is complete.

Fruix now has a real representation for native FreeBSD base artifacts in its package/materialization model rather than only the older host-copy package set. Just as importantly, the output identity story is no longer purely implicit: /usr/src, KERNCONF, and the selected build parameters are now part of the native artifact definition.

This is the necessary bridge into Phase 13.2, where those new package definitions need to be exercised to produce concrete kernel/world outputs in /frx/store.

Next recommended step

Proceed to Phase 13.2:

• build the first concrete freebsd-native-kernel and freebsd-native-world outputs from /usr/src
• inspect their staged contents in /frx/store
• document the exact split that the first native runtime target provides