Observability & Audit

Each read surface answers a different question.

status: cheap state

sow status -r local

It reports the Desired revision, Built Generation, dirty Dists, pending payload counts, lock state, and ready_to_copy. It does not hash the public tree, recover an operation, or build.

Use status to diagnose. Do not use it as a substitute for check.

check: delivery proof

sow check -r local

In steady state, the checker reports nine ordered layers:

A non-terminal layout transition has a shorter diagnostic surface: config, state, public-modes, then layout-transition. The check stops there and returns not-ready until the diagnosed maintenance operation completes or is safely aborted before commit.

check writes and repairs nothing. A dirty or recovering Repository is not deliverable even if its last committed tree remains readable. Put check in the release pipeline and stop on any nonzero exit.

Every unique physical package payload receives one authoritative SHA-256 pass per check, regardless of cached fingerprints. Descriptor-bound evidence is then shared across retained records, indexes, signatures, the final Generation manifest, and changes. Signed RPM verification uses one additional shared stream for all signature packets and trust rings; it is not multiplied by the number of Dists, keys, or retained Generations.

changes: Generation difference

sow changes -r local
sow changes 0 -r local
sow changes 42 -r local --json

• no base argument compares the current Built Generation with its predecessor;
• base 0 describes the complete current public tree;
• base N gives the net difference from recorded Generation N to current Built.

Rows include operation, phase, Repository-relative path, size, and SHA-256. Phases use the same vocabulary as local construction: payload, metadata, pointer, delete.

changes is a manifest/difference surface. It does not contact a destination, persist a remote checkpoint, enforce cache grace, or recover an interrupted transfer. Use sow publish TARGET for a configured live target. For an offline copy, stage a complete tree, verify it, and switch it into service atomically.

Generation retention and GC

sow retain add 42 -r local
sow retain ls -r local
sow retain rm 42 -r local
sow gc -r local

retain add verifies and freezes a Generation’s metadata and reference sets; it does not copy another package tree. The retained record is an explicit GC root. retain rm removes that root but deletes no package bytes itself.

Local sow gc deletes only payloads proven unreachable from the current state, explicit retentions, active recovery/publication state, and other recorded roots. Target GC is a separate operation: sow gc TARGET uses that Provider’s safety model.

During ordinary builds, SOW carries forward the immediately preceding RPM immutable metadata and APT by-hash objects so a reader of the previous pointer can finish. This bounded protocol window is separate from explicit retain.

Operation log

sow log -r local
sow log OPERATION -r local
sow log export operations.jsonl -r local
sow log prune 2026-01-01 -r local

The ledger records operation kind/state, timestamps, configuration/manifest identities, package dispositions, membership changes, and physical changes where applicable.

log export writes stable JSONL, refuses to overwrite an existing file, and validates its output path. log prune accepts a date or RFC 3339 timestamp and removes only eligible terminal audit records; it does not remove current state, recovery evidence, or Generation manifests still required elsewhere.

Operational pattern

sow build -r local
sow check -r local
sow publish public

Use status for monitoring, check for the gate, publish for target mutation, and log for later evidence.

See also

• sow build and sow check
• Log commands
• sow publish and sow gc