Ruohang Feng on SOW

SOW v0.4.0

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

SOW 0.4.0 is an integrity and recovery release for Managed repositories. It makes the deep checker’s I/O contract explicit, prevents RPM trust from being assembled across unrelated keys, adds an audited way to correct mutable publication-target settings, and closes the remaining v0.3 migration and interrupted-publication gaps.

Plain repository behavior and the public pool/ + dists/ layout do not change.

Upgrade from 0.3

Migrate every v0.3 Repository explicitly

Stop all Workspace writers, back up the Workspace, install 0.4.0, and run sow repo migrate REPOSITORY once for each Repository before ordinary reads or writes. The migration is explicit and one-way; do not reopen a migrated database with SOW 0.3.

SOW v0.3.0

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

SOW 0.3.0 is a performance, durability, and product-focus release. Plain repository generation completes with one package-content pass. Managed repositories avoid per-object membership queries, reuse authenticated package facts, and promote payloads in bounded group commits. The shipping binary and its release pipeline are also consolidated around the repository workflows that SOW supports.

Plain: one package-content pass

The default unsigned sow create path hashes and parses each RPM or DEB once, with parallelism controlled by --jobs. Metadata is rendered from the retained inspection result. Before publication, SOW performs one final package-set and file-stat snapshot check, catching concurrent input changes without reading and hashing every package again.

Coordinated Publication Decision

Fri, 14 Aug 2026 00:00:00 +0000

Decision finalized for SOW 0.4.0

An earlier version of this record proposed an rclone executor, publish --dry-run, and a separate sow audit command. None of those surfaces shipped in 0.4.0. SOW has no rclone dependency, publish has no --dry-run, and sow audit is not a command.

This page preserves the decision boundary so a historical proposal cannot be mistaken for the current product. The normative behavior is documented in sow publish and Publication & Recovery.

SOW v0.2.0

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

SOW 0.2.0 is a self-contained RPM and DEB repository manager from Pigsty. Release artifacts target Linux and macOS as single Go executables.

Two operating modes

Plain mode indexes RPM and DEB files already present at one directory’s top level:

sow create /srv/repo

It writes repodata/, Packages, and Packages.gz in place. Plain mode has no Workspace, state database, generations, or DEB Release signing.

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.

Publication & Recovery

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

Building and publishing are separate state transitions. A build produces a target-neutral Generation. Publication applies that Generation to one provider prefix and records enough evidence to recover without guessing.

Ownership split

Repository-scoped	Target-prefix-scoped
Package Object	Publication Attempt
Desired and Built state	Applied Checkpoint
Generation and Changeset	Remote inventory
Retained payload/metadata references	Grace and deletion evidence

The split prevents a successful filesystem publication from being treated as proof about R2, and prevents one target’s partial attempt from contaminating another target.

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.