diff --git a/docs/architecture/sad.md b/docs/architecture/sad.md index 44b8540..324e739 100644 --- a/docs/architecture/sad.md +++ b/docs/architecture/sad.md @@ -42,7 +42,7 @@ Chanora is a Flutter application with a Rust core. Flutter owns the user-facing | Flutter service layer | `apps/chanora_flutter/lib/services/` | Permission flows, lifecycle policy, host prefetch debounce, link trust, state mapping, platform back intent | Flutter app shell, generated bridge APIs, platform plugins | | Flutter widget layer | `apps/chanora_flutter/lib/widgets/` | Connect UI, channel tree, chat, voice controls, settings, diagnostics surfaces | Flutter services, generated DTOs, design tokens | | Bridge layer | `crates/chanora_bridge`, `apps/chanora_flutter/lib/src/rust/` | Typed Flutter/Rust boundary and generated bindings | Rust core, Flutter generated code | -| Rust core | `core/chanora_core` | Connection lifecycle, orchestration, reconnect behavior, storage coordination, voice state | Protocol, audio, storage, diagnostics, state, resolver/prefetch | +| Rust core | `core/chanora_core` | Connection lifecycle, orchestration, reconnect behavior, storage coordination, voice state, bridge-facing event DTOs | Protocol, audio, storage, diagnostics, state, resolver/prefetch | | Protocol adapter | `crates/chanora_protocol` | Isolate `tsclientlib`, expose typed protocol DTOs/errors | Rust core, external compatible server | | State sync | `crates/chanora_state` | Snapshot/delta model, channel join helpers, reducer behavior | Rust core, protocol DTOs | | Audio subsystem | `crates/chanora_audio` | Capture/playback, Opus, DSP, PTT, voice activity reservation, platform units | Rust core, platform APIs, protocol audio path | @@ -68,6 +68,8 @@ Flutter UI/widgets/services 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. +Current Core locality note: the public Core Interface remains available through `chanora_core::*` re-exports, while branch `simplify-project-review` has started moving internal Core responsibilities into focused Modules (`events.rs`, `network_diagnostics.rs`). This is an internal maintainability split, not a public Interface change. + ## 6. Runtime Flow Architecture ### 6.1 Connect Flow @@ -180,6 +182,8 @@ This SAD derives only from `docs/srs.md`. The broad SRS group-to-component alloc | SAD item numbering from historical status references is not reconstructed in this baseline | Existing references such as `SAD-043` and `SAD-046` are not itemized here | Treat this as a DV baseline SAD; add itemized SAD IDs in a follow-up if process requires strict ID-level review | | Some architecture views are textual rather than C4 diagrams | Reviewers may request visual C4 views | Record as documentation hardening, not a blocker for DV baseline if textual views are accepted | | Release/platform architecture evidence is incomplete | Public release remains blocked | Controlled by release-readiness and waiver records | +| Android runtime verification is not automatic in local reviews | Android permission/audio/lifecycle regressions can pass Rust-only tests | Require `adb devices -l` with a connected device/emulator and Android smoke evidence before claiming Android runtime success | +| Protocol voice packet re-export is an intentional exception to full protocol isolation | Future changes may accidentally widen the protocol/audio Seam | Document and keep the voice wire exception narrow, or move packet construction fully into `chanora_protocol` | ## 14. DV Conclusion diff --git a/docs/architecture/sdd.md b/docs/architecture/sdd.md index 022cbc3..77b646a 100644 --- a/docs/architecture/sdd.md +++ b/docs/architecture/sdd.md @@ -21,7 +21,7 @@ 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`, `ptt.rs` | Connection orchestration, reconnect, PTT state, storage coordination | Rust core | +| 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-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 | @@ -50,6 +50,7 @@ Design rules: |---|---| | Connection lifecycle | Rust core owns connect/disconnect/reconnect decisions and suppresses reconnect after user disconnect | | Backoff | Reconnect uses exponential backoff as described in implementation status, capped at 60 seconds | +| Core internal Modules | `lib.rs` remains the public Interface and orchestration entry point; `events.rs` owns public event/bridge-facing DTOs re-exported by `lib.rs`; `network_diagnostics.rs` owns private connect/loss counters and the last-loss ring buffer | | Server resolution | Resolver performs SRV/TSDNS/DNS fallback; prefetch cache may warm but must not be required for connect success | | Snapshot mapping | Rust state and bridge DTOs are mapped into Flutter view models by `snapshot_state_mapper.dart` | | Channel join | Channel join logic and errors are represented through Rust state/protocol handling and Flutter error mapper service | @@ -153,6 +154,7 @@ Design rules: | Some module designs are summarized rather than API-by-API | May be insufficient for final process audit | Use this as DV baseline; deepen high-risk modules before final release gate | | Android Keystore-backed DEK is not implemented | Limits storage/security design claims | Controlled by waiver and release-readiness records | | Full event replay tooling and live reducer integration evidence are absent | Limits state verification design beyond reducer unit behavior | Controlled as P1 gap and runtime-integration follow-up | +| Android runtime smoke is blocked when no device/emulator is attached | Android permission/audio/lifecycle paths cannot be claimed from Rust tests alone | Require `adb devices -l` and Android smoke evidence before closing Android verification claims | ## 13. DV Conclusion diff --git a/docs/governance/document-index.md b/docs/governance/document-index.md index 224b6ee..734b308 100644 --- a/docs/governance/document-index.md +++ b/docs/governance/document-index.md @@ -26,6 +26,7 @@ This index lists the documents required for DV review and identifies their curre | Release | `docs/release/release-readiness-go-nogo-record.md` | No-Go for public/store release | | Release | `docs/release/platform-release-policy.md` | Baseline candidate | | Governance | `docs/governance/traceability-matrix.md` | DV baseline candidate | +| Governance | `docs/governance/maintainability-review-2026-06-08.md` | Working-branch maintainability and fail-safe review | | Security/privacy/legal | `docs/security/security-privacy-legal-guideline.md` | Baseline candidate | | Privacy | `docs/privacy/privacy-policy.md` | Engineering baseline candidate | | Legal | `docs/legal/trademark-and-attribution-review.md` | DEC-012 open | diff --git a/docs/superpowers/plans/2026-06-08-core-internal-split.md b/docs/superpowers/plans/2026-06-08-core-internal-split.md new file mode 100644 index 0000000..1e6ab13 --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-core-internal-split.md @@ -0,0 +1,95 @@ +# Core Internal Split Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Improve `chanora_core` maintainability by moving stable event DTOs and network diagnostic state out of the oversized `lib.rs` while preserving the public crate Interface. + +**Architecture:** Keep `lib.rs` as the public Interface and session orchestration entry point. Move event-facing DTOs to `events.rs` and private network diagnostic ring-buffer state to `network_diagnostics.rs`; re-export public event types from `lib.rs` so downstream callers keep using `chanora_core::SessionEvent` and related names unchanged. + +**Tech Stack:** Rust 2021, Tokio broadcast/watch channels, `thiserror`, existing Cargo workspace tests. + +--- + +### Task 1: Move Core Event DTOs + +**Files:** +- Create: `core/chanora_core/src/events.rs` +- Modify: `core/chanora_core/src/lib.rs` +- Verify: `cargo test -p chanora_core` + +- [ ] **Step 1: Preserve current public Interface with tests** + +Run: `cargo test -p chanora_core` +Expected: PASS. Existing bridge-facing tests and compile checks prove the current public event names are valid. + +- [ ] **Step 2: Create `events.rs` with the moved public event DTOs** + +Move these exact public types from `lib.rs` to `events.rs`: +- `PttDescriptorSnapshot` +- `PersistedPttBinding` +- `SessionEvent` +- `VoiceJoinSyncState` +- `VoiceJoinErrorCode` +- `NetworkState` + +Use local imports in `events.rs` for `chanora_audio::{AudioRoute, PttBackendDescriptor}` and `chanora_protocol::MessageTarget`. + +- [ ] **Step 3: Re-export moved types from `lib.rs`** + +Add `mod events;` and `pub use events::{...};` for all moved public types. Remove the original definitions from `lib.rs`. + +- [ ] **Step 4: Run tests** + +Run: `cargo test -p chanora_core` +Expected: PASS with no public Interface break. + +### Task 2: Move Core Network Diagnostics State + +**Files:** +- Create: `core/chanora_core/src/network_diagnostics.rs` +- Modify: `core/chanora_core/src/lib.rs` +- Verify: `cargo test -p chanora_core network_diagnostics` + +- [ ] **Step 1: Move `NetworkDiagnostics` into a private module** + +Move the private `NetworkDiagnostics` struct and its methods from `lib.rs` into `network_diagnostics.rs`. Keep methods `pub(crate)` because `ChanoraSession` records connection/loss events and exports summaries. + +- [ ] **Step 2: Move the regression test with the module** + +Move `network_diagnostics_keeps_last_eight_loss_reasons` from the `lib.rs` test module into `network_diagnostics.rs` so the behaviour test lives next to the Implementation it protects. + +- [ ] **Step 3: Import the private module from `lib.rs`** + +Add `mod network_diagnostics;` and `use network_diagnostics::NetworkDiagnostics;`. Remove `VecDeque` from the `lib.rs` imports. + +- [ ] **Step 4: Run targeted and workspace verification** + +Run: `cargo test -p chanora_core network_diagnostics` +Expected: PASS. + +Run: `cargo test --workspace` +Expected: PASS. + +### Task 3: Format and Check Workspace + +**Files:** +- Modify: Rust files touched above only, except existing formatter-only churn may remain from prior `cargo fmt --all`. + +- [ ] **Step 1: Format Rust code** + +Run: `cargo fmt --all` +Expected: no command output. + +- [ ] **Step 2: Compile workspace** + +Run: `cargo check --workspace` +Expected: finishes successfully. + +- [ ] **Step 3: Inspect diff** + +Run: `git diff --stat` +Expected: new `events.rs` and `network_diagnostics.rs`; smaller `core/chanora_core/src/lib.rs`; no public API renames. + +--- + +Self-review: This plan covers the recommended Core split first slice, avoids public Interface changes, has no placeholders, and keeps testing tied to the moved Implementations. diff --git a/docs/verification/swe4-unit-verification-plan.md b/docs/verification/swe4-unit-verification-plan.md index 081e913..c27dcc7 100644 --- a/docs/verification/swe4-unit-verification-plan.md +++ b/docs/verification/swe4-unit-verification-plan.md @@ -32,6 +32,8 @@ This plan defines unit verification coverage for the software modules that imple | `flutter analyze` in `apps/chanora_flutter` | Software | Dart static analysis | | `flutter test --exclude-tags e2e` in `apps/chanora_flutter` | Software / QA | Flutter unit and widget tests | +For local code-change reviews, a Rust change is not complete until `cargo fmt --all`, `cargo check --workspace`, and `cargo test --workspace` have been run fresh and read for failures. Flutter or bridge changes additionally require Flutter analysis/tests. + ## 4. SRS Unit Coverage Focus | SRS group | Unit focus | Status for DV | @@ -51,6 +53,7 @@ This plan defines unit verification coverage for the software modules that imple | Event replay tool not found | P1 verification hook is incomplete | Mark deferred/P1 in SWE.6 and waiver register if discussed | | Platform keyring behavior not exercised in CI | Secure-storage unit evidence is incomplete for real OS services | Cover through platform audit/SYS.4, not CI-only claims | | Audio device hot-plug recovery follow-up exists | Limits reliability evidence for SRS-082 | Mark as P1 gap | +| Android runtime smoke cannot run without attached target | Rust unit tests do not exercise Android permission/audio/lifecycle fail-safes | `adb devices -l` must show a device or emulator before Android runtime success can be claimed | ## 6. SWE.4 DV Decision Rule