fruix/docs/reports/postphase10-runtime-prefix-shims-freebsd.md

# Post-Phase-10: removed runtime dependence on `/tmp` Guile/Shepherd compatibility-prefix shims

Date: 2026-04-02

## Goal

After validating both the `rc.d` bridge path and the new Shepherd-as-PID-1 path, the next priority was the remaining runtime-artifact problem:

- the guest still carried activation-time `/tmp/...` compatibility symlinks for locally built Guile, guile-extra, and Shepherd prefixes
- those shims were compensating for baked-in historical paths in staged runtime artifacts

The goal of this subphase was narrower than fully rebuilding Guile/Shepherd in a store-native way.  The immediate target was:

- remove the guest's *runtime dependence* on those `/tmp` compatibility-prefix symlinks,
- keep both validated boot modes working,
- and prove that Guile can still load the relevant modules from the store-backed runtime layout without those `/tmp` aliases.

## Result

This subphase succeeded.

The generated guest no longer needs activation to create:

- `/tmp/guile-freebsd-validate-install`
- `/tmp/guile-gnutls-freebsd-validate-install`
- `/tmp/shepherd-freebsd-validate-install`

Those shims are now absent in the booted guest, while both of these boot paths still pass on the real XCP-ng VM:

1. `freebsd-init+rc.d-shepherd`
2. `shepherd-pid1`

In both cases, the guest now also passes an explicit in-guest Guile module smoke test using the staged store paths and *without* the `/tmp` prefix aliases.

## What changed

### 1. Activation no longer creates `/tmp` compatibility-prefix symlinks

`modules/fruix/system/freebsd.scm` no longer emits activation logic that recreates the old `/tmp/...` prefix trees.

That means the guest is no longer depending on those aliases as part of ordinary first boot.

### 2. The staged runtime prefixes are sanitized as they are materialized into `/frx/store`

The prefix materializer now post-processes the copied runtime trees so the most relevant runtime-facing Scheme modules no longer require those `/tmp` prefix aliases.

This required a new prefix-materializer revision and deterministic post-copy sanitation.

### 3. Guile-extra runtime fixes

The staged guile-extra runtime now:

- patches `fibers/config.scm` so it can use `GUILE_EXTENSIONS_PATH` instead of falling back to the old `/tmp/guile-gnutls-freebsd-validate-install/...` path
- patches `gnutls.scm` so it can fall back to `GUILE_EXTENSIONS_PATH`
- removes stale compiled cache files that still embedded the old prefix values and would otherwise override the corrected source modules:
  - `fibers/config.go`
  - `gnutls.go`

### 4. Shepherd runtime fixes

The staged Shepherd runtime now:

- patches `share/guile/site/3.0/shepherd/config.scm` to use real runtime-facing paths instead of the old temporary install prefix:
  - `Prefix-dir` => `/frx`
  - `%localstatedir` => `/var`
  - `%runstatedir` => `/var/run`
  - `%sysconfdir` => `/etc`
  - `%localedir` => `/usr/share/locale`
  - `%pkglibdir` => `/usr/local/lib/shepherd`
- removes the stale compiled cache file that still embedded the old prefix values:
  - `shepherd/config.go`

### 5. Real-VM validation harnesses now assert shim absence directly

The main real-VM validation scripts now check that the old `/tmp` compatibility-prefix trees are absent in the guest:

- `tests/system/run-phase9-xcpng-boot.sh`
- `tests/system/run-phase11-shepherd-pid1-xcpng.sh`

They also run an in-guest Guile module smoke test using the store-backed runtime environment and require:

- `guile_module_smoke=ok`

## Validation

### Real VM, `freebsd-init+rc.d-shepherd`

Passing run:

- `PASS phase9-xcpng-boot`
- workdir: `/tmp/noshim-phase9-smoke-1775143001`

Key metadata:

```text
compat_prefix_shims=absent
guile_module_smoke=ok
ready_marker=ready
shepherd_status=running
sshd_status=running
```

### Real VM, `shepherd-pid1`

Passing run:

- `PASS phase11-shepherd-pid1-xcpng`
- workdir: `/tmp/noshim-phase11-smoke-1775142712`

Key metadata:

```text
compat_prefix_shims=absent
guile_module_smoke=ok
ready_marker=ready
shepherd_pid=1
shepherd_status=running
sshd_status=running
```

### Manual guest confirmation

A direct SSH probe on the real guest confirmed that all three historical `/tmp` compatibility prefixes are absent while Guile can still load:

- `(fibers config)`
- `(gnutls)`
- `(shepherd config)`

with output including:

```text
ABSENT:/tmp/guile-freebsd-validate-install
ABSENT:/tmp/guile-gnutls-freebsd-validate-install
ABSENT:/tmp/shepherd-freebsd-validate-install
1.4.2
/var/run
```

## Assessment

This removes an important transitional runtime crutch.

Fruix is no longer merely *booting despite* historical `/tmp` prefix aliases; it now boots and runs Guile/Shepherd services from the staged store-backed runtime arrangement without those guest-side compatibility symlinks.

## Remaining limitation

This does **not** mean every historical prefix string has disappeared from every staged artifact.

Some compiled binaries and libraries still contain old build/install strings internally, especially in places such as:

- `libguile`
- libtool metadata
- pkg-config metadata
- extension shared objects built upstream with the original prefixes

However, the important practical milestone is that the guest no longer depends on `/tmp` compatibility-prefix symlinks at runtime.

## Recommended next step

The next, deeper cleanup would be to eliminate the remaining baked prefix strings from the runtime artifacts themselves by moving the local Guile/guile-extra/Shepherd build/install flow closer to a genuinely store-native prefix from the start, rather than relying on post-copy sanitation.