# Proof-of-Concept Plan

**Document type:** Architecture / Proof-of-Concept Plan  
**Version:** 0.3.0  
**Status:** Draft  
**Language:** English  
**Product:** Chanora  
**Repo path:** `docs/architecture/proof-of-concept-plan.md`

---

## 1. Purpose

This document defines technical proof-of-concept work that should be completed before heavy product implementation.

## 2. Required PoCs

| PoC | Purpose | Exit criteria | Status |
|---|---|---|---|
| Flutter/Rust bridge hello | Prove command/result/event DTO boundary | Flutter can call Rust and receive event stream data | **PASS** — `poc/flutter_rust_bridge_hello/VERIFICATION.md` (Linux desktop, 3/3 tests, 2026-05-13). Closes DEC-014. |
| `tsclientlib` connect spike | Prove protocol feasibility | Rust can connect to a compatible server/test double | **PASS** — `poc/tsclientlib-connect-spike/VERIFICATION.md` (live against `cn.teamspeak.app`, 2026-05-13). |
| Audio capture/playback spike | Prove platform audio behavior | Capture/playback works on at least one desktop and one mobile target | **PASS** — desktop half: `poc/audio-capture-playback-spike/VERIFICATION.md` (Linux/PipeWire, 2026-05-13). Mobile half: `poc/audio-capture-playback-android-spike/VERIFICATION.md` (Android 14 arm64-v8a on a physical Motorola Moto G Stylus 5G, 2026-05-13). Closes DEC-011.1 for desktop + Android; iOS still Deferred. |
| Secure storage spike | Prove secret storage behavior | Secret write/read/delete works through platform secure storage | **PASS (Linux only)** — `poc/secure-storage-spike/VERIFICATION.md` (6/6 audit tests, 2026-05-13). Closes DEC-013.2 (Linux backend policy). |
| SQLite storage spike | Prove local non-secret persistence | Schema, migration, and repository pattern are demonstrated | **PASS** — `poc/sqlite-storage-spike/VERIFICATION.md` (11/11 tests, 2026-05-13). Closes DEC-013.1. |
| Diagnostics redaction spike | Prove redaction before export | Password and identity-secret samples are redacted | **PASS** — `poc/diagnostics-redaction-spike/VERIFICATION.md` (REDACT-TC-001..010, 2026-05-13). |

## 3. PoC Directory

Recommended future location:

```text
poc/
  flutter-rust-bridge-hello/
  tsclientlib-connect-spike/
  audio-capture-playback-spike/
  secure-storage-spike/
  sqlite-storage-spike/
  diagnostics-redaction-spike/
```

## 4. Rule

A PoC is not product code unless explicitly promoted.

## 5. Change History

| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial proof-of-concept plan. |
| 0.2.0 | 2026-05-14 | Recorded PoC outcomes: 5 PASS, 1 PARTIAL PASS (mobile half of audio still open). Added Status column. Spike directories live under `poc/`; see `poc/README.md` and `docs/governance/poc-results-summary.md`. |
| 0.3.0 | 2026-05-14 | Audio PoC promoted from PARTIAL PASS to PASS after `poc/audio-capture-playback-android-spike` verified the mobile half on a physical Android device. All six PoC plan entries are now PASS. iOS is explicitly deferred per DEC-011.1 and remains an open follow-up but is no longer a PoC-plan gap. |


## Desktop Push-to-Talk PoC Items (Baseline Candidate 0.9.3)

| PoC ID | Purpose | Owner | Acceptance |
|---|---|---|---|
| PoC-PTT-001 | Confirm `WindowsRawInputBackend` registers under `RIDEV_INPUTSINK` and forwards key + mouse-button events while Chanora is not focused. | Windows Platform Owner | Live press-release sequence toggles `transmit_active` on a Windows 10/11 reference host with another window focused. |
| PoC-PTT-002 | Confirm `MacOSEventTapBackend` works under granted Input Monitoring permission and degrades to `L0Focused` under denied permission. | macOS Platform Owner | Live measurement on a macOS reference host both before and after granting Input Monitoring; permission revocation degrades capability without crashing. |
| PoC-PTT-003 | Confirm `LinuxGnomeWaylandBackend` binds a shortcut via the GlobalShortcuts portal and receives `Activated` / `Deactivated` signals on a GNOME-on-Wayland reference host. | Linux Platform Owner | Portal dialog accepts a binding; press-release sequence toggles `transmit_active` outside the Chanora window. |
| PoC-PTT-004 | Confirm `PttSanitizer` drops records with banned key field names. | Diagnostics Owner | Unit test passes; manual diagnostic export inspection on a host with PTT bound to a real key shows zero raw key data. |
| PoC-PTT-005 | Confirm `MissedKeyUpWatchdog` clears `transmit_active` after the configured timeout. | Audio Owner | Unit test passes with tokio time paused; integration test on a Windows host where the OS suppresses the key-up event clears within the timeout. |

| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop-PTT PoC items PoC-PTT-001..005 covering Windows Raw Input, macOS Event Tap (permission states), Linux GlobalShortcuts portal, diagnostics sanitizer, and missed-key-up watchdog. |