# Chanora SDD — Software Detailed Design

**Document type:** SDD / Software Detailed Design  
**Process alignment:** ASPICE SWE.3 Software Detailed Design and Unit Construction  
**Version:** 0.9.7
**Status:** Baseline Candidate  
**Language:** English  
**Product:** Chanora  
**Lifecycle position:** `SysRS -> SysDes -> SRS -> SAD -> SDD`

**Repo path:** `docs/architecture/sdd.md`  ---

## 1. Purpose

This document defines detailed software design units, APIs, data structures, and implementation-level design rules for Chanora.

The SDD derives from the SAD only.

## 2. Strict Traceability Rules

```text
SDD shall link directly to SAD only.
SDD shall not use direct software-requirement source IDs.
SDD shall not use direct system-design source IDs.
SDD shall not use direct system-requirement source IDs.
```

## 3. Software Unit Decomposition

| Software Unit | Responsibility |
|---|---|
| `ChanoraApp` | Root application widget, initialization, theme mode, localization initialization |
| `ChanoraThemeFactory` | Builds ThemeData, ColorScheme, TextTheme, component themes |
| `ChanoraSemanticColors` | ThemeExtension for connection, voice, latency, diagnostic, and error states |
| `ChanoraSpacing` | ThemeExtension for spacing tokens |
| `ChanoraShape` | ThemeExtension for shape tokens |
| `ChanoraMotion` | ThemeExtension for motion tokens and reduced-motion behavior |
| `ChanoraAdaptiveShell` | Window class detection and shell layout selection |
| `CompactShell` | Single-column shell |
| `MediumShell` | Navigation rail / medium-width shell |
| `ExpandedShell` | Persistent pane shell |
| `ChanoraVoiceBar` | Persistent voice control component |
| `ChanoraChannelTree` | Hierarchical channel and client browser |
| `ChanoraClientTile` | Client row component |
| `ChanoraStatusBadge` | Accessible status indicator |
| `ChanoraAudioMeter` | Input level display |
| `LocalizationService` | Product-owned string localization and fallback |
| `ContentTextAdapter` | Server-provided text pass-through and display preparation |
| `UnicodeTextBoundary` | Boundary string validation and conversion helper |
| `PlatformInsetsService` | Safe area, keyboard, cutout, and desktop inset data |
| `BackIntentService` | Android/system back intent abstraction |
| `HapticsService` | Platform-aware haptic feedback wrapper |
| `BridgeFacade` | Flutter-to-Rust command and event facade |
| `CoreEventMapper` | Core-event-to-view-model mapping |
| `DiagnosticsTextPresenter` | Localized diagnostic descriptions and language-neutral event keys |
| `ArchitectureViewDocs` | Maintains context, container, component, runtime, deployment, and ADR architecture documentation |
| `DeploymentConfig` | Platform packaging and release configuration |
| `ArchitectureTraceChecker` | Checks direct-layer traceability rules for documentation |


## 4. SWE.3 Detailed Design Completeness Criteria

The detailed design shall be sufficient to support implementation and unit verification. For each software unit, the SDD shall identify where applicable:

| Detail | Required information |
|---|---|
| Unit responsibility | Purpose and boundaries of the unit |
| Inputs | Name, type, allowed range, default value, optionality |
| Outputs | Name, type, allowed range, default value, error behavior |
| Interfaces | Internal and external software interfaces |
| Dynamic behavior | State changes, sequence behavior, asynchronous behavior |
| Error behavior | Recoverable errors, fatal errors, fallback behavior |
| Resource behavior | Buffering, time-sensitive operations, memory expectations |
| Unit verification hooks | Test seams and expected verification approach |

## 5. Software Unit Interface Detail Catalog

| Unit | Interface | Direction | Name | Type | Unit | Resolution | Range | Default | Error / fallback |
|---|---|---:|---|---|---|---|---|---|---|
| `ChanoraThemeFactory` | Theme creation | Input | seedColor | Color value | n/a | n/a | valid color | Chanora default seed | fallback to default theme |
| `ChanoraThemeFactory` | Theme creation | Input | brightness | enum | n/a | n/a | light/dark | system setting | fallback to light |
| `ChanoraThemeFactory` | Theme creation | Output | themeData | ThemeData | n/a | n/a | valid ThemeData | n/a | construction error treated as app initialization failure |
| `ChanoraAdaptiveShell` | Window classification | Input | widthDp | double | dp | 1dp | >=0 | current window width | compact fallback |
| `ChanoraAdaptiveShell` | Window classification | Output | windowClass | enum | n/a | n/a | compact/medium/expanded | compact | compact fallback |
| `LocalizationService` | String lookup | Input | key | string | n/a | n/a | non-empty | n/a | fallback key display or English fallback |
| `LocalizationService` | String lookup | Input | locale | locale ID | n/a | n/a | supported locale | English | English fallback |
| `LocalizationService` | String lookup | Output | localizedText | UTF-8 string | n/a | n/a | valid Unicode | English fallback | missing-key diagnostic |
| `UnicodeTextBoundary` | Text validation | Input | rawText | external string/bytes | n/a | n/a | platform/protocol dependent | n/a | boundary conversion error |
| `UnicodeTextBoundary` | Text validation | Output | contentText | UTF-8 string | n/a | n/a | valid Unicode | replacement/failure policy | conversion diagnostic |
| `BridgeFacade` | Command bridge | Input | commandDto | DTO | n/a | n/a | valid command schema | n/a | bridge error DTO |
| `BridgeFacade` | Command bridge | Output | commandResult | DTO/result | n/a | n/a | success/error | n/a | typed error |
| `CoreEventMapper` | Event mapping | Input | coreEvent | event DTO | n/a | n/a | known event type | n/a | unknown event diagnostic |
| `CoreEventMapper` | Event mapping | Output | viewModelDelta | UI model delta | n/a | n/a | valid UI state change | n/a | safe no-op + diagnostic |
| `DiagnosticsTextPresenter` | Diagnostic presentation | Input | diagnosticKey | stable key | n/a | n/a | known/unknown key | n/a | generic localized fallback |
| `DiagnosticsTextPresenter` | Diagnostic presentation | Output | diagnosticText | localized string | n/a | n/a | valid Unicode | English fallback | fallback diagnostic text |
| `ChanoraAudioMeter` | Level display | Input | level | double | normalized | 0.01 | 0.0-1.0 | 0.0 | clamp to valid range |
| `ChanoraAudioMeter` | Level display | Output | semanticValue | localized string | n/a | n/a | valid string | "No input" | localized fallback |
| `BackIntentService` | Back handling | Input | platformBackEvent | platform event | n/a | n/a | platform-defined | n/a | ignored if unsupported |
| `BackIntentService` | Back handling | Output | backIntent | enum | n/a | n/a | pop/close/ignore/exitCandidate | ignore | safe no-op |

