repository on SOW

SOW Design Evolution: From Route Graphs to the Repository Core

Mon, 10 Aug 2026 00:00:00 +0000

This record dates to the 2026-08-10 consolidation of SOW around its Repository core. It distills the useful decisions from the earlier planning, ADR, review, migration, and verification trees without turning every intermediate artifact into maintained product documentation.

Some sealed folders use “v0.2” and “v0.3” for consecutive pre-release design lines. The version labels below refer only to released Git tags: the C2 hardlink line was replaced before v0.2.0 was tagged.

The short history

Line	Design center	Historical status
v0.1	Git/CAS ownership, route-aware materialization, edge authorization, provider workflows, and Pigsty migration	Released as v0.1.0; superseded
v0.2	Local Plain/Managed engine, Repository-scoped single-payload tree, metadata-only views, retained Generations, and target-scoped publication	Released as v0.2.0; public layout remains current
v0.3	V1 removal, package-facts caching, one-pass Plain builds, and bounded payload commits	Released as v0.3.0; same public layout
v0.4	Single-pass verification, independent RPM trust rings, explicit target rebind, and migration/recovery hardening	Current released baseline when this record was updated

The exact code and claims for each released line remain available in the v0.1.0, v0.2.0, v0.3.0, and v0.4.0 source tags.

System Model

Sat, 08 Aug 2026 00:00:00 +0000

The model is deliberately layered. Configuration expresses intent, the database records owned state, and the public tree is a deterministic projection. None of those layers may quietly become a substitute for another.

Object hierarchy

Workspace
├── Repository
│   ├── Package Object
│   ├── Dist
│   │   └── Membership -> Package Object
│   ├── Desired state
│   ├── Built Generation
│   └── Retained Generation references
└── Publication Target
    └── Repository + provider + prefix

Workspace

A Workspace supplies discovery, configuration, and coordination. It owns sow.yml, the private .sow/ directory, and stable lock paths. It is not a package deduplication domain.

Design Principles

Sat, 08 Aug 2026 00:00:00 +0000

SOW is not primarily a metadata generator. It is an ownership and state-transition system whose output happens to be APT and RPM repositories. The following principles keep that system small enough to reason about.

One owner for every durable fact

Every durable fact has one scope and one authority:

Fact	Owner
Package bytes and package identity	Repository
Desired memberships and Built state	Repository
Generation and Changeset	Repository
Publication target binding and revisions	Repository + target storage/prefix
Publication attempt and applied checkpoint	Repository + target prefix
Remote inventory, grace, and delete evidence	Repository + target prefix

State is not silently shared across Repositories or publish prefixes. The same package may therefore exist once in each Repository or target. That is intentional: local deduplication must not create distributed ownership.

Why SOW Uses One Payload Tree per Repository

Wed, 05 Aug 2026 00:00:00 +0000

This decision was drafted on 2026-08-05 during the pre-v0.2 release design consolidation and shipped in SOW v0.2.0 on 2026-08-08. It remains the layout contract in v0.3 and v0.4. It records an architecture choice, not a blanket compatibility claim: protocol closure, ordinary package clients, mirror tools, static hosting, and object storage are verified as separate evidence layers.

Decision

Each SOW Repository owns one public tree:

<repository>/
  pool/                         # canonical package bytes
  dists/
    <dist>/
      <architecture>/           # protocol metadata only

A Package Object has one canonical payload path inside one Repository. Adding the same object to several Dists or architecture views adds membership and metadata references; it does not create another canonical package file.

Your First Workspace

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

Managed mode keeps configuration, membership, generations, and audit state. This example starts from an empty directory.

Initialize the workspace

sow init /srv/sow
cd /srv/sow

init creates:

/srv/sow/
├── sow.yml   # configuration; schema: sow/v3
└── .sow/     # SQLite state, locks, staging, recovery, journals

Do not edit or serve .sow/. init is idempotent: rerunning it validates and converges declared repositories and Dists; it does not reset a valid workspace.

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:

Core Concepts

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

Plain or Managed

The two execution paths are separate.

	Plain	Managed
Entry point	`sow create DIR`	`init`, `repo`, `dist`, `add`, `rm`, `build`
State	package directory	`sow.yml` plus private SQLite/journals
Public layout	flat RPM/DEB indexes	Repository `pool/ + dists/`
Formats	RPM and DEB may share one directory	one format per Dist
Architecture views	no	yes
Policy and audit	no	yes
Metadata signing and publication targets	no	yes

Choose Plain when directory contents already equal the desired repository. Choose Managed when SOW must own membership, policy, generations, signing, audit, or publication.

Repository Layout

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

SOW has one fixed Managed layout: package payloads live once under pool/, while dists/ contains metadata-only client views. The complete repository directory is the unit to serve, copy, or publish.

Plain mode

sow create writes indexes next to existing packages and leaves every unrelated file unchanged:

/srv/offline/
├── blackbox_exporter-0.28.0-1.x86_64.rpm
├── libpq5_18.3-1.pgdg12+1_amd64.deb
├── repodata/
│   ├── <sha256>-primary.xml.gz
│   ├── <sha256>-filelists.xml.gz
│   ├── <sha256>-other.xml.gz
│   └── repomd.xml
├── Packages
├── Packages.gz
└── repo_complete                         # only with --pigsty

Flat RPM metadata uses a bare package basename; flat DEB metadata uses ./<filename>. While a build is active, .sow-plain-stage-* contains private generated output. Plain has no durable journal or recovery state; a later create discards stale reserved temporary paths and rebuilds. Never serve or copy those temporary paths.

sow repo

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

A Repository owns one pool/, one dists/, one SQLite database and one private state directory. It is the boundary of locking, transaction recovery, Generation numbering and Changesets — nothing is deduplicated across Repositories and no cross-Repository commit is atomic. sow repo manages that boundary.

Synopsis

sow repo ls [-C DIR] [--json]
sow repo new NAME [-C DIR] [-T DUR | -N] [--json]
sow repo show [NAME] [-C DIR] [-r NAME] [--json]
sow repo migrate [NAME] [--abort] [-j N] [-C DIR] [-r NAME] [-T DUR | -N] [--json]
sow repo rm NAME [-f|--force] [-C DIR] [-T DUR | -N] [--json]

Naming

A Repository name must match [a-z0-9][a-z0-9._-]* and may not be ., .., .sow, pool, dists, or collide with a Workspace reserved file.