# Module State Machine

## Purpose
This document defines the canonical lifecycle for BloxCore modules from physical detection to removal.

## States
1. `Detected`
2. `Seated`
3. `ElectricallyQualified`
4. `Authenticated`
5. `Enumerated`
6. `DriverBound`
7. `Active`
8. `Degraded`
9. `Faulted`
10. `Removed`

## State Definitions

### Detected
The controller has observed physical presence on a slot, but the module is not yet trusted or energized for normal operation.

### Seated
Mechanical alignment and latch state indicate the module is properly seated.

### ElectricallyQualified
The module passes initial electrical checks such as polarity, baseline voltage, and safe attach conditions.

### Authenticated
Required security checks have passed for the module class.

### Enumerated
The descriptor has been read and validated.

### DriverBound
The appropriate userspace service has attached and initialized.

### Active
The module is available to the system and its capabilities are published.

### Degraded
The module is accepted but running with restrictions due to power, thermal, or dependency limits.

### Faulted
The module failed validation or runtime safety checks. It must not be exposed as healthy.

### Removed
The module is no longer present or has been electrically detached.

## Transition Rules
- `Detected -> Seated` only if mechanical seating is confirmed
- `Seated -> ElectricallyQualified` only if attach checks succeed
- `ElectricallyQualified -> Authenticated` only if security policy permits
- `Authenticated -> Enumerated` only if descriptor parsing succeeds
- `Enumerated -> DriverBound` only if a compatible handler is available
- `DriverBound -> Active` only if initialization completes successfully
- `Active -> Degraded` if runtime limits require reduced service
- `Active -> Faulted` if safety or integrity checks fail
- any state -> `Removed` on module removal

## Forbidden Shortcuts
The daemon must never:

- publish capabilities before `Active`
- skip authentication for privileged module classes
- continue powering a module after terminal safety faults

## Logging Requirement
Each transition must emit an event with:

- timestamp
- slot ID
- previous state
- next state
- reason code
- optional policy notes