## 6. Detailed Design Evaluation Checklist

| Evaluation area | Question |
|---|---|
| Interoperability | Are interfaces compatible across units and layers? |
| Interaction | Are runtime interactions and asynchronous flows defined? |
| Criticality | Are critical voice, connection, security, and diagnostics behaviors detailed? |
| Technical complexity | Are complex units decomposed and testable? |
| Risks | Are platform, audio, protocol, encoding, and localization risks addressed? |
| Testability | Can unit tests, widget tests, integration tests, and platform tests be derived from the design? |
| Traceability | Does every detailed item link directly to SAD only? |
| Consistency | Are SAD, SDD, unit interfaces, and verification expectations consistent? |


## 7. Detailed Design Items

**SDD-001**: `ChanoraApp` shall initialize theme, localization, platform services, and routing before rendering feature content.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraApp`
- Source SAD: SAD-001, SAD-031
- Verification method: Unit Test, Integration Test

Initialization order: platform bindings -> localization resources -> theme model -> app router -> adaptive shell.

**SDD-002**: `ChanoraThemeFactory` shall create Material 3 ThemeData for light and dark modes.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraThemeFactory`
- Source SAD: SAD-001, SAD-002, SAD-043
- Verification method: Unit Test

The factory returns ThemeData instances with Material 3 enabled and populated ColorScheme and TextTheme values.

**SDD-003**: `ChanoraThemeFactory` shall support seed-color replacement without feature-screen changes.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraThemeFactory`
- Source SAD: SAD-001, SAD-002, SAD-044
- Verification method: Unit Test

Seed color is injected into theme construction and not referenced in feature modules.

**SDD-004**: `ChanoraSemanticColors` shall define connection state colors independently from base ColorScheme.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-004, SAD-007
- Verification method: Unit Test

Connection tokens include connected, connecting, reconnecting, disconnected, and error roles.

**SDD-005**: `ChanoraSemanticColors` shall define voice state colors independently from base ColorScheme.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-005, SAD-007
- Verification method: Unit Test

Voice tokens include speaking, muted, deafened, push-to-talk-active, and unavailable roles.

**SDD-006**: `ChanoraSemanticColors` shall define latency, packet-loss, diagnostics, and error semantic roles.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-006, SAD-007
- Verification method: Unit Test

Token names remain semantic and shall not embed raw color names in API names.

**SDD-007**: `ChanoraSpacing` shall define reusable spacing values for compact, medium, and expanded layouts.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSpacing`
- Source SAD: SAD-002, SAD-003
- Verification method: Unit Test

Spacing APIs expose xs, sm, md, lg, xl, and xxl values.

**SDD-008**: `ChanoraShape` shall define reusable corner and shape values for cards, buttons, panels, badges, and sheets.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraShape`
- Source SAD: SAD-002, SAD-003
- Verification method: Unit Test

Shape APIs expose none, small, medium, large, extraLarge, and full values.

**SDD-009**: `ChanoraMotion` shall define standard durations and reduced-motion behavior.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraMotion`
- Source SAD: SAD-009
- Verification method: Unit Test

The unit maps reduced-motion settings to no-motion or simplified-motion behavior.

**SDD-010**: Feature widgets shall read tokens through Flutter theme accessors only.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Feature Widgets`
- Source SAD: SAD-003, SAD-007
- Verification method: Static Inspection

Feature code may call Theme.of(context) and extension accessors, but shall not instantiate semantic tokens.

**SDD-011**: `ChanoraAdaptiveShell` shall classify window width into compact, medium, or expanded.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAdaptiveShell`
- Source SAD: SAD-008
- Verification method: Unit Test

Classification thresholds are centralized in the shell configuration.

**SDD-012**: `ChanoraAdaptiveShell` shall dispatch to `CompactShell`, `MediumShell`, or `ExpandedShell`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAdaptiveShell`
- Source SAD: SAD-008, SAD-009, SAD-010, SAD-011
- Verification method: Widget Test

Layout selection shall be deterministic for a given window class.

**SDD-013**: `CompactShell` shall render single-column content and mobile navigation.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `CompactShell`
- Source SAD: SAD-009
- Verification method: Widget Test

Compact layout shall avoid side-by-side pane requirements.

**SDD-014**: `MediumShell` shall render side navigation or navigation rail behavior.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MediumShell`
- Source SAD: SAD-010
- Verification method: Widget Test

Medium layout shall preserve main content and primary navigation.

**SDD-015**: `ExpandedShell` shall render persistent pane regions and persistent voice controls.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ExpandedShell`
- Source SAD: SAD-011
- Verification method: Widget Test

Expanded layout shall support a side pane, main pane, and persistent VoiceBar slot.

**SDD-016**: `ConnectionStatusPresenter` shall provide non-color-only connection state presentation data.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ConnectionStatusPresenter`
- Source SAD: SAD-012, SAD-014
- Verification method: Unit Test

The presenter returns label, icon, severity token, and accessibility description.

**SDD-017**: `ChanoraVoiceBar` shall expose mute, deaf, push-to-talk, input meter, current channel, and latency properties.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraVoiceBar`
- Source SAD: SAD-013
- Verification method: Widget Test

VoiceBar properties are supplied from view models and shall not call Rust Core directly.

**SDD-018**: `ChanoraVoiceBar` shall remain renderable as a persistent shell slot.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraVoiceBar`
- Source SAD: SAD-007, SAD-013
- Verification method: Widget Test

The component shall not depend on a specific route.

