Engineering

Repository boundary

The Farrow source repository contains code, tests, build/package definitions, legal notices, and a short landing README. This site is the authoritative home for user, design, operator, and release documentation. Raw review transcripts, historical scratch inventories, demo directories, generated binaries, and release output trees are not source inputs and must not be committed.

Generated output is disposable:

• bin/ — development builds;
• dist/ and .goreleaser-* — release/snapshot staging;
• root farrow, farrow-hosts-helper, and catalogsign binaries;
• Hugo public/ and resources/.

Build and source gates

make build
make test
make race
make vet
make staticcheck
make vuln
make cross-check
make image-pipeline-test
make license-check

make check combines these gates. A source gate is not native VM evidence; macOS HVF, Linux KVM/networking, package consumption, release publication, and the public render remain separate gates.

Release and package contract

Release tooling under packaging/, .goreleaser.yaml, and .github/workflows is source, even though its generated directories are not. Archives and Linux packages contain the matching binaries plus LICENSE, the minimal source README, build metadata, and exact upstream license bytes reconstructed from the module versions pinned by go.mod. Those generated license texts live under licenses/ in archives and are not tracked as source. Detailed documentation stays on this versioned site rather than being copied into every binary payload.

Never infer publication from a successful build. Commit, tag, archive/package, signature/attestation, upload, CI, and public consumption are distinct gates.

Image normalization

packaging/image-pipeline/ accepts an explicit local qcow2 source; it never downloads or uploads. It copies and hashes the source, forces qcow2 parsing, rejects backing/external/encrypted/unknown features, runs qemu-img check, and can perform a no-network offline Guest mutation in an explicit QEMU sandbox. UID/GID 88 collisions are rejected rather than rewritten ambiguously.

Catalog bytes are exported with:

go run ./tools/catalogexport /absolute/new/catalog.json

The exporter is atomic and no-clobber. Catalog signing and application release signing use separate keys and trust domains.

Evidence policy

Historical M0–M4 notes were useful during implementation but are not product documentation. Their durable conclusions are condensed into Design and Status. A later source edit inherits no native proof; every status claim names its date, host, path, and remaining gates.