Feature on SOW

Plain Flat Repositories

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

sow create takes a directory that already contains .rpm and .deb files and writes flat repository indexes beside them. Plain mode has no workspace, configuration file, database, desired state, or operation journal. The package directory is the authority; every index is a disposable projection of its current contents.

That distinction is intentional. Managed repositories retain state and recover transactions. Plain repositories are cheap to recreate: if a run fails or is interrupted, run the same command again and overwrite the derived metadata.

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.

Managed Workspaces

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

Managed mode is what you use when the same repository will be updated for months: packages arrive in batches, policy decides what stays, and you need to prove afterwards what changed and when. This page explains the three-tier model, the layout it produces, and how commands figure out which repository and which Dist you meant.

The three tiers

Workspace                          discovery and configuration boundary
└── Repository                     ownership boundary: pool, dists, SQLite, lock, generations
    └── Dist                       a named membership set in exactly one format
        └── Architecture View      a rendered projection — not a membership

Each tier has one job, and the boundaries are strict:

Pool & Metadata Views

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

The invariant

Within one Repository, every live Package Object has one canonical payload path under pool/. Dists and architecture views own metadata, not aliases of package bytes:

<repo>/pool/...                              canonical package payloads
<repo>/dists/<rpm-dist>/<arch>/repodata/... RPM metadata only
<repo>/dists/<deb-dist>/main/binary-*/...   APT metadata only

The same digest in another Repository or publication prefix is a separately owned object. SOW deliberately does not turn local deduplication into shared distributed ownership.

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.

Signing Model

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

There are two different questions a client can ask about a repository, and SOW answers them with two separate mechanisms. Confusing them is the most common source of “I signed it but dnf still complains”, so this page starts by pulling them apart.

Two independent trust chains

	Metadata signing	RPM package signing
Question answered	“Is this index really from you, and unmodified?”	“Is this `.rpm` file really from you?”
Configured by	`signing.rpm.metadata`, `signing.deb.metadata`	`signing.rpm.packages`
Produces	`repodata/repomd.xml.asc`, `InRelease`, `Release.gpg`	an OpenPGP signature embedded in the package
Changes package bytes	no	yes
Client setting	dnf `repo_gpgcheck=1`, apt `Signed-By`	dnf `gpgcheck=1`
Available in Plain mode	no	yes, via `create -S KEY`

They are configured separately and can be used separately. Metadata signing alone is usually the right starting point: it authenticates the whole index in one place and requires no change to the packages you received from upstream.

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.

Feature on SOW

Plain Flat Repositories

Features

Capability matrix

Managed Workspaces

The three tiers

Pool & Metadata Views

The invariant

Membership Policy

The two rules and their order

Signing Model

Two independent trust chains

Transactions & Recovery

The invariant

Observability & Audit

status: cheap state

`status`: cheap state