**SDD-019**: `ChanoraChannelTree` shall support hierarchical channel nodes and client rows.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraChannelTree`
- Source SAD: SAD-003, SAD-006
- Verification method: Widget Test

The component consumes ChannelTreeVm data and supports expansion state.

**SDD-020**: `ChanoraChannelTree` shall support selected state, expansion state, join intent, and context-menu intent.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraChannelTree`
- Source SAD: SAD-006, SAD-015
- Verification method: Widget Test

UI events are emitted through callbacks and view-model intents.

**SDD-021**: `ChanoraClientTile` shall display client status with text, icon, and semantic state cues.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraClientTile`
- Source SAD: SAD-003, SAD-014
- Verification method: Widget Test, Accessibility Test

Client state shall not rely on color alone.

**SDD-022**: `ChanoraStatusBadge` shall expose visible text or icon and accessibility semantics.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraStatusBadge`
- Source SAD: SAD-012, SAD-014
- Verification method: Widget Test, Accessibility Test

Badge states include normal, warning, error, speaking, muted, and disconnected.

**SDD-023**: `ChanoraAudioMeter` shall display audio input level and support reduced-motion fallback.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAudioMeter`
- Source SAD: SAD-009, SAD-013
- Verification method: Widget Test

Reduced-motion mode shall use simplified or static visual behavior.

**SDD-024**: All icon-only buttons shall provide localized semantic labels.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Design System Components`
- Source SAD: SAD-014, SAD-020
- Verification method: Accessibility Test

Icon-only control constructors require label keys or semantic labels.

**SDD-025**: Focusable components shall define focus order and visible focus style.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `FocusPolicy`
- Source SAD: SAD-015
- Verification method: Widget Test

Focus traversal shall be testable with keyboard navigation.

**SDD-026**: Adaptive shell panes shall support increased text scale without losing critical actions.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Adaptive Shell Components`
- Source SAD: SAD-016
- Verification method: Accessibility Test

Critical controls shall wrap, scroll, or remain reachable.

**SDD-027**: `PlatformInsetsService` shall provide safe area, keyboard inset, display cutout, and desktop inset data.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PlatformInsetsService`
- Source SAD: SAD-017
- Verification method: Platform Test

Insets are consumed by shell layout rather than individual feature screens.

**SDD-028**: `BackIntentService` shall normalize Android/system back behavior into route-level intents.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `BackIntentService`
- Source SAD: SAD-018
- Verification method: Platform Test

Back handling shall be testable without direct platform branching in feature screens.

**SDD-029**: `HapticsService` shall expose platform-aware haptic feedback operations.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `HapticsService`
- Source SAD: SAD-019
- Verification method: Platform Test

Haptics calls are optional and shall no-op where unsupported.

**SDD-030**: `KeyboardAvoidancePolicy` shall prevent critical controls from being covered by virtual keyboards.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `KeyboardAvoidancePolicy`
- Source SAD: SAD-017, SAD-019
- Verification method: Platform Test

Inputs and primary actions remain reachable when the virtual keyboard appears.

**SDD-031**: `LocalizationService` shall load product string resources for the active locale.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Unit Test

The unit returns localized strings by key.

**SDD-032**: `LocalizationService` shall fall back to the baseline English locale when a key is missing.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Unit Test

Fallback behavior is deterministic and logged for diagnostics.

**SDD-033**: `LocalizationService` shall allow new locale resources without changes to protocol, audio, state, or storage modules.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Inspection

Locale resource registration is separated from non-UI software modules.

**SDD-034**: `ContentTextAdapter` shall pass through server-provided names and messages without translation.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ContentTextAdapter`
- Source SAD: SAD-021
- Verification method: Integration Test

Server content is treated as user/server content rather than product copy.

**SDD-035**: `UnicodeTextBoundary` shall validate cross-layer text DTOs as UTF-8 compatible strings.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `UnicodeTextBoundary`
- Source SAD: SAD-022, SAD-023
- Verification method: Unit Test, Integration Test

Invalid external encodings are handled at boundaries.

**SDD-036**: Protocol-boundary conversion shall be implemented only in protocol adapter code.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Protocol Adapter Text Boundary`
- Source SAD: SAD-023
- Verification method: Inspection

No general Flutter feature code may perform protocol encoding conversion.

**SDD-037**: Platform-boundary conversion shall be implemented only in platform adapter code.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Platform Adapter Text Boundary`
- Source SAD: SAD-023
- Verification method: Inspection

Platform-specific string conversion remains explicit and localized.

**SDD-038**: Diagnostics export shall preserve Unicode after redaction.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-024
- Verification method: Test, Audit

Redaction removes secrets, not arbitrary multilingual content.

**SDD-039**: Bidi text rendering shall use Flutter text widgets and directionality behavior compatible with platform support.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Flutter Text Presentation`
- Source SAD: SAD-025
- Verification method: Localization Test

Text rendering allows LTR and RTL content where supported.

**SDD-040**: Locale-aware formatting shall be centralized in localization utilities.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationFormatting`
- Source SAD: SAD-026
- Verification method: Unit Test

Dates, times, numbers, and timestamps are formatted by locale-aware helpers.

**SDD-041**: Diagnostics event keys shall remain stable and language-neutral.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-027
- Verification method: Unit Test

User-facing descriptions are separate from machine-readable event keys.

**SDD-042**: UI/UX supporting documents shall be versioned with the software architecture baseline.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Documentation Set`
- Source SAD: SAD-028
- Verification method: Review

Guidelines, token docs, component docs, adaptive docs, and platform docs are maintained as supporting baselines.

**SDD-043**: SAD source validation shall reject direct lower-layer source fields.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Traceability Checker`
- Source SAD: SAD-029
- Verification method: Inspection

Automated or manual review checks SAD source fields.

**SDD-044**: SDD source validation shall reject direct non-SAD source fields.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Traceability Checker`
- Source SAD: SAD-030, SAD-045
- Verification method: Inspection

Automated or manual review checks SDD source fields.

**SDD-045**: Theme/localization/platform initialization shall be tested before first feature render.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `App Initialization Tests`
- Source SAD: SAD-031
- Verification method: Integration Test

The app shell is tested for initialization order.

**SDD-046**: Bridge facade DTOs shall expose only stable UI-safe data structures.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `BridgeFacade`
- Source SAD: SAD-040, SAD-041
- Verification method: Integration Test

Flutter must not depend on Rust internal types.

