edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
EdisonJwa
2026-05-15 14:51:22 +08:00
parent b932dc1405
commit 02ffadfa52
26 changed files with 991 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/verification/swe4-unit-verification-plan.md
+43
View File
@@ -356,9 +356,45 @@ Unit verification results shall be summarized in a unit verification summary rep
- Pass criteria: Non-secret storage, secret storage, typed bridge DTOs, and disabled automatic upload/crash behavior match detailed design.
- Evidence: Test result, security review
**SWE4-UV-035**: Verify `DesktopPttBackend` trait + `PttCapabilityLevel` enum + `FocusedPttBackend` units.
- Source SDD: SDD-081, SDD-082, SDD-087
- Verification method: Unit test
- Pass criteria: Trait surface compiles for every implementation; enum `as_str()` mapping is unambiguous; `FocusedPttBackend` reports `L0Focused` and forwards `set_ptt` events into `AudioTransmitGate` unchanged.
- Evidence: Test result
**SWE4-UV-036**: Verify Windows / macOS / Linux platform backend units in isolation.
- Source SDD: SDD-083, SDD-084, SDD-085, SDD-086
- Verification method: Unit test (with mocked OS surfaces), Platform Test (Windows / macOS / GNOME-Wayland reference hosts)
- Pass criteria: Each backend reports the expected `PttCapabilityLevel` for the current host configuration; the ladder falls through to `FocusedPttBackend` when its preferred OS API is unavailable.
- Evidence: Test result, platform-test trace
**SWE4-UV-037**: Verify `PttController` + `AudioTransmitGate` units.
- Source SDD: SDD-088, SDD-089
- Verification method: Unit test
- Pass criteria: `PttController::set_binding` rebinds the active backend without dropping `AudioTransmitGate`; `AudioTransmitGate::subscribe()` returns a `watch::Receiver` that delivers every transition the gate observes.
- Evidence: Test result
**SWE4-UV-038**: Verify `PttSanitizer` and `PttCapabilityBadge` units.
- Source SDD: SDD-090, SDD-091
- Verification method: Unit test, UI review
- Pass criteria: `PttSanitizer` drops records whose field names match the banned list (`key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence`); `PttCapabilityBadge` renders the correct label and explanation sheet for each `PttCapabilityLevel`.
- Evidence: Test result, UI screenshot
**SWE4-UV-039**: Verify `MissedKeyUpWatchdog` unit.
- Source SDD: SDD-092
- Verification method: Unit test (tokio time-paused)
- Pass criteria: After a simulated `false -> true -> (timeout elapsed)` sequence the watchdog calls `AudioTransmitGate::set(false)` exactly once and emits a sanitised diagnostic record naming only `capability_level` and `backend_id`.
- Evidence: Test result
| SDD Range | SWE.4 Coverage |
|---|---|
| SDD-071 through SDD-080 | SWE4-UV-031 through SWE4-UV-034 |
| SDD-081 through SDD-092 | SWE4-UV-035 through SWE4-UV-039 |
## Baseline Candidate 0.9.1 Update
@@ -373,3 +409,10 @@ Unit verification results shall be summarized in a unit verification summary rep
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT unit-verification items SWE4-UV-035 through SWE4-UV-039: `DesktopPttBackend` trait + `PttCapabilityLevel`, platform backends, `PttController` + `AudioTransmitGate`, `PttSanitizer` + `PttCapabilityBadge`, `MissedKeyUpWatchdog`. |
docs/verification/swe5-software-integration-verification-plan.md
+22
View File
@@ -210,6 +210,21 @@ Software integration verification results shall be summarized in an integration
| SAD-061 through SAD-070 | SWE5-IV-014 |
| SDD-071 through SDD-080 | SWE5-IV-014 |
**SWE5-IV-015**: Verify integrated desktop PTT subsystem (audio engine, Rust core PTT controller, bridge, Flutter UI, diagnostics).
- Source SAD: SAD-071 through SAD-079
- Source SDD: SDD-081 through SDD-092
- Verification method: Software integration test on every supported desktop reference host (Windows, macOS, GNOME-on-Wayland Linux)
- Pass criteria: For each platform the live measurement of `PttCapabilityLevel` and `backend_id` matches the design expectation; pressing the bound input toggles `transmit_active` end-to-end; the missed-key-up watchdog clears `transmit_active` after the configured timeout; the user-initiated diagnostic export does not contain raw key data; the UI capability badge matches the active capability.
- Evidence: Integration test trace, diagnostic-export inspection, UI screenshot
| Architecture / Design Area | SWE.5 Coverage |
|---|---|
| SAD-061 through SAD-070 | SWE5-IV-014 |
| SDD-071 through SDD-080 | SWE5-IV-014 |
| SAD-071 through SAD-079 | SWE5-IV-015 |
| SDD-081 through SDD-092 | SWE5-IV-015 |
## Baseline Candidate 0.9.1 Update
@@ -223,3 +238,10 @@ Software integration verification results shall be summarized in an integration
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT software-integration verification item SWE5-IV-015 covering the integrated audio engine + Rust core PTT controller + bridge + Flutter UI + diagnostics path on Windows, macOS, and GNOME-on-Wayland Linux reference hosts. |
docs/verification/swe6-software-verification-plan.md
+19
View File
@@ -209,6 +209,18 @@ Software verification results shall be summarized in a software verification sum
|---|---|
| SRS-185 through SRS-194 | SWE6-SV-016 |
**SWE6-SV-017**: Verify integrated software behaviour for desktop Push-to-Talk against SRS-195 through SRS-203.
- Source SRS: SRS-195, SRS-196, SRS-197, SRS-198, SRS-199, SRS-200, SRS-201, SRS-202, SRS-203
- Verification method: Software verification test (end-to-end) on Windows, macOS, GNOME-on-Wayland reference hosts
- Pass criteria: PTT trait abstraction is platform-agnostic from the caller's perspective; reported capability level equals live runtime behaviour; Windows ladder degrades correctly when Raw Input is denied; macOS Global ↔ Focused toggles with permission state changes; Linux honours portal availability; mouse-side-button binding works where the backend exposes it; `capture_active` and `transmit_active` are independently observable; diagnostic export contains zero raw key data; missed-key-up watchdog clears `transmit_active` after the configured timeout.
- Evidence: SWE.6 test report
| SRS Range | SWE.6 Coverage |
|---|---|
| SRS-185 through SRS-194 | SWE6-SV-016 |
| SRS-195 through SRS-203 | SWE6-SV-017 |
## Baseline Candidate 0.9.1 Update
@@ -222,3 +234,10 @@ Software verification results shall be summarized in a software verification sum
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT software-verification item SWE6-SV-017 covering end-to-end SRS-195..203 verification across Windows, macOS, and GNOME-on-Wayland Linux reference hosts. |
docs/verification/sys4-system-integration-verification-plan.md
+19
View File
@@ -226,6 +226,18 @@ System integration verification results shall be summarized in a system integrat
|---|---|
| SysDes-133 through SysDes-141 | SYS4-SIV-015 |
**SYS4-SIV-016**: Verify integrated system-level desktop Push-to-Talk behaviour against SysDes-142 through SysDes-148.
- Source SysDes: SysDes-142, SysDes-143, SysDes-144, SysDes-145, SysDes-146, SysDes-147, SysDes-148
- Verification method: System integration verification on Windows, macOS, GNOME-on-Wayland reference hosts
- Pass criteria: Platform PTT Backend layer is the only surface generating PTT state transitions; `PttCapabilityLevel` and `backend_id` propagate from backend through Rust Core through bridge to Flutter UI without modification; `transmit_active` and `capture_active` are observably independent at the system boundary; diagnostics sanitizer rejects raw key payloads; UI capability badge matches the active capability; release readiness record carries the live-measurement evidence per RR-PTT-001..008.
- Evidence: SYS.4 verification report
| SysDes Range | SYS.4 Coverage |
|---|---|
| SysDes-133 through SysDes-141 | SYS4-SIV-015 |
| SysDes-142 through SysDes-148 | SYS4-SIV-016 |
## Baseline Candidate 0.9.1 Update
@@ -239,3 +251,10 @@ System integration verification results shall be summarized in a system integrat
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT system-integration verification item SYS4-SIV-016 covering SysDes-142..148 across Windows, macOS, and GNOME-on-Wayland Linux reference hosts. |