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.
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.
-
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: …