**SDD-047**: Core event mapping shall convert Rust Core events into feature view models.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `CoreEventMapper`
- Source SAD: SAD-041
- Verification method: Unit Test

Event mapping is deterministic and testable.

**SDD-048**: Audio state view models shall separate UI state from real-time audio processing.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `VoiceViewModel`
- Source SAD: SAD-034, SAD-039
- Verification method: Unit Test

Voice UI receives status values without performing DSP.

**SDD-049**: Storage access shall be isolated from feature widgets behind repository or service APIs.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `StorageFacade`
- Source SAD: SAD-035
- Verification method: Inspection

Feature widgets shall not call database APIs directly.

**SDD-050**: Diagnostics UI shall obtain localized display text from diagnostics presentation services.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-027, SAD-036, SAD-050
- Verification method: Widget Test

Diagnostics UI consumes display models.

**SDD-051**: `ArchitectureViewDocs` shall maintain context, container, component, runtime, deployment, data, security, diagnostics, UI, audio, protocol, and i18n views.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-046, SAD-048, SAD-049, SAD-050
- Verification method: Review

Architecture views are updated when architecture-affecting changes occur.

**SDD-052**: `ArchitectureViewDocs` shall maintain an ADR index for accepted, deprecated, and superseded architectural decisions.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-047
- Verification method: Review

ADR entries include decision, rationale, status, and impact.

**SDD-053**: `DeploymentConfig` shall define platform-specific packaging and release configuration units.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DeploymentConfig`
- Source SAD: SAD-049
- Verification method: Inspection

Deployment configuration separates platform package metadata from feature code.

**SDD-054**: `DiagnosticsArchitecture` shall centralize logging, event keys, localized descriptions, redaction, and export presentation.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DiagnosticsArchitecture`
- Source SAD: SAD-050
- Verification method: Unit Test, Audit

Diagnostics behavior is implemented through centralized services.

**SDD-055**: `ArchitectureTraceChecker` shall check that SDD items reference only SAD IDs.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureTraceChecker`
- Source SAD: SAD-030, SAD-045
- Verification method: Inspection

A documentation check fails when non-SAD source IDs appear in SDD item source fields.

**SDD-056**: `ArchitectureTraceChecker` shall check that SAD items reference only SRS IDs.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureTraceChecker`
- Source SAD: SAD-029
- Verification method: Inspection

A documentation check fails when non-SRS source IDs appear in SAD item source fields.



**SDD-057**: `ArchitectureViewDocs` shall define reviewable architecture views for context, containers, components, runtime behavior, deployment, data, security, diagnostics, UI, audio, protocol, and i18n.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-046, SAD-051
- Verification method: Review

Each architecture view is maintained as part of the SAD baseline and referenced by the affected detailed design units.

**SDD-058**: `ArchitectureViewDocs` shall define an ADR record structure with ID, title, status, decision, rationale, consequences, affected units, and change history.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-047
- Verification method: Review

ADR records support architecture communication and change impact analysis.

**SDD-059**: `InterfaceDetailCatalog` shall refine SAD architectural interfaces into unit-level interface entries.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `InterfaceDetailCatalog`
- Source SAD: SAD-052, SAD-057
- Verification method: Inspection

Each entry includes name, type, unit, resolution, range, default value, and error/fallback behavior where applicable.

**SDD-060**: `InterfaceDetailCatalog` shall define command, event, localization, Unicode, diagnostics, adaptive layout, audio meter, and platform-intent interfaces.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `InterfaceDetailCatalog`
- Source SAD: SAD-052, SAD-056, SAD-057
- Verification method: Inspection

The catalog supports integration and unit verification planning.

**SDD-061**: `PerformanceDesignNotes` shall record UI responsiveness, audio latency, memory growth, reconnect, localization, and diagnostics resource considerations.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `PerformanceDesignNotes`
- Source SAD: SAD-053
- Verification method: Review, Analysis

Performance notes identify design mechanisms and verification hooks.

**SDD-062**: `AssumptionRegister` shall record software design assumptions and dependencies that affect feasibility.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `AssumptionRegister`
- Source SAD: SAD-054
- Verification method: Review

Assumptions are reviewed during change impact analysis.

**SDD-063**: `ArchitectureGlossary` shall provide definitions for architecture and detailed design terms.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P2 / Production
- Software unit: `ArchitectureGlossary`
- Source SAD: SAD-055
- Verification method: Review

The glossary reduces ambiguity across software architecture, detailed design, and verification.

**SDD-064**: Each software unit detailed design shall include responsibility, inputs, outputs, interfaces, dynamic behavior, error behavior, resource behavior, and verification hooks where applicable.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitDesignTemplate`
- Source SAD: SAD-058, SAD-059
- Verification method: Review, Inspection

The template defines the minimum expected detail for unit construction and unit verification.

**SDD-065**: `UnitConstructionGuideline` shall state that software units are constructed according to the SDD rather than reverse-documented from code.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `UnitConstructionGuideline`
- Source SAD: SAD-059
- Verification method: Review

The unit construction guideline preserves design-to-code traceability.

**SDD-066**: `SoftwareUnitTraceChecker` shall verify that SDD items link directly to SAD IDs only.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `SoftwareUnitTraceChecker`
- Source SAD: SAD-030, SAD-045, SAD-060
- Verification method: Inspection

The checker supports traceability rule enforcement.

**SDD-067**: `SoftwareUnitTraceChecker` shall support impact analysis from changed SAD items to affected SDD items.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitTraceChecker`
- Source SAD: SAD-060
- Verification method: Inspection

Impact analysis output identifies affected detailed design units.

**SDD-068**: `DetailedDesignReviewRecord` shall capture review evidence for SDD completeness, testability, and consistency with SAD.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DetailedDesignReviewRecord`
- Source SAD: SAD-059, SAD-060
- Verification method: Review

Review records support baseline approval and communication.

**SDD-069**: `UnitVerificationHandoff` shall identify verification method candidates for each software unit.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `UnitVerificationHandoff`
- Source SAD: SAD-059
- Verification method: Review

The handoff supports unit verification planning.

**SDD-070**: `SoftwareUnitRegistry` shall maintain the list of software units, their owning component, source SAD items, and implementation status.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitRegistry`
- Source SAD: SAD-058, SAD-060
- Verification method: Inspection

