diff --git a/docs/architecture/sad.md b/docs/architecture/sad.md index 19ec3d5..fe829f4 100644 --- a/docs/architecture/sad.md +++ b/docs/architecture/sad.md @@ -50,6 +50,7 @@ Chanora is a Flutter application with a Rust core. Flutter owns the user-facing | Diagnostics | `crates/chanora_diagnostics` | Redaction, log sink, export bundle, known-secret registry | Rust core, Flutter diagnostics UI | | Server resolver | `crates/chanora_resolver` | SRV/TSDNS/DNS fallback resolution | Rust core, prefetch crate | | Server prefetch | `crates/chanora_prefetch`, Flutter `prefetch_debouncer.dart` | Invisible host-field resolution warming, TTL cache, generation safety | Resolver, Flutter connect UI, Rust core | +| Cache | `crates/chanora_cache` | Typed caching layer for server resolution results and other transient data | Rust core, resolver, prefetch | ## 5. Static Architecture View @@ -63,7 +64,7 @@ Flutter UI/widgets/services -> chanora_audio -> platform audio APIs / Opus / DSP -> chanora_storage -> platform secure storage / SQLite -> chanora_diagnostics - -> chanora_prefetch -> chanora_resolver -> network DNS/TSDNS + -> chanora_cache -> chanora_prefetch -> chanora_resolver -> network DNS/TSDNS ``` The bridge is the trust and type boundary between Flutter and Rust. Flutter must not directly depend on protocol-library internals. Rust core must not expose platform-specific storage or audio details to UI code except through stable DTOs and capability fields. diff --git a/docs/architecture/sdd.md b/docs/architecture/sdd.md index 4b2a735..1278626 100644 --- a/docs/architecture/sdd.md +++ b/docs/architecture/sdd.md @@ -21,14 +21,20 @@ This Software Detailed Design defines the module-level design details needed for | SDD-MOD-005 Voice UI | `voice_bar.dart`, `voice_compact.dart`, `voice_settings*.dart`, `voice_level_meter.dart`, `ptt_capability_badge.dart` | Voice controls, processing settings, metering, PTT capability | Flutter widget layer | | SDD-MOD-006 Platform services | `android_permissions_service.dart`, `ios_permissions_service.dart`, `audio_lifecycle_service.dart`, `back_intent_*`, `link_trust_service.dart` | Permission, lifecycle, navigation, route/link trust behavior | Flutter service layer | | SDD-MOD-007 Bridge API | `crates/chanora_bridge/src/api.rs`, generated Dart/Rust bridge files | Typed command/event boundary | Bridge layer | -| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs`, `events.rs`, `network_diagnostics.rs`, `ptt.rs` | Connection orchestration, reconnect, bridge-facing event DTOs, network diagnostics, PTT state, storage coordination | Rust core | +| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs` | Connection orchestration entry point, re-exports from submodules | Rust core | +| SDD-MOD-008a Core events module | `core/chanora_core/src/events.rs` | Public event/bridge-facing DTOs, connection state DTOs | Rust core | +| SDD-MOD-008b Core network diagnostics | `core/chanora_core/src/network_diagnostics.rs` | Private connect/loss counters, last-loss ring buffer for diagnostics | Rust core | +| SDD-MOD-008c Core PTT state | `core/chanora_core/src/ptt.rs` | Push-to-talk state machine, capability level, key bindings | Rust core | | SDD-MOD-009 Protocol adapter | `crates/chanora_protocol/src/` | `tsclientlib` isolation, DTO/error mapping | Protocol adapter | | SDD-MOD-010 State sync | `crates/chanora_state/src/lib.rs`, `channel_join.rs` | Snapshot/delta model, reducer, channel join support | State sync | | SDD-MOD-011 Audio subsystem | `crates/chanora_audio/src/` | Audio capture/playback, DSP, Opus, PTT, mode stack, platform units | Audio subsystem | | SDD-MOD-012 Storage | `crates/chanora_storage/src/lib.rs` | Bookmarks, identity storage, encrypted local records, keyring abstraction | Storage | | SDD-MOD-013 Diagnostics | `crates/chanora_diagnostics/src/lib.rs` | Redaction, log sink, known-secret registry, export bundle | Diagnostics | | SDD-MOD-014 Resolution and prefetch | `crates/chanora_resolver/src/lib.rs`, `crates/chanora_prefetch/src/lib.rs`, `prefetch_debouncer.dart` | SRV/TSDNS/DNS fallback and generation-safe resolution warming | Server resolver / prefetch | -| SDD-MOD-015 Build and release hooks | `.github/workflows/`, `tools/`, platform project files | CI, unsigned iOS build, benchmark advisory, platform smoke procedures | Release / platform architecture | +| SDD-MOD-015 Server resolver | `crates/chanora_resolver/src/lib.rs` | SRV record, TSDNS, and DNS A/AAAA fallback resolution | Server resolver | +| SDD-MOD-016 Server prefetch | `crates/chanora_prefetch/src/lib.rs` | TTL-based resolution cache, invisible host-field warming | Server prefetch | +| SDD-MOD-017 Cache | `crates/chanora_cache/src/lib.rs` | Typed caching layer for server resolution results and other transient data | Cache | +| SDD-MOD-018 Build and release hooks | `.github/workflows/`, `tools/`, platform project files | CI, unsigned iOS build, benchmark advisory, platform smoke procedures | Release / platform architecture | ## 3. Bridge Boundary Design diff --git a/docs/srs.md b/docs/srs.md index a194c7c..584d2e4 100644 --- a/docs/srs.md +++ b/docs/srs.md @@ -1700,6 +1700,87 @@ Therefore: - Owner: Software Team +## 5.x. Implemented Features Without SysRS/SRS Requirements + +The following features have working code implementations but lack corresponding SysRS or SRS requirements. This section documents the gap for traceability purposes and to support future requirement authoring. + +### 5.x.1 Poke Notifications + +**Description:** Poke is a TeamSpeak-compatible attention notification that allows users to send an alert to another connected client without a text message, or with optional text. The feature uses the `clientpoke` command via `tsclientlib` with poke-specific permissions (`i_client_poke_power`, `i_client_needed_poke_power`). + +**Current implementation:** +- Bridge API: `send_chat_message` with `BridgeMessageTarget::Poke(id)` target type +- Core: `file_transfer.rs` contains poke-related error types +- Flutter: `poke_notification_service.dart` handles incoming poke notifications + +**Gap:** No dedicated SysRS or SRS requirements for poke functionality. Poke should trace to a SysDes item for attention notifications. + +**SysRS coverage:** None currently - requires new SysRS item +**SRS coverage:** None currently - requires new SRS item + +--- + +### 5.x.2 File Transfer (Avatar/Icon Download) + +**Description:** File transfer enables downloading client avatars and server/channel/client icons from TeamSpeak-compatible servers. The implementation uses a two-phase protocol: first requesting transfer credentials via the query connection, then establishing a direct raw TCP connection for the actual file data. + +**Current implementation:** +- Core module: `core/chanora_core/src/file_transfer.rs` +- Design document: `docs/architecture/file-transfer-design.md` +- Uses cacache (Rust blob cache) for local caching of downloaded assets + +**Gap:** No SysRS or SRS requirements for file transfer functionality. Avatar/icon retrieval is a key user-facing feature. + +**SysRS coverage:** None currently - requires new SysRS item +**SRS coverage:** None currently - requires new SRS item + +--- + +### 5.x.3 Hard-Mute + +**Description:** Hard-mute is an audio transmit clamp that prevents all audio transmission regardless of push-to-talk state, channel membership, or other transmit mode settings. It is the final gate in the transmit selector chain. + +**Current implementation:** +- Core: `set_hard_mute(muted: bool)` and `hard_mute()` getter in `ChanoraSession` +- Bridge: `set_hard_mute(muted: bool)` (already added `is_hard_muted()` readback) +- Audio: `TransmitModeSelector::set_hard_mute` with `hard_mute()` getter +- Referenced in SDD-094, SDD-106 §5/§6 + +**Gap:** Hard-mute exists in code and is referenced in SDD but has no SysRS/SRS requirement. Should trace to a SysDes item for audio transmit control. + +**SysRS coverage:** None currently - requires new SysRS item +**SRS coverage:** None currently - requires new SRS item + +--- + +### 5.x.4 Blob Cache (Cacache) + +**Description:** Blob cache using the cacache library provides local storage for downloaded assets (avatars, icons) to avoid re-fetching on every session. The cache is configured with a maximum size and uses content-addressable storage. + +**Current implementation:** +- Core: `file_transfer.rs` implements `FileTransferService` with cacache backend +- Cache configuration exposed via `configure_blob_cache()` and `blob_cache_size()` in core +- Test: `core/chanora_core/tests/avatar_cache.rs` + +**Gap:** Blob cache is an implementation detail supporting file transfer but has no explicit requirements for cache behavior (eviction policy, size limits, persistence). + +**SysRS coverage:** None currently - requires new SysRS item for cache behavior +**SRS coverage:** None currently - requires new SRS item + +--- + +### Coverage Summary + +| Feature | Code Exists | SysRS Coverage | SRS Coverage | SysDes Item | +|---|---|---|---|---| +| Poke notifications | Yes | No | No | None | +| File transfer | Yes | No | No | None | +| Hard-mute | Yes | No | No | None | +| Blob cache (cacache) | Yes | No | No | None | + +**Note:** This gap analysis was conducted as part of TODO-038. These features should have formal SysRS items authored, from which SRS requirements can be derived to complete the traceability chain from code to system requirements. + + ## 6. Operating Environment Impact Analysis | Environment element | Software impact | Related SRS | diff --git a/docs/sysdes.md b/docs/sysdes.md index 5066c94..10bbbd3 100644 --- a/docs/sysdes.md +++ b/docs/sysdes.md @@ -2937,7 +2937,7 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through - Verification method: Review, Platform Test (macOS), Release Inspection - Verification owner: macOS Owner / Release Manager - ASPICE SYS.3 alignment: Static architecture, architecture constraints, element allocation, consistency -- Allocated SysRS: SysRS-002, SysRS-050, SysRS-193 +- Allocated SysRS: SysRS-002, SysRS-050, SysRS-193, SysRS-310 - Notes: Parallel in role to SysDes-133 (iOS runtime baseline) and SysDes-135 (Android runtime baseline); neither SysDes-133 nor SysDes-135 is modified by this item. Source SysRS selection: SysRS-002 anchors the multi-platform obligation that explicitly enumerates macOS as a target client platform, SysRS-050 anchors the macOS runtime environment obligation for native desktop integration, and SysRS-193 anchors the signed/notarized macOS build obligation that the `.framework` `Versions/A` layout and universal-binary policy must satisfy in the release pipeline. No macOS-specific deployment-target or universal-binary SysRS item currently exists; if a finer-grained macOS minimum-runtime SysRS item is required (analogous to SysRS-286 for iOS and SysRS-288 for Android), the systems-requirements owner should consider authoring it in a follow-up — this SysDes item is structured so that such a future SysRS item can be added to `Allocated SysRS` without restructuring the element. SysDes-155 cites the podspec file path only and does not embed its current deployment-target value; the value itself remains owned by the Build Configuration subsystem. **SysDes-156**: The system architecture shall allocate to SE-13 (Audio Subsystem) the obligation to expose its realtime capture and playback paths to benchmark instrumentation, such that the maintained numeric performance baselines authorized by SysRS-307 are measurable as a deterministic, automated comparison surface. The metric set authored at this layer is: (i) **heap allocation count per realtime callback after warmup** — zero allocations are expected on the steady-state realtime audio thread, where warmup is defined as the first N callbacks with N implementation-specific (recommended N=100 callbacks; refined at SDD); (ii) **per-callback wall-clock time expressed as a fraction of the cpal stream's reported audio frame period**, captured and reported as p50, p95, and p99 of the callback wall-clock as a fraction of that period; (iii) **Opus encode latency** — end-to-end wall-clock time for `encoder.encode_float()` on a 960-sample (20 ms) frame, captured per call; (iv) **Opus decode latency** — same shape, decoder side; (v) **resampler throughput** in samples-per-second produced at the canonical rate pairs 44.1 kHz → 48 kHz, 16 kHz → 48 kHz, and 48 kHz → 48 kHz passthrough (the passthrough pair serves as a control point). The baseline storage format is declared at this layer as structured JSON committed to a deterministic location in the repository; the exact path is delegated to SDD. Each JSON record shall include the metric value, the host architecture, the toolchain version, the git SHA of the measurement, and a timestamp, so that a baseline snapshot is reproducible and traceable to the commit that produced it. This SysDes item does not authorize off-device transmission of any measured baseline data and is consistent with SysRS-295. @@ -2991,7 +2991,7 @@ The **comparison methodology** authored at this layer is: each PR-triggered benc ## 17. Updated SysRS Coverage Statement -This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-309`. +This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-310`. | SysRS Range | SysDes Coverage | |---|---| @@ -3002,6 +3002,7 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through | SysRS-305 through SysRS-306 | Covered by `SysDes-152` through `SysDes-154` (with SysDes-154 additionally refining SysRS-055 for the Android voice audio backend) | | SysRS-002 / SysRS-050 / SysRS-193 (macOS platform-baseline slice) | Additionally refined by `SysDes-155` (macOS runtime baseline, parallel to SysDes-133 / SysDes-135) | | SysRS-307 through SysRS-309 (realtime-audio benchmark infrastructure) | Covered by `SysDes-156` (audio benchmark surface, SE-13), `SysDes-157` (advisory CI integration, SE-18), and `SysDes-158` (per-metric tolerance window and comparison methodology, SE-18) | +| SysRS-310 (macOS minimum runtime baseline) | Covered by `SysDes-155` allocation (macOS deployment target policy) ## Baseline Candidate 0.9.1 Update