Design Records
Design records explain why SOW adopted a contract, what it rejected, and which evidence
boundary applies. They are ordered by date, which records when the rationale first took
its maintained form; lastmod records later editorial or implementation-alignment
updates. Release notes and source tags remain authoritative for when behavior actually
shipped.
The Design History records distill the original v0.1 program, its 44 surviving ADR files, 112 dated evidence reports, and the v0.2 reset into a small maintained narrative. Raw planning prompts, reviews, and transcripts stay available through immutable source tags and commits; they are primary sources, not a second documentation hierarchy.
Authority and evidence
This column is the maintained authority for design rationale and decision history. Current commands, configuration, and operator behavior remain in SOW Docs; exact behavior of a historical release remains attached to that release’s source tag and release note.
Each operational claim should match the evidence layer it has actually reached:
Passing one layer does not imply the next. The platform and integration reference records the automated client, Provider, and filesystem coverage; release artifacts are a separate delivery gate.
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 v0.1 was retired, v0.2 shipped the single-payload Repository core, and v0.3-v0.4 hardened it.
Design Principles
The invariants SOW uses to keep ownership, generated state, publication, and evidence understandable.
System Model
The objects and state transitions that connect packages, distributions, generations, and publication targets.
Publication & Recovery
The target-scoped state machine for publishing, recovering, retaining, and safely deleting repository objects.
Why SOW Uses One Payload Tree per Repository
The decision to replace RPM view-local package hardlinks with one canonical pool and metadata-only views.
What SOW v0.1 Actually Proved
A curated account of 112 dated v0.1 evidence reports: the real clients, scale, failure, migration, and provider claims they supported—and what they never proved.
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
A curated ledger of all 44 surviving v0.1 ADR files, the problem each addressed, and whether its decision survived, evolved, became migration-only, or retired with V1.
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
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 …
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 Design Evolution: From Route Graphs to the Repository Core
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 …
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 …
-
Design Principles
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 …
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 …
-
System Model
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 ├── …
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 ├── …
-
Publication & Recovery
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 …
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 …
-
Why SOW Uses One Payload Tree per Repository
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: …
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: …
-
What SOW v0.1 Actually Proved
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 …
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 …
-
The v0.2 Reset: Plain and Managed Instead of a Universal Control Plane
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 …
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 …
-
SOW v0.1 Decision Ledger: What Survived and What Was Retired
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 …
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 …
-
The Original SOW v0.1 Program: A Git for Package Repositories
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 …
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 …