The registry supports consistency between architecture, detailed design, implementation, and verification.


## 8. SAD-to-SDD Coverage Matrix

| SAD Range | SDD Coverage |
|---|---|
| SAD-001 through SAD-007 | SDD-001 through SDD-010 |
| SAD-008 through SAD-011 | SDD-011 through SDD-015 |
| SAD-012 through SAD-016 | SDD-016 through SDD-026 |
| SAD-017 through SAD-019 | SDD-027 through SDD-030 |
| SAD-020 through SAD-027 | SDD-031 through SDD-041 |
| SAD-028 through SAD-031 | SDD-042 through SDD-045 |
| SAD-032 through SAD-038 | SDD-046 through SDD-050 |
| SAD-039 through SAD-045 | SDD-046 through SDD-050, SDD-055, SDD-056 |
| SAD-046 through SAD-050 | SDD-051 through SDD-058, SDD-061 |
| SAD-051 through SAD-060 | SDD-057 through SDD-070 |

## 9. Change History

| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial SDD baseline covering SAD-001 through SAD-045 and enforcing SAD-only direct traceability. |
| 0.2.0 | 2026-05-14 | Updated SDD coverage for expanded SAD v0.2 architecture views, ADRs, deployment architecture, diagnostics architecture, and traceability checker units. |
| 0.3.0 | 2026-05-14 | Added SWE.3 detailed-design completeness criteria, unit interface detail catalog, evaluation checklist, unit construction guideline, and additional SAD coverage. |

---

## 10. Platform Baseline and Product Decision Detailed Design Addendum

**SDD-071**: `IOSBuildConfig` shall define the iOS minimum runtime deployment target as iOS 13 unless an approved platform change raises it.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSBuildConfig`
- Source SAD: SAD-061
- Verification method: Inspection, Platform Test

**SDD-072**: `IOSReleaseGate` shall verify that App Store Connect upload builds use Xcode 26 or later and the iOS 26 / iPadOS 26 SDK or later on or after 2026-04-28 unless Apple publishes a newer applicable upload requirement.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSReleaseGate`
- Source SAD: SAD-062
- Verification method: Release Inspection

**SDD-073**: `AndroidBuildConfig` shall define Android API 24 as the minimum Android runtime baseline and shall expose target SDK configuration for release inspection.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AndroidBuildConfig`
- Source SAD: SAD-063
- Verification method: Platform Test, Release Inspection

**SDD-074**: `ConnectionSessionManager` shall enforce a single active server connection in MVP.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ConnectionSessionManager`
- Source SAD: SAD-064
- Verification method: Unit Test, System Test

**SDD-075**: `AudioProcessingSettings` shall default AEC, AGC, Noise Suppression, and High-Pass Filter to enabled where supported and stable.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AudioProcessingSettings`
- Source SAD: SAD-065
- Verification method: Unit Test, Audio Test

**SDD-076**: `AudioProcessingBackendSelector` shall select platform-native audio processing first where available and stable and isolate any fallback backend behind the audio subsystem interface.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `AudioProcessingBackendSelector`
- Source SAD: SAD-066
- Verification method: Unit Test, Audio Test

**SDD-077**: `LocalDatabaseRepository` shall persist non-secret local state through SQLite or an equivalent embedded database abstraction.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalDatabaseRepository`
- Source SAD: SAD-067
- Verification method: Unit Test, Storage Test

**SDD-078**: `SecretStorageRepository` shall persist secrets only through platform secure storage service interfaces.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `SecretStorageRepository`
- Source SAD: SAD-067
- Verification method: Unit Test, Security Audit

**SDD-079**: `TypedBridgeFacade` shall define generated or schema-controlled DTOs for Flutter/Rust commands, results, and events.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `TypedBridgeFacade`
- Source SAD: SAD-068
- Verification method: Integration Test, Inspection

**SDD-080**: `DiagnosticsPrivacyGate` shall disable automatic diagnostic upload, telemetry upload, and crash reporting in MVP release configuration unless an approved decision enables them.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsPrivacyGate`
- Source SAD: SAD-069, SAD-070
- Verification method: Privacy Review, Security Audit

**SDD-081**: `DesktopPttBackend` shall be a Rust trait in `chanora_audio::ptt` exposing `fn capability(&self) -> PttCapabilityLevel`, `fn backend_id(&self) -> &'static str`, `fn start(&mut self, gate: Arc<AudioTransmitGate>, binding: PttBinding) -> Result<(), PttError>`, `fn stop(&mut self)`, and `fn rebind(&mut self, binding: PttBinding) -> Result<(), PttError>`. Implementations shall be Send and stop on Drop.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DesktopPttBackend`
- Source SAD: SAD-071
- Verification method: Unit Test, Inspection

**SDD-082**: `PttCapabilityLevel` shall be a plain Rust enum (`L0Focused`, `L1GlobalShortcut`, `L2GlobalHoldToTalk`, `L3GlobalWithMouseButtons`, `L4DeviceAware`) with a public `as_str(&self) -> &'static str` mapping for diagnostics. `L4DeviceAware` is reserved and shall not be produced by any MVP implementation.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttCapabilityLevel`
- Source SAD: SAD-071
- Verification method: Unit Test

**SDD-083**: `WindowsRawInputBackend` shall use the `RegisterRawInputDevices` Win32 API targeting `HID_USAGE_PAGE_GENERIC` keyboard and mouse usages, run a dedicated message-only window on its own OS thread, and forward only sanitised binding-match results to the `AudioTransmitGate`. Raw `RAWINPUT` payloads shall never cross the backend boundary.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `WindowsRawInputBackend`
- Source SAD: SAD-072
- Verification method: Platform Test (Windows), Unit Test

**SDD-084**: `WindowsHookBackend` shall be used only when Raw Input registration fails. It installs `WH_KEYBOARD_LL` and `WH_MOUSE_LL` hooks on its dedicated thread; the hook callbacks compare against the active binding and call `AudioTransmitGate::set` only, never logging key data. The hook is uninstalled on Drop.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `WindowsHookBackend`
- Source SAD: SAD-072
- Verification method: Platform Test (Windows), Unit Test

**SDD-085**: `MacOSEventTapBackend` shall create a `CGEventTap` filtered to keyboard and mouse-button events, attached to the main run loop with an explicit retain. The tap callback shall consult the active binding and call `AudioTransmitGate::set` only. The backend shall expose `permission_state() -> Granted | Denied | Undetermined` via `IOHIDCheckAccess` (or the macOS-version-appropriate equivalent) and shall return `PttCapabilityLevel::L0Focused` when permission is not Granted.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MacOSEventTapBackend`
- Source SAD: SAD-073
- Verification method: Platform Test (macOS), User Acceptance Test

