SOW Blog on SOW

SOW v0.5.0

Vonng — Tue, 29 Sep 2026 00:00:00 +0800

SOW 0.5.0 focuses on adopting SOW for existing flat YUM repositories. The main addition is sow create --metadata-timestamp SECONDS: publishers can retain a valid publication time when replacing another metadata generator, including repositories used by EL7 YUM clients.

See Download SOW for installation options and the upgrade guide for an existing workspace.

Publication time for an existing YUM repository

EL7 YUM compares the largest metadata timestamp in a downloaded repomd.xml with its cached copy. If the new index has an older timestamp, YUM can reject it and retain the cached index. A new checksum, a different revision, or a newer file modification time does not satisfy this comparison.

SOW v0.4.0

Vonng — 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

Vonng — 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

Vonng — 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

Vonng — 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

Vonng — 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 detailed history is preserved in four companion records:

Publication & Recovery

Vonng — 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

Vonng — 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

Vonng — 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

Vonng — 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.

The v0.2 Reset: Plain and Managed Instead of a Universal Control Plane

Vonng — Fri, 31 Jul 2026 00:00:00 +0000

Development-line versus release version

The archived “v0.2” design line initially used C2 view-local RPM hardlinks. That was a real development implementation, but it was replaced by the single-payload design before the final v0.2.0 tag. The released v0.2.0 layout already used one canonical Pool and metadata-only views.

Several archived v0.2/v0.3 files nevertheless say “v0.2.0” used C2 hardlinks. They were written before the tag existed and used “v0.2.0” for the planned build. The delivered boundary is defined by the final 0.2.0 Changelog, release note, and source tag, all of which record one canonical Pool and metadata-only views.

What SOW v0.1 Actually Proved

Vonng — Fri, 31 Jul 2026 00:00:00 +0000

Version-bound evidence

Every result on this page belongs to the v0.1 source, layout, fixtures, and environment recorded at the time. It does not establish compatibility or release readiness for current SOW.

The v0.1 archive contains 112 dated evidence reports from 2026-07-11 through 2026-07-31. Publishing all of them as blog posts would make the public site less useful: many are narrow fault closures, repeated current-source audits, or transcripts for a specific implementation seam.

SOW v0.1 Decision Ledger: What Survived and What Was Retired

Vonng — Sun, 12 Jul 2026 00:00:00 +0000

Historical decision ledger

The v0.1.0 tag contains 44 ADR files numbered 0001 through 0045; 0006 is absent. This page preserves their meaning without republishing each historical implementation contract as current guidance.

An ADR is valuable even when its implementation is retired. It records the failure mode the team refused to ignore, the boundary selected at the time, and often the evidence required before a dangerous operation could proceed.

The Original SOW v0.1 Program: A Git for Package Repositories

Vonng — Sat, 11 Jul 2026 00:00:00 +0000

Historical design record

This article describes the v0.1 program initiated on 2026-07-11 and sealed in the v0.1.0 source baseline on 2026-07-31. The Git/CAS/Route/Edge product model is retired. Current behavior is defined by SOW Docs and the maintained System Model.

SOW did not begin as a small repository indexer. The original goal was to replace a large Pigsty Makefile-and-rclone workflow with one Go control plane for APT, YUM, and static assets. It would own local state, package lifecycle, upstream synchronization, channels, views, snapshots, publication to two independent clouds, CDN behavior, commercial access control, migration, recovery, and verification.