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

16 KiB

Raw Blame History

Chanora SWE.4 Software Unit Verification Plan

Document type: Software Unit Verification Plan
Process alignment: ASPICE SWE.4 Software Unit Verification
Version: 0.9.2 Status: Baseline Candidate
Language: English
Product: Chanora
Verification object: Software units defined by SDD
Direct source layer: SDD only

Repo path: docs/verification/swe4-unit-verification-plan.md ---

1. Purpose

This document defines the software unit verification strategy for Chanora. It verifies that software units implement the Software Detailed Design.

This document is downstream of SDD and shall not bypass the document hierarchy.

SysRS -> SysDes -> SRS -> SAD -> SDD -> SWE.4 Unit Verification

Direct source rule:

SWE.4 unit verification items shall link directly to SDD only.

2. Verification Scope

In scope:

Flutter unit tests
Flutter widget-level unit verification where a widget is treated as a software unit
Dart static analysis
Dart code review
Rust unit tests
Rust static analysis
Rust code review
Unit-level regression verification
Unit-level interface boundary tests
Unit-level localization, Unicode, design-token, and diagnostics verification

Out of scope:

Software integration verification across components; handled by SWE.5.
Fully integrated software verification against SRS; handled by SWE.6.
System integration verification against SysDes; handled by SYS.4.

3. Unit Verification Strategy

Verification type	Applies to	Purpose
Static analysis	Dart, Rust	Detect structural, lint, safety, style, and maintainability issues
Code review	Dart, Rust, build scripts	Confirm design compliance and maintainability
Unit tests	Dart, Rust	Verify individual units against SDD behavior
Widget tests	Flutter widgets	Verify component rendering, semantics, and state behavior
Golden tests	Design-system components	Verify stable UI rendering where appropriate
Localization tests	Localization service and accessibility labels	Verify fallback, keys, and localized display strings
Unicode tests	Protocol/bridge/text-boundary units	Verify UTF-8 and multilingual content handling
Regression tests	Changed units	Confirm unchanged behavior remains valid after modifications

4. Entry Criteria

Criterion	Description
SDD baseline available	Unit design items and source SAD links are available.
Unit implementation available	The unit exists in source code or executable test double form.
Unit test environment available	Flutter and/or Rust test infrastructure is configured.
Verification measure defined	Test, review, or static analysis objective is defined.
Pass/fail criteria defined	Expected result is objective and reviewable.

5. Exit Criteria

Criterion	Description
Selected unit verification measures executed	Tests, reviews, and analyses required for the release scope are complete.
Results recorded	Verification results are stored in test reports or review records.
Nonconformances recorded	Failures are recorded for problem resolution.
Traceability complete	Each unit verification item traces to SDD and result evidence.
Regression scope complete	Changed units have selected regression measures executed.

6. Unit Verification Measures

SWE4-UV-001: Verify ChanoraApp initialization order.

Source SDD: SDD-001, SDD-045
Verification method: Flutter unit/integration test
Pass criteria: Theme, localization, platform services, routing, and adaptive shell initialize before feature rendering.
Evidence: Test result

SWE4-UV-002: Verify ChanoraThemeFactory Material 3 theme creation.

Source SDD: SDD-002, SDD-003
Verification method: Dart unit test
Pass criteria: Light and dark Material 3 ThemeData objects are created with valid ColorScheme and TextTheme values.
Evidence: Test result

SWE4-UV-003: Verify ChanoraSemanticColors connection token behavior.

Source SDD: SDD-004, SDD-006
Verification method: Dart unit test
Pass criteria: All connection semantic roles are present and do not require feature-screen hardcoding.
Evidence: Test result

SWE4-UV-004: Verify voice semantic token behavior.

Source SDD: SDD-005, SDD-006
Verification method: Dart unit test
Pass criteria: Speaking, muted, deafened, and push-to-talk active states are available through semantic tokens.
Evidence: Test result

SWE4-UV-005: Verify feature widgets use theme accessors rather than hardcoded semantic values.

Source SDD: SDD-010
Verification method: Static inspection
Pass criteria: Feature widgets do not construct product semantic token values directly.
Evidence: Review record

