SouveraineOS/saf/authority/02-device-state.md

Device state

One machine describes the device's operational state. Evidence enters it, sessiond forms belief, rules choose actions, and executors touch the body. The long design and hardware audit remain in SouveraineOS at docs/DEVICE-STATE-MACHINE.md; this chapter owns the living architecture.

The code is principally src/sessiond/device_state.rs, with ingestion and execution in src/sessiond/server.rs, compositor idle evidence in src/sessiond/idle.rs, and logind lock truth in src/sessiond/lockhint.rs.

State is singular; the panel is orthogonal

The state enum has eight cells:

• Active: interactive and fully awake;
• Dimmed: interactive intent has receded and brightness is reduced;
• Locked: secure session state, without claiming whether the panel is lit;
• Observed: locked but showing a bounded glance because evidence warranted it;
• DozeLight: low-power receptive tier;
• DozeDeep: the deeper low-power tier;
• Suspending: the ordered transition into system sleep;
• Asleep: system sleep as far as this authority can observe it.

Panel on/off is a separate field. Locked + panel off is common and must not be invented as a ninth state; DozeLight is not a synonym for a dark lock screen. Legal transitions are explicit. An action that would skip the graph is refused and recorded rather than coerced into the nearest-looking cell.

Evidence is not authority

Sensors, recognizers, compositor events, logind, and network services submit evidence. They do not each own a private device state. The machine records value, recency, source health, and confidence before it interprets them.

Unknown, Live, Down, and Absent are materially different source states. A quiet proximity sensor and a dead sensor may both produce no new sample, but they cannot support the same decision. Silence is only evidence when a source expected to speak is known healthy.

Confidence combines weighted evidence and falls when sources disagree. It is not a cosmetic number. Until a rule actually branches on its gate, however, the gate is only measured—not enforced. The current machine still has places where confidence is computed and logged without universally deciding the action.

Placement and proximity

Motion alone cannot distinguish pocket, ear, table, or hand. Cross-sensor placement remains ambiguous unless session context resolves it. Proximity uses positive debounce so a noisy edge cannot chatter the device between lock and glance.

Proximity has one real veto: double-tap-to-wake. A near reading can suppress an accidental tap in a pocket. The power button is direct intent and is never vetoed by proximity. Repeated taps open a bounded fail-open path so a stuck sensor cannot permanently make the body unreachable.

This is the general pattern: evidence may lower confidence or constrain an ambiguous gesture; it must not silently overrule an explicit user action.

Lock before blank

Every dark-panel path crosses one function. It requests a lock when needed, waits up to the lock acknowledgement budget for compositor proof, and only then blanks. If the acknowledgement times out, the panel may still fail dark to protect the hardware and power budget, but the authority records error-security and never claims the lock was secure.

Competing writers break this invariant even when their timers happen to be in the right order. Shell timers, hypridle listeners, and stand-alone proximity scripts are therefore not alternate lock or DPMS authorities.

Actions and executors

Rules produce named actions. The current vocabulary includes dim, restore, blank, unblank, volume, window sheet, power menu, power, USB mode, preferred link, tunnel-underlay pinning, and lock. Producing an action does not itself touch hardware. The executor owns side effects and reports the result back into the trail.

Charge now reaches the machine as sensor source/value evidence through sensord. sessiond interprets thresholds and chooses consequences. Bearer selection has not completed the same separation: sessiond still probes bearer state on its own cadence and interprets some of it locally. That is a current divergence, not a second endorsed pattern.

One forensic chronology

The trail is durable, bounded, and hash-chained. It records transitions, actions, refusals, operational failures, and security failures with enough context to reconstruct why the authority acted. The somatic plexus writes its notable events into this same chronology, so the device's mechanical state and the body's believed state can be examined on one clock.

The trail is evidence, not the event bus. The bus may drop transient messages; anything required for audit is written here deliberately.

See belief for the evidence contract and felt state for the somatic side of the same timeline.

What remains open

• light and deep doze exist as states, but their full power-domain actuation and freeze/thaw boundary are not complete;
• confidence gates are not yet authoritative across every relevant rule;
• automatic brightness still lacks its final action and calibration path;
• bearer evidence still crosses an internal probe path instead of arriving wholly through an owning source;
• some source-health and belief machinery is structurally parallel between device state and the somatic plexus rather than one shared Rust type;
• glass-level proof remains required for changes whose correctness depends on compositor acknowledgement, sensor timing, or panel behavior.

Proof

Unit tests prove arithmetic, transition guards, debounce, and pure rules. Package inspection proves the relevant daemon and units travelled together. Only the forensic trail plus observed hardware behavior proves that the body received evidence, chose the action, executed it, and saw the acknowledgement on the intended device.