spencer237

"""Handler for discovery.enrollment messages from CMS.

Validates the incoming signed envelope (HMAC + ts window + nonce replay),
extracts the PiEnrollmentPayload fields, and plans the side effects. The
module is pure: it never writes to disk, runs SAS commands, or publishes
MQTT itself. The caller (wiring layer in mqtt/client/thread.py) reads
``EnrollmentPlan`` and performs the apply steps in order.

Apply order expected from the caller (when plan.valid is True):
1. Write runtime.env with plan.runtime_env_updates (atomic, persistent).

spencer237

"""Wiring glue between MQTT _on_message and the enrollment_handler/apply pair.

This module is the ONE entry point invoked by ``mqtt/client/thread.py``
when an ``discovery/{device_uid}/enrollment`` message arrives. It:

1. Decodes the JSON payload (rejects non-object).
2. Loads the Pi's persistent state (or builds an ephemeral fallback).
3. Auto-transitions BLANK → BOOTSTRAPPED → DISCOVERABLE if needed, so a
   freshly imaged Pi receiving its first enrollment can accept it
   (state.json is wiped by smc-clone-hygiene on every boot until we