# Desktop Push-to-Talk Architecture

| Field | Value |
|---|---|
| Document type | Architecture |
| Version | 0.9.3 |
| Status | Baseline Candidate |
| Language | English |
| Product | Chanora |
| Date | 2026-05-15 |

Owner-resolved review questions from `gen2/chanora-desktop-ptt-review-summary-v0.9.2.md` are recorded as DEC-023 through DEC-028 in `docs/governance/product-decision-register.md`.

---

## 1. Purpose

Desktop Push-to-Talk (PTT) is the operation by which a user holds a bound keyboard key or mouse button to enable voice transmission and releases it to disable transmission. This document fixes the architecture so the product can describe, implement, verify, and release desktop PTT honestly — every capability claim made to the user is auditable against a live runtime measurement.

The previous architecture treated PTT as a single global behaviour. That over-promised on platforms where the operating system, the user-granted permission set, the display server, or the compositor does not permit unconditional global key capture. This document replaces that with a capability-based model.

## 2. Architectural Decisions

| ID | Decision | Source |
|---|---|---|
| DEC-023 | Windows Global PTT is **P0 / MVP**. | Owner ruling 2026-05-15 |
| DEC-024 | macOS Global PTT is **P0 / MVP** with explicit permission UX flow. | Owner ruling 2026-05-15 |
| DEC-025 | The officially-tested Linux environment for the first public release is **GNOME on Wayland** (only). | Owner ruling 2026-05-15 |
| DEC-026 | Mouse side buttons are **supported** in the first desktop PTT release on Windows and macOS; Linux support follows whatever the GlobalShortcuts portal exposes. | Owner ruling 2026-05-15 |
| DEC-027 | The diagnostic export carries **capability and availability state only** — no raw key codes, scan codes, or virtual-key values ever leave the device. | Owner ruling 2026-05-15 |
| DEC-028 | The **missed-key-up watchdog is P0**: the audio engine shall self-release `transmit_active` if the OS suppresses a key-up event. | Owner ruling 2026-05-15 |

## 3. Capability Ladder

| Level | Name | Meaning |
|---|---|---|
| `L0Focused` | Focused PTT | PTT works only while the Chanora window has input focus. Mandatory on every desktop platform per SysRS-296. |
| `L1GlobalShortcut` | Global shortcut activation | The OS recognises a global accelerator and notifies the application, but hold-to-talk semantics may be approximated rather than guaranteed. |
| `L2GlobalHoldToTalk` | Global hold-to-talk | Press and release events are delivered while the application is not focused. The common Windows / macOS / GNOME-Wayland-portal MVP target. |
| `L3GlobalWithMouseButtons` | Global hold-to-talk plus mouse buttons | Includes mouse side buttons (Mouse4 / Mouse5). |
| `L4DeviceAware` | Device-aware PTT | Backend can distinguish specific input devices. **Reserved.** No MVP implementation produces `L4DeviceAware`. |

The reported capability shall match runtime behaviour. A backend that *could* deliver `L2GlobalHoldToTalk` but lacks the user-granted permission shall report `L0Focused` until permission is granted.

## 4. Component Allocation

```
+------------------------------------+
| Flutter Voice UI                   |
|   PTT binding-capture sheet        |
|   VoiceBar PttCapabilityBadge      |
+---------------+--------------------+
                |
                |  set_binding(...)
                |  events_stream() -> BridgeEvent::PttCapability
                v
+---------------+--------------------+
| chanora_bridge                     |
|   typed DTOs, no key data crosses  |
+---------------+--------------------+
                |
                v
+------------------------------------+
| chanora_core                       |
|   PttController                    |
|     owns Box<dyn DesktopPttBackend>|
|     owns Arc<AudioTransmitGate>    |
|     publishes PttCapabilityLevel   |
|   MissedKeyUpWatchdog (tokio task) |
+---------------+--------------------+
                |
                v
+------------------------------------+
| chanora_audio                      |
|   DesktopPttBackend trait          |
|     WindowsRawInputBackend         |
|     WindowsHookBackend             |
|     MacOSEventTapBackend           |
|     LinuxGnomeWaylandBackend       |
|     FocusedPttBackend              |
|   AudioTransmitGate                |
|   capture_active / transmit_active |
+------------------------------------+
                |
                v
+------------------------------------+
| chanora_diagnostics                |
|   RedactingLogLayer                |
|   PttSanitizer (drops banned keys) |
+------------------------------------+
```

The audio engine reads `transmit_active` once per outbound Opus frame. No code path other than `AudioTransmitGate::set` flips the value.

## 5. Per-Platform Strategy

### 5.1 Windows

Three-level ladder evaluated once at audio-engine start:

