Skip to main content

Module state

Module state 

Source
Expand description

Persistent supervisor state under the operator-local state/headless.json.

§Why persist

Without persistence, a daemon crash-and-respawn would default to “off” — silently reverting the operator’s stated intent. The M2 spec rejects that: if the operator asked for the supervisor to be armed, a restart must reinstate that posture and the operator’s next /headless status must show “started”, not “stopped”.

§Atomic writes

Every state mutation is written via the classic write-to-tempfile + fsync + rename dance. Partial writes on power loss would otherwise leave the daemon with unparseable state, and the honest response to unparseable state is to refuse to start — not a great experience when the alternative is “safely lose the last change”.

§Wire format

The on-disk format is deliberately the same JSON shape as the IPC protocol’s state envelope. An operator who wants to see why the daemon started the way it did can just inspect the operator-local state file instead of learning a second schema.

Structs§

State
Persistent state shape. Kept intentionally small so the file is human-grippable under cat. Additions that don’t alter the supervisor’s recovery behaviour should stay out of this struct and into a sibling file.

Enums§

PersistError

Constants§

MAX_RECENT_ACTIONS
How many recent actions to keep on disk. Spec wants /headless status to be able to show the last 3 under headless_recent_actions; we keep one extra slot as cheap context for debugging without turning the state file into an append-only log.