Control Plane

Status: living

The control plane reconciles requested mode intent with runtime facts. It is a local privileged authority, not a convenience shell script.

Authority Model

V1 decision:

transition execution is privileged
the initial operator path is sudo mode request <mode> or a root-owned mode-controller@.service
unprivileged users must not mutate observed state or forge transition success

Future options:

polkit-mediated request path
local service endpoint
richer automation integration

Those options should not be added until the root/sudo path proves the control loop on the target host.

State Model

Live state lives under /run/mode-controller:

desired
current
lock
last-transition.json
last-guards.json
capability-placement.json
hardware-topology.json

Persistent transition history lives under:

/var/lib/mode-controller/events.jsonl

Each line is an append-only JSON event emitted by the reconciler. Initial event types:

transition

Initial event fields:

timestamp
requested
prior
final
success
reason

This event stream is intended to become the basis for:

audit history
degraded transition diagnosis
future reconciliation analytics
operator replay/debug tooling
higher-level memory/context systems

V1 accepts plain desired and current files for the first bootable milestone. The hardening path is either:

migrate to desired.json and current.json, or
explicitly document the plain-text files as stable interface and keep structured metadata in transition records.

When impermanence is introduced, the persistent event path can be mapped to:

/persist/var/lib/mode-controller/events.jsonl

Reconciliation Sequence

Every requested transition follows this sequence:

acquire lock
observe current state
validate requested target
validate capability placement
run guards
execute bounded actions
re-observe
classify final state
record guard, action, timing, and outcome data
release lock

If target predicates fail after mutation, the controller must attempt rollback, classify a degraded state, or report failed-transition.

Observer Contract

The observer must derive current state from evidence only. It must not trust desired state as proof of success.

Required output fields for JSON mode:

{
  "observed_state": "desktop",
  "confidence": "high",
  "degraded": false,
  "signals": {},
  "conflicts": [],
  "timestamp": "..."
}

Required signal families:

graphical session presence
compositor/display-manager state
compute.target
vllm.service
studio-local-policy.service
PipeWire/JACK/REAPER indicators
GPU process/VRAM evidence when available
controller lock/transition marker
latest failed transition marker

Conservative rule: report unknown, transitioning, degraded-*, or failed-transition instead of pretending a stable target has been reached.

Guard Contract

Guards are small deterministic checks with stable exit classes:

0     pass
10-19 policy block
20+   execution error

Initial guard set:

check_target_reachable
check_audio_idle
check_graphical_session_terminable
check_gpu_display_released
check_vllm_drainable
check_compute_capability_local
check_studio_capability_local
check_memory_headroom
check_persistence_paths_ready

Each guard should emit a reason code and evidence payload suitable for mode explain and transition logs.

Failure Semantics

Blocked transition:

a guard returns a policy block
desired state may remain requested
current state must not be rewritten to target

Execution error:

a guard or action could not run reliably
target should not be considered safe

Degraded state:

system is usable but does not satisfy all target guarantees
must be surfaced directly in status

Failed transition:

no stable or acceptable degraded contract could be established
rollback failed or final observation remained unsafe/conflicted

Keyboard shortcuts