SWE4-UV-006: Verify adaptive shell window classification.

Source SDD: SDD-011, SDD-012
Verification method: Dart unit test
Pass criteria: Compact, medium, and expanded classes are selected deterministically.
Evidence: Test result

SWE4-UV-007: Verify CompactShell layout behavior.

Source SDD: SDD-013
Verification method: Flutter widget test
Pass criteria: Compact shell renders a single-column layout and mobile navigation entry points.
Evidence: Test result

SWE4-UV-008: Verify MediumShell layout behavior.

Source SDD: SDD-014
Verification method: Flutter widget test
Pass criteria: Medium shell renders side navigation or navigation rail behavior.
Evidence: Test result

SWE4-UV-009: Verify ExpandedShell persistent pane behavior.

Source SDD: SDD-015
Verification method: Flutter widget test
Pass criteria: Expanded shell renders persistent side pane and VoiceBar slot.
Evidence: Test result

SWE4-UV-010: Verify connection status presentation uses non-color-only cues.

Source SDD: SDD-016, SDD-022
Verification method: Dart unit test, widget test
Pass criteria: The presenter exposes label, icon, semantic label, and severity token.
Evidence: Test result

SWE4-UV-011: Verify ChanoraVoiceBar exposed properties.

Source SDD: SDD-017, SDD-018
Verification method: Flutter widget test
Pass criteria: Mute, deaf, push-to-talk, input meter, current channel, and latency properties render correctly.
Evidence: Test result

SWE4-UV-012: Verify ChanoraChannelTree data and interaction behavior.

Source SDD: SDD-019, SDD-020
Verification method: Flutter widget test
Pass criteria: Channel hierarchy, selected state, expansion state, join intent, and context-menu intent operate as designed.
Evidence: Test result

SWE4-UV-013: Verify ChanoraClientTile state semantics.

Source SDD: SDD-021
Verification method: Widget test, accessibility test
Pass criteria: Client status is available through text/icon/semantic cues and not color alone.
Evidence: Test result

SWE4-UV-014: Verify localized semantic labels for icon-only buttons.

Source SDD: SDD-024, SDD-031, SDD-032
Verification method: Accessibility test, localization unit test
Pass criteria: Icon-only controls expose localized semantic labels with fallback.
Evidence: Test result

SWE4-UV-015: Verify keyboard focus traversal.

Source SDD: SDD-025
Verification method: Widget test
Pass criteria: Primary interactive controls can be traversed in a logical order.
Evidence: Test result

SWE4-UV-016: Verify text-scale resilience of critical controls.

Source SDD: SDD-026
Verification method: Accessibility widget test
Pass criteria: Critical controls remain reachable under increased text scale.
Evidence: Test result

SWE4-UV-017: Verify platform inset service unit behavior.

Source SDD: SDD-027, SDD-030
Verification method: Unit test with platform test doubles
Pass criteria: Insets are normalized and exposed to the shell.
Evidence: Test result

SWE4-UV-018: Verify back intent service behavior.

Source SDD: SDD-028
Verification method: Unit test with platform test doubles
Pass criteria: Platform back events map to expected route-level intents.
Evidence: Test result

SWE4-UV-019: Verify localization fallback.

Source SDD: SDD-031, SDD-032, SDD-033
Verification method: Unit test
Pass criteria: Missing localized strings fall back deterministically.
Evidence: Test result

SWE4-UV-020: Verify server-content pass-through.

Source SDD: SDD-034
Verification method: Unit test
Pass criteria: Server-provided content is not translated by product localization.
Evidence: Test result

SWE4-UV-021: Verify Unicode text boundary behavior.

Source SDD: SDD-035, SDD-036, SDD-037
Verification method: Unit test
Pass criteria: Valid multilingual Unicode content is preserved; invalid external encodings are handled at boundaries.
Evidence: Test result

SWE4-UV-022: Verify diagnostic Unicode preservation and redaction behavior.

Source SDD: SDD-038, SDD-041, SDD-050, SDD-054
Verification method: Unit test, security review
Pass criteria: Secrets are redacted while multilingual content is preserved.
Evidence: Test result, review record

