Why start file-backed
A no-database registry is easier to inspect, archive, sign, and move. It is sufficient for an early model-breeding lab if package records are immutable and state transitions are append-only. A database can come later when concurrency and scale require it.
Directory layout
registry/
packages/
package-digest-a/manifest.uai
package-digest-a/scorecard.json
package-digest-a/card.md
states/
active.json
candidate.json
archived.json
retired.json
lineage/
lineage-dag.json
ledger/
decisions.jsonlRegistry operations
| Operation | File effect |
|---|---|
| register candidate | create immutable package folder |
| attach scorecard | add signed evaluator output |
| promote to shadow | append decision ledger and update state file |
| promote to canary | append approval and canary scope |
| retire package | append retirement reason and move state |
| query by capability | read manifests and active state |
API sketch
INTERFACE PopulationRegistry
register_candidate(manifest, artifacts) RETURNS package_id
attach_scorecard(package_id, scorecard) RETURNS evidence_id
set_lifecycle_state(package_id, state, decision_record) RETURNS state_change_id
find_by_capability(capability_id, constraints) RETURNS package_list
get_lineage(package_id) RETURNS lineage_graph
get_active_population(environment_id) RETURNS package_list
END INTERFACEAtomic writes
Every write should be atomic: write to a temporary file, fsync if available, then rename. The decision ledger should be append-only. State files can be derived from the ledger and regenerated if needed.
Migration path
When the file registry becomes too slow, keep the file format as the export format. Move query acceleration into SQLite or another database, but preserve append-only source records so the registry remains auditable.
Source reports used for this guide
These reports are preserved verbatim in the site archive. The guide above is an editorial synthesis and may narrow, qualify, or reorganize claims from the source material.