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/requirements/srs.md
+89
View File
@@ -2506,12 +2506,94 @@ This section extends the ASPICE SWE.1 Software Requirements Specification. The s
- Source SysDes: SysDes-141
- Verification method: Privacy Review, Security Audit
**SRS-195**: The software shall expose a `DesktopPttBackend` trait owned by the audio subsystem, with one implementation per supported desktop platform (Windows, macOS, Linux/GNOME-Wayland) and a `FocusedPttBackend` implementation used as the universal terminal fallback. The selected backend shall be discoverable at runtime and shall report its identifier through the diagnostics sanitizer.
- Status: Baseline Candidate
- Type: Software Interface Requirement
- Stage: P0 / MVP
- Allocated to: Audio, Platform Input
- Source SysDes: SysDes-142, SysDes-145
- Verification method: Architecture Review, Unit Test
**SRS-196**: The software shall publish a `PttCapabilityLevel` enum value (`L0` Focused, `L1` Global-shortcut-activation, `L2` Global-hold-to-talk, `L3` Global-with-mouse-buttons, `L4` Device-aware) from the active backend, and the value shall match the actual runtime capability rather than the platform's theoretical maximum.
- Status: Baseline Candidate
- Type: Software Behavioural Requirement
- Stage: P0 / MVP
- Allocated to: Audio, Rust Core
- Source SysDes: SysDes-143
- Verification method: Unit Test, Integration Test
**SRS-197**: The Windows desktop backend shall attempt Raw Input first; if Raw Input is unavailable or initialisation fails, it shall attempt a low-level keyboard hook; if that also fails it shall return `PttCapabilityLevel::L0` and engage Focused PTT. The selected sub-strategy shall be recorded as the backend identifier for diagnostics and release verification.
- Status: Baseline Candidate
- Type: Platform Behavioural Requirement
- Stage: P0 / MVP
- Allocated to: Audio (Windows)
- Source SysDes: SysDes-145
- Verification method: Platform Test (Windows), Unit Test
**SRS-198**: The macOS desktop backend shall query the operating-system Input Monitoring / Accessibility permission state, return `PttCapabilityLevel::L0` while the permission is undecided or denied, and upgrade to the appropriate Global level only after the user grants the required permission. The user shall be able to dismiss the permission prompt and continue using Focused PTT without functional regression.
- Status: Baseline Candidate
- Type: Platform Behavioural Requirement
- Stage: P0 / MVP
- Allocated to: Audio (macOS)
- Source SysDes: SysDes-145
- Verification method: Platform Test (macOS), User Acceptance Test
**SRS-199**: The Linux desktop backend shall probe the active display server and compositor at runtime. On GNOME-on-Wayland (the officially-tested target per DEC-026), the backend shall use the freedesktop GlobalShortcuts portal. On any other Linux environment the backend shall return `PttCapabilityLevel::L0` and engage Focused PTT.
- Status: Baseline Candidate
- Type: Platform Behavioural Requirement
- Stage: P0 / MVP
- Allocated to: Audio (Linux)
- Source SysDes: SysDes-145
- Verification method: Platform Test (Linux, GNOME Wayland), Unit Test
**SRS-200**: The software shall support mouse side buttons (typically labelled Mouse4 / Mouse5 or "back" / "forward") as bindable inputs for Global PTT on the Windows and macOS backends per DEC-027. The Linux GlobalShortcuts portal binding shall accept whatever input classes the portal exposes for the current session; missing mouse-button support shall not block release.
- Status: Baseline Candidate
- Type: Platform Behavioural Requirement
- Stage: P0 / MVP
- Allocated to: Audio (Windows/macOS/Linux)
- Source SysDes: SysDes-142, SysDes-145
- Verification method: Platform Test, User Acceptance Test
**SRS-201**: The audio engine shall expose `capture_active` and `transmit_active` as independent atomic states. `capture_active` shall reflect the input-stream lifecycle and the platform input-permission state; `transmit_active` shall reflect the PTT subsystem's decision and shall be the only gate on outbound Opus frame emission.
- Status: Baseline Candidate
- Type: Software Interface Requirement
- Stage: P0 / MVP
- Allocated to: Audio
- Source SysDes: SysDes-144
- Verification method: Unit Test, Integration Test
**SRS-202**: The diagnostics subsystem shall reject any log record carrying a raw key code, scan code, virtual-key value, or key-press timing sequence. The diagnostic export shall include the active `PttCapabilityLevel`, the active backend identifier, and the bound input class (for example "keyboard", "mouse-side-button") but shall never include the specific key value of any user binding.
- Status: Baseline Candidate
- Type: Software Privacy Requirement
- Stage: P0 / MVP
- Allocated to: Diagnostics, Audio
- Source SysDes: SysDes-146
- Verification method: Privacy Review, Unit Test, Diagnostic Inspection
**SRS-203**: The software shall implement a missed-key-up watchdog per DEC-028: if `transmit_active` has been true for longer than a configured upper bound without a corresponding release event (for example because the OS suppressed the key-up while the application was minimised), the watchdog shall force `transmit_active` to false and emit a sanitised diagnostic record naming only the capability level and backend identifier.
- Status: Baseline Candidate
- Type: Software Safety Requirement
- Stage: P0 / MVP
- Allocated to: Audio
- Source SysDes: SysDes-142, SysDes-144
- Verification method: Unit Test, Integration Test
## 17. Updated SRS to SysDes Coverage Statement
| SysDes Range | SRS Coverage |
|---|---|
| SysDes-001 through SysDes-132 | Covered by inherited SRS baseline `SRS-001` through `SRS-184` |
| SysDes-133 through SysDes-141 | Covered by `SRS-185` through `SRS-194` |
| SysDes-142 through SysDes-148 | Covered by `SRS-195` through `SRS-203` |
## Baseline Candidate 0.9.1 Update
@@ -2526,3 +2608,10 @@ This section extends the ASPICE SWE.1 Software Requirements Specification. The s
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate effective date and preserved SRS direct-source rule through SysDes only. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT software requirements SRS-195 through SRS-203: `DesktopPttBackend` trait + per-platform implementations, `PttCapabilityLevel` enum, Windows Raw-Input ladder, macOS permission-aware backend, Linux GNOME-Wayland GlobalShortcuts portal backend, mouse-side-button support per DEC-027, `capture_active` / `transmit_active` split, sanitised diagnostics, missed-key-up watchdog per DEC-028. Sourcing remains strict (`SRS -> SysDes` only). |
docs/requirements/sysrs.md
+41
View File
@@ -1889,6 +1889,41 @@ This section converts the baseline product decisions into auditable system-level
- Priority: P0
- Verification: Privacy Review, Security Audit
**SysRS-296**: The Chanora desktop application shall support **Focused Push-to-Talk** on Windows, macOS, and Linux. Focused PTT is the minimum required behaviour: the user shall be able to hold a bound input (keyboard key, mouse button) inside the focused Chanora window to enable voice transmission, and release of that input shall disable voice transmission.
- Priority: P0
- Verification: Platform Test, User Acceptance Test
**SysRS-297**: The Chanora desktop application shall additionally support **Global Push-to-Talk** where the operating system, the user-granted permission set, the display server, and the available input backend together permit it. Where global PTT is not available, the application shall fall back to Focused PTT without claiming Global PTT support.
- Priority: P0
- Verification: Platform Test, Architecture Review
**SysRS-298**: The detected desktop PTT capability level shall be exposed to the user interface and to the release verification record. The exposed value shall match the actual runtime capability — the application shall not advertise a Global PTT level when the active backend is the Focused fallback.
- Priority: P0
- Verification: Integration Test, Release Inspection
**SysRS-299**: The Chanora Windows desktop application shall prefer the Raw Input backend for Global PTT, with a low-level keyboard hook used only as a fallback when Raw Input is unavailable, and Focused PTT used as the final fallback when no Global PTT backend can be initialised.
- Priority: P0
- Verification: Platform Test (Windows), Architecture Review
**SysRS-300**: The Chanora macOS desktop application shall request the operating-system permission required for Global PTT (Input Monitoring / Accessibility), use the permission-aware Global PTT backend when the permission is granted, and fall back to Focused PTT when the permission is denied, revoked, or not yet decided. The application shall not block voice functionality while the user decides on the permission prompt.
- Priority: P0
- Verification: Platform Test (macOS), User Acceptance Test
**SysRS-301**: The Chanora Linux desktop application shall use a capability-dependent Global PTT backend selected from the available display server (X11 or Wayland) and compositor support (GNOME on Wayland is the officially-tested target for the first public release per DEC-026; other compositors fall back to Focused PTT). The application shall not claim Global PTT support on an untested Linux environment.
- Priority: P0
- Verification: Platform Test (Linux, GNOME Wayland), Architecture Review
**SysRS-302**: The Chanora application system shall not log, store, persist, or include in the user-initiated diagnostic export any raw desktop key-event history, key code stream, or key-press timing sequence. Diagnostic export may include the detected PTT capability level, the active backend identifier, and the bound input class (for example "keyboard", "mouse-side-button"), but shall not include the specific key code, scan code, or virtual-key value of any user binding.
- Priority: P0
- Verification: Privacy Review, Security Audit, Diagnostic Inspection
## 32. Change History Addendum
@@ -1902,3 +1937,9 @@ This section converts the baseline product decisions into auditable system-level
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate effective date to 2026-04-28 and propagated distinction between runtime deployment target and build-SDK upload gate. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop Push-to-Talk requirements SysRS-296 through SysRS-302: mandatory Focused PTT on Windows/macOS/Linux, capability-dependent Global PTT, capability-level exposure to UI and release record, Windows Raw Input + low-level-hook + Focused fallback ladder, macOS permission-aware Global PTT, Linux capability-dependent Global PTT (GNOME on Wayland officially-tested per DEC-026), and the privacy rule prohibiting raw key-event history in logs and diagnostic exports. Owner-resolved gen2 review questions PTT-OPEN-001..006 land as DEC-023..028 in the product decision register. |