exlab_wizard.controller.state_machine

Creation-session state machine. Backend Spec §4.7, §4.7.1.

Defines two enums and the mapping/transition tables that govern a CreationController session’s lifecycle:

• SessionState – the internal state the controller drives (Backend Spec §4.7). Includes terminal-error states (FAILED, ABORTED) and the holding state INPUT_REQUIRED that emit no phase WebSocket frame on entry.

• Phase – the externally-emitted phase enum (Backend Spec §4.6.2). Sent over the WS /api/v1/sessions/{id}/events channel on every state transition that has a corresponding phase event.

• state_to_phase() – the §4.7.1 mapping table verbatim. Returns None for transitional / terminal-error states; returns Phase.INPUT_REQUIRED for INPUT_REQUIRED (the API surface encodes this as a kind: "input_required" envelope rather than a phase frame – the helper still emits the phase value so a single switch on state_to_phase can drive both code paths).

• VALID_TRANSITIONS – the per-state outbound transition table per the §4.7 diagram. FAILED and ABORTED are reachable from any non-terminal state (cancel/fail can fire mid-pipeline); the table is hand-written rather than generated to keep the spec ↔ code mapping auditable.

• assert_transition() – guard used by SessionStore and CreationController to reject invalid state transitions (caught by the type system at the API surface; the runtime raise is defensive against logic bugs in the controller’s pipeline).

Functions

assert_transition(current, new_state)	Raise ValueError if current -> new_state is illegal.
state_to_phase(state)	Return the Phase event corresponding to state.

Classes

Phase(*values)	Externally-emitted phase event.
SessionState(*values)	Internal creation-session state.

class exlab_wizard.controller.state_machine.Phase(*values)

Bases: StrEnum

Externally-emitted phase event. Backend Spec §4.6.2.

Sent over the WS /api/v1/sessions/{id}/events channel on every state transition that has a corresponding phase event. The enum values match the spec’s wire-format strings verbatim.

DONE = 'done'

INPUT_REQUIRED = 'input_required'

QUEUEING_NAS_SYNC = 'queueing_nas_sync'

RENDERING_TEMPLATE = 'rendering_template'

RUNNING_PLUGINS = 'running_plugins'

VALIDATING_INPUTS = 'validating_inputs'

VALIDATING_POST_CREATION = 'validating_post_creation'

WRITING_CACHE = 'writing_cache'

class exlab_wizard.controller.state_machine.SessionState(*values)

Bases: StrEnum

Internal creation-session state. Backend Spec §4.7.

Values mirror the §4.7 state-machine diagram. Lower-case strings so JSON encoding is direct (StrEnum makes SessionState.PENDING render as "pending").

ABORTED = 'aborted'

CACHE_WRITE = 'cache_write'

DONE = 'done'

FAILED = 'failed'

INPUT_REQUIRED = 'input_required'

PENDING = 'pending'

PLUGIN_PASS = 'plugin_pass'

POST_VALIDATE = 'post_validate'

RENDERING = 'rendering'

SYNC_QUEUED = 'sync_queued'

VALIDATING = 'validating'

exlab_wizard.controller.state_machine.assert_transition(current, new_state)

Raise ValueError if current -> new_state is illegal.

Defensive guard used by SessionStore.transition and the controller’s pipeline. Backend Spec §4.7 / §4.7.1 are the source of truth for the legal edges; this function consults VALID_TRANSITIONS via the shared exlab_wizard.utils.state.assert_forward_transition() helper.

Parameters:

• current (SessionState)

• new_state (SessionState)

Return type:

None

exlab_wizard.controller.state_machine.state_to_phase(state)

Return the Phase event corresponding to state.

Backend Spec §4.7.1 mapping table. PENDING, FAILED, and ABORTED return None (no phase event). INPUT_REQUIRED returns Phase.INPUT_REQUIRED; the API surface encodes that as a kind: "input_required" envelope rather than a phase frame, but the mapping is preserved so a single dispatch knows the relationship.

Parameters:

state (SessionState)

Return type:

Phase | None