**SDD-086**: `LinuxGnomeWaylandBackend` shall call `CreateSession`, `BindShortcuts`, and listen for `Activated` / `Deactivated` signals on the freedesktop `org.freedesktop.portal.GlobalShortcuts` D-Bus interface. Binding capture shall use the portal's own configuration dialog; Chanora itself does not read raw key events. Missing D-Bus or missing portal interface resolves to `PttCapabilityLevel::L0Focused`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LinuxGnomeWaylandBackend`
- Source SAD: SAD-074
- Verification method: Platform Test (Linux, GNOME Wayland), Unit Test

**SDD-087**: `FocusedPttBackend` shall integrate with Flutter's keyboard / pointer event stream via the existing `Listener` widget path and the bridge `set_ptt` command. Reports `PttCapabilityLevel::L0Focused` and `backend_id = "focused"`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `FocusedPttBackend`
- Source SAD: SAD-071, SAD-072, SAD-073, SAD-074
- Verification method: Unit Test, UI Review

**SDD-088**: `PttController` shall sit in `chanora_core::ptt` and own a `Box<dyn DesktopPttBackend>`, a clone of `AudioTransmitGate`, a `watch::Sender<PttCapabilityLevel>` for live publication to the bridge, and a `tokio::sync::Mutex` over the active `PttBinding`. Public surface: `set_binding`, `current_capability`, `subscribe_capability`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttController`
- Source SAD: SAD-071, SAD-076
- Verification method: Unit Test, Integration Test

**SDD-089**: `AudioTransmitGate` shall be `Arc<AudioTransmitGate>` wrapping a `tokio::sync::watch::Sender<bool>` and an internal `AtomicBool`. `set(v)` updates both atomically; `load()` reads the atomic; `subscribe()` hands out a `watch::Receiver` for the missed-key-up watchdog task.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AudioTransmitGate`
- Source SAD: SAD-075
- Verification method: Unit Test

**SDD-090**: `PttSanitizer` shall implement `tracing_subscriber::Layer` and decorate the existing `RedactingLogLayer`. Records whose field names match any of the following banned field names shall be dropped before `on_event` reaches the wrapped sink: `key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence` (7 fields required by SAD-077) and `key_press_history`, `key_timing` (2 defensive additions for future PTT diagnostic fields that might carry raw key data). The implementation shall be allocation-free on the success path (the typical "no banned field" case).

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttSanitizer`
- Source SAD: SAD-077
- Verification method: Unit Test, Privacy Review

**SDD-091**: `PttCapabilityBadge` shall be a Flutter widget rendered inside the Voice Bar, subscribed to the FRB stream of `BridgeEvent::PttCapability`. The widget shall map each enum value to a short user-facing label and shall render an info icon that opens a per-platform explanation sheet when the resolved capability is `L0Focused`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttCapabilityBadge`
- Source SAD: SAD-078
- Verification method: UI Review, User Acceptance Test

**SDD-092**: `MissedKeyUpWatchdog` shall be a tokio task spawned by the audio engine that holds the `watch::Receiver<bool>` from `AudioTransmitGate::subscribe()`. On each transition from `false` to `true` the task records the timestamp; on each `true -> false` transition the task clears the timestamp. If the transition timeline shows `true` for longer than the configured timeout the task calls `AudioTransmitGate::set(false)` and emits a sanitised diagnostic record.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MissedKeyUpWatchdog`
- Source SAD: SAD-079
- Verification method: Unit Test, Integration Test

**SDD-093**: `PttInputClass` shall be a Rust enum in `chanora_audio::ptt_backends` with variants `None`, `Keyboard`, and `MouseSideButton`. The enum is the only carrier of the user's bound input class across the audio + bridge + Flutter boundary; its `as_str(&self) -> &'static str` mapping returns the diagnostic-safe label (`""` / `"keyboard"` / `"mouse-side-button"`) consumed by `PttBackendDescriptor::bound_input_class`. The Windows backend ladder and the macOS event-tap backend shall observe the `MouseSideButton` variant on their binding-rebind path and translate it into the platform's native side-button identifier internally; the Linux GNOME-Wayland portal backend shall accept whatever input class the portal returns from `BindShortcuts` and apply the same classifier already documented in `desktop-ptt-architecture.md` §5.3. The Flutter binding-capture dialog shall capture mouse side-button presses through the `PointerEvent.buttons` bitmask (back = `0x08`, forward = `0x10`) and never forward the raw bitmask beyond the dialog — the bridge `set_ptt_binding` call carries only the enum variant.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttInputClass`, `WindowsRawInputBackend`, `WindowsHookBackend`, `MacOSEventTapBackend`, `LinuxGnomeWaylandBackend`, `_PttBindingCaptureDialog`
- Source SAD: SAD-080
- Verification method: Unit Test, Platform Test (Windows / macOS / Linux), UI Review

**SDD-094**: `chanora_bridge::voice::voice_join(channel_id: ChannelId) -> Result<(), VoiceError>` and `chanora_bridge::voice::voice_leave() -> Result<(), VoiceError>` shall be the only public-bridge voice lifecycle calls. Internally `chanora_audio::engine::AudioEngine::ensure_running()` shall be idempotent and shall open the cpal input and output streams on the first call of the session; `chanora_audio::engine::AudioEngine::shutdown_if_idle()` shall be called from `voice_leave` and shall close both streams when no voice channels remain. The Flutter widget tree shall subscribe to `BridgeEvent::VoiceState { in_channel, transmit_mode, mute, release_tail_ms }` through the existing FRB stream and shall render the Voice Bar from that stream. The pre-existing `start_audio` and `stop_audio` FRB symbols shall be deleted from `crates/chanora_bridge/src/api.rs` together with their generated bindings; the corresponding caller in `apps/chanora_flutter/lib/main.dart` shall be removed.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_bridge::voice`, `chanora_audio::engine::AudioEngine`, `BridgeEvent::VoiceState`, `apps/chanora_flutter/lib/main.dart`
- Source SAD: SAD-081
- Verification method: Integration Test, UI Review

