policy on SOW

Features

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

SOW has two isolated execution paths. Plain mode is a stateless rebuild of one directory; Managed mode records package membership and immutable repository generations in a workspace. Neither path silently adopts state from the other.

Capability matrix

Capability	Plain	Managed
RPM and DEB metadata	yes	yes
Mixed RPM + DEB operation	one directory	one Repository, separate Dists
Persistent membership and generations	no	yes
Per-architecture views and neutral packages	no	yes
`exclude` and version `limit` policy	no	yes
Metadata signing	no	RPM and DEB
RPM package signing	`--sign-with`	`never`, `fill`, `always`
Transaction journal and recovery	rerun `create`	workspace, Repository, publication
Queryable operation log and JSONL export	no	yes
Publication targets	no	filesystem and R2

SOW parses packages and renders metadata in-process. It does not invoke createrepo_c, dpkg-scanpackages, reprepro, or modifyrepo_c. RPM package signing is the exception: it needs the host rpm command and GPG environment because it rewrites package payloads.

Membership Policy

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

Policy is the answer to “I dumped a build directory into this Dist and I do not want the debuginfo packages, and I only want the latest version of each package.” Two rules do that work, they run in a fixed order, and they run over the whole candidate set — not just the packages you happened to add this time.

The two rules and their order

candidate set  →  exclude  →  limit  →  Desired Membership

exclude drops packages that match a rule. limit then caps how many versions survive per package name and architecture. The order is fixed and never configurable, because the reverse order would let an excluded package consume a version slot on its way out.

sow add

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

sow add is the main write path. It parses the packages you point at, derives their format and architecture from the package headers, applies the Dist’s membership policy, and — unless you pass --skip — rebuilds every affected index before it returns. When the command exits 0, clients can already see the new packages.

Synopsis

sow add PATH... [-R|--recursive] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-R, --recursive`	Descend into subdirectories of a `PATH` directory	off (top level only)
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers for parsing, hashing and rendering	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

Inputs and targets

PATH can be a file or a directory. A directory is scanned top level only unless you pass -R.

sow rm

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

sow rm takes packages out of the Desired Membership of the Dists you select and, by default, rebuilds the affected indexes immediately. It does not delete bytes from pool/ — membership and content are separate concepts, and reclamation is the separate conservative sow gc operation.

Synopsis

sow rm PACKAGE... [-c|--check] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-c, --check`	Preview only; compute and print the plan without writing anything	off
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

--check and --skip are mutually exclusive: