Version: 0.1.0
The kernel state machine defines exactly seven states. A conforming implementation MUST support all states and MUST NOT define additional states.
Description: Kernel is initializing and loading configuration.
Entry Conditions:
- Kernel instantiation
Exit Conditions:
- Configuration loaded successfully → IDLE
- Configuration load failure → HALTED
Invariants:
- No requests SHALL be accepted in BOOTING state
- Duration SHOULD be minimal
Description: Kernel is ready to accept requests.
Entry Conditions:
- Successful boot from BOOTING
- Successful audit completion from AUDITING
Exit Conditions:
- Request received → VALIDATING
- Halt command → HALTED
Invariants:
- Kernel MUST accept requests only in IDLE state
- No pending operations SHALL exist in IDLE state
Description: Kernel is checking request structure and required fields.
Entry Conditions:
- Request submitted from IDLE
Exit Conditions:
- Validation passed → ARBITRATING
- Validation failed → AUDITING (with DENY)
- Fatal error → HALTED
Invariants:
- Validation MUST be deterministic
- Validation MUST NOT have side effects
Description: Kernel is evaluating jurisdiction policy and making decision.
Entry Conditions:
- Validation passed from VALIDATING
Exit Conditions:
- Decision ALLOW with tool_call → EXECUTING
- Decision ALLOW without tool_call → AUDITING
- Decision DENY → AUDITING
- Decision HALT → HALTED
Invariants:
- Arbitration MUST evaluate all policy rules
- Arbitration MUST NOT modify request
Description: Kernel is dispatching tool call and capturing result.
Entry Conditions:
- Decision ALLOW with tool_call from ARBITRATING
Exit Conditions:
- Execution complete → AUDITING
- Execution failure → AUDITING (with error)
- Fatal error → HALTED
Invariants:
- Execution MUST be synchronous
- Execution MUST capture result or error
Description: Kernel is writing audit entry for completed operation.
Entry Conditions:
- Validation failure from VALIDATING
- Arbitration complete from ARBITRATING
- Execution complete from EXECUTING
Exit Conditions:
- Audit entry written → IDLE
- Audit failure → HALTED
Invariants:
- Audit entry MUST be written before state change
- Audit entry MUST include all required fields
Description: Terminal state, no further operations permitted.
Entry Conditions:
- Halt command from any non-terminal state
- Fatal error from any state
- Boot failure from BOOTING
Exit Conditions:
- None (terminal state)
Invariants:
- No operations SHALL be permitted in HALTED state
- HALTED state MUST be irrevocable
The following matrix defines all allowed transitions. An X indicates the transition is allowed.
| From \ To | BOOTING | IDLE | VALIDATING | ARBITRATING | EXECUTING | AUDITING | HALTED |
|---|---|---|---|---|---|---|---|
| BOOTING | - | X | - | - | - | - | X |
| IDLE | - | - | X | - | - | - | X |
| VALIDATING | - | - | - | X | - | X | X |
| ARBITRATING | - | - | - | - | X | X | X |
| EXECUTING | - | - | - | - | - | X | X |
| AUDITING | - | X | - | - | - | - | X |
| HALTED | - | - | - | - | - | - | - |
- A transition MUST NOT occur unless explicitly defined in the transition matrix.
- Every transition MUST produce an audit entry (except BOOTING → IDLE).
- Transitions MUST be atomic with respect to state.
- The HALTED transition MUST be available from any non-terminal state.
- Unhandled exceptions MUST result in transition to HALTED.
- Recoverable errors MUST result in transition to AUDITING with error recorded.
- The kernel MUST NOT remain in an intermediate state after an error.
- Given the same current state and input, the same transition MUST occur.
- Transition selection MUST NOT depend on external factors.
- Time-based decisions MUST use the virtual clock.
┌─────────┐
│ BOOTING │
└────┬────┘
│
success │ failure
┌──────────────┴──────────────┐
▼ ▼
┌─────────┐ ┌─────────┐
┌───►│ IDLE │ │ HALTED │
│ └────┬────┘ └─────────┘
│ │ ▲
│ │ submit() │
│ ▼ │
│ ┌────────────┐ │
│ │ VALIDATING │────────────────────────┤
│ └─────┬──────┘ failure │
│ │ │
│ │ success │
│ ▼ │
│ ┌────────────┐ │
│ │ARBITRATING │────────────────────────┤
│ └─────┬──────┘ HALT │
│ │ │
│ │ ALLOW + tool │
│ ▼ │
│ ┌────────────┐ │
│ │ EXECUTING │────────────────────────┤
│ └─────┬──────┘ failure │
│ │ │
│ │ complete │
│ ▼ │
│ ┌────────────┐ │
└──│ AUDITING │────────────────────────┘
└────────────┘ failure
- Current state MUST be stored in a single location.
- State MUST NOT be inferred from other variables.
- State changes MUST be explicit assignments.
- All state changes MUST go through a transition function.
- The transition function MUST validate the transition is allowed.
- Invalid transitions MUST raise StateError.
- State transitions MUST be serialized.
- Concurrent access to state MUST be prevented.
- A kernel instance MUST NOT be shared across threads without synchronization.