Files

T

EdisonJwa 02ffadfa52 docs(ptt): land Baseline Candidate v0.9.3 — capability-based desktop PTT

Applies the gen2 desktop-PTT review summary
(`gen2/chanora-desktop-ptt-review-summary-v0.9.2.md`) to our doc set
with the owner rulings PTT-OPEN-001 through PTT-OPEN-006 resolved as
accepted decisions DEC-023 through DEC-028:

  * DEC-023 Windows Global PTT P0 / MVP
  * DEC-024 macOS Global PTT P0 / MVP with permission UX
  * DEC-025 Linux officially-tested env: GNOME on Wayland only
  * DEC-026 Mouse side buttons supported (Win + macOS; Linux portal)
  * DEC-027 PTT diagnostics: capability + availability only, no
            raw key codes ever
  * DEC-028 Missed-key-up watchdog: P0

Requirements (SysRS / SRS) and architecture (SysDes / SAD / SDD)
gain the desktop-PTT ID set the gen2 summary describes:

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

ID totals advance from 295 / 141 / 194 / 70 / 80 to 302 / 148 / 203
/ 79 / 92. The strict layered sourcing rule (`SRS -> SysDes` only,
`SAD -> SRS` only, `SDD -> SAD` only) is preserved; the
`tools/validate_docs.py` validator reports zero undefined refs and
zero direct-layer-rule violations.

New document:

  * `docs/architecture/desktop-ptt-architecture.md` — capability
    ladder (L0Focused, L1GlobalShortcut, L2GlobalHoldToTalk,
    L3GlobalWithMouseButtons, L4DeviceAware reserved), Windows /
    macOS / Linux strategies, privacy rule, audio-gate rule,
    missed-key-up watchdog, release-readiness evidence requirement,
    traceability summary.

Doc addenda (Baseline Candidate 0.9.3):

  * `privacy/privacy-policy.md` — no raw key history, capability-
    dependent Global PTT, UI reflects actual runtime capability
  * `security/threat-model.md` — THREAT-PTT-001..006
  * `security/diagnostic-redaction-audit-report.md` —
    REDACT-PTT-001..006 banned field list enforced by `PttSanitizer`
  * `release/platform-release-policy.md` — per-platform evidence
    fields, no over-claim on untested Linux compositors
  * `release/release-readiness-go-nogo-record.md` — RR-PTT-001..008
    release-readiness items
  * `verification/swe4-unit-verification-plan.md` —
    SWE4-UV-035..039
  * `verification/swe5-software-integration-verification-plan.md` —
    SWE5-IV-015
  * `verification/swe6-software-verification-plan.md` — SWE6-SV-017
  * `verification/sys4-system-integration-verification-plan.md` —
    SYS4-SIV-016
  * `governance/traceability-matrix.md` — full PTT trace rows +
    verification map
  * `governance/decision-impact-assessment.md` — DEC-023..028
    impact matrix
  * `governance/product-decision-register.md` v0.9.9 entry
    recording DEC-023..028 in the decision table and the status
    table at §7
  * `governance/document-index.md` — adds
    `desktop-ptt-architecture.md` to the controlled set
  * `architecture/proof-of-concept-plan.md` —
    PoC-PTT-001..005 platform items
  * `references/external-references.md` — Windows Raw Input,
    macOS event-tap, Linux GlobalShortcuts portal references
  * Both validation reports
    (`baseline-candidate-validation-report.md`,
    `repo-format-validation-report.md`) bumped to v0.9.3 with the
    new ID totals (302 / 148 / 203 / 79 / 92).

README §"Desktop Push-to-Talk" added between Architecture Overview
and Repository Layout: capability levels, per-platform strategy,
privacy posture, missed-key-up watchdog.

Tooling:

  * `tools/validate_docs.py` copied from the gen2 zip into the
    repo tree (was previously available only inside the zip).
    Reports zero undefined refs, zero direct-layer-rule violations,
    English-only CJK check passes. The 35 "old package-style
    filename" hits are pre-existing and identical to the gen2
    baseline (they live in `path-migration-map.md` and config-ID
    headers of governance docs and are intentional per the path
    migration policy).
  * `.gitignore` adds `/gen2/` so the externally-provided review
    package does not enter the repo.

No code changes in this commit; B (the implementation split into
`transmit_active` / `capture_active`, `PttCapabilityLevel`
reporting, `PttSanitizer` diagnostics rule, and the UI capability
badge) follows in a separate commit.

2026-05-15 14:51:22 +08:00

4.8 KiB

Raw Blame History

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:

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.

4.8 KiB Raw Blame History