Design docs

Working documents: the shape of a change and its trade-offs, written before or alongside the code. They are not reference — a design doc can describe something that shipped differently, or has not shipped at all, so check its status line before trusting a detail. Decisions that were made live in decision records; how to run what shipped is the Operator's Manual.

Design	What it covers
Actor model and control plane	Why Orpheus hand-rolls actors on NATS rather than adopting an actor framework, with the survey of eleven that were rejected
Audio-events agent	The PANNs/AudioSet classifier: model choice, the curated class whitelist, and interval post-processing
Cross-classifier identity	Making three classifiers agree that two labels mean one animal — namespaces, the equivalence table, and the layered identity stack
Distributed and config service	Sequencing for splitting Orpheus across hosts, and the backplane as the config source
Distributed deployment	The ops layer for multi-host installs: per-host component sets, the backbone URL, and what a sensor-only host needs
Entity source identity	Grouping observations by source rather than by clock time, so one clip does not collapse into one entity
Event-sourcing determinism contract	What a future rebuild from the event log may and may not reconstruct
Observability and event sourcing	Keeping telemetry out of the detection stream, and what a durable shadow stream would cost
Read-only portal	A public-facing read path: the projection chokepoint, and the replica that keeps browsing off the recording database
Sim test matrix	Testing failure modes against topologies without a field station
Storage retention	One component owning every deletion: ceilings, floors, the free-space reserve, and why floors win