**SDD-095**: `chanora_audio::TransmitMode` shall be a `#[repr(u8)]` Rust enum with variants `Ptt = 0`, `Continuous = 1`, `VoiceActivity = 2`. Persistence shall be provided by `chanora_storage::IdentityStore::set_transmit_mode(&self, mode: TransmitMode)` and `chanora_storage::IdentityStore::get_transmit_mode(&self) -> TransmitMode`, the latter returning `TransmitMode::Ptt` on first read for a fresh install. The bridge surface shall carry the enum across the FFI boundary via `mirror` codegen as `BridgeTransmitMode`. The Flutter settings page in `apps/chanora_flutter/lib/widgets/voice_settings.dart` shall render three radio rows; the `VoiceActivity` row shall be rendered with `enabled: false` and a "Coming soon" trailing label until DEC-030 is resolved and an implementation is allocated.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_audio::TransmitMode`, `chanora_storage::IdentityStore::{set_transmit_mode, get_transmit_mode}`, `BridgeTransmitMode`, `apps/chanora_flutter/lib/widgets/voice_settings.dart`
- Source SAD: SAD-083
- Verification method: Unit Test, UI Review

**SDD-096**: `chanora_audio::release_tail::ReleaseTailTimer` shall be a tokio-task-owning struct exposing `arm(&self, gate: AudioTransmitGate, tail_ms: u32)`, `key_down(&self)`, `key_up(&self)`, and `cancel(&self)`. Internally the struct shall hold a `tokio::sync::watch::Sender<bool>` plus a `JoinHandle<()>` for the pending close. `key_down` shall cancel any pending close by aborting the `JoinHandle` (`cancel_pending()`) and shall set `transmit_active = true` via the gate; `key_up` shall abort the prior close handle via `JoinHandle::abort()` and shall spawn a new task that sleeps for `tail_ms` milliseconds and then sets `transmit_active = false`. Cancellation is performed by aborting the pending `JoinHandle`; the watch channel enables cooperative early exit — the spawned task races `cancel_rx.changed()` against the tail sleep so that it can exit without writing to the gate when the sender is replaced or dropped. The struct shall use no `unsafe`. No `std::sync::Mutex` — interior mutability shall use `std::sync::RwLock` for brief edge-transition writes (`arm`, `key_down`, `key_up`, `cancel`); concurrent reads are uncontended. The watch handle shall be shared via atomic refcounts. The configuration value `release_tail_ms` shall live in the identity store next to `transmit_mode`, with a default of 200 and validated range 0–500 inclusive on every write.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_audio::release_tail::ReleaseTailTimer`, `chanora_storage::IdentityStore` (`release_tail_ms`)
- Source SAD: SAD-082
- Verification method: Unit Test, Integration Test

**SDD-097**: `apps/chanora_flutter/lib/widgets/voice_bar.dart` shall replace the existing `_AudioControls` widget in `apps/chanora_flutter/lib/main.dart` as the rendering surface for voice state. Its input shall be the `BridgeEvent::VoiceState` stream; its children, in render order, shall be: the channel-name pill (visible only when `in_channel` is true); the mode badge (`PTT: <key_label>` / `Continuous` / `Voice activity (coming soon)`); the hard-mute toggle button; the release-tail and threshold disclosure; the level meter; and the PTT capability badge already specified in SDD-091. The "Start audio" button shall be removed from the widget tree. The settings dialog in `apps/chanora_flutter/lib/widgets/voice_settings.dart` shall render the `TransmitMode` radio group, the bind-key button, and a release-tail slider over the range 0–500 ms with step 25 ms; the dialog shall never expose a "Start audio" affordance.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `apps/chanora_flutter/lib/widgets/voice_bar.dart`, `apps/chanora_flutter/lib/widgets/voice_settings.dart`, `apps/chanora_flutter/lib/main.dart`
- Source SAD: SAD-081, SAD-083
- Verification method: UI Review, Widget Test

**SDD-098**: `IOSAudioSessionConfig` shall be a Swift unit that configures `AVAudioSession` with category `.playAndRecord`, mode `.default`, and options `.defaultToSpeaker | .allowBluetoothHFP | .allowBluetoothA2DP`. `setCategory` shall be called from `didFinishLaunching` in the app delegate; `setActive` shall be called from the `UIApplication.didBecomeActiveNotification` observer. The actual session state shall be read back after both calls and logged for verification.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSAudioSessionConfig`
- Source SAD: SAD-061, SAD-064
- Verification method: Platform Test, Release Inspection

**SDD-099**: `IOSPermissionRequester` shall call `AVAudioSession.sharedInstance().requestRecordPermission` approximately 1 second after app launch. The permission result shall be logged. A denied permission shall surface as an audio engine failure at `voice_join` time with a user-safe message; the UI shall not crash or hang.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSPermissionRequester`
- Source SAD: SAD-061
- Verification method: Platform Test, Demo

**SDD-100**: Swift shall observe `AVAudioSession.routeChangeNotification`. On route change where `reason == .oldDeviceUnavailable` or `reason == .newDeviceAvailable`, Swift shall call the Rust bridge method `handleRouteChange()`. The Rust side shall invoke the `ios_voice_unit` restart path, uninitialising then reinitialising per `ios_voice_unit.rs` comments §5. Audio shall continue after rebind.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSRouteChangeHandler`, `ios_voice_unit`
- Source SAD: SAD-061, SAD-064
- Verification method: Platform Test TC-9.3

**SDD-101**: Swift shall observe `AVAudioSession.interruptionNotification`. On `.began` the audio shall pause via `VPIO.stop()`. On `.ended` with `shouldResume == true` the audio shall resume via `VPIO.start()`. A phone call shall yield the audio session; the end of the call shall resume audio without user action. The interruption state shall be communicated to Flutter via `BridgeEvent`.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSInterruptionRecovery`, `BridgeEvent`
- Source SAD: SAD-061
- Verification method: Platform Test TC-9.1, TC-9.2

