Clarify transitional FreeBSD base package boundary

docs/PROGRESS.md

@@ -2810,3 +2810,67 @@ Next recommended step:
 1. complete Phase 12.3 by making the host-staged FreeBSD base boundary explicit in the package/model layer and docs
 2. document the first intended replacement order for native world/kernel work
 3. then begin Phase 13 with a clearer transitional boundary
+
+## 2026-04-02 — Phase 12.3: made the host-staged FreeBSD base boundary explicit
+
+Completed work:
+
+- wrote the Phase 12.3 report:
+  - `docs/reports/phase12-host-staged-base-boundary-freebsd.md`
+- refined `modules/fruix/packages/freebsd.scm` so the transitional host-copy base boundary is now explicit in the package/model layer
+- added and exported named transitional package sets:
+  - `%freebsd-host-staged-all-packages`
+  - `%freebsd-host-staged-core-packages`
+  - `%freebsd-host-staged-development-profile-packages`
+  - `%freebsd-host-staged-system-packages`
+- added and exported:
+  - `freebsd-host-staged-package?`
+  - `%freebsd-host-staged-replacement-order`
+- preserved compatibility aliases so existing callers still work:
+  - `%freebsd-core-packages`
+  - `%freebsd-development-profile-packages`
+  - `%freebsd-system-packages`
+- encoded the intended first replacement order for native base-build work directly in the package layer:
+  1. `freebsd-kernel`, `freebsd-bootloader`
+  2. `freebsd-runtime`, `freebsd-libc`, `freebsd-userland`, `freebsd-rc-scripts`
+  3. `freebsd-networking`, `freebsd-openssh`
+  4. `freebsd-kernel-headers`, `freebsd-clang-toolchain`
+  5. `freebsd-gmake`, `freebsd-autotools`, `freebsd-openssl`, `freebsd-zlib`, `freebsd-sh`, `freebsd-bash`
+- updated `modules/fruix/system/freebsd.scm` so the generated closure metadata now carries this boundary information too:
+  - `metadata/store-layout.scm` now includes:
+    - `host-base-stores`
+    - `fruix-runtime-stores`
+    - `host-base-replacement-order`
+    - `init-mode`
+
+Validation:
+
+- confirmed package-layer behavior directly with Guile:
+  - `(freebsd-host-staged-package? freebsd-runtime)` => `#t`
+  - `%freebsd-host-staged-replacement-order` prints the expected staged replacement order
+- `tests/system/run-phase7-system-closure.sh` still passes after the package-layer clarification:
+  - workdir: `/tmp/phase12-3-closure-1775162784`
+- inspected generated closure metadata file:
+  - `/frx/store/25ae9bb85da60b8c77971325e0e11d5390a064132a35e1bab0866cabb802a606-fruix-system-fruix-freebsd/metadata/store-layout.scm`
+  - confirmed it now includes:
+    - `host-base-stores`
+    - `fruix-runtime-stores`
+    - `host-base-replacement-order`
+
+Important findings:
+
+- the current host-staged FreeBSD base model is no longer just an implicit fact of the implementation; it is now named and documented as a transitional boundary
+- preserving compatibility aliases means the current working system model does not need a broad rename/refactor just to make that boundary explicit
+- encoding the replacement order directly in the package/model layer gives Phase 13 a clearer starting point for native `world`/`kernel` work
+
+Current assessment:
+
+- Phase 12 is now complete
+- the current Fruix pipeline is better documented, easier to diagnose, less noisy at runtime, and clearer about what remains transitional in the FreeBSD base layer
+- this is a good stopping point before beginning native FreeBSD base-build artifacts in `/frx/store`
+
+Next recommended step:
+
+1. begin Phase 13.1 by modeling FreeBSD `world` and `kernel` as Fruix-managed build artifacts rather than host-copy packages
+2. use `/usr/src` as the initial source of truth on the builder side
+3. target the first bootable replacement for the current host-staged kernel and core runtime path

docs/PROMPT.md

@@ -1,4 +1,4 @@
-Your task is described in ./docs/PLAN_2.md. Current progress is stored in ./docs/PROGRESS.md.
+Your task is described in ./docs/PLAN_3.md. Current progress is stored in ./docs/PROGRESS.md.
 
 Perform the next step towards the final goal. Update the progress file and `git commit` after each subphase (or even in between, if adequate).
 

