Design Records
Design records explain the choices behind SOW’s repository layout, state model, and publication workflow. Article dates record when a decision was documented; modification dates record later revisions.
Start with these current design explanations:
- System model: packages, Dists, Generations, and targets.
- One package tree: why views share a Pool.
- Publication and recovery: upload order, checkpoints, and cleanup.
- Design principles: state ownership and coordination.
The historical series follows the v0.1 program, its design decisions and tests, the v0.2 reset, and later releases. It links to dated source snapshots. Use SOW Docs for current commands and release notes for version-specific changes.
Coordinated Publication Decision
The v0.4.0 decision to keep SOW's native publication providers, and the earlier rclone proposal that did not ship.
SOW Design Evolution: From Route Graphs to the Repository Core
How SOW moved from the v0.1 distribution platform to a repository engine, and how v0.2 through v0.5 refined that model.
Design Principles
Why SOW separates package storage, repository builds, and publication.
System Model
The objects and state transitions that connect packages, distributions, generations, and publication targets.
Publication & Recovery
How SOW uploads a repository, resumes interrupted publication, and removes unused files.
Why SOW Uses One Payload Tree per Repository
One package pool per repository, with metadata-only distribution views that share its files.
What SOW v0.1 Actually Proved
A summary of 112 dated v0.1 reports covering client compatibility, scale, recovery, migration, and cloud-provider behavior.
The v0.2 Reset: Plain and Managed Instead of a Universal Control Plane
How SOW replaced the v0.1 Git/CAS/Edge platform with two small execution modes, explicit ownership, SQLite state, and a repository-focused release.
SOW v0.1 Decision Ledger: What Survived and What Was Retired
All 44 surviving v0.1 architecture decisions: their original purpose and how each changed after the repository model reset.
The Original SOW v0.1 Program: A Git for Package Repositories
Why SOW began as a Git/CAS/Route/Edge control plane, what that model achieved, and why the product later reset around a smaller Repository core.
-
Coordinated Publication Decision
SOW 0.4.0 kept the native filesystem and r2 publication backends. An earlier proposal used rclone and added remote audit and preview commands. The native design was selected because SOW needs to track each conditional write and its result. Current …
SOW 0.4.0 kept the native filesystem and r2 publication backends. An earlier proposal used rclone and added remote audit and preview commands. The native design was selected because SOW needs to track each conditional write and its result. Current …
-
SOW Design Evolution: From Route Graphs to the Repository Core
SOW moved from a Git-based distribution control plane in v0.1 to a repository engine in v0.2. This article traces that change and the refinements through v0.5.0. Version numbers below refer to released Git tags. Some archived plans used “v0.2” and …
SOW moved from a Git-based distribution control plane in v0.1 to a repository engine in v0.2. This article traces that change and the refinements through v0.5.0. Version numbers below refer to released Git tags. Some archived plans used “v0.2” and …
-
Design Principles
SOW separates package storage, repository builds, and publication. These principles explain where each kind of state belongs and how operations use it. One owner for each record Record Owner Package bytes and identity Repository Desired membership …
SOW separates package storage, repository builds, and publication. These principles explain where each kind of state belongs and how operations use it. One owner for each record Record Owner Package bytes and identity Repository Desired membership …
-
System Model
SOW uses configuration for repository settings, SQLite for managed state, and a public directory for client access. The model separates the packages you select from the files that have been built and published. Objects Workspace ├── Repository │ ├── …
SOW uses configuration for repository settings, SQLite for managed state, and a public directory for client access. The model separates the packages you select from the files that have been built and published. Objects Workspace ├── Repository │ ├── …
-
Publication & Recovery
A build creates a local snapshot (Generation). Publication uploads its files to a target and records progress for recovery. Each target keeps a checkpoint that identifies its last completed publication. State ownership Repository records Target …
A build creates a local snapshot (Generation). Publication uploads its files to a target and records progress for recovery. Each target keeps a checkpoint that identifies its last completed publication. State ownership Repository records Target …
-
Why SOW Uses One Payload Tree per Repository
This decision was drafted on 2026-08-05 and shipped in SOW v0.2.0 on 2026-08-08. SOW 0.5.0 still uses this layout. Each Repository stores one package tree and lets its distribution views reference that tree. Decision Each SOW Repository owns one …
This decision was drafted on 2026-08-05 and shipped in SOW v0.2.0 on 2026-08-08. SOW 0.5.0 still uses this layout. Each Repository stores one package tree and lets its distribution views reference that tree. Decision Each SOW Repository owns one …
-
What SOW v0.1 Actually Proved
The v0.1 archive contains 112 dated reports from 2026-07-11 through July 31. They record client tests, scale measurements, failure recovery, migration, and cloud-provider experiments. This article summarizes the main results and links to …
The v0.1 archive contains 112 dated reports from 2026-07-11 through July 31. They record client tests, scale measurements, failure recovery, migration, and cloud-provider experiments. This article summarizes the main results and links to …
-
The v0.2 Reset: Plain and Managed Instead of a Universal Control Plane
On 2026-07-31, after sealing the v0.1 source baseline, SOW began a product reset. The goal was a small repository engine that could replace Pigsty’s daily package-build workflow. It kept the earlier lessons about integrity and recovery while removing …
On 2026-07-31, after sealing the v0.1 source baseline, SOW began a product reset. The goal was a small repository engine that could replace Pigsty’s daily package-build workflow. It kept the earlier lessons about integrity and recovery while removing …
-
SOW v0.1 Decision Ledger: What Survived and What Was Retired
The v0.1.0 tag contains 44 architecture decision records (ADRs), numbered 0001 through 0045; 0006 is absent. Each ADR records a problem, the decision made at the time, and the conditions that implementation had to meet. This table shows what happened …
The v0.1.0 tag contains 44 architecture decision records (ADRs), numbered 0001 through 0045; 0006 is absent. Each ADR records a problem, the decision made at the time, and the conditions that implementation had to meet. This table shows what happened …
-
The Original SOW v0.1 Program: A Git for Package Repositories
The v0.1 program began on 2026-07-11 and was sealed as v0.1.0 on July 31. It aimed to replace Pigsty’s Makefile-and-rclone workflow with one Go control plane for APT, YUM, and static assets. That control plane covered local state, package history, …
The v0.1 program began on 2026-07-11 and was sealed as v0.1.0 on July 31. It aimed to replace Pigsty’s Makefile-and-rclone workflow with one Go control plane for APT, YUM, and static assets. That control plane covered local state, package history, …