Skip to content

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): spec is the desired state, written by its user, and status the observed state, written by the system; this ADR takes the split as is and adds one key per Nereid under status.
  • 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 status is 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.