fruix/docs/reports/phase17-source-policy-freebsd.md

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.