# Fruix FreeBSD Source Policy

This document records the current intended policy for how Fruix models, fetches, caches, identifies, invalidates, and consumes FreeBSD source inputs.

It reflects the behavior implemented through Plan 4 Phases 16 and 17.

## 1. Source object model

Fruix represents FreeBSD source inputs explicitly with `freebsd-source`.

Currently supported source kinds are:

- `local-tree`
- `git`
- `src-txz`

A source object records some combination of:

- `name`
- `kind`
- `url`
- `path`
- `ref`
- `commit`
- `sha256`

Fruix distinguishes between:

- the **declared source**
  - what the operator asked for
- the **effective source**
  - what Fruix actually resolved/materialized and built from

That distinction matters most for Git refs and local-tree snapshots.

## 2. Source identity boundaries

### `local-tree`

Declared selector:

- local filesystem path

Effective identity boundary:

- filtered source-tree hash computed from `mtree`

Current rule:

- Fruix computes source identity from:
  - `mtree -c -k type,link,size,mode,sha256digest`
- comment lines are removed before hashing

This avoids unstable `mtree` comment headers such as:

- date
- user
- machine

So the effective local-tree identity is content-oriented rather than host-comment-oriented.

### `git`

Declared selectors:

- `commit`, or
- `ref`

Effective identity boundary:

- resolved commit

Current rule:

- if `commit` is present, Fruix uses it as the fetch selector
- otherwise, Fruix uses `ref`
- after fetch, Fruix records the resolved commit as the effective Git identity

Policy consequence:

- a Git **ref** is a convenience selector
- a Git **commit** is the reproducibility boundary

Therefore:

- use `ref` alone for exploratory/latest tracking when drift is acceptable
- use `commit` for reproducible builds, side-by-side comparisons, installation artifacts, and rollback-sensitive workflows
- it is valid to record both:
  - `ref` for human provenance
  - `commit` for stable identity

### `src-txz`

Declared selectors:

- URL
- expected `sha256`

Effective identity boundary:

- verified archive `sha256`

Policy consequence:

- `src-txz` materialization is only valid when `sha256` is declared
- archive URL alone is not enough

## 3. Cache policy

Default cache root:

- `/frx/var/cache/fruix/freebsd-source`

Current cache layout:

- Git:
  - `/frx/var/cache/fruix/freebsd-source/git/<hash>.git`
- release/snapshot archives:
  - `/frx/var/cache/fruix/freebsd-source/archives/<hash>-src.txz`

### Git cache behavior

Fruix keeps a bare repository cache keyed by source URL.

Current behavior:

- initialize bare repo if absent
- ensure `origin` matches the declared URL
- fetch the requested selector from `origin`
- archive the resolved commit into the materialized store object

Policy:

- the cache is a transport/proxy optimization, not the identity boundary
- the identity boundary is the resolved commit recorded in the effective source and materialization metadata

### `src-txz` cache behavior

Fruix keeps the downloaded archive under the cache root.

Current behavior:

- if a cached archive exists, hash it
- if its hash does not match the declared `sha256`, delete it
- fetch the archive if missing
- verify the downloaded archive hash
- fail if the verified hash does not match the declared `sha256`

Policy:

- the cache is reusable only when the declared hash still matches
- hash mismatch invalidates the cached archive immediately

### `local-tree`

Current behavior:

- no separate network cache
- Fruix snapshots the local tree into a materialized store object

Policy:

- the local path is only a selector to a mutable host tree
- the materialized snapshot and its filtered tree hash are the meaningful Fruix identity boundary

## 4. Materialized source store policy

Materialized FreeBSD sources are stored in:

- `/frx/store/*-freebsd-source-*`

Current manifest inputs for a materialized source object include:

- materializer version
- declared source
- effective source
- source identity tuple
  - for example resolved commit, archive sha256, or local tree hash

Policy consequence:

- changing any of those identity inputs should produce a distinct source store path
- changing materialization semantics should bump the materializer version