SWE4-UV-023: Verify locale-aware formatting.

Source SDD: SDD-040
Verification method: Unit test
Pass criteria: Dates, times, numbers, and timestamps format through localization utilities.
Evidence: Test result

SWE4-UV-024: Verify traceability checker behavior.

Source SDD: SDD-043, SDD-044, SDD-055, SDD-056, SDD-066, SDD-067
Verification method: Unit test / script test
Pass criteria: Invalid direct-layer references are detected.
Evidence: Test result

SWE4-UV-025: Verify bridge DTO safety.

Source SDD: SDD-046
Verification method: Unit test, static inspection
Pass criteria: Bridge DTOs do not expose internal Rust implementation types.
Evidence: Test result, review record

SWE4-UV-026: Verify Rust core event mapping.

Source SDD: SDD-047
Verification method: Rust unit test
Pass criteria: Core events map deterministically to view model deltas.
Evidence: Test result

SWE4-UV-027: Verify voice view model separation from DSP.

Source SDD: SDD-048
Verification method: Code review, unit test
Pass criteria: Voice UI receives status values and does not perform audio DSP.
Evidence: Review record, test result

SWE4-UV-028: Verify storage facade isolation.

Source SDD: SDD-049
Verification method: Static inspection, unit test
Pass criteria: Feature widgets do not directly call database APIs.
Evidence: Review record, test result

SWE4-UV-029: Verify interface detail catalog completeness.

Source SDD: SDD-059, SDD-060
Verification method: Review
Pass criteria: Unit-level interface entries include required details where applicable.
Evidence: Review record

SWE4-UV-030: Verify unit construction and review records.

Source SDD: SDD-064, SDD-065, SDD-068, SDD-069, SDD-070
Verification method: Review
Pass criteria: Unit construction, review, verification handoff, and registry records exist for release scope units.
Evidence: Review record

7. Traceability Matrix

SDD Range	SWE.4 Coverage
SDD-001 through SDD-010	SWE4-UV-001 through SWE4-UV-005
SDD-011 through SDD-018	SWE4-UV-006 through SWE4-UV-011
SDD-019 through SDD-026	SWE4-UV-012 through SWE4-UV-016
SDD-027 through SDD-037	SWE4-UV-017 through SWE4-UV-021
SDD-038 through SDD-050	SWE4-UV-022 through SWE4-UV-028
SDD-051 through SDD-070	SWE4-UV-029 through SWE4-UV-030

8. Result Reporting

Unit verification results shall be summarized in a unit verification summary report including:

verification scope
selected verification measures
skipped measures and rationale
pass/fail result
nonconformances
regression scope
residual risks
release recommendation

9. Change History

Version	Date	Description
0.1.0	2026-05-14	Initial SWE.4 unit verification plan derived from SDD v0.3.

10. Platform Decision Unit Verification Addendum

SWE4-UV-031: Verify iOS and Android build configuration units.

Source SDD: SDD-071, SDD-072, SDD-073
Verification method: Static inspection, platform test
Pass criteria: iOS minimum runtime, Apple SDK gate, Android minimum runtime, and Android target SDK configuration are inspectable and match release policy.
Evidence: Test result, release inspection

SWE4-UV-032: Verify single active connection enforcement.

Source SDD: SDD-074
Verification method: Unit test
Pass criteria: Attempting to create a second active MVP connection is rejected or routed through a controlled disconnect/switch policy.
Evidence: Test result

SWE4-UV-033: Verify audio processing defaults and backend selection.

Source SDD: SDD-075, SDD-076
Verification method: Unit test, audio test
Pass criteria: AEC, AGC, Noise Suppression, and High-Pass Filter default to enabled where supported and stable; backend selector prefers platform-native processing.
Evidence: Test result

SWE4-UV-034: Verify local database, secret storage, bridge, and diagnostics privacy gate units.

Source SDD: SDD-077, SDD-078, SDD-079, SDD-080
Verification method: Unit test, security inspection
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

Version	Date	Description
0.9.1	2026-05-14	Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set.

Baseline Candidate 0.9.2 Update

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`.

16 KiB Raw Blame History