0005. One writer per field: spec by the API, status by the Nereid¶
In short
The API writes spec; each Nereid writes only its own part of status. A field that needs two writers is split. Status: Proposed (2026-10-17).
Status: Proposed (2026-10-17)
Context¶
With Nereids swapped and added at runtime, several processes touch the same objects. When two of them write the same field, the last write wins and the bug shows up far from its cause.
Decision¶
- The API (or the CLI, before the API exists) writes
spec: what was asked. - Each Nereid (its controller) writes only its own part of
status: what it did and what it publishes. When several Nereids look after the same reef side by side, each writes under its own key,status.nereids.<name>. - Choosing which Nereid handles a request is a Mandate's
spec(ADR 0002), written through the API.
Prior art¶
- Kubernetes API conventions, "Spec and Status" (kubernetes/community; Kubernetes objects):
specis the desired state, written by its user, andstatusthe observed state, written by the system; this ADR takes the split as is and adds one key per Nereid understatus. - The controller pattern (Kubernetes, "Controllers"): a control loop that reads the desired state, works towards it and reports what it observes.
Consequences¶
- Every new field is designed with its writer. A field that needs two writers is split.
- Reading
statusis how the API and the CLI learn what a Nereid offers: endpoints, commands (ADR 0004), readiness.
Aligned in wording 2026-10-25 from voice session (reef, Nereid, Mandate, nereus); raw data in Drive #pontos/raw/2026-10-25.