docs/reports/phase12-host-staged-base-boundary-freebsd.md

@@ -0,0 +1,129 @@
+# Phase 12.3: made the host-staged FreeBSD base boundary explicit
+
+Date: 2026-04-02
+
+## Goal
+
+The current Fruix FreeBSD system still uses a transitional base layer assembled by copying selected files from the builder host.  That was already true in practice, but the code needed to make this boundary explicit so the later move toward native `world`/`kernel` artifacts is easier to reason about.
+
+The goal of this subphase was therefore not to change how the system boots, but to clarify in both code and generated metadata:
+
+- which package sets are still host-staged FreeBSD base packages
+- that this is an explicit transitional boundary
+- what the first intended replacement order is for native base-build work
+
+## Implementation
+
+### 1. Explicit host-staged package sets in `modules/fruix/packages/freebsd.scm`
+
+The package module now exports named transitional sets instead of only generic lists:
+
+- `%freebsd-host-staged-all-packages`
+- `%freebsd-host-staged-core-packages`
+- `%freebsd-host-staged-development-profile-packages`
+- `%freebsd-host-staged-system-packages`
+- `%freebsd-host-staged-replacement-order`
+- `freebsd-host-staged-package?`
+
+The older names remain as compatibility aliases:
+
+- `%freebsd-core-packages`
+- `%freebsd-development-profile-packages`
+- `%freebsd-system-packages`
+
+This preserves existing callers while making the transitional nature of the current base model visible in the code.
+
+### 2. Replacement order is now encoded directly in the package layer
+
+The new `%freebsd-host-staged-replacement-order` documents the intended first replacement sequence:
+
+1. `freebsd-kernel`, `freebsd-bootloader`
+2. `freebsd-runtime`, `freebsd-libc`, `freebsd-userland`, `freebsd-rc-scripts`
+3. `freebsd-networking`, `freebsd-openssh`
+4. `freebsd-kernel-headers`, `freebsd-clang-toolchain`
+5. `freebsd-gmake`, `freebsd-autotools`, `freebsd-openssl`, `freebsd-zlib`, `freebsd-sh`, `freebsd-bash`
+
+This is not yet native base-build implementation, but it makes the intended transition path concrete.
+
+### 3. The closure metadata now carries that boundary too
+
+`modules/fruix/system/freebsd.scm` now records the replacement order directly in:
+
+- `metadata/store-layout.scm`
+
+alongside:
+
+- host-staged base store paths
+- Fruix runtime store paths
+- init mode
+
+This means the generated closure itself now explains both:
+
+- what part of the current system still comes from the host-staged FreeBSD base, and
+- what part is expected to be replaced first by future native base artifacts.
+
+## Validation
+
+### Package-layer validation
+
+Confirmed directly with Guile:
+
+```scheme
+(use-modules (fruix packages freebsd))
+(freebsd-host-staged-package? freebsd-runtime)  => #t
+%freebsd-host-staged-replacement-order
+```
+
+Observed output included:
+
+```text
+#t
+((first-wave freebsd-kernel freebsd-bootloader)
+ (second-wave freebsd-runtime freebsd-libc freebsd-userland freebsd-rc-scripts)
+ ...)
+```
+
+### System-closure validation
+
+Passing run:
+
+- `PASS phase7-system-closure`
+- workdir: `/tmp/phase12-3-closure-1775162784`
+
+The generated closure metadata file:
+
+- `/frx/store/25ae9bb85da60b8c77971325e0e11d5390a064132a35e1bab0866cabb802a606-fruix-system-fruix-freebsd/metadata/store-layout.scm`
+
+now records:
+
+- `host-base-stores`
+- `fruix-runtime-stores`
+- `host-base-replacement-order`
+
+with content including:
+
+```text
+(host-base-replacement-order
+ (first-wave freebsd-kernel freebsd-bootloader)
+ (second-wave freebsd-runtime freebsd-libc freebsd-userland freebsd-rc-scripts)
+ ...)
+```
+
+## Assessment
+
+This subphase makes the current architectural compromise explicit instead of leaving it implicit in naming and package-list accidents.
+
+That matters because Fruix is now moving into the phase where native FreeBSD base artifacts should start displacing the host-copy model.  The system now has a clearer answer to the question:
+
+- what exactly is still transitional,
+- and in what order should it be retired?
+
+## Next recommended step
+
+Phase 12 is now complete.
+
+The next major step is Phase 13:
+
+- start modeling and producing native FreeBSD `world`/`kernel` artifacts from `/usr/src`
+- stage them in `/frx/store`
+- and begin replacing the current host-staged base boundary with those new outputs

