audit on SOW

Transactions & Recovery

Mon, 01 Jan 0001 00:00:00 +0000

This page explains how Managed mode prevents a live pointer from naming missing content and how it coordinates SQLite state with filesystem changes.

The invariant

On a supported local POSIX filesystem, a client following a Managed protocol pointer reads a complete old view or a complete new view, including after interruption.

Everything below exists to hold that line: metadata is fully staged and verified before anything public moves, the pointer swap is the commit decision, and every operation records enough durable evidence that the next command can finish it or undo it without guessing.

Observability & Audit

Mon, 01 Jan 0001 00:00:00 +0000

Each read surface answers a different question.

Command	Question	Writes?
`status`	What state is the Repository in?	no
`check`	Does the selected Repository satisfy the complete delivery contract?	no
`changes`	What physical files differ between Built Generations?	no
`log`	Which operations and dispositions were recorded?	no
`retain ls`	Which Generations are explicit local GC roots?	no

`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.

sow status

Mon, 01 Jan 0001 00:00:00 +0000

sow status is the cheap Repository health query. It reads state but does not hash files, verify signatures, recover Operations, build metadata, or take the write lock.

Synopsis

sow status [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Restrict status to these Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Repository states

Every Repository tracks a Desired Revision in SQLite and the Built Generation represented by its public dists/ tree.

sow check

Mon, 01 Jan 0001 00:00:00 +0000

sow check is the deep read-only gate for a managed Repository. It hashes bytes, validates state, reconstructs expected views, and verifies declared signatures. It never repairs, builds, recovers an Operation, or takes the write lock.

Synopsis

sow check [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-j, --jobs N`	Parallel verification workers; at least `1`	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Verify named Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Verification layers

In steady state, the checker reports nine ordered layers:

sow log

Mon, 01 Jan 0001 00:00:00 +0000

Every write command inside a Repository commits an application-level Operation to that Repository’s SQLite database before it produces any external file side effect. That record is what makes crash recovery possible — and once the Operation reaches a terminal state, the same record is your audit trail. sow log reads it.

Synopsis

sow log [OPERATION] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME] [--json]
sow log export [FILE] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]
sow log prune BEFORE [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

Operation lifecycle

Understanding the state field is most of understanding the log:

audit on SOW

Transactions & Recovery

The invariant

Observability & Audit

status: cheap state

sow status

Synopsis

Repository states

sow check

Synopsis

Verification layers

sow log

Synopsis

Operation lifecycle

`status`: cheap state