# Chanora SAD — Software Architecture Description **Document type:** SAD / Software Architecture Description **Process alignment:** ASPICE SWE.2 Software Architectural Design **Version:** 0.9.8 **Status:** Baseline Candidate **Language:** English **Product:** Chanora **Architecture baseline:** Flutter + Rust Core **Lifecycle position:** `SysRS -> SysDes -> SRS -> SAD -> SDD` **Repo path:** `docs/architecture/sad.md` --- ## 1. Purpose This Software Architecture Description defines the software architecture for Chanora. The SAD is intentionally structured as an architecture document, not only a list of modules. It includes: - Stakeholders and concerns - Architecture drivers and constraints - System context view - Container view - Component view - Runtime / sequence views - Deployment view - Data and storage view - Security and privacy view - Diagnostics and observability view - UI architecture view - Audio architecture view - Protocol architecture view - Internationalization architecture view - Architecture decision records - SRS-to-SAD traceability ## 2. Strict Traceability Rules The documentation hierarchy is: ```text SysRS -> SysDes -> SRS -> SAD -> SDD ``` The SAD shall use only the SRS layer as its direct source. Rules: ```text SAD items shall use Source SRS only. SAD items shall not use direct system-requirement sources. SAD items shall not use direct system-design sources. SDD items shall use Source SAD only. ``` ## 3. Stakeholders and Architecture Concerns | Stakeholder | Concerns | |---|---| | End user | Fast voice access, stable connection, clear UI, safe controls | | Power user | Audio configuration, diagnostics, reliable reconnect | | Software team | Clear module boundaries, testability, maintainability | | Platform team | OS permissions, audio routing, lifecycle behavior, packaging | | QA team | Traceability, test seams, platform coverage, regression verification | | Security reviewer | Secret storage, redaction, input validation, diagnostics safety | | UX designer | Material 3 consistency, adaptive layout, accessibility, i18n | | Release operator | Repeatable builds, signing, packaging, release metadata | ## 4. Architecture Drivers | Driver | Architectural impact | |---|---| | Flutter + Rust Core | UI and core logic are separated by bridge DTOs and event streams. | | `tsclientlib` | Protocol integration is isolated inside a protocol adapter. | | Cross-platform operation | Platform behavior is isolated behind platform services and adapters. | | Low-latency voice | Real-time audio processing is isolated from UI rendering. | | Material 3 baseline | UI architecture uses a design-system layer above Material 3. | | Strict traceability | SAD derives only from SRS and SDD derives only from SAD. | | i18n readiness | Product localization, server content, Unicode, and diagnostics text are separated. | | Diagnostics and support | Logging, redaction, exports, and machine-readable diagnostics are centralized. | ## 5. Context View ```text User -> Chanora Flutter Client -> Rust Core -> tsclientlib Protocol Adapter -> External TeamSpeak-compatible Server Chanora Flutter Client -> Operating System Services -> Audio devices -> Secure storage -> Permissions -> Notifications -> Lifecycle / insets / routing ``` ### Context boundaries Inside Chanora software: - Flutter app shell - Chanora design system - Feature modules - Flutter state and view models - Bridge facade - Rust Core - Protocol adapter - Audio subsystem - Storage subsystem - Diagnostics subsystem - Localization subsystem - Platform service abstractions Outside Chanora software: - External compatible voice servers - Operating systems - Physical audio devices - App stores / package repositories - Network infrastructure ## 6. Container View ```text +---------------------------------------------------------------+ | Flutter Application Container | | App Shell | | Design System | | Adaptive Shell | | Feature Modules | | Flutter State / View Models | | Localization Service | | Platform Services | +------------------------- Bridge DTOs / Events ----------------+ | Rust Core Container | | Connection Manager | | State Synchronization | | Protocol Adapter | | Audio Engine | | Storage Services | | Diagnostics | +---------------------------------------------------------------+ ``` | Container | Responsibility | |---|---| | Flutter Application Container | UI, navigation, Material 3 theming, accessibility, localization, platform presentation | | Bridge Container | Stable DTOs, commands, event streams, error mapping | | Rust Core Container | Authoritative connection, protocol coordination, state, audio, storage, diagnostics | | Platform Services Container | OS-specific services exposed to Flutter/Rust boundaries | | External Server | Compatible server providing channels, users, voice, and text | ## 7. Component View ### 7.1 Flutter application components | Component | Responsibility | |---|---| | `app_shell` | App initialization, routing, global providers, theme mode, localization bootstrap | | `design_system` | Material 3 configuration, Chanora tokens, typography, shapes, motion, density | | `adaptive_shell` | Compact, medium, expanded layout branching | | `features/connect` | Manual connection and bookmark entry | | `features/server` | Channel tree, users, connection status | | `features/voice` | Voice controls and audio settings | | `features/chat` | Channel text UI | | `features/settings` | User settings, audio processing settings, i18n options | | `features/diagnostics` | Redacted diagnostics and export flow | | `state` | View models derived from Rust Core events | | `localization` | Product string resources and fallback | | `platform_services` | Insets, back intent, haptics, permissions, platform behavior | ### 7.2 Rust components | Component | Responsibility | |---|---| | `chanora_core` | Top-level Rust API, connection orchestration, command handling | | `chanora_protocol` | `tsclientlib` isolation and protocol event mapping | | `chanora_state` | Snapshot, delta, reducers, authoritative state model | | `chanora_audio` | Capture, processing, encode/decode, jitter, mixing | | `chanora_storage` | Bookmarks, settings, identity references, non-secret data | | `chanora_diagnostics` | Logs, redaction, event recording, export | | `chanora_bridge` | Flutter/Rust DTOs, API, event streams | ## 8. Runtime Views ### 8.1 Application startup ```text Start process -> Initialize platform bindings -> Load localization baseline -> Build Material 3 theme -> Register Chanora design tokens -> Initialize bridge facade -> Initialize app router -> Render adaptive shell ``` ### 8.2 Connect to server ```text User submits connection -> Connect feature controller -> Bridge command -> Rust Core connection manager -> Protocol adapter -> tsclientlib -> External server -> Snapshot fetch -> State reducer -> Core event stream -> Flutter view model -> Server screen render ``` ### 8.3 Incoming server event ```text External server event -> tsclientlib -> Protocol adapter -> Internal protocol event -> State reducer -> Core event -> Bridge stream -> Flutter state -> UI update ``` ### 8.4 Outgoing voice ```text Microphone -> Platform capture -> Audio pipeline -> High-pass filter -> Noise suppression -> Echo canceller -> Automatic gain control -> Push-to-talk / mute gate -> Encoder -> Protocol adapter -> External server ``` ### 8.5 Incoming voice ```text External server -> Protocol adapter -> Jitter buffer -> Decoder -> Per-user mute / volume -> Mixer -> Platform playback ``` ### 8.6 Product-localized text rendering ```text String key -> Localization service -> Locale lookup -> Fallback if missing -> Flutter text widget -> Accessibility semantics ``` ### 8.7 Server-content rendering ```text Server-provided text -> Protocol boundary conversion if required -> UTF-8 internal representation -> DTO / state -> Flutter UI -> Display without translation ``` ## 9. Deployment View | Platform | Deployment form | |---|---| | Windows | Signed installer or packaged desktop artifact | | macOS | Signed and notarized application bundle | | Linux | Selected package format such as AppImage, Flatpak, deb, or rpm | | Android | AAB/APK with platform permissions and foreground voice behavior | | iOS | TestFlight/App Store build with platform permission and audio session behavior | Deployment architecture separates: - Build scripts - Signing assets - Store metadata - Release notes - Platform permission declarations - Runtime configuration ## 10. Data and Storage View | Data type | Storage architecture | |---|---| | Bookmarks | Local database / repository | | Recent servers | Local database / repository | | Audio settings | Local database / repository | | UI preferences | Local database / repository | | Identity secrets | Platform secure storage | | Server passwords | Platform secure storage | | Diagnostic bundles | User-initiated generated export | | Protocol state | Runtime state, rebuilt from snapshot | | Product localization | Static or packaged localization resources | | Server content | Runtime content, optionally session-level persistence later | ## 11. Security and Privacy View Security architecture rules: - Secrets are not stored in plaintext. - Passwords and identity secrets are stored through platform secure storage. - Logs and diagnostic exports are redacted. - User-visible errors do not expose internal stack traces. - Diagnostics export requires user action. - Protocol and platform text conversions occur only at explicit boundaries. - Product localization does not translate server-provided content. ## 12. Diagnostics and Observability View Diagnostics components provide: - Structured logs - Redaction - Network diagnostics - Audio diagnostics - Protocol event recording where enabled - Event replay support where enabled - User-initiated diagnostic export - Stable language-neutral diagnostic keys - Localizable diagnostic display descriptions ## 13. UI Architecture View ```text Material 3 -> Chanora Design System -> Tokens -> Component themes -> Chanora components -> Feature screens -> View models ``` Rules: - Feature screens do not hardcode semantic colors, spacing, shapes, or motion. - Design system owns Material 3 mapping. - Components own accessibility semantics for common controls. - Voice and connection controls remain visible or directly reachable across layouts. - Adaptive shell owns layout class selection. ## 14. Audio Architecture View The audio subsystem is separate from UI rendering. Key elements: - Platform capture - Audio preprocessing - Echo cancellation - Automatic gain control - Noise suppression - High-pass filtering - Voice activity and metering - Push-to-talk and mute gate - Opus-compatible encode/decode - Jitter buffer - Mixer - Playback routing ## 15. Protocol Architecture View The protocol subsystem isolates all `tsclientlib` interaction. Rules: - Flutter does not call `tsclientlib`. - Rust Core does not expose raw protocol library types to Flutter. - Protocol events are converted to internal protocol events. - Protocol errors are converted to user-safe error models. - Reconnect orchestration remains above protocol adapter behavior when required. ## 16. Internationalization Architecture View i18n architecture separates: | Text type | Handling | |---|---| | Product strings | Localized | | Accessibility labels | Localized | | Settings labels | Localized | | Error descriptions | Localized where user-facing | | Diagnostic keys | Stable and language-neutral | | Server names | Preserved, not translated | | Channel names | Preserved, not translated | | Client nicknames | Preserved, not translated | | Chat messages | Preserved, not translated | UTF-8 is the internal representation for cross-layer text. Conversion occurs only at protocol or platform boundaries. ## 17. Architecture Decisions | ADR | Decision | Status | |---|---|---| | ADR-001 | Use Flutter for cross-platform UI | Accepted | | ADR-002 | Use Rust Core for protocol, state, audio, storage, and diagnostics logic | Accepted | | ADR-003 | Use `tsclientlib` and isolate it in the protocol adapter | Accepted | | ADR-004 | Use Material 3 as UI design baseline | Accepted | | ADR-005 | Define Chanora Design System above Material 3 | Accepted | | ADR-006 | Use strict `SysRS -> SysDes -> SRS -> SAD -> SDD` traceability | Accepted | | ADR-007 | Do not let SAD link directly to system requirement or system design IDs | Accepted | | ADR-008 | Use UTF-8 internally and boundary-only string conversion | Accepted | | ADR-009 | Treat server-provided text as content, not product localization | Accepted | ## 18. SWE.2 Architecture Completeness and Evaluation Criteria The architecture shall be evaluated against the following SWE.2 criteria before baseline approval and after architecture-affecting changes. | Criterion | Architecture evidence | |---|---| | Software elements are identified | Component View and Software Architecture Items | | Software requirements are allocated | SRS-to-SAD coverage matrix | | Interfaces are defined | Interface Catalog | | Dynamic behavior is defined | Runtime Views | | Resource consumption objectives are considered | Performance and Resource View | | Architecture is technically feasible | Architecture evaluation checklist | | Architecture is testable | Verification hooks and test seams | | Traceability is maintained | Direct `Source SRS` references only | | Consistency is maintained | View consistency checklist and change impact review | | Architecture is communicated | Change History and baseline approval record | ## 19. Interface Catalog The interface catalog records software architectural interfaces. Detailed design shall refine these interfaces in the SDD. | Interface ID | Interface | Producer | Consumer | Data / message | Error handling | Source SAD | |---|---|---|---|---|---|---| | IF-SAD-001 | Flutter command bridge | Flutter Feature Controller | Rust Bridge Facade | Command DTO | Bridge error DTO | SAD-040 | | IF-SAD-002 | Rust event stream | Rust Core | Flutter State | Core event DTO | Stream close / error event | SAD-041 | | IF-SAD-003 | Protocol adapter boundary | Rust Core | Protocol Adapter | Protocol command / event | Protocol error mapping | SAD-032 | | IF-SAD-004 | Audio capture boundary | Platform Audio | Audio Subsystem | Audio frame | Device unavailable / underrun | SAD-034 | | IF-SAD-005 | Audio playback boundary | Audio Subsystem | Platform Audio | Mixed audio frame | Device unavailable / route changed | SAD-034 | | IF-SAD-006 | Secure storage boundary | Storage Service | Platform Secure Storage | Secret key/value | Secure-store error | SAD-035 | | IF-SAD-007 | Localization lookup | Flutter UI | Localization Service | String key + parameters | Missing-key fallback | SAD-020 | | IF-SAD-008 | Server-content text path | Protocol Adapter | Flutter UI | UTF-8 content text | Boundary conversion error | SAD-021, SAD-022 | | IF-SAD-009 | Diagnostics export | Diagnostics | File/share target | Redacted diagnostic bundle | Export failure | SAD-036, SAD-050 | | IF-SAD-010 | Platform behavior service | Flutter Shell | Platform Services | Insets, back, haptics, permissions | Unsupported platform behavior | SAD-017, SAD-018, SAD-019 | ## 20. Performance and Resource View | Area | Objective | Architecture mechanism | |---|---|---| | UI responsiveness | Avoid blocking UI during connection, sync, reconnect, and diagnostics export | Async bridge calls, view models, Rust Core background work | | Audio latency | Minimize local audio pipeline latency | Dedicated audio subsystem and platform audio adapters | | Memory growth | Avoid unbounded growth in logs, audio buffers, chat history, and event queues | Bounded buffers, retention policies, diagnostic export controls | | Reconnect | Rebuild state after recoverable connection failure | Connection manager, fresh snapshot, state reducer | | Localization | Avoid runtime string lookup failures | Baseline English fallback and localization service tests | | Diagnostics | Export without leaking secrets | Central redaction and export service | ## 21. Assumptions and Dependencies | ID | Assumption / Dependency | Impact | |---|---|---| | SAD-ASM-001 | Flutter Material 3 support is available on the target Flutter version. | Design System depends on Material 3 widgets and ThemeData behavior. | | SAD-ASM-002 | Rust and Flutter bridge tooling supports stable DTO generation. | Bridge and event stream interfaces depend on stable generated bindings. | | SAD-ASM-003 | `tsclientlib` supports or can be adapted for required MVP protocol behavior. | Protocol Adapter feasibility depends on library capability. | | SAD-ASM-004 | Target operating systems expose required audio, permission, and secure storage services. | Platform Services depend on OS capabilities. | | SAD-ASM-005 | Flutter text rendering can preserve Unicode and support bidirectional text where platform engines support it. | i18n architecture depends on platform text support. | ## 22. Architecture Glossary | Term | Meaning | |---|---| | App Shell | Top-level Flutter composition root for routing, initialization, theme, localization, and adaptive layout | | Design System | Chanora UI layer that maps Material 3 and product semantic tokens to components | | Bridge Facade | Software boundary used by Flutter to call Rust Core and receive Rust events | | Runtime View | Architecture view describing runtime interaction, sequence, or state behavior | | Interface Catalog | Architectural list of software interfaces to be refined by detailed design | | ADR | Architecture Decision Record | | Product string | User-visible string owned by Chanora and eligible for localization | | Server content | User/server-provided text received from a compatible voice server and displayed without translation | ## 23. Software Architecture Items **SAD-001**: The architecture shall use a Flutter App Shell as the top-level software composition root. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter App Shell - Source SRS: SRS-144, SRS-149, SRS-151, SRS-184 - Verification method: Review, Inspection The shell initializes routing, theme, localization, adaptive layout, platform services, and feature containers before rendering feature screens. **SAD-002**: The architecture shall use a Chanora Design System package above Material 3. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Design System - Source SRS: SRS-145, SRS-146, SRS-147, SRS-148, SRS-149 - Verification method: Review, Widget Test The design system contains product tokens, Material 3 theme configuration, component themes, and product semantic mappings. **SAD-003**: The architecture shall isolate feature screens from direct theme-token construction. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Feature Modules, Design System - Source SRS: SRS-150 - Verification method: Static Inspection Feature screens consume design-system APIs and components instead of creating colors, spacing, shape, or motion locally. **SAD-004**: The architecture shall implement connection-state token mapping in the design system. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Design System - Source SRS: SRS-146, SRS-148 - Verification method: Unit Test Connection states such as connected, connecting, reconnecting, disconnected, and error map to product semantic tokens. **SAD-005**: The architecture shall implement voice-state token mapping in the design system. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Design System - Source SRS: SRS-147 - Verification method: Unit Test Voice states such as speaking, muted, deafened, and push-to-talk active map to product semantic tokens. **SAD-006**: The architecture shall implement latency, packet-loss, diagnostics, and error token mapping. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Design System - Source SRS: SRS-148 - Verification method: Unit Test Latency, packet loss, diagnostics severity, warning, and error semantics are separated from Material base colors. **SAD-007**: The architecture shall expose tokens through Flutter theming mechanisms. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Design System - Source SRS: SRS-149 - Verification method: Widget Test ThemeData, ColorScheme, component themes, TextTheme, and ThemeExtension are the allowed token access mechanisms. **SAD-008**: The architecture shall provide an Adaptive Shell that owns window-class resolution. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter App Shell - Source SRS: SRS-151, SRS-152, SRS-153, SRS-154 - Verification method: Widget Test, Integration Test Window class is resolved once at shell level and passed into layout composition. **SAD-009**: The architecture shall implement a compact layout branch. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Adaptive Shell - Source SRS: SRS-152, SRS-155, SRS-156 - Verification method: Integration Test Compact layout uses single-column content and keeps connection and voice controls visible or directly reachable. **SAD-010**: The architecture shall implement a medium layout branch. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Adaptive Shell - Source SRS: SRS-153, SRS-155, SRS-156 - Verification method: Integration Test Medium layout supports side navigation or navigation rail and main content. **SAD-011**: The architecture shall implement an expanded layout branch. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Adaptive Shell - Source SRS: SRS-154, SRS-155, SRS-156 - Verification method: System Test Expanded layout supports persistent panes and persistent voice controls. **SAD-012**: The architecture shall implement a Connection Status UI component. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Components, Feature Modules - Source SRS: SRS-155, SRS-159 - Verification method: Widget Test Connection state is displayed with non-color-only cues. **SAD-013**: The architecture shall implement a persistent VoiceBar component. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Components, Voice Feature - Source SRS: SRS-156 - Verification method: Widget Test, Integration Test VoiceBar exposes mute, deaf, push-to-talk, input level, current channel, and latency summary. **SAD-014**: The architecture shall implement accessible semantics for critical controls. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Components, Localization - Source SRS: SRS-157, SRS-158, SRS-159 - Verification method: Accessibility Test Critical controls expose semantic labels and state descriptions. **SAD-015**: The architecture shall implement keyboard focus traversal for desktop and tablet keyboard use. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter UI - Source SRS: SRS-160 - Verification method: Widget Test, System Test Focusable components use a predictable traversal order and visible focus indication. **SAD-016**: The architecture shall protect critical controls under increased text scaling. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Adaptive Shell, Components - Source SRS: SRS-161 - Verification method: Accessibility Test Shell and components are designed to avoid clipping or loss of critical actions when text scale increases. **SAD-017**: The architecture shall centralize safe-area and inset handling. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter App Shell, Platform Services - Source SRS: SRS-162 - Verification method: Platform Test Safe area, display cutout, system bars, keyboard, and desktop inset handling is performed through shared shell utilities. **SAD-018**: The architecture shall model Android back behavior through platform services. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Platform Services - Source SRS: SRS-163 - Verification method: Platform Test Back behavior is represented as an intent handled by route and shell policy. **SAD-019**: The architecture shall model iOS navigation, keyboard avoidance, safe area, and haptics through platform services. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Platform Services - Source SRS: SRS-164 - Verification method: Platform Test iOS behavior is not hardcoded in feature screens. **SAD-020**: The architecture shall implement a Localization Service for product-owned strings. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Localization Service - Source SRS: SRS-165, SRS-166, SRS-167, SRS-168, SRS-169 - Verification method: Unit Test, Integration Test Product strings are loaded from localization resources with English fallback. **SAD-021**: The architecture shall separate product localization from server-provided content. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Localization Service, Protocol DTOs, Flutter UI - Source SRS: SRS-170 - Verification method: Integration Test Server content is displayed as content and is not translated by the client. **SAD-022**: The architecture shall preserve Unicode through protocol, bridge, state, and UI paths. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Protocol Adapter, Bridge, Rust Core, Flutter UI - Source SRS: SRS-171, SRS-172 - Verification method: Integration Test DTOs and internal state use UTF-8 compatible representations. **SAD-023**: The architecture shall isolate non-UTF-8 conversion in boundary adapters. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Protocol Adapter, Platform Adapter, Bridge - Source SRS: SRS-173 - Verification method: Inspection, Integration Test Encoding conversion is not permitted in feature screens or general business logic. **SAD-024**: The architecture shall preserve multilingual content in diagnostics except for intentional redaction. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Diagnostics, Storage - Source SRS: SRS-174 - Verification method: Test, Audit Diagnostic payload builders preserve Unicode values while applying redaction policy. **SAD-025**: The architecture shall support bidirectional text where the platform text engine supports it. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter UI - Source SRS: SRS-175 - Verification method: Localization Test Text widgets are selected and configured to allow natural bidirectional rendering. **SAD-026**: The architecture shall centralize locale-aware formatting. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Localization Service, Diagnostics UI - Source SRS: SRS-176 - Verification method: Localization Test Date, time, number, and visible diagnostic timestamp formatting occurs through localization utilities. **SAD-027**: The architecture shall keep diagnostic machine fields language-neutral. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Diagnostics, Localization Service - Source SRS: SRS-177, SRS-178 - Verification method: Inspection, Test Diagnostic keys and codes remain stable while display descriptions are localized. **SAD-028**: The architecture shall maintain downstream UI/UX and design-system documentation. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: UX, Software Engineering - Source SRS: SRS-179 - Verification method: Review The UI/UX guideline, token guide, component catalog, adaptive layout guide, and platform guide are treated as supporting baselines. **SAD-029**: The architecture shall enforce SRS-only source traceability for SAD. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Software Architecture - Source SRS: SRS-180, SRS-181, SRS-182 - Verification method: Inspection SAD items contain Source SRS and do not contain lower-layer source IDs. **SAD-030**: The architecture shall enforce SAD-only source traceability for SDD. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Software Design - Source SRS: SRS-183 - Verification method: Inspection Detailed design items are derived from SAD items only. **SAD-031**: The architecture shall initialize theme, localization, and platform services before first feature render. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter App Shell - Source SRS: SRS-184 - Verification method: Integration Test The app shell performs initialization sequencing before rendering user-visible feature content. **SAD-032**: The architecture shall isolate TeamSpeak-compatible protocol integration behind Rust protocol components. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Rust Core, Protocol Adapter - Source SRS: SRS-001 through SRS-030 - Verification method: Integration Test Protocol responsibilities remain outside Flutter feature screens. **SAD-033**: The architecture shall isolate authoritative server state in Rust Core and state synchronization components. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Rust Core, State Sync - Source SRS: SRS-031 through SRS-060 - Verification method: System Test Flutter consumes state events and view models rather than mutating protocol state. **SAD-034**: The architecture shall isolate real-time audio processing in the audio subsystem. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio Subsystem, Platform Audio - Source SRS: SRS-061 through SRS-090 - Verification method: Audio Test Capture, preprocessing, encoding, decoding, jitter buffer, and mixing are assigned to audio software components. **SAD-035**: The architecture shall isolate local storage and secure storage behavior behind storage components. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Storage, Platform Secure Storage - Source SRS: SRS-091 through SRS-110 - Verification method: Security Test, Inspection Storage APIs separate non-secret data from secrets. **SAD-036**: The architecture shall isolate diagnostics and redaction behavior in diagnostics components. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Diagnostics - Source SRS: SRS-111 through SRS-124 - Verification method: Audit, Test Logs, event capture, export, and redaction stay centralized. **SAD-037**: The architecture shall isolate deployment, release, and packaging support in build and release assets. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Build, Release, Operations - Source SRS: SRS-125 through SRS-134 - Verification method: Inspection, Demo Packaging and release decisions are outside feature-screen code. **SAD-038**: The architecture shall provide verification hooks for requirements traceability and platform validation. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Verification Support - Source SRS: SRS-135 through SRS-143 - Verification method: Review, Inspection Traceability checks and verification evidence are supported by documentation and test structure. **SAD-039**: The architecture shall use view models as the boundary between feature screens and application state. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Flutter State - Source SRS: SRS-001 through SRS-184 - Verification method: Unit Test, Review Feature screens receive render-ready state and issue user intents through controllers. **SAD-040**: The architecture shall use a bridge facade as the only Flutter-to-Rust command boundary. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Bridge Facade - Source SRS: SRS-001 through SRS-184 - Verification method: Inspection, Integration Test Flutter feature modules call bridge services rather than Rust implementation details. **SAD-041**: The architecture shall map asynchronous Rust events into Flutter UI state updates. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Bridge, Flutter State - Source SRS: SRS-001 through SRS-184 - Verification method: Integration Test Core event streams update UI view models deterministically. **SAD-042**: The architecture shall define test seams for theme, localization, adaptive shell, platform services, and bridge facade. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Verification Support - Source SRS: SRS-165 through SRS-184 - Verification method: Review, Test Test seams allow widget, integration, platform, and golden tests. **SAD-043**: The architecture shall support light and dark theme mode behavior. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Design System, Flutter App Shell - Source SRS: SRS-157 - Verification method: Widget Test Theme mode is controlled centrally and propagates through Material theme data. **SAD-044**: The architecture shall allow dynamic color as an optional enhancement without overriding Chanora semantic state tokens. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Design System - Source SRS: SRS-158 - Verification method: Widget Test Dynamic color affects base Material scheme but not product semantic safety states. **SAD-045**: The architecture shall keep future SDD derivation independent from non-SAD requirement IDs. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Software Design - Source SRS: SRS-183 - Verification method: Inspection The SAD-to-SDD boundary is the only source path for SDD. **SAD-046**: The architecture shall include C4-style architecture views in the SAD baseline. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review Context, container, component, runtime, deployment, and data views are part of the architecture baseline. **SAD-047**: The architecture shall include ADRs for architecturally significant decisions. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review ADR entries document the rationale for major design decisions. **SAD-048**: The architecture shall identify software stakeholders and architecture concerns. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review Stakeholder concerns guide architecture views and tradeoffs. **SAD-049**: The architecture shall include deployment and operational architecture views. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Release Architecture - Source SRS: SRS-125 through SRS-134, SRS-182 - Verification method: Review, Inspection Deployment view covers platform-specific packaging and release architecture. **SAD-050**: The architecture shall include diagnostics and observability architecture views. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Diagnostics Architecture - Source SRS: SRS-111 through SRS-124, SRS-177, SRS-178 - Verification method: Review, Test Diagnostics view covers logs, redaction, event keys, localization, and exports. **SAD-051**: The architecture shall include a SWE.2 evaluation checklist covering software elements, allocation, interfaces, dynamic behavior, resource objectives, feasibility, testability, traceability, consistency, and communication. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review, Inspection The checklist is used before SAD baseline approval and after architecture-affecting changes. **SAD-052**: The architecture shall maintain an interface catalog for architecturally significant software interfaces. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review, Inspection The catalog records producers, consumers, data/message type, and error handling for each architectural interface. **SAD-053**: The architecture shall include performance and resource views for UI responsiveness, audio latency, memory growth, reconnect, localization, and diagnostics. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review, Analysis Performance and resource objectives are linked to architecture mechanisms. **SAD-054**: The architecture shall document assumptions and dependencies that affect design feasibility. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review Assumptions and dependencies are reviewed during change impact analysis. **SAD-055**: The architecture shall include a glossary for architecture-specific terms. - Status: Baseline - Type: Software Architecture Item - Stage: P2 / Production - Allocated to: Software Architecture - Source SRS: SRS-182 - Verification method: Review The glossary reduces ambiguity across architecture, detailed design, and verification activities. **SAD-056**: The architecture shall define software interface error-handling responsibilities at the architectural level. - Status: Baseline - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Software Architecture, Bridge, Rust Core, Platform Services - Source SRS: SRS-182 - Verification method: Review, Integration Test Each architecturally significant interface identifies error handling responsibilities. **SAD-057**: The architecture shall explicitly support detailed design refinement of interface names, types, units, resolutions, ranges, and default values. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture, Software Design - Source SRS: SRS-183 - Verification method: Review, Inspection The SAD delegates detailed per-unit interface metadata to the SDD. **SAD-058**: The architecture shall define software units as the target decomposition level for SWE.3 detailed design. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture, Software Design - Source SRS: SRS-183 - Verification method: Review Software components are decomposed into software units in the SDD. **SAD-059**: The architecture shall define that SDD detail must be sufficient to support implementation and unit verification. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Design, Verification - Source SRS: SRS-183 - Verification method: Review, Inspection The required SDD detail level is driven by implementation and unit verification needs. **SAD-060**: The architecture shall require SAD and SDD changes to be communicated to relevant affected parties before downstream implementation or verification updates are treated as baseline. - Status: Baseline - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Software Architecture, Software Design, Verification - Source SRS: SRS-180, SRS-182, SRS-183 - Verification method: Review Communication evidence is maintained through change history and baseline approval records. ## 24. SRS-to-SAD Coverage Matrix ### 24.1 Cross-cutting + platform-specific allocations A single SRS item may be intentionally allocated to more than one SAD item when it has both a cross-cutting concern (logging, diagnostics, lifecycle, error handling, redaction, permission policy) and a platform-specific architectural realization (Android foreground service, iOS background audio session, macOS permission gating, Linux portal binding, etc.). In that case the SAD records both anchors: the cross-cutting anchor covers the concern at the architecture level, and the platform-specific anchor covers the realization on a particular OS. This is a deliberate dual allocation, not a duplication, and the §24.2 matrix marks affected rows explicitly. Worked example: SRS-111 (foreground voice-session behaviour) is allocated both to SAD-036 (cross-cutting diagnostics / lifecycle isolation across SRS-111..124) and to SAD-086 (Android `AndroidVoiceForegroundService` realization). The cross-cutting anchor is the right place to refine concern-wide rules; the platform-specific anchor is the right place to refine the OS-bound element. ### 24.2 SRS-to-SAD coverage matrix | SRS Range | SAD Coverage | |---|---| | SRS-001 through SRS-030 | SAD-032, SAD-039, SAD-040, SAD-041 | | SRS-031 through SRS-060 | SAD-033, SAD-039, SAD-041 | | SRS-061 through SRS-090 | SAD-034, SAD-039, SAD-041 | | SRS-091 through SRS-110 | SAD-035 | | SRS-111 through SRS-124 | SAD-036, SAD-050 (cross-cutting). SRS-111 additionally allocated to SAD-086 (Android-specific realization) per §24.1 dual-allocation pattern. | | SRS-125 through SRS-134 | SAD-037, SAD-049 | | SRS-135 through SRS-143 | SAD-038 | | SRS-144 through SRS-184 | SAD-001 through SAD-031, SAD-039 through SAD-060 | ## 25. Change History | Version | Date | Description | |---|---|---| | 0.1.0 | 2026-05-14 | Initial SAD baseline covering SRS-001 through SRS-184 and enforcing SRS-only direct traceability. | | 0.2.0 | 2026-05-14 | Expanded SAD into a full software architecture document with stakeholders, concerns, context/container/component/runtime/deployment/data/security/diagnostics/UI/audio/protocol/i18n views and ADRs. | | 0.3.0 | 2026-05-14 | Added SWE.2 evaluation checklist, interface catalog, performance/resource view, assumptions/dependencies, glossary, and SDD refinement requirements. | --- ## 26. Platform Baseline and Product Decision Architecture Addendum **SAD-061**: The software architecture shall isolate iOS runtime minimum version configuration from feature logic. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: iOS Build Configuration, Platform Services - Source SRS: SRS-185 - Verification method: Platform Test, Inspection **SAD-062**: The software architecture shall treat Apple App Store SDK compliance as a release pipeline and build configuration responsibility. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Release Pipeline, iOS Build Configuration - Source SRS: SRS-186 - Verification method: Release Inspection **SAD-063**: The software architecture shall isolate Android runtime minimum version and Play target API compliance in Android build configuration and platform services. The Android minimum runtime baseline is API 28 (Android 9.0) per DEC-004 (Accepted 2026-05-14), which superseded the earlier API 24 recommendation. The `minSdkVersion` / `minSdk` value, the Play target API value, and any conditional platform-capability branching that depends on the minimum baseline shall be expressed in a single Android build-configuration location and consumed by platform services rather than by feature screens; this isolation allows the minimum baseline to be raised, when Flutter, plugin, audio, or platform constraints require it, without touching feature code. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Android Build Configuration, Platform Services, Release Pipeline - Source SRS: SRS-187, SRS-188 - Verification method: Platform Test, Release Inspection **SAD-064**: The software architecture shall model one active connection as the MVP runtime invariant across UI, Rust Core, state synchronization, audio routing, and protocol adapter components. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter UI, Rust Core, State Sync, Audio Subsystem, Protocol Adapter - Source SRS: SRS-189 - Verification method: System Test, Review **SAD-065**: The software architecture shall assign audio processing defaults and capability detection to the audio subsystem and settings presentation layer. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio Subsystem, Platform Audio, Settings UI - Source SRS: SRS-190 - Verification method: Audio Test **SAD-066**: The software architecture shall hide platform-native and fallback audio processing implementations behind the audio subsystem interface. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P1 / Beta - Allocated to: Audio Subsystem, Platform Audio Adapter - Source SRS: SRS-191 - Verification method: Architecture Review, Audio Test **SAD-067**: The software architecture shall isolate non-secret local persistence in a database repository layer and secret persistence in platform secure storage services. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Storage, Platform Secure Storage - Source SRS: SRS-192 - Verification method: Storage Test, Security Audit **SAD-068**: The software architecture shall use a stable typed bridge facade with schema-controlled DTO boundaries between Flutter and Rust. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Bridge Facade, Flutter State, Rust Core - Source SRS: SRS-193 - Verification method: Integration Test, Architecture Review **SAD-069**: The software architecture shall exclude automatic telemetry, automatic diagnostic upload, and automatic crash reporting from MVP components and release configuration. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Diagnostics, Privacy, Release Pipeline - Source SRS: SRS-194 - Verification method: Privacy Review, Security Audit **SAD-070**: The software architecture shall record the product decisions affecting platform baselines, connection scope, audio defaults, audio implementation path, storage, bridge, diagnostics, and crash reporting in the ADR and decision baseline. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Software Architecture, Documentation Control - Source SRS: SRS-185 through SRS-194 - Verification method: Review, Inspection **SAD-071**: The software architecture shall isolate desktop PTT into a `DesktopPttBackend` trait owned by the audio subsystem, with the active implementation selected at runtime by a `platform_input::select` factory. Only the factory and the audio engine know which implementation is active; the rest of the application sees only the trait surface and the published capability level. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio, Platform Input - Source SRS: SRS-195 - Verification method: Architecture Review, Unit Test **SAD-072**: The Windows PTT backend shall be a three-level ladder (`WindowsRawInputBackend` -> `WindowsHookBackend` -> `FocusedPttBackend`). The ladder is evaluated once at audio-engine start; the chosen rung is fixed for the lifetime of that engine and is reported as the backend identifier. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio (Windows) - Source SRS: SRS-197 - Verification method: Platform Test (Windows), Architecture Review **SAD-073**: The macOS PTT backend shall be a two-level ladder (`MacOSEventTapBackend` -> `FocusedPttBackend`) with explicit permission state surfaced through `PttCapabilityLevel`. The permission query shall not block the audio-engine start path; an undecided permission shall resolve to `L0` and may upgrade asynchronously when the user grants the permission. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio (macOS) - Source SRS: SRS-198 - Verification method: Platform Test (macOS), Architecture Review **SAD-074**: The Linux PTT backend shall be a two-level ladder (`LinuxGnomeWaylandBackend` using the freedesktop `org.freedesktop.portal.GlobalShortcuts` interface, -> `FocusedPttBackend`). Untested display servers, untested compositors, and missing D-Bus access shall all resolve to `L0`. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio (Linux) - Source SRS: SRS-199 - Verification method: Platform Test (Linux, GNOME Wayland), Architecture Review **SAD-075**: The audio engine shall expose `AudioTransmitGate`, a thin object that owns the `transmit_active` AtomicBool and exposes `set` and `load` operations only. The Opus encoder feed shall consult `AudioTransmitGate::load()` once per outbound frame; no other code path may flip `transmit_active`. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio - Source SRS: SRS-201 - Verification method: Unit Test, Audio Test **SAD-076**: The bridge shall expose PTT events through the existing `BridgeEvent` stream, adding a `BridgeEvent::PttCapability { level, backend_id }` variant. The bridge shall never carry raw key codes or scan codes across the FFI boundary; the trait surface and the event shape together enforce SRS-202 at the architectural layer. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Bridge, Audio, Diagnostics - Source SRS: SRS-202 - Verification method: Architecture Review, Privacy Review **SAD-077**: The diagnostics subsystem shall add a `PttSanitizer` decorator over the `RedactingLogLayer` log sink. The decorator shall scan each record's field set for the well-known names `key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence` and drop the record before it reaches storage. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Diagnostics - Source SRS: SRS-202 - Verification method: Unit Test, Privacy Review **SAD-078**: The Flutter UI shall consume `BridgeEvent::PttCapability` and render a small capability badge in the Voice Bar. When the capability resolves to `L0` on a platform that the user reasonably expected to support Global PTT (for example Windows or macOS with the relevant permission undecided), the UI shall render an explanation row pointing to the corresponding fix (run-as-administrator path, permission grant path, environment-not-supported note). - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Flutter UI - Source SRS: SRS-196, SRS-198 - Verification method: UI Review, User Acceptance Test **SAD-079**: The audio engine shall own the missed-key-up watchdog as a single tokio task that subscribes to `transmit_active` transitions through a `tokio::sync::watch` channel; on a configured timeout (default 30 s, owner-tunable) without a release event, the task shall clear `transmit_active` and emit a sanitised diagnostic record. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio - Source SRS: SRS-203 - Verification method: Unit Test, Integration Test **SAD-080**: The software architecture shall expose a mouse-side-button input class as a first-class member of the cross-platform PTT binding type so the Windows and macOS backends can drive `transmit_active` from `Mouse4` / `Mouse5` events while the Linux GNOME-Wayland portal backend honours whatever input classes the portal's own dialog returns. The bridge surface and the Flutter binding-capture dialog shall carry the same coarse class without ever exposing a raw mouse button id beyond the `PointerEvent.buttons` bitmask on the platform side. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio (Windows / macOS / Linux), Bridge, Flutter UI - Source SRS: SRS-200 - Verification method: Unit Test, Platform Test, UI Review **SAD-081**: The software architecture shall remove the `start_audio` and `stop_audio` bridge calls from the public bridge surface and shall replace them with `voice_join(channel_id) -> Result<(), VoiceError>` and `voice_leave() -> Result<(), VoiceError>`. The audio engine's `ensure_running()` private method shall be invoked from the `voice_join` handler on first call of the session and shall be idempotent; the `voice_leave` handler shall call a private `shutdown_if_idle()` that closes the input and output streams when no voice channels remain. The Voice Bar UI shall not surface any manual-start affordance and shall instead key off the bridge event stream `BridgeEvent::VoiceState { in_channel, transmit_mode, mute, release_tail_ms }`, which the audio subsystem publishes on every lifecycle transition. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio, Bridge, Flutter UI - Source SRS: SRS-204 - Verification method: Integration Test, UI Review **SAD-082**: The software architecture shall add a `ReleaseTailTimer` element to the audio subsystem, owned by the `PttController` and acting as an adapter between the `DesktopPttBackend` `transmit` signal and the `AudioTransmitGate::set()` call. On key-down the adapter forwards `true` immediately; on key-up the adapter starts a tokio sleep of `release_tail_ms` (default 200, configurable 0–500); a key-down within the sleep window cancels the pending close; a timer expiration calls `AudioTransmitGate::set(false)`. The adapter is independent of the missed-key-up watchdog defined in SAD-079 and does not interact with `capture_active`. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio - Source SRS: SRS-206 - Verification method: Unit Test, Integration Test **SAD-083**: The software architecture shall add a `TransmitModeSelector` element owned by the audio engine that consults the current `TransmitMode` from the identity store on every state evaluation. In `Ptt` mode the selector defers to the `PttController` + `ReleaseTailTimer` pipeline; in `Continuous` mode the selector sets `transmit_active = !mute` while `in_channel` is true and clears `transmit_active` otherwise; in `VoiceActivity` mode (placeholder per DEC-030) the selector shall behave identically to `Continuous` until a VAD implementation is allocated in a later baseline. The selector shall be the only writer of `transmit_active` other than the missed-key-up watchdog defined in SAD-079, and the hard-mute toggle defined in SRS-207 shall be applied by the selector as a final clamp on the output value. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio - Source SRS: SRS-205, SRS-207 - Verification method: Unit Test, Integration Test **SAD-084**: The software architecture shall allocate Android in-call audio-mode management to an `AndroidAudioModeController` element inside the Android platform audio adapter, owned by the audio subsystem and bound to the voice-session lifecycle rather than to any UI screen lifecycle. The controller shall engage Android's voice-communication audio mode (for example `AudioManager.setMode(MODE_IN_COMMUNICATION)` or an equivalent platform routing-assist mechanism) no later than the moment a voice session becomes connected — driven from the same audio-engine lifecycle hook that opens the input/output streams per SAD-081 — so that microphone gain, output routing, echo handling, and Bluetooth SCO behaviour follow Android's voice-communication path rather than the media path. The controller shall snapshot the prior audio mode on engage and restore it on the last voice-session leave. The controller shall be the only writer of the Android audio mode within the application; feature screens, the Flutter UI layer, and the bridge surface shall not reach Android `AudioManager` mode APIs directly. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio Subsystem, Platform Audio Adapter (Android) - Source SRS: SRS-208 - Verification method: Platform Test (Android), Audio Test, Architecture Review **SAD-085**: The software architecture shall extend the Android platform permission adapter (within Platform Services) to own the runtime `RECORD_AUDIO` permission flow on behalf of the audio subsystem, and shall recognise listen-only operation (`capture_active = false` while the output stream remains open, consistent with SAD-081 / SRS-204) as a first-class audio operating mode at the architecture layer rather than as an error or degraded state. The permission adapter shall request `RECORD_AUDIO` at or before voice-session activation, shall expose the current permission state to the audio engine and to the Flutter UI through the existing bridge event stream, and shall block microphone capture (`capture_active` shall remain false) when the permission is not granted, revoked, or undecided. In that case, the `TransmitModeSelector` defined in SAD-083 shall remain clamped such that `transmit_active = false` regardless of PTT or Continuous-mode inputs, while the output mix path defined in SAD-081 continues to operate. The Flutter UI shall surface a user-visible path to grant `RECORD_AUDIO` before retrying transmit; the permission adapter shall not auto-retry beyond Android platform conventions. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Platform Services (Android Permission Adapter), Audio Subsystem, Flutter UI, Bridge - Source SRS: SRS-209 - Verification method: Platform Test (Android), Integration Test, Privacy Review **SAD-086**: The software architecture shall allocate Android foreground-service behaviour for active voice sessions to an `AndroidVoiceForegroundService` element owned by the Android platform services container, bound to the voice-session lifecycle (start on first `voice_join`, stop on last `voice_leave`, consistent with SAD-081) rather than to any UI screen lifecycle. The service shall declare the appropriate Android foreground-service type for voice communication, post the required ongoing notification, and coordinate with the `AndroidAudioModeController` (SAD-084) and the Android permission adapter (SAD-085) so that microphone capture and Bluetooth SCO routing survive UI backgrounding and process trimming under Android background-execution restrictions. Feature screens shall not start, stop, or interrogate the foreground service directly; they shall observe voice-session state through `BridgeEvent::VoiceState`. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Platform Services (Android), Audio Subsystem - Source SRS: SRS-111 - Verification method: Platform Test (Android), Integration Test **SAD-087**: The software architecture shall isolate macOS runtime baseline configuration, universal-binary packaging, framework layout, and CocoaPods integration in macOS build configuration and platform services, parallel to SAD-061 (iOS runtime) and SAD-063 (Android runtime). Specifically: (a) the macOS deployment target shall be expressed in a single macOS build-configuration location (currently `10.15`, declared in `apps/chanora_flutter/macos/chanora_bridge.podspec`) and consumed by platform services rather than feature screens, so the minimum macOS version can be raised without touching feature code; (b) the macOS Rust bridge artifact shall be packaged as a universal binary covering both `arm64` and `x86_64` slices, combined via `lipo` into a single dylib so a single signed framework runs on Apple-silicon and Intel Macs; (c) the bridge shall be delivered as a `.framework` bundle using the macOS `Versions/A` layout convention expected by the system loader and code-signing tools; (d) CocoaPods integration shall be driven by a hand-rolled podspec (the same `chanora_bridge.podspec`) maintained and regenerated through release-pipeline build automation rather than authored ad hoc per release. Feature screens, the Flutter UI layer, and the bridge surface shall not reach macOS build settings or framework layout details directly. This item is the macOS counterpart to SAD-061 / SAD-063 and is the proper SAD anchor for downstream detailed-design items concerning macOS bridge build automation, framework layout, and podspec maintenance. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: macOS Build Configuration, Platform Services (macOS), Release Pipeline - Source SRS: SRS-013 - Source SysDes: SysDes-155 (macOS runtime baseline — deployment target, universal-binary packaging, `.framework` `Versions/A` layout, CocoaPods podspec automation) - Verification method: Platform Test (macOS), Release Inspection, Architecture Review **SAD-088**: The software architecture shall add a `criterion`-based realtime-audio benchmark harness as a first-class architectural element of the `chanora_audio` crate, extending the existing audio-subsystem allocation in SAD-034. The harness lives in `crates/chanora_audio/benches/` as a Cargo-convention `benches/` directory (a sibling of the crate's `src/`, not a public seam of the crate's library API). The harness shall use the `criterion` crate as its measurement framework (selected at this layer; SDD pins the exact version and feature flags). Rationale for `criterion`: it is the de-facto stable-toolchain Rust microbenchmark harness, produces stable statistical output (mean / p50 / p95 / p99) without requiring a nightly compiler, and integrates with `cargo bench` so the same invocation works in developer shells and on CI runners. The harness shall expose one bench function (or one criterion `BenchmarkGroup`) per SysDes-156 metric family, with the following architectural assignment of metric → bench element: (a) `bench_capture_alloc_count` — counts heap allocations on the steady-state `CaptureState::ingest` path after a warmup phase, using a per-bench allocation-counting mechanism (a dev-dependency allocation tracker such as `dhat`, or a custom global-allocator counter — selection deferred to SDD); (b) `bench_capture_callback_wall_clock` — measures wall-clock duration of `CaptureState::ingest` and reports p50 / p95 / p99 from criterion's sample distribution; (c) `bench_opus_encode_latency` — directly times an Opus encoder over a fixed 960-sample / 20 ms input frame; (d) `bench_opus_decode_latency` — directly times the Opus decode path; if the upstream `tsclientlib` `AudioHandler` is opaque to the crate, the bench shall time the smallest decode wrapper the crate owns and the SDD shall name that wrapper; (e) `bench_resampler_throughput` — measures samples-per-second on the three canonical rate pairs (44.1→48, 16→48, 48→48 kHz). The harness shall emit, for each bench function, the SRS-217 baseline JSON record (one record per metric, in the SRS-217 schema); the emission mechanism (a custom `criterion` measurement reporter, a post-bench JSON-aggregation step, or equivalent) is delegated to SDD. The harness shall not introduce any new public seam on the `chanora_audio` crate's library API surface — benches consume the same internal entry points that the realtime callback consumes, so SAD-034's isolation property is preserved. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio Subsystem (`chanora_audio` crate, `benches/` directory; extends SAD-034) - Source SRS: SRS-216, SRS-217 - Source SysDes: SysDes-156 (realtime-audio benchmark surface, SE-13; five metric families; baseline-JSON storage) - Verification method: Inspection (bench-function presence and metric coverage), Bench Run (criterion executes on the host runner), Architecture Review **SAD-089**: The software architecture shall pin the baseline-JSON on-disk path for the SAD-088 harness to `crates/chanora_audio/benches/baselines/x86_64-unknown-linux-gnu.json`, a single deterministic file per host architecture under the crate's `benches/` directory. The filename is keyed on Rust target triple (`x86_64-unknown-linux-gnu`) so future multi-host expansion can add sibling files (`aarch64-apple-darwin.json`, `x86_64-pc-windows-msvc.json`, etc.) without restructuring the directory layout; for the present revision, exactly one such file exists because SysDes-157 fixes the host to Linux x86_64 (`ubuntu-latest`). The file shall be committed to the default branch so that the SAD-090 advisory workflow has a deterministic comparison target at every PR's merge-base commit. The file contents shall conform to the SRS-217 record schema (one record per metric, fields `metric`, `value`, `unit`, `host_arch`, `toolchain`, `git_sha`, `timestamp` at minimum). The file is the sole on-disk output sink of the SAD-088 harness; it is written by exactly one workflow (SAD-091) and read by exactly one workflow (SAD-090) — see SAD-090 / SAD-091 for the workflow isolation property. Multi-host baselines (additional sibling files keyed on alternate target triples) are explicitly out of scope for this revision per SysDes-157 point 2. - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Audio Subsystem (`chanora_audio` crate, `benches/baselines/` subdirectory; output sink of SAD-088) - Source SRS: SRS-217 - Source SysDes: SysDes-156 (baseline-JSON storage; deterministic repo location) - Verification method: Inspection (file path, schema), Bench Run (file is regenerable end-to-end) **SAD-090**: The software architecture shall add an advisory CI workflow file `.github/workflows/bench-advisory.yml` to the build/release/operations allocation (extending SAD-037), realizing the SRS-218 advisory-reporting workflow. Triggers: `pull_request` against the default branch, plus `push` to the default branch (matching SRS-218 clause 1; tag pushes and non-default branch pushes are excluded). Runner: `ubuntu-latest` (the sole host in scope per SysDes-157 point 2). Step shape (high-level; SDD authors the exact YAML): (1) checkout the PR head; (2) install the Rust toolchain pinned by the repo's `rust-toolchain.toml`; (3) for each bench function defined under SAD-088, invoke `cargo bench` on the `chanora_audio` crate; (4) read the baseline JSON at SAD-089's path *as of the PR's merge-base commit* (using `git show :crates/chanora_audio/benches/baselines/x86_64-unknown-linux-gnu.json` or an equivalent git-plumbing read) — never the default-branch-tip baseline, per SRS-219's anti-retroactive-reclassification rule; (5) compare current measurements against that merge-base baseline using the SRS-219 per-metric tolerance window; (6) render the comparison as a markdown table with one row per metric and a 🟢 / 🟡 / 🔴 marker per the SAD-determined semantics (see below); (7) post the table as a PR comment via `actions/github-script@v7` or an equivalent comment-posting action (exact action choice delegated to SDD); (8) the workflow's status check shall always exit `success` (exit code 0) regardless of any 🔴 marker, per SRS-218 clause 4 — regression visibility is delivered through the markdown table, not through the check status. The named status check shall follow existing repo workflow-naming convention (e.g. `bench-advisory`; SDD reads existing workflow files and matches the convention). This workflow shall never write to the baseline JSON file authored under SAD-089 — write authority is exclusively SAD-091's, enforcing the SRS-218 clause 5 workflow-isolation property at the architecture layer. Yellow-marker semantics is pinned at this SAD layer (see §24.1 paragraph below). The workflow is allocated to the CI surface (SE-18) and is the realization of the SE-18 anchor previously named only at the SysDes layer (no prior SAD item exists for the SE-18 surface; this is the first such allocation). - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Build, Release, Operations (`.github/workflows/bench-advisory.yml`; extends SAD-037 — CI surface, SE-18 realization) - Source SRS: SRS-218, SRS-219 (tolerance binding consumed by comparator step) - Source SysDes: SysDes-157 (advisory CI integration), SysDes-158 (tolerance window and merge-base-snapshot comparator) - Verification method: Inspection (workflow trigger / runner / non-blocking exit), CI Dry Run (synthetic PR exercises markdown rendering end-to-end), Architecture Review **SAD-091**: The software architecture shall add a separate baseline-update CI workflow file `.github/workflows/bench-baseline-update.yml` to the build/release/operations allocation (extending SAD-037), realizing the SRS-218 clause 5 baseline-update-isolation property. Trigger: `workflow_dispatch` only — the workflow is manually invoked from the GitHub Actions tab on the default branch and shall not fire on `pull_request`, `push`, or any tag event. Runner: `ubuntu-latest` (matching SAD-090's host for byte-comparability of measurements). Step shape: (1) checkout the default branch; (2) install the Rust toolchain pinned by `rust-toolchain.toml`; (3) execute the same `cargo bench` invocations as SAD-090 across the SAD-088 bench functions; (4) write the resulting JSON, conformant to SRS-217's schema, to the SAD-089 path `crates/chanora_audio/benches/baselines/x86_64-unknown-linux-gnu.json` (overwriting the prior file); (5) commit and push the updated file to the default branch — the commit mechanism (a direct push using a GitHub-bot token, the `peter-evans/create-pull-request` action, or an equivalent push action) is delegated to SDD. This workflow is the **only** writer of the SAD-089 baseline JSON. The SAD-090 PR-triggered workflow is strictly a reader. This single-writer property is the architectural realization of SRS-218 clause 5 and shall be invariant under future revisions (any future revision adding a second writer requires a SAD revision, not an SDD revision). - Status: Baseline Candidate - Type: Software Architecture Item - Stage: P0 / MVP - Allocated to: Build, Release, Operations (`.github/workflows/bench-baseline-update.yml`; extends SAD-037 — CI surface, SE-18 realization; sole writer of SAD-089) - Source SRS: SRS-218 (workflow-isolation clause) - Source SysDes: SysDes-157 (baseline-update isolation via `workflow_dispatch`) - Verification method: Inspection (trigger is `workflow_dispatch` only; commit destination is SAD-089's path), CI Dry Run (manual invocation regenerates baseline end-to-end), Architecture Review ### Yellow-marker semantics (pinned at SAD) Pinned at SAD layer to remove a downstream ambiguity that would otherwise surface as an open question in the SAD-090 SDD unit: the 🟡 "within tolerance but trending" marker (SRS-218 clause 3, third element of the marker set) shall be defined as follows: a metric is rendered 🟡 if and only if (a) the metric is within the SRS-219 per-metric tolerance window relative to the merge-base baseline (i.e. it is not 🔴), AND (b) the absolute delta between the PR's current measurement and the **previous run of the SAD-090 workflow on the default branch** (i.e. the most recent default-branch CI bench result, not the baseline JSON itself) is greater than 50% of the SRS-219 tolerance window for that metric. Metrics whose SRS-219 tolerance is exactly zero (the heap-allocation-count metric, SRS-219 clause a) cannot be 🟡 because the 50% trigger is undefined when the window has zero width; for those metrics only 🟢 (zero allocations) and 🔴 (any non-zero allocation count) apply. Rationale for pinning at SAD rather than deferring to SDD: the question "is yellow relative to baseline or relative to previous-run-on-default" is an architectural choice about what state the workflow consumes (baseline JSON only, vs baseline JSON + a previous-runs cache), not an implementation detail; pinning it here fixes the workflow's required inputs at the architecture layer so SDD has a fully determined input set. Operationally, the "previous-run-on-default" datum may be sourced from the SAD-091 baseline (treating the committed baseline as the latest default-branch run, which is the simpler and recommended SDD realization) or from a separate run-history artifact; SDD selects which. ## 27. Updated SRS-to-SAD Coverage Matrix | SRS Range | SAD Coverage | |---|---| | SRS-001 through SRS-184 | Covered by inherited SAD baseline `SAD-001` through `SAD-060` | | SRS-185 through SRS-194 | Covered by `SAD-061` through `SAD-070` | | SRS-195 through SRS-199, SRS-201 through SRS-203 | Covered by `SAD-071` through `SAD-079` | | SRS-200 | Covered by `SAD-080` | | SRS-204 through SRS-207 | Covered by `SAD-081` through `SAD-083` | | SRS-208 | Covered by `SAD-084` | | SRS-209 | Covered by `SAD-085` | | SRS-111 (Android foreground voice service) | Covered by `SAD-086` (Android-specific allocation; SAD-036 retains the cross-cutting diagnostics allocation for the SRS-111–124 range per §24.1 dual-allocation pattern) | | SRS-013 (multi-platform support — macOS runtime baseline aspect) | Covered by `SAD-087` (macOS runtime baseline; counterpart to SAD-061 / SAD-063) | | SRS-216 (realtime-audio benchmark instrumentation) | Covered by `SAD-088` (criterion-based bench harness in `chanora_audio/benches/`; extends SAD-034 audio-subsystem allocation). Cross-cutting note: this is a cross-cutting allocation per §24.1 in the sense that the harness sits in the Audio Subsystem (SAD-034 extension) but its CI consumers sit in Build/Release/Operations (SAD-037 extensions); there is no platform-specific variation because SysDes-157 fixes the host to Linux x86_64. | | SRS-217 (baseline-JSON storage format and on-disk path) | Covered by `SAD-088` (the harness emits the JSON) and `SAD-089` (the on-disk path is pinned to `crates/chanora_audio/benches/baselines/x86_64-unknown-linux-gnu.json`) | | SRS-218 (CI advisory workflow + baseline-update isolation) | Covered by `SAD-090` (`.github/workflows/bench-advisory.yml`, advisory reader, non-blocking exit) and `SAD-091` (`.github/workflows/bench-baseline-update.yml`, `workflow_dispatch`, sole writer of SAD-089); both extend SAD-037 build/release/operations allocation | | SRS-219 (per-metric tolerance window and merge-base-snapshot comparison methodology) | Covered by `SAD-090` (comparator step consumes the SRS-219 tolerance and the merge-base-snapshot rule; tolerance-window evaluation is the workflow's comparator-step responsibility) | ## 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 software-architecture items SAD-071 through SAD-079: backend isolation behind `DesktopPttBackend` trait, Windows three-rung ladder, macOS two-rung permission-aware ladder, Linux GNOME-Wayland portal ladder, `AudioTransmitGate` object, sanitised `BridgeEvent::PttCapability`, `PttSanitizer` log-sink decorator, UI capability badge with platform-specific explanation, missed-key-up watchdog task. Strict layered sourcing preserved (`SAD -> SRS` only). | ## Baseline Candidate 0.9.4 Update | Version | Date | Description | |---|---|---| | 0.9.4 | 2026-05-15 | Added `SAD-080` to close the SRS-200 coverage gap surfaced by a P0 traceability audit. The earlier baseline matrix folded SRS-200 under the `SRS-195..203 -> SAD-071..079` range without giving it a dedicated SAD item; the new entry restores the strict one-to-many SRS-to-SAD discipline (SRS-200 is now sourced by SAD-080; SAD-080 is in turn covered by the new SDD-093). No other rows mutate; the existing PTT SAD items (071..079) retain their original SRS sources. | ## Baseline Candidate 0.9.5 Update | Version | Date | Description | |---|---|---| | 0.9.5 | 2026-05-15 | Added v1 audio + PTT lifecycle architecture items SAD-081 through SAD-083 sourced from SRS-204..207: dropped the `start_audio` / `stop_audio` bridge calls and replaced them with `voice_join(channel_id)` / `voice_leave()` keyed off implicit engine init plus `BridgeEvent::VoiceState`; added the `ReleaseTailTimer` adapter on the `DesktopPttBackend` → `AudioTransmitGate` path (default 200 ms, range 0–500 ms, key-down within window cancels the pending close); added the `TransmitModeSelector` element as the sole writer of `transmit_active` (other than the SAD-079 watchdog) with hard-mute applied as a final clamp and `VoiceActivity` mapped to `Continuous` until DEC-030 resolves. Strict layered sourcing preserved (`SAD -> SRS` only). | ## Baseline Candidate 0.9.6 Update | Version | Date | Description | |---|---|---| | 0.9.6 | 2026-05-17 | Propagated reconciled P0 Android SRS updates into SAD. SAD-063 text extended in place (ID preserved) to record the API 28 minimum runtime baseline per DEC-004 (Accepted 2026-05-14, superseding the earlier API 24 recommendation), while keeping the existing SRS-187 / SRS-188 trace. Added SAD-084 (Android in-call audio mode controller in the platform audio adapter, bound to the voice-session lifecycle, sourced from SRS-208). Added SAD-085 (Android `RECORD_AUDIO` runtime permission flow on the existing Android permission adapter, naming listen-only — `capture_active = false` with output stream open per SAD-081 — as a first-class operating mode at the architecture layer, sourced from SRS-209). Added SAD-086 (`AndroidVoiceForegroundService` allocation for SRS-111, bound to `voice_join` / `voice_leave` lifecycle rather than UI lifecycle, coordinating with SAD-084 and SAD-085). SAD-018 (Android back intent, SRS-163) and the existing Android AAB allocation in §9 / SAD-037 (SRS-119) were re-read and left unchanged because they remain coherent with the reconciled SRS. Strict layered sourcing preserved (`SAD -> SRS` only). | ## Baseline Candidate 0.9.7 Update | Version | Date | Description | |---|---|---| | 0.9.7 | 2026-05-18 | Formalized the cross-cutting + platform-specific SAD allocation pattern flagged by the traceability-auditor: added §24.1 narrative subsection describing the deliberate dual-allocation rule (cross-cutting concern + platform-specific realization both recorded), with SRS-111 / SAD-036 / SAD-086 as the worked example, and annotated the §24.2 matrix row for SRS-111..124 accordingly. Added SAD-087 (macOS runtime baseline: deployment target isolation, universal-binary `lipo` packaging, `.framework` `Versions/A` layout, hand-rolled CocoaPods podspec automation), parallel to SAD-061 (iOS runtime) and SAD-063 (Android runtime), closing the macOS-runtime anchor gap flagged by the SDD-119 detailed-designer. SAD-087 traces upward through SRS-013 (multi-platform support); a parallel macOS-runtime SysDes derivation does not yet exist and is recorded as an open follow-up for the system-architect (SysDes-133 covers iOS, SysDes-135 covers Android, macOS has no counterpart yet). §27 matrix updated with the SAD-087 row. Strict layered sourcing preserved (`SAD -> SRS` only). | | 0.9.8 | 2026-05-18 | Retargeted SAD-087's `Source SysDes` field from the "open follow-up — no dedicated macOS-runtime SysDes anchor exists" placeholder to `SysDes-155` (macOS runtime baseline — deployment target, universal-binary `lipo` packaging, `.framework` `Versions/A` layout, CocoaPods podspec automation), authored by the system-architect in SysDes v0.9.7 as the parallel macOS-runtime anchor to SysDes-133 (iOS) / SysDes-135 (Android). This closes the open follow-up that SAD-087 carried at its 0.9.7 authoring, giving SAD-087 a proper upward SysDes trace. Surgical single-field edit: no behavioral content of SAD-087 changed; `Source SRS` retained as `SRS-013` (multi-platform support — Windows, macOS, Linux, iOS, Android), which remains the correct SRS anchor (the SRS-013 vs alternate-anchor question raised during SysDes-155 authoring referred to SysRS-013 / SysRS-002 at the system-requirements layer, not to SRS at the software-requirements layer). §27 SRS-to-SAD coverage matrix row for SRS-013 unchanged because it already cites SAD-087 and remains textually accurate. Strict layered sourcing preserved (`SAD -> SRS`, with SysDes cross-reference now resolved). | | 0.9.9 | 2026-05-18 | Added realtime-audio benchmark-infrastructure software-architecture items SAD-088 through SAD-091 sourced from SRS-216 / SRS-217 / SRS-218 / SRS-219 (the Option B benchmark-infrastructure scope decision propagated through the Wave 1.5 benchmark chain SysRS-307/308/309 → SysDes-156/157/158 → SRS-216..219). SAD-088 allocates a `criterion`-based bench harness to the `chanora_audio` crate's `benches/` directory, extending SAD-034 (audio subsystem allocation); the harness covers the five SysDes-156 metric families (heap allocation count, per-callback wall-clock at p50/p95/p99, Opus encode latency on 960-sample/20 ms frame, Opus decode latency on the same shape, resampler throughput at 44.1→48 / 16→48 / 48→48 kHz) and emits SRS-217 baseline records. SAD-089 pins the baseline-JSON on-disk path to `crates/chanora_audio/benches/baselines/x86_64-unknown-linux-gnu.json` (single deterministic file, single host architecture in scope, target-triple-keyed filename to permit future multi-host expansion without directory restructuring). SAD-090 adds the advisory CI workflow `.github/workflows/bench-advisory.yml` extending SAD-037 (build/release/operations allocation): triggers on PR-against-default + push-to-default, runs on `ubuntu-latest`, reads the merge-base baseline (never the default-tip baseline, per SRS-219 anti-retroactive-reclassification), compares using SRS-219 tolerances, posts a markdown table with 🟢/🟡/🔴 markers, and always exits success (non-blocking per SRS-218 clause 4). SAD-091 adds the separate baseline-update workflow `.github/workflows/bench-baseline-update.yml` extending SAD-037: `workflow_dispatch` trigger only, sole writer of the SAD-089 baseline file, realizing the SRS-218 clause 5 workflow-isolation property at the architecture layer (single-writer invariant). Yellow-marker semantics pinned at this SAD layer in a §26 subsection: 🟡 means "within SRS-219 tolerance relative to merge-base baseline AND delta-from-previous-default-branch-run exceeds 50% of the tolerance window"; metrics with zero-width tolerance (heap allocations) cannot be 🟡. Rationale for pinning at SAD: the choice between baseline-only vs baseline-plus-run-history as workflow input is an architectural input-set decision, not an implementation detail. §27 SRS-to-SAD coverage matrix updated with four new rows (SRS-216, SRS-217, SRS-218, SRS-219) citing SAD-088..091; the SRS-216 row also annotates the cross-cutting allocation pattern per §24.1 (harness sits in Audio Subsystem via SAD-034 extension while CI consumers sit in Build/Release/Operations via SAD-037 extensions, with no platform-specific variation because SysDes-157 fixes the host to Linux x86_64). Intentionally NOT authored consistent with the SysRS/SysDes/SRS deferral chain: (a) Dimension 3 production telemetry export (deferred to P1; SysRS-295 active); (b) build-failing hard CI gate (SysRS-308 advisory-only rule active; SAD-090 status-check always exits success); (c) multi-host benchmarking (SysDes-157 host-scope clause active; SAD-089 holds a single target-triple-keyed file); (d) IDE integration (e.g. `cargo bench` invocation from rust-analyzer in VS Code — tooling polish, not P0 architecture). Strict layered sourcing preserved (`SAD -> SRS` only per the SAD §2 rule, with SysDes cross-references recorded for completeness on each new item). |