modules/fruix/packages/freebsd.scm

@@ -28,6 +28,12 @@
             freebsd-zlib
             freebsd-sh
             freebsd-bash
+            freebsd-host-staged-package?
+            %freebsd-host-staged-all-packages
+            %freebsd-host-staged-core-packages
+            %freebsd-host-staged-development-profile-packages
+            %freebsd-host-staged-system-packages
+            %freebsd-host-staged-replacement-order
             %freebsd-core-packages
             %freebsd-development-profile-packages
             %freebsd-system-packages))
@@ -455,7 +461,12 @@ library for profile experiments."
    #:install-plan
    '((file "/lib/libz.so.6" "lib/libz.so.6"))))
 
-(define %freebsd-core-packages
+;; Transitional boundary: the FreeBSD base layer below is still staged by
+;; copying selected artifacts from the builder host.  Plan 3 keeps these
+;; package sets explicit so they can be replaced incrementally by native
+;; FreeBSD world/kernel build outputs in /frx/store.
+
+(define %freebsd-host-staged-core-packages
   (list freebsd-kernel
         freebsd-kernel-headers
         freebsd-libc
@@ -468,7 +479,7 @@ library for profile experiments."
         freebsd-sh
         freebsd-bash))
 
-(define %freebsd-development-profile-packages
+(define %freebsd-host-staged-development-profile-packages
   (list freebsd-kernel
         freebsd-kernel-headers
         freebsd-libc
@@ -481,7 +492,7 @@ library for profile experiments."
         freebsd-sh
         freebsd-bash))
 
-(define %freebsd-system-packages
+(define %freebsd-host-staged-system-packages
   (list freebsd-kernel
         freebsd-bootloader
         freebsd-libc
@@ -492,3 +503,26 @@ library for profile experiments."
         freebsd-userland
         freebsd-sh
         freebsd-bash))
+
+(define %freebsd-host-staged-all-packages
+  (delete-duplicates
+   (append %freebsd-host-staged-core-packages
+           %freebsd-host-staged-development-profile-packages
+           %freebsd-host-staged-system-packages)))
+
+(define (freebsd-host-staged-package? package)
+  (any (lambda (candidate)
+         (string=? (freebsd-package-name candidate)
+                   (freebsd-package-name package)))
+       %freebsd-host-staged-all-packages))
+
+(define %freebsd-host-staged-replacement-order
+  '((first-wave . (freebsd-kernel freebsd-bootloader))
+    (second-wave . (freebsd-runtime freebsd-libc freebsd-userland freebsd-rc-scripts))
+    (third-wave . (freebsd-networking freebsd-openssh))
+    (fourth-wave . (freebsd-kernel-headers freebsd-clang-toolchain))
+    (fifth-wave . (freebsd-gmake freebsd-autotools freebsd-openssl freebsd-zlib freebsd-sh freebsd-bash))))
+
+(define %freebsd-core-packages %freebsd-host-staged-core-packages)
+(define %freebsd-development-profile-packages %freebsd-host-staged-development-profile-packages)
+(define %freebsd-system-packages %freebsd-host-staged-system-packages)

modules/fruix/system/freebsd.scm

@@ -1105,6 +1105,7 @@
                    (host-base-stores . ,host-base-stores)
                    (fruix-runtime-store-count . ,(length fruix-runtime-stores))
                    (fruix-runtime-stores . ,fruix-runtime-stores)
+                   (host-base-replacement-order . ,%freebsd-host-staged-replacement-order)
                    (init-mode . ,(operating-system-init-mode os)))))))
          (generated-files (append (operating-system-generated-files os
                                                                     #:guile-store guile-store