# Phase 17.3: clarify FreeBSD source provenance, caching, and update policy

Date: 2026-04-03

## Goal

Phase 17.3 turns the source behavior implemented in Phases 16 through 17.2 into an explicit repo-level policy.

The main question was no longer whether Fruix *can* fetch and boot from declared FreeBSD sources. It can.

The question here is:

- how should operators think about source selectors versus stable source identity?
- what exactly lives in cache versus store?
- when should native outputs be invalidated?
- what is the intended policy for moving Git refs, pinned commits, and archive hashes?

## Added documentation

Added:

- `docs/freebsd-source-policy.md`

This document explains:

- supported source kinds:
  - `local-tree`
  - `git`
  - `src-txz`
- declared source vs effective source
- cache locations under:
  - `/frx/var/cache/fruix/freebsd-source`
- materialized source outputs under:
  - `/frx/store/*-freebsd-source-*`
- effective identity rules for:
  - local-tree snapshots
  - Git refs/commits
  - verified `src.txz` archives
- effective source root detection rules:
  - `tree`
  - `tree/usr/src`
- native build invalidation policy
- closure provenance policy
- update policy for moving refs vs pinned commits
- the current no-hidden-patch-layer rule

## Key policy conclusions

The repo now states clearly that:

- Git refs are selectors, not stable reproducibility boundaries
- resolved Git commits are the effective Git identity boundary
- `src.txz` URLs are not enough by themselves; `sha256` is required
- local trees are mutable selectors; the materialized snapshot and filtered tree hash are the meaningful Fruix identity
- native FreeBSD base outputs must invalidate when the materialized source identity changes, even if the visible base version label does not
- cache objects are transport optimizations, not the final identity boundary

## Relation to validated behavior

The new policy document matches the validated Phase 17 behavior:

- Phase 17.1 proved that distinct source identities can coexist side by side and produce different native outputs for the same visible base version label
- Phase 17.2 proved that systems built from those distinct source identities can boot successfully through the validated native path

## Result

Phase 17.3 is complete.

The repo now clearly explains how FreeBSD source objects are:

- fetched
- cached
- identified
- invalidated
- and consumed by native FreeBSD base builds

That completes Phase 17 and leaves Fruix in a better position to begin the installation/deployment work in Phase 18.