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/architecture/sysdes.md
+93 -1
View File
@@ -2768,14 +2768,99 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through
- ASPICE SYS.3 alignment: Architecture constraints, communication
- Allocated SysRS: SysRS-295
**SysDes-142**: The desktop Push-to-Talk subsystem shall be allocated to a dedicated **Platform PTT Backend** layer that is selected at runtime per operating system, display server, and granted permission set, with the **Rust Core PTT State Machine** owning the authoritative `transmit_active` flag and the Flutter Voice UI owning the binding-capture UX.
- Status: Baseline Candidate
- Type: Subsystem Allocation
- Stage: P0 / MVP
- Allocated to: Platform Input, Rust Core, Flutter UI, Audio Engine
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: Architecture Review, Platform Test
- Verification owner: Software Architect
- ASPICE SYS.3 alignment: Element decomposition, interface definition
- Allocated SysRS: SysRS-296, SysRS-297
**SysDes-143**: The platform PTT backend layer shall report a typed `PttCapabilityLevel` (`L0` Focused, `L1` Global-shortcut-activation, `L2` Global-hold-to-talk, `L3` Global-with-mouse-buttons, `L4` Device-aware) to the Rust Core, and the Rust Core shall publish the same value to the Flutter UI through the bridge event stream so capability advertising matches actual runtime behaviour.
- Status: Baseline Candidate
- Type: Cross-Subsystem Interface
- Stage: P0 / MVP
- Allocated to: Platform Input, Rust Core, Flutter UI, Bridge
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: Integration Test, Architecture Review
- Verification owner: Software Architect
- ASPICE SYS.3 alignment: Interface definition, consistency
- Allocated SysRS: SysRS-298
**SysDes-144**: The audio capture pipeline shall expose two distinct atomic states: `capture_active` (the input stream is open and frames flow into the encoder feeder) and `transmit_active` (the encoder is producing outbound Opus frames and the protocol layer is forwarding them). The PTT subsystem shall drive `transmit_active` only; `capture_active` shall follow the audio engine lifecycle and the platform input-permission state independently.
- Status: Baseline Candidate
- Type: Subsystem Interface
- Stage: P0 / MVP
- Allocated to: Audio Engine, Rust Core
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: Audio Test, Integration Test
- Verification owner: Audio Owner + Software Architect
- ASPICE SYS.3 alignment: Element behaviour, interface definition
- Allocated SysRS: SysRS-296
**SysDes-145**: The Windows desktop backend shall be allocated to a Raw-Input-first implementation with a low-level-hook fallback and a Focused-PTT terminal fallback. The macOS desktop backend shall be allocated to a permission-aware Global PTT implementation with a Focused-PTT terminal fallback. The Linux desktop backend shall be allocated to a GNOME-on-Wayland portal-based implementation (the officially-tested compositor) with a Focused-PTT terminal fallback on every other Linux environment.
- Status: Baseline Candidate
- Type: Platform Allocation
- Stage: P0 / MVP
- Allocated to: Platform Input
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: Platform Test (Win/macOS/Linux), Architecture Review
- Verification owner: Software Architect + Platform Owners
- ASPICE SYS.3 alignment: Element decomposition, platform mapping
- Allocated SysRS: SysRS-299, SysRS-300, SysRS-301
**SysDes-146**: A **diagnostics sanitizer** shall sit between the platform PTT backend and the application log sink. The sanitizer shall reject any record carrying raw key codes, scan codes, virtual-key values, or key-press timing sequences before the record reaches the in-memory log sink, the platform sink (logcat / fmt / etc.), or the user-initiated diagnostic export pipeline.
- Status: Baseline Candidate
- Type: Cross-Cutting Constraint
- Stage: P0 / MVP
- Allocated to: Diagnostics, Platform Input
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: Privacy Review, Diagnostic Inspection, Unit Test
- Verification owner: Security / Privacy Reviewer
- ASPICE SYS.3 alignment: Architecture constraints, safety / security
- Allocated SysRS: SysRS-302
**SysDes-147**: The Flutter Voice UI shall surface the active PTT capability level and the active backend identifier as user-facing status (capability badge, fallback notice) so the user understands when a Global PTT binding cannot be honoured and a Focused-PTT fallback is in effect.
- Status: Baseline Candidate
- Type: User-Facing Behaviour Allocation
- Stage: P0 / MVP
- Allocated to: Flutter UI
- Downstream artifact: SRS, SAD, SDD, Verification
- Verification method: User Acceptance Test, UI Review
- Verification owner: UX Owner
- ASPICE SYS.3 alignment: Element behaviour
- Allocated SysRS: SysRS-298
**SysDes-148**: The release verification record shall carry per-platform PTT capability evidence (detected `PttCapabilityLevel`, active backend identifier, fallback exercised yes/no) before any release artefact may claim Global PTT support. Release notes shall mirror the actual capability per platform and shall not over-claim.
- Status: Baseline Candidate
- Type: Release Constraint
- Stage: P0 / MVP
- Allocated to: Release / Operations, Verification
- Downstream artifact: Release Readiness Record, Verification
- Verification method: Release Inspection, Architecture Review
- Verification owner: Release Manager
- ASPICE SYS.3 alignment: Architecture constraints
- Allocated SysRS: SysRS-298
## 17. Updated SysRS Coverage Statement
This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-295`.
This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-302`.
| SysRS Range | SysDes Coverage |
|---|---|
| SysRS-001 through SysRS-285 | Covered by inherited SysDes baseline `SysDes-001` through `SysDes-132` |
| SysRS-286 through SysRS-295 | Covered by `SysDes-133` through `SysDes-141` |
| SysRS-296 through SysRS-302 | Covered by `SysDes-142` through `SysDes-148` |
## Baseline Candidate 0.9.1 Update
@@ -2790,3 +2875,10 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate effective date and separated release build SDK compliance from iOS runtime deployment target. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT subsystem allocation SysDes-142 through SysDes-148: Platform PTT Backend layer, typed `PttCapabilityLevel` cross-interface, audio-pipeline split into `capture_active` and `transmit_active`, per-OS backend allocation (Windows Raw-Input ladder, macOS permission-aware, Linux GNOME-Wayland portal), diagnostics sanitizer for raw key events, UI capability badge, release-record evidence requirement. |