Design Principles
The invariants SOW uses to keep ownership, generated state, publication, and evidence understandable.
Design
The architectural decisions behind SOW: ownership, repository layout, publication, compatibility, and version evolution.
This section records the reasoning that should survive an implementation rewrite: where SOW draws ownership boundaries, which invariants make a repository safe to copy and publish, and why a compatibility choice was accepted or rejected.
Version boundary
The operational guides and CLI reference on this site describe the released v0.2.0 line. These design pages also document the implemented 0.3 development architecture. They label the boundary explicitly; a development design is not a release or compatibility claim.
Design PrinciplesThe small set of invariants that decide what SOW owns, what can be rebuilt, and what must
fail closed.
System ModelWorkspace, Repository, Dist, Package Object, Membership, Generation, and publication
target — and why each has a separate owner.
Single-Payload LayoutWhy 0.3 keeps one canonical package path per Repository while rendering metadata-only
APT and RPM views.
Publication & RecoveryPointer-last publication, commit intent, forward recovery, retained generations, and
evidence-gated garbage collection.
Compatibility BoundariesSeparate protocol, client, mirror-tool, filesystem, HTTP, and object-storage compatibility
instead of hiding them behind one green check mark.
Design EvolutionHow the V1 experiment, v0.2 C2 hardlink layout, and 0.3 single-payload layout relate —
including the decision that 0.3 deliberately reverses.
Authority and evidence
These pages are the maintained design authority. Historical PRDs, review transcripts, ADRs, and dated acceptance reports are preserved in the source repository’s sealed archive. They remain evidence for the version and environment they name, but they do not silently redefine the current product.
A claim progresses through distinct layers:
design contract -> source implementation -> focused tests -> real client/provider evidence -> release
Passing an earlier layer never implies that a later one passed. The compatibility design and each release note state the highest verified layer explicitly.
System Model
The objects and state transitions that connect packages, distributions, generations, and publication targets.
Single-Payload Repository
How the 0.3 design keeps one canonical package path per Repository and renders metadata-only APT and RPM views.
Publication & Recovery
The target-scoped state machine for publishing, recovering, retaining, and safely deleting repository objects.
Compatibility Boundaries
How SOW separates protocol correctness, client behavior, mirror tools, relocation, HTTP normalization, and storage-provider semantics.
Design Evolution
The path from the V1 repository experiment through v0.2 C2 views to the 0.3 single-payload architecture.