Current materializer version:

- `freebsd-source-materializer-version = "2"`

## 5. Effective source root policy

Not every source unpacks to the same top-level directory shape.

Current behavior:

- if `tree/Makefile` exists, effective root is:
  - `tree`
- else if `tree/usr/src/Makefile` exists, effective root is:
  - `tree/usr/src`

This is why:

- Git exports materialize effectively at `.../tree`
- official `src.txz` archives materialize effectively at `.../tree/usr/src`

Policy:

- native builds must consume the detected effective source root, not assume `/usr/src`
- the declared transitional `source-root` may still be recorded for provenance, but it is not the effective build root once materialization is in use

## 6. Native build invalidation policy

Native FreeBSD kernel/world/runtime/bootloader outputs must be invalidated by source identity, not just by package name/version.

Current behavior:

- native package materialization rewrites the install plan to use the materialized source root
- native manifests record both:
  - `declared-source`
  - `materialized-source`
- package materialization caching keys on the full manifest identity rather than only package name/version
- native build common metadata includes:
  - `source-root`
  - `source-tree-sha256`
  - kernconf hash
  - target metadata

Policy consequence:

- two builds with the same visible base version label but different source identities must still produce different native output store paths
- that behavior is intentional and required

## 7. Closure provenance policy

System closures and images should preserve enough source metadata to explain exactly what source snapshot was used.

Current closure/image metadata includes:

- `metadata/freebsd-source.scm`
- `metadata/freebsd-source-materializations.scm`
- `materialized_source_store_count`
- `materialized_source_stores`

Native `.freebsd-native-build-info.scm` records:

- declared source
- materialized source store path
- materialized source root
- materialized source tree hash
- effective Git commit or archive hash when applicable

Policy:

- source provenance is part of the closure boundary, not just a transient fetch detail

## 8. Update policy

### Recommended operator policy

For reproducible and rollback-sensitive workflows:

- prefer Git sources pinned by `commit`
- prefer archive sources pinned by `sha256`
- treat `local-tree` as a development/debugging input unless the resulting materialized snapshot is itself the explicit artifact being compared

### Moving refs

A moving Git ref is expected to drift over time.

Policy:

- if only `ref` is declared, Fruix may legitimately produce a new materialized source store later
- that new materialized source identity should then invalidate native outputs
- this is expected behavior, not a cache bug

### Installed/deployed systems

For installation artifacts and generation management, the source identity should be stable enough to answer:

- what exact source revision produced this system?
- can it be rebuilt later?
- should this update be considered a new generation boundary?

That means later installation/deployment work should prefer:

- Git commit-pinned sources
- hash-pinned archives

rather than floating refs alone.

## 9. Patch/transformation policy

Fruix does not yet expose a first-class patch queue or transformation layer on top of `freebsd-source`.

Current policy until that exists:

- the declared source object should be treated as the full upstream-source identity boundary
- when a patch/transformation layer is introduced later, it must become part of the materialized source identity and manifest versioning

In other words:

- applying patches without changing source identity metadata would be wrong

## 10. Relation to Guix-inspired semantics

This policy follows the same important high-level idea as Guix:

- selectors are not enough
- resolved, content-stable identities matter
- cached transport objects are not the same as reproducible store identities

Fruix applies that idea in FreeBSD-specific form:

- `src.txz` handling
- FreeBSD source-tree effective-root detection
- mtree-based FreeBSD tree identity
- native FreeBSD base builds driven from materialized source snapshots under `/frx/store`

## 11. Practical summary

Use these rules:

- **Want reproducibility?**
  - pin Git by `commit`
  - pin archives by `sha256`
- **Want side-by-side comparison?**
  - keep distinct source objects and let Fruix materialize them separately
- **Want native base outputs to differ only when they should?**
  - rely on materialized source identity, not mutable `/usr/src`
- **Want stable deployment provenance?**
  - preserve the closure metadata files and materialized source store references