Mode State Machine Design (v0.1 — Living)

Purpose

Define an explicit, enforceable state machine governing operational modes for a dual-use NixOS system (desktop + AI compute), including states, transitions, guards, and actions.

1. State Definitions

S0: Boot

• Initial system state
• Minimal services active
• Transitions automatically to default mode

S1: Desktop (Dev)

• Interactive workstation mode
• Balanced resource usage
• GUI + audio enabled
• Limited AI workloads allowed

S2: Studio (Audio)

• Strict low-latency mode
• Audio prioritized
• AI workloads disabled or near-zero

S3: Compute (Headless)

• Throughput-oriented mode
• No GUI
• Full AI utilization (multi-GPU)

S4: Transitioning

• Temporary state
• Ensures safe handoff between modes

2. State Diagram

stateDiagram-v2
    [*] --> Boot

    Boot --> Desktop : default

    Desktop --> Studio : enter_studio
    Studio --> Desktop : exit_studio

    Desktop --> Transitioning : to_compute
    Transitioning --> Compute : success
    Transitioning --> Desktop : abort

    Compute --> Transitioning : to_desktop
    Transitioning --> Desktop : success

    Studio --> Desktop : enforced_exit

3. State Properties

Desktop

• GUI: ON
• Audio: ON
• GPU0: Display
• GPU1: AI (optional)
• vLLM: constrained (1 GPU)
• k3s: control plane only

Studio

• GUI: ON
• Audio: RT priority
• GPU0: Display (exclusive)
• GPU1: disabled or minimal
• vLLM: OFF
• k3s: minimal

Compute

• GUI: OFF
• Audio: OFF/minimal
• GPU0 + GPU1: AI
• vLLM: multi-GPU
• k3s: full workloads

4. Transitions

T1: Desktop → Studio

Trigger: user command

Guards:

• No active compute jobs above threshold

Actions:

• Reduce/stop vLLM
• Raise audio priority
• Restrict background jobs

T2: Studio → Desktop

Trigger: user command

Guards: none

Actions:

• Restore normal scheduling
• Allow background workloads

T3: Desktop → Compute

Trigger:

• manual command
• idle-triggered event

Guards:

• No active audio sessions (PipeWire graph empty)
• No REAPER process OR project inactive
• GPU not held by compositor
• CPU load below threshold
• No long-running user jobs

Actions:

1. Notify user (if interactive)
2. Terminate GUI session
3. Wait for GPU release
4. Stop audio services
5. Expand vLLM to multi-GPU
6. Enable compute services (k3s workloads)

T4: Compute → Desktop

Trigger: user command

Guards:

• vLLM can scale down OR be stopped
• GPU memory can be reclaimed

Actions:

1. Drain or stop AI workloads
2. Reduce vLLM to single GPU or stop
3. Start graphical target
4. Reassign GPU0 to display
5. Start audio stack

T5: Studio → Compute

Trigger: (not allowed)

Policy:

• Must transition via Desktop

5. Guards (Detailed)

G1: Audio Idle

• PipeWire graph contains no active nodes
• No JACK clients

G2: GPU Availability

• No compositor process using GPU
• Low GPU utilization

G3: CPU Load

• Load average below threshold (configurable)

G4: User Workload Safety

• No known long-running dev tasks
• Optional: no foreground terminals

G5: Memory Headroom

• Sufficient free RAM for mode switch

6. Actions (Atomic Steps)

A1: Stop GUI

• loginctl terminate-session

A2: Release GPU

• Wait until no graphical processes hold GPU

A3: Adjust Services

• systemd isolate target

A4: Adjust Resource Limits

• Modify cgroups/slices

A5: Scale AI Services

• Adjust CUDA_VISIBLE_DEVICES
• Restart vLLM

7. Failure Handling

Abort Conditions

• Guard failure
• Timeout waiting for GPU release
• Service failure

Behavior

• Log reason
• Return to previous stable state

8. Observability

Required Signals

• Current mode
• Last transition
• Guard evaluation results
• Resource usage snapshot

Interfaces

• CLI: mode status
• Logs: journald

9. Extensibility

Future states may include:

• Maintenance mode
• Remote-only desktop mode
• GPU-partitioned mode

10. Notes

• This state machine should be implemented via systemd targets + controller script
• Transitions must be idempotent
• Guards should be configurable
• Prefer dry-run capability before execution

Summary

This system treats operational modes as a formal state machine with:

• explicit states
• guarded transitions
• deterministic actions

This enables safe coexistence of:

• low-latency desktop workloads
• high-throughput AI services