# Rust Runtime Migration Plan

## Summary

Migrate the non-installer runtime from the current `duo.sh` + Python helper model to a Rust-first architecture with:
- a privileged system daemon as the single source of truth for hardware state and policy
- a small user-session agent for compositor/session-bound actions
- the existing Tauri app refactored into a client of the daemon over a Unix socket API

This is a one-shot cutover, not a staged parity rollout. Installer/setup scripts remain Bash, but they will install and wire up the new Rust binaries/services instead of `duo.sh` and Python helpers.

## Architecture and Key Changes

### 1. Replace `duo.sh` and Python helpers with Rust services

- Rebuild all runtime behavior currently owned by `duo.sh`: dock attach/detach handling, backlight persistence/control, brightness sync, Wi-Fi/Bluetooth state tracking, lock/resume handling, rotation handling, and USB remap lifecycle.
- Fold the three Python helpers into Rust:
  - USB keyboard backlight control into the existing HID/rusb path
  - Bluetooth hidraw backlight control into the existing ioctl HID path
  - brightness key injection into a Rust uinput helper path
- Replace shell-managed state in `/tmp/duo*` with daemon-owned structured runtime state under a new Rust-controlled path; the shell-era temp-file contract is not preserved.

### 2. Introduce two Rust runtime processes

- **System daemon**: owns hardware watchers, state machine, policy, persistence, logging, and privileged operations.
- **User-session agent**: a minimal unprivileged process started per login session that performs GNOME/KDE/Niri display changes and other session-scoped actions on behalf of the daemon.
- The daemon and agent communicate over a local Unix socket contract; the daemon is authoritative and the agent is an executor for session-scoped operations only.

### 3. Refactor the Tauri app into a daemon client

- Move the UI off direct file reads, direct shell control, and direct runtime ownership.
- Replace `status`, control, logs, remap, and event flows with daemon-backed requests and event subscriptions over the Unix socket API.
- Keep the Tauri binary as the UI plus existing privileged helper modes only where still useful during migration; post-cutover, the daemon becomes the runtime authority.
- Profiles/settings remain user-facing concepts in the UI, but application of those settings goes through daemon APIs.

### 4. Preserve backend coverage in the Rust world

- Initial Rust cutover must fully support GNOME, KDE, and Niri.
- Backend-specific display logic currently split across shell helpers becomes Rust-managed backend adapters, with the session agent responsible for invoking the compositor-specific commands/tools inside the user session.
- The system daemon must not directly depend on shell-era display helper scripts after the cutover.

### 5. Installer/setup changes only at the integration boundary

- Keep installer/setup scripts in Bash, but switch them to installing/enabling:
  - the Rust system daemon service
  - the Rust user-session agent service
  - the updated UI/client binary
- Remove installation of Python helpers and `duo.sh` from the target state.
- Preserve simple one-line install/update UX even though the runtime beneath it changes completely.

## Public Interfaces and Contracts

### Unix socket daemon API

Define a structured local API for:
- status snapshot
- control actions: backlight, orientation, display layout, profile activation, service reload/restart-style actions
- settings read/write needed by the UI
- remap control and status
- log/event streaming or polling

The API should be versioned from day one so the UI and daemon can detect mismatches cleanly.

### Session-agent contract

Define a narrow daemon-to-agent contract for:
- apply display layout
- set orientation / rotate modes
- launch session UI actions such as emoji picker
- report execution success/failure and session capability/backends

### Service model

Adopt:
- one systemd **system service** for the daemon
- one systemd **user service** for the session agent
- the Tauri app as an optional client, not a required runtime component

## Test Plan

### Functional parity scenarios

- Boot with keyboard attached and detached
- USB attach/detach transitions
- Bluetooth fallback behavior after detach
- Backlight set/cycle/persist across attach-detach and restart
- Brightness up/down behavior with compositor-native handling
- Wi-Fi/Bluetooth restore behavior across dock transitions
- Lock/unlock and suspend/resume transitions
- Rotation/orientation flows
- USB remap start/stop/pause behavior
- GNOME, KDE, and Niri display reconfiguration paths

### Integration scenarios

- UI connects to daemon, reads status, sends controls, and receives events
- Session agent registration and daemon-to-agent action execution
- Agent absent/unavailable behavior is surfaced clearly without daemon crash
- Service startup ordering and recovery when daemon or agent restarts independently

### Failure-mode coverage

- device disappearance during hotplug
- stale session agent socket
- daemon running without a logged-in agent
- permission/device-open failures
- backend command failures on GNOME/KDE/Niri
- UI/daemon API version mismatch

## Assumptions and Defaults

- Installer/setup scripts stay Bash and are explicitly out of scope for Rust migration except for changing what they install and enable.
- Migration includes replacing `duo.sh`, the three Python helpers, and shell-era runtime file/state ownership.
- This is a one-shot cutover, so the implementation must reach full GNOME/KDE/Niri runtime parity before switching installers/services to the Rust daemon by default.
- The new architecture is intentionally a clean break: no requirement to preserve `/usr/local/bin/duo`, `/tmp/duo*`, or the old CLI/state-file contract.
- The recommended execution order is: implement daemon core first, then session agent, then UI refactor to daemon API, then installer/service cutover, then parity validation across all three backends.