> **Design note (shouldResume == false):** When iOS signals interruption end with `shouldResume == false`, the VPIO unit remains paused and the `BridgeEvent_InterruptionState` carries `shouldResume: false` to Flutter. The Flutter UI surfaces a snackbar indicating the interruption. The user must manually rejoin the voice channel or the app must implement a "resume audio" action in a future release. This is a known limitation for P0.
>
> **Design note (lifecycle interleaving):** The current iOS audio lifecycle handlers (route change, interruption began/ended) are individually serialized by the session mutex and `_ios_voice_unit` mutex, but do not track an explicit lifecycle state (e.g., `Running`, `Interrupted`, `Restarting`). This means that a route change arriving during an active interruption will restart the VPIO unit even though the app should remain paused. A future release should introduce an explicit iOS audio lifecycle state model that gates restart/resume decisions accordingly. For P0, the risk is mitigated by iOS serializing these notifications on the main thread and the low probability of interleaving in practice.

**SDD-102**: `Info.plist` shall contain `UIBackgroundModes = [audio]`. The VPIO unit shall continue running when the app backgrounds. iOS shall show the red microphone indicator in the status bar while background audio is active. `AVAudioSession` shall remain active. On iOS lock screen, audio shall continue if the network remains available.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Info.plist`, `VPIOUnit`
- Source SAD: SAD-061
- Verification method: Platform Test TC-8

**SDD-103**: iOS P0 shall use `FocusedPttBackend` only. There shall be no `DesktopPttBackend` ladder on iOS. `PttCapabilityLevel` shall always be `L0Focused`. The UI shall render an on-screen PTT button. A capability badge shall explain the iOS limitation. Users shall bind a key through the in-app dialog only when the app is in the foreground.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `FocusedPttBackend`, `PttCapabilityLevel`, `FocusedPttBindingDialog`
- Source SAD: SAD-061, SAD-071
- Verification method: Platform Test TC-3, TC-12

**SDD-104**: `VoiceProcessingIO` AudioUnit shall provide hardware AEC, AGC, and noise suppression. These shall always be engaged and shall not be user-disableable. The Flutter audio processing settings UI shall display these as hardware-enabled with switches disabled and a "Hardware-enabled" label.

- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `VoiceProcessingIO`, `AudioProcessingSettings` (Flutter)
- Source SAD: SAD-061, SAD-065
- Verification method: Platform Test, Audio Test

## 11. Updated SAD-to-SDD Coverage Matrix

| SAD Range | SDD Coverage |
|---|---|
| SAD-001 through SAD-060 | Covered by inherited SDD baseline `SDD-001` through `SDD-070` |
| SAD-061 through SAD-070 | Covered by `SDD-071` through `SDD-080` |
| SAD-061 through SAD-070 | Covered by `SDD-098` through `SDD-104` (iOS platform additions) |


## 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 effective date and preserved layer-specific traceability. |


## Baseline Candidate 0.9.3 Update

| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT detailed design SDD-081 through SDD-092: `DesktopPttBackend` trait, `PttCapabilityLevel` enum, Windows Raw-Input + low-level-hook + Focused implementations, macOS event-tap + Focused implementations, Linux GNOME-Wayland portal + Focused implementations, `PttController`, `AudioTransmitGate`, `PttSanitizer` layer, `PttCapabilityBadge` widget, `MissedKeyUpWatchdog` task. Strict sourcing (`SDD -> SAD` only) preserved. |


## Baseline Candidate 0.9.4 Update

| Version | Date | Description |
|---|---|---|
| 0.9.4 | 2026-05-15 | Added `SDD-093` covering `SAD-080`. `SDD-093` fixes the `PttInputClass` enum surface, the cross-backend rebind contract for `MouseSideButton`, and the Flutter side-button capture path against the `PointerEvent.buttons` bitmask. Strict layered sourcing preserved (`SDD -> SAD` only). |


## Baseline Candidate 0.9.5 Update

| Version | Date | Description |
|---|---|---|
| 0.9.5 | 2026-05-15 | Added v1 audio + PTT lifecycle detailed design SDD-094 through SDD-097 sourced from SAD-081..083: bridge surface drops `start_audio` / `stop_audio` and exposes `chanora_bridge::voice::voice_join` / `voice_leave` with idempotent `AudioEngine::ensure_running` and `shutdown_if_idle`, `chanora_audio::TransmitMode` as `#[repr(u8)]` enum persisted via `chanora_storage::IdentityStore::{set,get}_transmit_mode` and mirrored across FRB as `BridgeTransmitMode`, `chanora_audio::release_tail::ReleaseTailTimer` as a tokio-task-owning adapter on the watch handle (no `unsafe`, no mutex; configurable 0–500 ms via `release_tail_ms`), and the new `apps/chanora_flutter/lib/widgets/voice_bar.dart` + `voice_settings.dart` surfaces replacing the legacy `_AudioControls` widget. Strict layered sourcing preserved (`SDD -> SAD` only). |

## Baseline Candidate 0.9.6 Update

| Version | Date | Description |
|---|---|---|
| 0.9.6 | 2026-05-17 | Added iOS P0 platform SDD-098 through SDD-104 to close traceability gaps identified in the P0 audit: `IOSAudioSessionConfig` (AVAudioSession `.playAndRecord` configuration), `IOSPermissionRequester` (microphone permission flow), `IOSRouteChangeHandler` (route change observation and Rust bridge call), `IOSInterruptionRecovery` (audio interruption handling), `Info.plist` / `VPIOUnit` (background audio), `FocusedPttBackend` only (iOS no global PTT), and `VoiceProcessingIO` (hardware AEC/AGC/NS always engaged). Sourced from SAD-061, SAD-064, SAD-065, SAD-071. Strict layered sourcing preserved (`SDD -> SAD` only). |

## Baseline Candidate 0.9.7 Update

| Version | Date | Description |
|---|---|---|
| 0.9.7 | 2026-05-17 | Added design notes to SDD-101: (1) `shouldResume == false` behavior for iOS audio interruption recovery — VPIO remains paused, `BridgeEvent_InterruptionState` carries `shouldResume: false` to Flutter, snackbar surfaces the interruption, manual rejoin required; (2) iOS audio lifecycle interleaving concern — handlers are individually serialized but lack explicit lifecycle state, route-change-during-interruption risk is mitigated by iOS main-thread serialization for P0. |