1. **`WindowsRawInputBackend`** — preferred. Uses `RegisterRawInputDevices` with `RIDEV_INPUTSINK` to receive keyboard and mouse events even when Chanora is not focused. Runs a message-only window on its own OS thread so the WndProc is non-blocking. Reports `L2GlobalHoldToTalk` (keyboard) or `L3GlobalWithMouseButtons` (when a mouse side button is bound).
2. **`WindowsHookBackend`** — fallback. Installs `WH_KEYBOARD_LL` and `WH_MOUSE_LL` hooks on its own thread. Used when Raw Input registration fails (some constrained environments). Reports `L2GlobalHoldToTalk` / `L3GlobalWithMouseButtons`.
3. **`FocusedPttBackend`** — final fallback. Reports `L0Focused`.

The chosen rung is fixed for the lifetime of the audio engine; restart of the engine re-evaluates the ladder.

### 5.2 macOS

Two-level ladder with explicit permission gating:

1. **`MacOSEventTapBackend`** — preferred when Input Monitoring (or Accessibility, depending on macOS version) permission is `Granted`. Creates a `CGEventTap` on the main run loop, filtered to keyboard and mouse-button events. Reports `L2GlobalHoldToTalk` / `L3GlobalWithMouseButtons`.
2. **`FocusedPttBackend`** — fallback when permission is `Denied`, `Undetermined`, or revoked at runtime. Reports `L0Focused`.

The audio engine starts immediately on user request; the permission state is queried in parallel and the capability level is upgraded asynchronously through `BridgeEvent::PttCapability` if the user grants the permission. This avoids blocking voice functionality on a permission prompt.

### 5.3 Linux

Two-level ladder restricted to the officially-tested environment per DEC-025:

1. **`LinuxGnomeWaylandBackend`** — used when `XDG_SESSION_TYPE=wayland` and the desktop environment is GNOME, **and** the `org.freedesktop.portal.GlobalShortcuts` D-Bus interface is reachable. Calls `CreateSession`, `BindShortcuts` (delegates binding capture to the portal's own dialog), and listens for `Activated` / `Deactivated` signals. Reports `L2GlobalHoldToTalk`; mouse-button support follows whatever the portal exposes for the current session.
2. **`FocusedPttBackend`** — fallback on any other Linux environment (X11, sway, KDE, untested compositor, missing portal). Reports `L0Focused`.

Per DEC-025 the application does **not** claim Global PTT support on an untested Linux environment. The UI capability badge explicitly notes "Focused PTT — untested compositor for Global PTT" when the user runs Chanora outside GNOME-on-Wayland.

## 6. Privacy Rule

Per SysRS-302 and SRS-202:

- Raw key codes, scan codes, virtual-key values, keysyms, and key-press timing sequences shall not be logged, persisted, or included in any user-initiated diagnostic export.
- The `PttSanitizer` log-sink decorator enforces this at write time by inspecting field names and dropping records whose field names match a banned list (`key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence`). The check is structural — it does not rely on a content scan.
- The diagnostic export shall name only the capability level (`PttCapabilityLevel::as_str()`), the backend identifier (a fixed `&'static str` per implementation), and the bound input class (`"keyboard"`, `"mouse-side-button"`).

## 7. Audio Gate Rule

Per SRS-201:

- `capture_active: AtomicBool` is set by the audio engine on input-stream lifecycle transitions (stream opened or closed) and by the platform input-permission state. The PTT subsystem does not write `capture_active`.
- `transmit_active: AtomicBool` lives inside `AudioTransmitGate`. The Opus encoder feed reads it once per outbound frame; the gate is the only mutator path.
- A muted self-input (per `set_input_muted`) forces `transmit_active` to false regardless of the PTT subsystem's wish; this preserves the existing self-mute semantics.

## 8. Missed-Key-Up Watchdog

Per SRS-203 / DEC-028:

- The audio engine spawns one `MissedKeyUpWatchdog` task per audio session.
- It subscribes to `AudioTransmitGate`'s `watch::Receiver<bool>` and notes the timestamp of each `false -> true` transition.
- On each `true -> false` transition it clears the timestamp.
- If a `true` lifetime exceeds the configured ceiling (default 30 s, owner-tunable through a future setting), the watchdog calls `AudioTransmitGate::set(false)` and emits a sanitised diagnostic line naming only the capability level and backend identifier.

## 9. Release Readiness

Per SysDes-148 and the release-readiness record:

- Every release artefact carries a per-platform capability-evidence row listing the detected `PttCapabilityLevel`, the active backend identifier, and whether the Focused fallback was exercised during verification.
- Release notes shall mirror that evidence and shall not over-claim Global PTT support.

## 10. Traceability

```
SysRS-296..302
  -> SysDes-142..148
  -> SRS-195..203
  -> SAD-071..079
  -> SDD-081..092
```

Verification coverage:

```
SDD-081..092 -> SWE4-UV-035..039
SAD-071..079 + SDD-081..092 -> SWE5-IV-015
SRS-195..203 -> SWE6-SV-017
SysDes-142..148 -> SYS4-SIV-016
```

## 11. Change History

| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Initial baseline-candidate architecture for capability-based desktop Push-to-Talk. Codifies the owner rulings for PTT-OPEN-001 through PTT-OPEN-006 as DEC-023 through DEC-028. |