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](../nervous/02-belief.md) for the evidence contract and
[felt state](../nervous/03-felt-state.md) 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.