Design on SOW

Design Principles

Mon, 01 Jan 0001 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 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.

System Model

Mon, 01 Jan 0001 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.

Single-Payload Repository

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

The 0.3 development design changes the physical RPM layout while preserving the ownership model introduced in v0.2. Its objective is precise: within one Repository and within each publish prefix, every live Package Object has exactly one payload path.

Development design

This page describes the implemented 0.3 source layout. The released v0.2 operational reference still describes C2 view-local hardlinks. Read Design Evolution before migrating an existing v0.2 repository.

Canonical tree

<repo>/
├── pool/ # canonical package payloads
│ └── <prefix>/<source>/<filename>
└── dists/ # metadata-only projections
 ├── <rpm-dist>/<arch>/repodata/
 └── <deb-dist>/<component>/binary-<arch>/

There is no canonical release/, reposync/, per-view pool/, per-generation package tree, or snapshot package tree. pool/ + dists/ is the complete relocation and publication unit.

Publication & Recovery

Mon, 01 Jan 0001 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.

Compatibility Boundaries

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

“Compatible” is too broad to be a useful engineering claim. A package may install while a mirror tool refuses the same metadata; a tree may work on POSIX disk while multiplying objects after upload. SOW therefore treats compatibility as a set of independent gates.

The layers

Layer	Question	Required evidence
Format	Is the metadata valid rpm-md / Debian archive syntax?	parser and structural validation
Ordinary client	Can `apt`, `dnf`, or `yum` refresh, resolve, download, verify, and install?	real client run
Mirror tool	Can the named mirror tool materialize the repository safely?	that exact tool and version
Relocation	Does a whole-root copy remain byte-closed and consumable?	copy + manifest + client run
HTTP/proxy	Are relative URLs normalized inside the same prefix without traversal or double encoding?	target HTTP matrix
Storage	Do object identity, conditional operations, listing, caching, and deletion match the state machine?	real provider protocol test

No row inherits PASS from another row or from an earlier Repository layout.

Design Evolution

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

SOW’s old documents came from three materially different systems. Preserving them without a version boundary made contradictory statements look simultaneous. This page keeps the useful decisions while making their scope explicit.

Timeline

Line	Primary problem	Physical model	Disposition
V1 experiment (July 2026)	absorb Pigsty’s existing APT/YUM trees and remote publishing workflow	Git/CAS, route-aware projections, edge/provider contracts	archived research and implementation evidence
v0.2.0	ship a compact local Plain + Managed repository manager	root Pool plus C2 view-local RPM hardlinks	released; operational docs remain live
0.3 development	publish one canonical payload per Repository/target prefix	root Pool plus metadata-only views and target-scoped publication	implemented in source; release evidence pending

What survived V1

The broad V1 program explored repository adoption, remote publication, provider fencing, edge authorization, migration, recovery, and large-repository evidence. Much of its exact Git/CAS/route model was replaced, but several principles survived: