diff --git a/CHANGELOG.md b/CHANGELOG.md index 47569b9..dee7b92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,10 @@ This project follows a Conventional Commits style workflow. The v0.3.0 milestone transitions Chanora from an internal-beta voice prototype to a cross-platform baseline client with event-driven UI, -per-user audio controls, non-self client info parity, and CI-hardened -Android / iOS / macOS / Linux builds. +visible per-client audio state, non-self client info parity, and +documented host Rust workspace plus Flutter validation gates. Android +target compile/install/smoke evidence remains blocked locally pending the +required NDK compiler and an authorized ADB target. ### Added @@ -17,10 +19,9 @@ Android / iOS / macOS / Linux builds. deltas (client join/leave/move/update, channel add/remove/update) flow through a typed `ProtocolDelta` enum and update the Flutter UI in real time. Channel switching is instant. -- **Per-user volume controls.** Each client in the snapshot gets an - independent volume slider persisted in the bridge layer. Avatar - badges show muted/deafened state. Volume adjustments take effect - immediately on the audio mix. +- **Per-client audio state visibility.** Client rows surface + muted/deafened state in avatar badges. Per-user volume UI, persistence, + and mixer wiring remain tracked as follow-up work. - **Non-self client info parity with Qint.** The Info tab now populates connection metadata (name, description, created, last connected, connections, transfer, ping deviation) for other clients via an @@ -29,9 +30,10 @@ Android / iOS / macOS / Linux builds. - **Ping deviation in client profiles.** `ping_deviation_milliseconds` propagated from protocol DTO through bridge API to Dart, with a conditional l10n row in the client info sheet (en + zh). -- **Apple CoreML Silero VAD** as the preferred voice activity detector - on iOS / macOS when the private `silero-coreml` SwiftPM submodule is - available. WebRTC VAD remains the runtime fallback. +- **Apple CoreML Silero VAD scaffolding/assets** for iOS / macOS when + the private `silero-coreml` SwiftPM package is available. Product + `VoiceActivity` remains reserved/disabled per DEC-030 until a later + baseline enables and verifies it. - **TeamSpeak address resolver** (`chanora_resolver`) for DNS SRV lookups and `ts3server://` URI handling. - **Per-ABI Android APK splitting.** `flutter build apk @@ -50,8 +52,9 @@ Android / iOS / macOS / Linux builds. - **iOS / macOS audio lifecycle hardened.** Voice unit restart-in-place, serialized lifecycle events, WebRTC VAD on iOS, unblocked connect-time audio startup. -- **Linux native audio path promoted** with ONNX Runtime bundled for - VAD. Desktop voice I/O works on PipeWire / PulseAudio. +- **Linux native audio path promoted** with ONNX Runtime VAD assets + bundled for future `VoiceActivity` work. Desktop voice I/O works on + PipeWire / PulseAudio; product `VoiceActivity` remains disabled. - **Android audio routing** uses `MODE_IN_COMMUNICATION`, proper startup permission flow, and system back-button integration. - **`SnapshotChanged` event removed.** Replaced by the typed delta @@ -59,7 +62,8 @@ Android / iOS / macOS / Linux builds. Flutter). - **Prefetch crate renamed** from the PoC-era name to `chanora_prefetch`. All docs, specs, and code updated. -- **Build number bumped to 76.** +- **Flutter app version/build bumped to `0.3.0+100`.** Rust workspace + packages remain versioned separately at `0.2.0-beta.1`. - **Flutter bridge regenerated** for `flutter_rust_bridge` 2.12.0. ### Fixed diff --git a/README.md b/README.md index ebd2765..09e9f02 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,10 @@ Flutter UI + Rust Core + tsclientlib ## Status -Chanora is currently in early planning and baseline-candidate design. +Chanora is currently a baseline-candidate Flutter + Rust workspace. It is not production-ready and is not approved for public or store release. ```text -Current documentation baseline: v0.9.2 +Current documentation baseline: v0.9.x document set Current status: Baseline Candidate Implementation status: Not production-ready ``` @@ -25,7 +25,7 @@ Implementation status: Not production-ready The current engineering focus is: - defining the system and software architecture; -- preparing the Flutter + Rust application structure; +- hardening the Flutter + Rust application structure; - validating TeamSpeak-compatible protocol integration through `tsclientlib`; - defining cross-platform audio behavior; - preparing release, verification, security, privacy, and legal gates. @@ -49,7 +49,7 @@ Current platform policy: | iOS / iPadOS runtime target | iOS 16+ while Apple CoreML Silero VAD is linked | | macOS runtime target | macOS 13+ while Apple CoreML Silero VAD is linked | | App Store Connect upload gate | Xcode 26+ with iOS 26 / iPadOS 26 SDK+ for upload on or after 2026-04-28 | -| Android runtime target | Android API 24+ unless Flutter, plugin, audio, or product constraints require raising it | +| Android runtime target | Android API 28+ per DEC-004, SysRS-288, SRS-187, and Gradle `minSdk = 28` | | Google Play target API | Target the Google Play-required API level on upload date | The App Store / Play Store upload gates are release requirements. They are separate from local development and internal testing requirements. @@ -230,7 +230,7 @@ docs/ aspice-swe2-swe3-integration-note.md ``` -Implementation source folders may be added later. A likely structure is: +Implementation source folders are present in this workspace. The current high-level structure is: ```text apps/ @@ -248,7 +248,7 @@ crates/ chanora_bridge/ ``` -The exact implementation layout should be finalized when the repository scaffold is created. +The exact implementation layout may continue to evolve as maintainability reviews split or merge Modules, but the repository scaffold exists. --- @@ -395,9 +395,7 @@ docs/governance/git-commit-message-convention.md ## Development -Implementation commands will be added after the repository scaffold is finalized. - -Expected future commands may include: +Common local commands include: ```bash flutter pub get @@ -407,7 +405,7 @@ cargo clippy cargo fmt ``` -Do not treat these as authoritative until the actual Flutter/Rust workspace has been created. +Android runtime success also requires an available Android NDK toolchain and an authorized device or emulator for build/install/smoke verification. --- diff --git a/docs/governance/maintainability-review-2026-06-08.md b/docs/governance/maintainability-review-2026-06-08.md new file mode 100644 index 0000000..cd53933 --- /dev/null +++ b/docs/governance/maintainability-review-2026-06-08.md @@ -0,0 +1,77 @@ +# Chanora Maintainability Review — 2026-06-08 + +**Document status:** Working-branch review record +**Branch:** `simplify-project-review` +**Scope:** Project-wide simplification, fail-safe, and verification review + +## 1. Purpose + +This record captures the current maintainability review so implementation, verification, and release documents do not drift behind the code. It focuses on unnecessary Modules, shallow Interfaces, duplicate Implementations, built-in replacement opportunities, and fail-safe gaps that need explicit evidence before release claims. + +## 2. Changes Already Applied on the Branch + +| Area | Files | Maintainability result | +|---|---|---| +| Core event DTO locality | `core/chanora_core/src/events.rs`, `core/chanora_core/src/lib.rs` | Public Core event DTOs moved out of the oversized Core integration Module while preserving the public `chanora_core::*` Interface through re-exports. | +| Core network diagnostics locality | `core/chanora_core/src/network_diagnostics.rs`, `core/chanora_core/src/lib.rs` | Private network diagnostic ring-buffer state and its regression test now live next to the Implementation they protect. | +| Bounded queues | `core/chanora_core/src/network_diagnostics.rs`, `crates/chanora_diagnostics/src/lib.rs` | Replaced `Vec + remove(0)` queue behaviour with `VecDeque`, reducing custom queue code and avoiding O(n) front removal. | +| PTT backend errors | `crates/chanora_audio/src/ptt_backends/mod.rs` | Replaced manual `Display` / `Error` Implementation with existing `thiserror::Error`; regression test keeps user-facing strings stable. | +| Render downmix | `crates/chanora_audio/src/voice_render.rs`, `crates/chanora_audio/src/ios_raw_unit.rs` | Removed duplicate mono-i16 downmix loop by using the interleaved helper with one output channel. | +| State reducer | `crates/chanora_state/src/lib.rs` | Reused the main snapshot reducer for reconnect snapshots instead of duplicating normalization and delta construction. | +| Workspace metadata | `crates/chanora_resolver/Cargo.toml`, `Cargo.lock` | Resolver inherits workspace package metadata, improving release metadata Locality. | +| Flutter voice fail-safes | `apps/chanora_flutter/lib/main.dart`, `apps/chanora_flutter/lib/widgets/voice_compact.dart`, `apps/chanora_flutter/lib/services/ios_audio_session_controller.dart` | Commit `d835394` preserves independent mute owners, releases touch PTT on disposal while held, and catches iOS audio-session `MissingPluginException` / activation failures so they do not become unhandled async errors. | +| Rust realtime callback hardening | `crates/chanora_audio/src/android_voice_unit.rs`, `crates/chanora_audio/src/ios_raw_unit.rs`, `crates/chanora_audio/src/engine.rs` | Commit `8606eb4` hardens Android/iOS realtime callback paths. Android target compilation and device runtime verification are still blocked locally; full lock-free audio-handler/config/debug-recorder redesign remains follow-up work. | + +## 3. Remaining Simplification Opportunities + +| Recommendation | Candidate files | Strength | Notes | +|---|---|---|---| +| Continue splitting Core internals by responsibility | `core/chanora_core/src/lib.rs` | Strong | Next slices should be reconnect/session, voice projection, storage helpers, and diagnostics export. Keep public re-exports stable. | +| Make Bridge depend on Core rather than Audio where possible | `crates/chanora_bridge/Cargo.toml`, `crates/chanora_bridge/src/api.rs`, `core/chanora_core/src/lib.rs` | Worth exploring | The Bridge currently has a direct audio edge. Apply the deletion test before removing it. | +| Decide whether prefetch deserves a crate-level Seam | `crates/chanora_prefetch/src/lib.rs`, `crates/chanora_resolver/src/lib.rs`, `core/chanora_core/src/lib.rs` | Worth exploring | Prefetch is a small TTL cache and fire-and-forget resolver Adapter. Merge into resolver if it is resolver policy; merge into Core if it is app orchestration policy. | +| Consolidate protocol/core/bridge event catalogues | `crates/chanora_protocol/src/dto.rs`, `core/chanora_core/src/events.rs`, `crates/chanora_bridge/src/api.rs` | Worth exploring | Protocol-owned deltas and Core-owned lifecycle events are currently mirrored through multiple DTO layers. | +| Reduce bridge DTO mirror boilerplate | `crates/chanora_bridge/src/api.rs` | Worth exploring | Verify Flutter Rust Bridge support before deleting mirrors. If mirrors remain required, centralize conversion patterns and keep field order aligned with Core DTOs. | +| Clarify protocol voice packet exception | `crates/chanora_protocol/src/lib.rs`, `crates/chanora_audio/Cargo.toml` | Worth exploring | The protocol crate documents `tsclientlib` isolation but deliberately re-exports voice packet types for audio. Document this as an explicit voice wire Seam or move packet construction fully into protocol. | +| Remove shallow audio helpers only after public API check | `crates/chanora_audio/src/processor/noop.rs`, `crates/chanora_audio/src/processor/platform.rs`, `crates/chanora_audio/src/frame.rs` | Speculative | These Modules are shallow, but deletion must wait until external/public API expectations are checked. | +| Redesign remaining audio shared state outside realtime callbacks | `crates/chanora_audio/src/engine.rs`, platform voice units, debug recorder/config paths | Strong follow-up | The focused callback hardening is complete, but a full lock-free `AudioHandler` / config / debug-recorder redesign should be planned separately and verified on device. | +| Review protocol/core disconnect and control-plane bounds | `core/chanora_core/src/lib.rs`, `crates/chanora_protocol/src/adapter.rs` | Strong follow-up | Unless closed by a later code slice, sustained voice traffic and broken transport should be reviewed for bounded control request and disconnect progress. | + +## 4. Fail-Safe Gaps That Need Evidence + +| Gap | Risk | Required evidence before release claim | +|---|---|---| +| Android Keystore-backed DEK remains deferred | Android identity/bookmark encryption has weaker fail-safe properties than final target secure-storage design. | Android secure-storage audit or waiver; explicit release-readiness limitation. | +| Android runtime verification not executed in this review | Rust unit tests pass, but device permission/audio/lifecycle paths are not proven without a connected device or emulator. | `adb devices -l` showing a target plus Android build/install/smoke evidence. | +| Android target compilation blocked locally | Android build evidence cannot be recorded while the Android NDK compiler `aarch64-linux-android-clang` is unavailable in the local toolchain. | Install/fix the Android NDK toolchain, rerun Android target build, then install/smoke on an authorized target. | +| iOS device runtime verification not executed in this review | The iOS audio-session error path is hardened, but VoiceProcessingIO/session ordering and runtime audio behavior still need device evidence. | iOS device or simulator build/run plus audio-session smoke evidence before iOS runtime success is claimed. | +| VAD / VoiceActivity wording drift | VAD assets, tests, and scaffolding exist, but product-enabled `VoiceActivity` remains reserved/disabled per DEC-030. | Release, README, and verification wording must distinguish scaffolding/assets/tests from shipped product behavior. | +| Protocol voice packet re-export is an intentional exception | Future maintainers may assume complete protocol isolation and accidentally widen the Seam. | Architecture note in SAD/SDD or a decision-register entry. | +| Bridge DTO mirror drift | Field additions can be missed across Core, Bridge, and Dart generated DTOs. | Bridge generation check plus Flutter analyze/test after bridge DTO changes. | +| Full live reducer integration remains separate from reducer unit coverage | State reducer tests are strong, but runtime UI still has snapshot/probe paths. | SWE.5 integration run proving live protocol events fold through the intended state path, or explicit P1 deferral. | +| Event replay tooling remains absent | Replay-based diagnosis and regression reproduction are limited. | Event replay tool implementation or waiver. | + +## 5. Verification Policy for Future Code Changes + +| Change type | Required verification | +|---|---| +| Rust-only change | `cargo fmt --all`, `cargo check --workspace`, `cargo test --workspace` | +| Bridge DTO/API change | Rust verification plus bridge generation check, `flutter analyze`, and `flutter test --exclude-tags e2e` in `apps/chanora_flutter` | +| Android platform/audio/permission change | Rust/Flutter verification plus NDK target compilation, `adb devices -l`, Android build/install, and a device or emulator smoke test | +| Documentation-only change | Read affected docs and ensure cross-links/document index stay current; code tests are not required unless docs describe a code change just made | + +## 6. Android ADB Status for This Review + +`adb` is installed at `/opt/homebrew/bin/adb`, but `adb devices -l` returned no connected devices. Android runtime verification is therefore blocked until a device or emulator is connected and authorized. + +Android target compilation is also blocked locally until the Android NDK compiler `aarch64-linux-android-clang` is available. No Android runtime success, permission-flow success, or audio-lifecycle success is claimed by this review. + +## 7. Release and Documentation Alignment Notes + +- Android minimum runtime baseline is API 28 (Android 9.0) per SysRS-288, SRS-187, DEC-004, and the Gradle `minSdk = 28` configuration. Documents must not revive the older API 24 baseline. +- Flutter app version/build is `0.3.0+100` in `apps/chanora_flutter/pubspec.yaml`. Rust workspace package version remains `0.2.0-beta.1`. Release documents must distinguish these values instead of treating them as one candidate version. +- The v0.3.0 changelog entry may mention VAD assets/backends only as implementation scaffolding; product-enabled `VoiceActivity` remains disabled/coming-soon until DEC-030 is superseded and runtime verification exists. +- README wording must describe the existing Flutter/Rust workspace and app scaffold, not a future scaffold that has not been created. + +## 8. Git Policy + +No commit is created automatically. Commit only on explicit user demand, after reviewing `git status`, `git diff`, and recent log output. diff --git a/docs/governance/product-decision-register.md b/docs/governance/product-decision-register.md index 143cfc8..bab8124 100644 --- a/docs/governance/product-decision-register.md +++ b/docs/governance/product-decision-register.md @@ -11,12 +11,14 @@ This register records product and engineering decisions referenced by the DV doc | Decision | State | DV impact | |---|---|---| +| DEC-004 Android minimum runtime API 28 | Accepted by requirements baseline | Android release, verification, and README wording must use API 28 rather than the earlier API 24 recommendation | | DEC-012 legal/trademark/OSS review | Open | Blocks public/store release | | DEC-020 dual license MIT OR Apache-2.0 | Accepted per README | Supports license posture; dependency notices still require review | | DEC-027 desktop mouse side-button PTT | Accepted by requirements baseline | Verification must not over-claim unsupported platform input classes | -| DEC-030 VAD deferral | Accepted as deferral | `VoiceActivity` remains disabled/coming-soon | +| DEC-030 VAD deferral | Accepted as deferral | VAD scaffolding, assets, and tests may exist, but product `VoiceActivity` remains disabled/coming-soon until a later baseline enables and verifies it | | DEC-032 Android CMake patch exit path | Active tracking | Patched dependency requires reevaluation | | DEC-033 macOS VPIO ducking configuration | Accepted | Write `kAUVoiceIOProperty_OtherAudioDuckingConfiguration` with `mEnableAdvancedDucking=0` (disables dynamic voice-activity-driven ducking) and `mDuckingLevel=Min` (= 10) to minimise the ducking of other apps' audio during a voice session; property is macOS 14+ only, the macOS 13 set fails silently (debug log) and VPIO uses its default behaviour; matches the iOS `.voiceChat` baseline on macOS 14+ | +| DEC-034 Android runtime verification gate | Active tracking | Android target compilation, install, and runtime smoke are blocked locally until `aarch64-linux-android-clang` is available and `adb devices -l` shows an authorized target; release docs must not claim Android runtime success | ## 3. DV Rule diff --git a/docs/implementation-status-2026-05-28.md b/docs/implementation-status-2026-05-28.md index 5920bd3..126e1bc 100644 --- a/docs/implementation-status-2026-05-28.md +++ b/docs/implementation-status-2026-05-28.md @@ -1,8 +1,9 @@ # Chanora Implementation Status — 2026-05-28 **Workspace version:** `v0.2.0-beta.1` -**CHANGELOG latest:** `v1.0.0-rc.1` -**Build status:** All 9 crates compile cleanly. +**Flutter app version/build:** `0.3.0+100` +**CHANGELOG latest:** `v0.3.0` +**Build status:** Host Rust workspace evidence shows all 9 crates compile cleanly. This does not claim Android target success; Android target compile/install/smoke evidence remains blocked locally as noted below. --- @@ -18,9 +19,9 @@ | Localization (en + zh-Hans) | `l10n/generated/app_localizations_en.dart` + `app_localizations_zh.dart`, `l10n.yaml` | | Flutter/Rust bridge | `chanora_bridge` crate (2152-line `api.rs`), generated `frb_generated.rs`, Dart side generated | | Protocol adapter | `chanora_protocol` — `tsclientlib` isolated behind `ProtocolClient`, typed DTOs, `ProtocolError` catalogue | -| Connection lifecycle | `chanora_core` (2682-line `lib.rs`) — supervisor task, exponential backoff reconnect (1s→60s), user-disconnect suppresses reconnect | +| Connection lifecycle | `chanora_core` — supervisor task, exponential backoff reconnect (1s→60s), user-disconnect suppresses reconnect; branch `simplify-project-review` has started splitting the previous large `lib.rs` into focused internal Modules (`events.rs`, `network_diagnostics.rs`) while preserving public re-exports | | State sync reducer unit | `chanora_state` — `ConnectionState`, `channel_join`, snapshot/delta reducers, reconnect handling, deterministic ordering, malformed duplicate normalization, channel-delete/client cleanup, and reducer unit tests. Runtime core integration still uses snapshot/probe refresh paths and remains separate validation work. | -| Audio subsystem | `chanora_audio` — Opus encode/decode, HPF/NS/AEC3/AGC2 DSP, PTT backends (Windows/macOS/Linux/focused), iOS VoiceProcessingIO, Android Oboe, jitter buffer via `tsclientlib::audio::AudioHandler`, mixer, mute/deaf gates, release-tail timer, VAD | +| Audio subsystem | `chanora_audio` — Opus encode/decode, HPF/NS/AEC3/AGC2 DSP, PTT backends (Windows/macOS/Linux/focused), iOS VoiceProcessingIO, Android Oboe, jitter buffer via `tsclientlib::audio::AudioHandler`, mixer, mute/deaf gates, release-tail timer, and VAD scaffolding/assets. Product `VoiceActivity` remains disabled per DEC-030. | | Push-to-talk | Per-platform backends: Windows Raw Input + hook fallback, macOS Event Tap, Linux freedesktop portal, focused fallback; `PttCapabilityLevel` (L0–L3); missed-key-up watchdog | | Voice controls UI | `voice_bar`, `voice_compact`, `voice_haptics`, `voice_level_meter`, `voice_platform`, `ptt_capability_badge`, `talk_power_warning` | | Storage (non-secret) | `chanora_storage` — `BookmarkRepository` (SQLite/rusqlite bundled, schema v2), ChaCha20-Poly1305 encrypted passwords | @@ -45,7 +46,7 @@ | Link trust | `link_trust_service.dart` | | About dialog | Non-affiliation statement, dual-license declaration, NOTICE pointer | | CI | GitHub Actions on every push | -| Workspace compiles | All 9 crates build cleanly | +| Workspace compiles | Host Rust workspace evidence shows all 9 crates build cleanly; Android target compilation remains blocked locally as noted below. | ### Partial / Scaffold Only @@ -54,16 +55,17 @@ | Event replay tooling | Reducer tests cover the state-sync contract, but standalone replay-file tooling remains a P1 verification gap. | | Reducer runtime integration evidence | The standalone reducer is unit-tested, but `chanora_core` still refreshes UI state through snapshot/probe paths rather than folding all live protocol events through `chanora_state::reduce`. | | Silero VAD | `assets/models/silero_vad.onnx` bundled but DEC-030 defers VAD to P1; `TransmitMode::VoiceActivity` is reserved and disabled in this baseline. | -| macOS build | Not in `v1.0.0-rc.1` release artifacts (source-buildable only per `staged-release-plan.md`). | -| Windows build | Same — source-buildable, not in rc.1 release artifacts. | -| iOS build | Same — source-buildable, not in rc.1 release artifacts. | +| macOS build | Source-buildable only; no public release artifact is approved. | +| Windows build | Source-buildable only; no public release artifact is approved. | +| iOS build | Source-buildable/unsigned validation only; no TestFlight/App Store release artifact is approved. | ### Not Done (P0 blockers remaining) | Item | Status | |---|---| -| DEC-012 legal/trademark/OSS review | Explicitly open — `v1.0.0-rc.1` is the candidate awaiting sign-off. Public release is blocked. | +| DEC-012 legal/trademark/OSS review | Explicitly open. Public release is blocked. | | Android Keystore-backed DEK | Deferred to v1.1. Android still uses file-fallback for the Data Encryption Key. | +| Android target compile/install/smoke evidence | Blocked locally until the Android NDK compiler `aarch64-linux-android-clang` is available and `adb devices -l` shows an authorized device or emulator. | | iOS `AVAudioSession.Mode.voiceChat` | Implemented in `apps/chanora_flutter/ios/Runner/AppDelegate.swift` with call-scoped activation (idle `.ambient` baseline; VoIP `.playAndRecord` + `.voiceChat` + `.mixWithOthers` engaged only on `BridgeEvent::AudioStarted` via `chanora/ios_audio_session` MethodChannel). Release readiness still requires device audio validation and candidate evidence attachment. | | Candidate state-sync evidence attachment | Reducer tests exist and pass locally; release readiness still needs candidate CI/run IDs and runtime integration evidence attached before public release approval. | @@ -92,7 +94,7 @@ | Recent servers persistence (SRS-085) | Not confirmed in storage crate | | UI settings persistence (SRS-087) | Implemented for current P1 scope using `shared_preferences`: host, nickname, permission explanation flag, and theme mode (`system` / `light` / `dark`). SQLite-backed UI settings remain a future hardening option if multi-profile or transactional settings are introduced. | | Event replay tool (SRS-061, SRS-098) | No replay infrastructure found | -| Network diagnostics (SRS-100) | Not found in diagnostics export | +| Network diagnostics (SRS-100) | Core tracks connect/disconnect counts and last-loss reasons in `network_diagnostics.rs`; export/integration evidence still needs release-candidate attachment | | Side navigation rail for medium layout (SRS-153) | Not confirmed | | Keyboard focus traversal (SRS-160) | Not confirmed | | Android audio focus / BT route changes (SRS-112) | Partial — `MODE_IN_COMMUNICATION` done; full focus/BT handling not confirmed | diff --git a/docs/release/dv-waiver-register.md b/docs/release/dv-waiver-register.md index adb94d8..e588c53 100644 --- a/docs/release/dv-waiver-register.md +++ b/docs/release/dv-waiver-register.md @@ -20,6 +20,7 @@ A waiver records a known gap that reviewers may accept for a limited decision sc | DV-WVR-006 | Desktop and iOS artifacts are source-buildable or unsigned only | `docs/implementation-status-2026-05-28.md`, `docs/release/ios-build.md` | Blocks packaged public release claims | Internal validation from source/unsigned builds only | Signed/notarized/package artifacts exist and hashes are recorded | | DV-WVR-007 | Silero VAD asset bundled while `VoiceActivity` is deferred | `docs/implementation-status-2026-05-28.md` | Risk that UI/release wording overstates VAD availability | DV may pass if VoiceActivity remains disabled/coming-soon | VAD implementation allocated in a later baseline or asset/wording reconciled | | DV-WVR-008 | Artifact hashes, tag, and candidate run IDs are not recorded in release record | `docs/release/release-readiness-go-nogo-record.md` | Blocks final release approval and reproducibility | DV documentation review only | Candidate build run records, tag, commit SHA, and artifact hashes are recorded | +| DV-WVR-009 | Android target compile and runtime smoke blocked locally | `docs/governance/maintainability-review-2026-06-08.md`, `docs/release/release-readiness-go-nogo-record.md` | Blocks Android runtime, permission-flow, and audio-lifecycle success claims | Documentation review only; internal validation must keep Android limitation stated | Android NDK compiler `aarch64-linux-android-clang` is available, `adb devices -l` shows an authorized target, and Android build/install/smoke evidence is attached | ## 3. Waiver Review Rules diff --git a/docs/release/release-readiness-go-nogo-record.md b/docs/release/release-readiness-go-nogo-record.md index 605316c..04833d2 100644 --- a/docs/release/release-readiness-go-nogo-record.md +++ b/docs/release/release-readiness-go-nogo-record.md @@ -2,7 +2,7 @@ **Document status:** DV meeting baseline candidate **Date:** 2026-05-29 -**Candidate:** `v1.0.0-rc.1` evidence over workspace version `0.2.0-beta.1` +**Candidate:** documentation/DV evidence over Rust workspace version `0.2.0-beta.1`; Flutter app version/build `0.3.0+100` **Decision:** No-Go for public/store release; Conditional Go only for documentation review and continued internal DV validation ## 1. Decision Summary @@ -23,10 +23,11 @@ The phrase `Conditional Go` in this record is restricted to document-baseline re | Field | Value | |---|---| | Workspace version | `0.2.0-beta.1` | -| CHANGELOG latest candidate | `v1.0.0-rc.1` | -| Build number | `76` from `apps/chanora_flutter/pubspec.yaml` | +| Flutter app version/build | `0.3.0+100` from `apps/chanora_flutter/pubspec.yaml` | +| CHANGELOG latest candidate | `v0.3.0` baseline entry; public release version not reached | +| Build number | `100` from `apps/chanora_flutter/pubspec.yaml` | | Commit SHA | To be recorded from the candidate build job before release approval | -| Git tag | To be recorded if `v1.0.0-rc.1` is tagged for release validation | +| Git tag | To be recorded if a candidate is tagged for release validation | | Artifact hashes | Not recorded in current workspace; required before release approval | | Release owner | Product / Release Operations | | Verification owner | Software QA with System Engineering support | @@ -54,6 +55,7 @@ Current implementation status is summarized in `docs/implementation-status-2026- | Privacy policy baseline | Baseline candidate | Requires owner/legal review before public/store release | | Security/privacy evidence | Partial | Blocks strong secure-storage and diagnostic claims until audits attach evidence | | Android secure-storage DEK | Deferred to v1.1 | Requires waiver for internal testing; limits release claim | +| Android target compile/install/smoke | Blocked locally | Missing Android NDK compiler `aarch64-linux-android-clang` and no authorized ADB target block Android runtime claims | | iOS release build/signing | Unsigned verification only | Blocks TestFlight/App Store release | | macOS signing/notarization | Not complete | Blocks macOS public binary release | | Windows/Linux packaging | Source-buildable only for candidate | Blocks packaged public desktop release claims | @@ -70,6 +72,7 @@ Current implementation status is summarized in `docs/implementation-status-2026- | iOS unsigned build | CI defined | Attach latest passing candidate run; add signing evidence before release | | Compatible-server demo | Evidence not attached in this record | Run and attach demo notes/logs | | Audio send/receive and processing demo | Evidence not attached in this record | Run and attach platform evidence | +| Android target build/install/smoke | Blocked locally | Install/fix Android NDK compiler, connect/authorize a device or emulator, then attach build/install/smoke evidence | | Diagnostics redaction/export demo | Evidence not attached in this record | Run and attach export review | | Platform secure-storage audit | Partial | Attach per-platform audit or waiver | | PTT capability evidence | Partial | Attach per-platform `PttCapabilityLevel` and backend record | @@ -78,7 +81,7 @@ Current implementation status is summarized in `docs/implementation-status-2026- | Platform | Current readiness | Release decision | |---|---|---| -| Android | Core platform implementation present; Android Keystore-backed DEK deferred | Conditional internal validation only | +| Android | Core platform implementation present; Android Keystore-backed DEK deferred; local target compile/install/smoke blocked by missing `aarch64-linux-android-clang` and no authorized ADB target | Conditional internal validation only after Android build/install/smoke evidence or explicit waiver | | iOS | Unsigned build path present; signing and store pipeline incomplete | No-Go for store release | | Windows | Source-buildable; smoke procedure exists | No-Go for packaged release until smoke/signing evidence exists | | macOS | Source-buildable; public artifact not in candidate | No-Go for packaged release until signing/notarization evidence exists | diff --git a/docs/superpowers/plans/2026-06-08-maintainability-continuation.md b/docs/superpowers/plans/2026-06-08-maintainability-continuation.md index e79b679..2f01cb7 100644 --- a/docs/superpowers/plans/2026-06-08-maintainability-continuation.md +++ b/docs/superpowers/plans/2026-06-08-maintainability-continuation.md @@ -2,9 +2,11 @@ > **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:** Continue the current maintainability review with safe simplifications, current documentation, explicit fail-safe evidence, and Android runtime verification status. +**Goal:** Continue the current maintainability review with safe simplifications, full code-review remediation, current documentation, explicit fail-safe evidence, and Android runtime verification status. -**Architecture:** Treat the existing uncommitted maintainability changes as the baseline slice. Preserve public Rust Core, Bridge, Protocol, Audio, and Flutter responsibilities while applying only small simplifications that are covered by focused tests and workspace verification. Record larger seam decisions as follow-up findings instead of forcing broad rewrites into this pass. +**Current status:** Task 0 and the audio-realtime portion of Task 0.1 have landed in commits `d835394` and `8606eb4`. Task 0.2 is a documentation/status alignment slice only; it must not claim Android or iOS runtime success. + +**Architecture:** Treat the existing uncommitted maintainability changes as the baseline slice. Fix safety and hidden-bug findings before broad Module splits. Preserve public Rust Core, Bridge, Protocol, Audio, and Flutter responsibilities while applying only tested simplifications and risk-reducing refactors. Record larger seam decisions as follow-up findings unless a huge Module must be split to make a safety fix testable. **Tech Stack:** Rust 2021 Cargo workspace, Flutter/Dart 3.11, Flutter Rust Bridge 2.12, Android ADB, Markdown governance and verification documents. @@ -30,6 +32,164 @@ Implementation should keep the following responsibilities stable: - `docs/implementation-status-2026-05-28.md`: implementation status updates. - `docs/verification/swe4-unit-verification-plan.md`, `docs/verification/swe5-software-integration-verification-plan.md`: verification evidence and requirements updates. +## Review Findings To Remediate First + +The full review added these priority fixes before the original maintainability cleanup sequence: + +- Flutter privacy fail-safe: talk-power recovery must not clear a user/manual mute. Fixed in commit `d835394`. +- Flutter stuck-transmit fail-safe: touch PTT must release when disposed while held. Fixed in commit `d835394`. +- Flutter/iOS fail-safe: iOS audio-session activation errors must be caught, and activation should be moved before Rust VoiceProcessingIO startup where the current app flow allows. Missing-plugin/error hardening fixed in commit `d835394`; iOS device runtime verification remains required. +- Rust realtime safety: Android and iOS raw render-reference buffers must not use unsynchronized mutable aliasing. Callback-path hardening fixed in commit `8606eb4`; the full lock-free `AudioHandler` / config / debug-recorder redesign remains a follow-up. +- Rust realtime safety: Android input callback must not block on a mutex, and non-48 kHz capture should not allocate/clone per callback. Focused callback-path hardening fixed in commit `8606eb4`; Android target compilation and runtime verification remain blocked locally until the missing NDK compiler and an authorized ADB target are available. +- Rust control-plane safety: disconnect and protocol control requests must remain bounded under broken transport or sustained voice traffic. +- Governance correctness: README/release/VAD/Android API/product-decision docs must not contradict code or verification status. + +## Task 0: Fix Flutter Privacy and Stuck-Transmit Fail-Safes + +**Files:** +- Modify: `apps/chanora_flutter/lib/main.dart` +- Modify: `apps/chanora_flutter/lib/widgets/voice_compact.dart` +- Modify: `apps/chanora_flutter/lib/services/ios_audio_session_controller.dart` +- Test: `apps/chanora_flutter/test/widgets/voice_compact_test.dart` +- Test: existing Flutter tests under `apps/chanora_flutter/test/` + +- [ ] **Step 1: Add failing touch PTT disposal regression test** + +Create or update `apps/chanora_flutter/test/widgets/voice_compact_test.dart` with a widget test that presses the touch PTT button, replaces the widget without sending pointer-up, and expects the callback sequence `[true, false]`. + +- [ ] **Step 2: Run touch PTT test and verify RED** + +Run from `apps/chanora_flutter`: `flutter test test/widgets/voice_compact_test.dart` + +Expected before production fix: FAIL because disposal does not emit `false`. + +- [ ] **Step 3: Implement touch PTT release-on-dispose** + +Add `dispose()` to the touch PTT button state so an active press calls `widget.onHeldChanged(false)` exactly once before disposal. + +- [ ] **Step 4: Run touch PTT test and verify GREEN** + +Run from `apps/chanora_flutter`: `flutter test test/widgets/voice_compact_test.dart` + +Expected after fix: PASS. + +- [ ] **Step 5: Add or preserve mute-owner regression coverage** + +If an existing pure reducer seam is available, add a failing test for manual mute true -> talk power blocked -> talk power restored. If no testable seam exists, first extract the smallest voice mute owner helper from `main.dart` and test it directly. + +- [ ] **Step 6: Implement independent mute owners** + +Ensure talk-power recovery clears only the talk-power owner and does not clear manual/user mute or permission mute. Effective hard mute is the OR of manual, permission, and talk-power owners. + +- [ ] **Step 7: Harden iOS audio-session controller errors** + +Add tests for `MissingPluginException` in `ios_audio_session_controller_test.dart`, then catch `MissingPluginException` or `Object` so activation/deactivation failures do not become unhandled async errors. + +- [ ] **Step 8: Run focused Flutter verification** + +Run from `apps/chanora_flutter`: `flutter test test/widgets/voice_compact_test.dart test/services/ios_audio_session_controller_test.dart && flutter analyze` + +Expected: PASS. + +- [ ] **Step 9: Commit Flutter fail-safe slice** + +Run: + +```bash +git add apps/chanora_flutter/lib/main.dart apps/chanora_flutter/lib/widgets/voice_compact.dart apps/chanora_flutter/lib/services/ios_audio_session_controller.dart apps/chanora_flutter/test/widgets/voice_compact_test.dart apps/chanora_flutter/test/services/ios_audio_session_controller_test.dart +git commit -m "fix(voice): preserve mute owners and release touch ptt" +``` + +Expected: one commit containing only Flutter fail-safe fixes and tests. + +## Task 0.1: Fix Rust Realtime and Control-Plane Safety Findings + +**Files:** +- Modify: `crates/chanora_audio/src/android_voice_unit.rs` +- Modify: `crates/chanora_audio/src/ios_raw_unit.rs` +- Modify: `crates/chanora_audio/src/engine.rs` +- Modify: `crates/chanora_protocol/src/adapter.rs` +- Modify: `core/chanora_core/src/lib.rs` +- Test: Rust tests in affected crates + +- [ ] **Step 1: Add failing bounded-buffer regression for render-reference handoff** + +Add host-testable unit coverage around the render-reference buffer behavior so a writer can publish a frame and a reader can read a complete latest frame without unsynchronized mutation. + +- [ ] **Step 2: Replace unsafe shared mutable render-reference buffers** + +Replace unsynchronized mutable aliasing in Android and iOS raw render-reference buffers with a realtime-safe handoff such as an `ArrayQueue` of complete frames or a documented atomic double-buffer. Do not add mutex locking to realtime callbacks. + +- [ ] **Step 3: Add failing protocol progress regression where feasible** + +Add or isolate a test proving control requests are not starved by sustained voice packet drain. + +- [ ] **Step 4: Bound voice draining and disconnect shutdown** + +Cap voice packet draining per protocol loop and make disconnect/shutdown bounded so UI/Core locks are not held across unbounded transport waits. + +- [ ] **Step 5: Run focused Rust verification** + +Run: `cargo test -p chanora_audio -p chanora_protocol -p chanora_core` + +Expected: PASS. + +- [ ] **Step 6: Commit Rust safety slice** + +Run: + +```bash +git add crates/chanora_audio/src/android_voice_unit.rs crates/chanora_audio/src/ios_raw_unit.rs crates/chanora_audio/src/engine.rs crates/chanora_protocol/src/adapter.rs core/chanora_core/src/lib.rs +git commit -m "fix(audio): harden realtime and protocol fail-safes" +``` + +Expected: one commit containing only Rust safety fixes and tests. + +## Task 0.2: Align Review Findings With Specs, Plans, and Governance Docs + +**Status:** In progress / documentation-only alignment. Do not commit from this task unless explicitly requested. + +**Files:** +- Modify: `docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md` +- Modify: `docs/superpowers/plans/2026-06-08-maintainability-continuation.md` +- Modify: `docs/governance/maintainability-review-2026-06-08.md` +- Modify: `README.md` +- Modify if needed: `CHANGELOG.md` +- Modify if needed: `docs/governance/product-decision-register.md` +- Modify if needed: `docs/release/release-readiness-go-nogo-record.md` +- Modify if needed: `docs/release/dv-waiver-register.md` +- Modify if needed: `docs/verification/verification-master-plan.md` +- Modify if needed: `docs/verification/sys4-system-integration-verification-plan.md` + +- [x] **Step 1: Record full-review findings in maintainability review** + +Update `docs/governance/maintainability-review-2026-06-08.md` with the full code-review findings, fixed items, blocked items, and follow-up Module split candidates. + +- [x] **Step 2: Fix stale platform/release claims** + +Update Android minimum runtime claims to API 28 where code and requirements require it. Update release metadata so Flutter app version/build and Rust workspace version are clearly distinguished. + +- [x] **Step 3: Clarify VAD/VoiceActivity status** + +Document the difference between VAD scaffolding/assets/tests and product-enabled VoiceActivity behavior. Do not claim runtime VoiceActivity is shipped unless verified. + +- [x] **Step 4: Promote Android runtime verification blocker** + +Add Android ADB/build/install/smoke as a blocker or waiver in governing release/verification docs when no authorized target is connected. + +- [ ] **Step 5: Commit plan/spec/governance alignment slice** + +Skipped in this subagent run because the instruction for Task 0.2 explicitly says not to commit. + +Run: + +```bash +git add docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md docs/superpowers/plans/2026-06-08-maintainability-continuation.md docs/governance/maintainability-review-2026-06-08.md README.md CHANGELOG.md docs/governance/product-decision-register.md docs/release/release-readiness-go-nogo-record.md docs/release/dv-waiver-register.md docs/verification/verification-master-plan.md docs/verification/sys4-system-integration-verification-plan.md +git commit -m "docs: align review findings and verification gates" +``` + +Expected: one documentation/governance commit, with unavailable optional files omitted only if unchanged. + ## Task 1: Verify Current Branch Baseline **Files:** diff --git a/docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md b/docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md index 1d8ac5e..ee43502 100644 --- a/docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md +++ b/docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md @@ -1,20 +1,29 @@ # Maintainability Continuation Design **Date:** 2026-06-08 -**Status:** Approved design for implementation planning -**Scope:** Continue the current working-branch maintainability pass without broad rewrites. +**Status:** Approved design for implementation and full code-review remediation; Task 0 and focused audio-realtime fixes landed, documentation/governance alignment in progress +**Scope:** Continue the current working-branch maintainability pass, add full code-review findings, and fix high-risk bugs before broad rewrites. ## Purpose This design continues the project review already present in the working tree. The goal is to simplify the project where changes are low-risk, testable, and documented, while avoiding speculative architecture churn. -The work covers unnecessary functions, structs, files, modules, duplicated custom implementations, built-in replacement opportunities, outdated documents, fail-safe gaps, and Android runtime verification requirements. +The work covers unnecessary functions, structs, files, modules, duplicated custom implementations, built-in replacement opportunities, outdated documents, fail-safe gaps, Android runtime verification requirements, and full code-review remediation for hidden bugs. ## Recommended Approach -Use a targeted continuation of the current maintainability pass. +Use a targeted continuation of the current maintainability pass, now ordered by safety risk. -The existing branch already contains a first slice of simplification: core event DTO extraction, network diagnostics locality, `VecDeque` queue improvements, derived PTT backend errors, render downmix helper reuse, state reducer reuse, workspace metadata cleanup, and documentation updates. This design treats those changes as the baseline and adds only small, provable follow-up changes. +The existing branch already contains a first slice of simplification: core event DTO extraction, network diagnostics locality, `VecDeque` queue improvements, derived PTT backend errors, render downmix helper reuse, state reducer reuse, workspace metadata cleanup, and documentation updates. This design treats those changes as the baseline, but the full review found privacy, realtime-audio, disconnect, and documentation-governance issues that take priority over cosmetic simplification. + +The remediation order is: + +- Privacy and stuck-transmit fail-safes in Flutter voice state. Fixed in commit `d835394`. +- iOS audio-session error hardening before Rust VoiceProcessingIO startup. Missing-plugin/error handling fixed in commit `d835394`; iOS device runtime verification remains required. +- Rust realtime audio safety, especially unsynchronized render-reference buffers and blocking/allocating callbacks. Focused callback-path hardening fixed in commit `8606eb4`; full lock-free `AudioHandler` / config / debug-recorder redesign remains a follow-up. +- Bounded disconnect/control-plane progress in Rust protocol/core. Pending unless later code-review evidence closes it. +- Documentation and release/governance contradictions that can cause wrong verification claims. Addressed by Task 0.2 documentation alignment. +- Larger Module splits after behavior is protected by tests. Rejected alternatives: @@ -48,6 +57,16 @@ The implementation review should inspect these areas first: - `apps/chanora_flutter/lib`, excluding generated localization and bridge files unless an API change requires updates - governance, architecture, implementation-status, and verification documents affected by the code review +Full code-review remediation targets: + +- `apps/chanora_flutter/lib/main.dart`: mute ownership, iOS audio-session preflight, chat/unread follow-ups, and oversized session-controller extraction candidates. +- `apps/chanora_flutter/lib/widgets/voice_compact.dart`: touch PTT release-on-dispose fail-safe. +- `apps/chanora_flutter/lib/services/ios_audio_session_controller.dart`: missing-plugin fail-safe handling. +- `apps/chanora_flutter/lib/services/audio_lifecycle_service.dart`: macOS route/default-device no-op documentation or future adapter seam. +- `crates/chanora_audio/src/android_voice_unit.rs`, `ios_raw_unit.rs`, `ios_voice_unit.rs`, and `engine.rs`: realtime callback safety and platform lifecycle rollback. +- `core/chanora_core/src/lib.rs` and `crates/chanora_protocol/src/adapter.rs`: bounded disconnect and control-plane progress under voice load. +- `README.md`, `CHANGELOG.md`, `docs/release/*`, `docs/verification/*`, and `docs/governance/product-decision-register.md`: stale platform, release, VAD, Android runtime, and decision-register claims. + ## Simplification Rules Every code change must satisfy these rules: @@ -59,6 +78,14 @@ Every code change must satisfy these rules: - Do not introduce backward-compatibility shims unless there is a persisted-data, shipped-API, external-consumer, or explicit product need. - Record larger architectural opportunities in the maintainability review instead of forcing them into this pass. +Full code-review fix rules: + +- Fix safety bugs before Module split work. +- Use test-driven development for production behavior changes: write the failing test, run it, implement the minimal fix, then rerun the test. +- Keep manual/generated bridge files out of direct edits unless regeneration is intentionally verified. +- Split huge Modules only when the split creates a deeper Module with leverage and locality; file-size-only sharding is not sufficient. +- Compare architecture choices against established voice/chat client practice: Mumble-style bounded voice/control separation, Discord/TeamSpeak-style independent mute owners, WebRTC-style realtime callback minimalism, and Matrix/Element-style coherent state replication. + ## Testing Design Verification is tied to change type: @@ -66,10 +93,10 @@ Verification is tied to change type: - Rust-only changes require `cargo fmt --all`, `cargo check --workspace`, and `cargo test --workspace`. - Flutter changes require `flutter analyze` and `flutter test --exclude-tags e2e` from `apps/chanora_flutter`. - Bridge DTO/API changes require Rust verification, bridge generation check, Flutter analyze, and Flutter tests. -- Android platform, permission, lifecycle, or audio changes require Rust and Flutter verification plus `adb devices -l`, Android build/install, and a device or emulator smoke test. +- Android platform, permission, lifecycle, or audio changes require Rust and Flutter verification plus Android NDK target compilation, `adb devices -l`, Android build/install, and a device or emulator smoke test. - Documentation-only changes require affected docs and cross-links to be read and checked; code tests are not required unless the docs describe a code change just made. -If no ADB target is connected, Android runtime verification must be recorded as blocked. The implementation must not claim Android runtime success without device or emulator evidence. +If no ADB target is connected, Android runtime verification must be recorded as blocked. If Android target compilation cannot find the NDK compiler, for example `aarch64-linux-android-clang`, Android build evidence must also be recorded as blocked. The implementation must not claim Android runtime success without build/install/smoke evidence from an authorized device or emulator. ## Fail-Safe Review @@ -77,6 +104,12 @@ The review must identify fail-safe gaps and either verify them, fix them, or rec Priority fail-safe areas: +- User mute ownership must not be cleared by talk-power or permission recovery. +- Touch and keyboard PTT must release on cancellation, disposal, disconnect, lifecycle transition, or missed-up conditions. +- iOS AVAudioSession must be configured and activated before VoiceProcessingIO startup. +- Realtime callbacks must not block, allocate repeatedly, or use unsynchronized mutable aliasing. +- Disconnect and control requests must be bounded and must not hold global session locks across unbounded transport waits. +- Android and iOS device runtime behavior must be verified on hardware or an authorized emulator/simulator where applicable before platform success is claimed. - Android secure storage and Keystore-backed data-encryption-key handling - Android permission and audio lifecycle behavior - Stuck PTT prevention and missed-key-up recovery @@ -93,12 +126,19 @@ The working review record remains `docs/governance/maintainability-review-2026-0 Documents to update when affected: +- `README.md` +- `CHANGELOG.md` - `docs/governance/document-index.md` +- `docs/governance/product-decision-register.md` - `docs/architecture/sad.md` - `docs/architecture/sdd.md` - `docs/implementation-status-2026-05-28.md` - `docs/verification/swe4-unit-verification-plan.md` - `docs/verification/swe5-software-integration-verification-plan.md` +- `docs/verification/verification-master-plan.md` +- `docs/verification/sys4-system-integration-verification-plan.md` +- `docs/release/release-readiness-go-nogo-record.md` +- `docs/release/dv-waiver-register.md` - release or fail-safe records if verification status changes Documentation should distinguish completed changes, follow-up opportunities, blocked verification, and release limitations. @@ -114,6 +154,7 @@ This work is successful when: - Safe simplifications are implemented or recorded as follow-up opportunities. - Built-in replacement opportunities are applied only when behavior remains covered by tests. - Fail-safe gaps are documented with required evidence or fixed with verification. -- Rust and Flutter verification are run as required by the touched files. +- Rust and Flutter verification are run as required by the touched files, including targeted regression tests for every fixed bug. - Android ADB runtime verification is run when a target is available or explicitly recorded as blocked. - Documents reflect the final code and verification state. +- Full code-review findings are either fixed, downgraded with evidence, or recorded as follow-up risks with verification requirements. diff --git a/docs/verification/swe5-software-integration-verification-plan.md b/docs/verification/swe5-software-integration-verification-plan.md index 14d3271..be4231e 100644 --- a/docs/verification/swe5-software-integration-verification-plan.md +++ b/docs/verification/swe5-software-integration-verification-plan.md @@ -52,7 +52,20 @@ An integration path passes when: | iOS build is unsigned | Blocks App Store/TestFlight release approval | Release record must state unsigned verification only | | Android Keystore-backed DEK deferred | Limits secure-storage integration claim on Android | Waiver required for internal testing; public release claim blocked | | Event replay infrastructure not found | Limits protocol-state integration stress evidence | Mark P1 gap | +| Android target compile/runtime blocked during local review | Missing NDK compiler `aarch64-linux-android-clang` and no attached authorized target block device/emulator verification of Android audio, permission, lifecycle, and storage fail-safe behaviour | Fix/install the NDK toolchain, connect a device/emulator, confirm with `adb devices -l`, then run Android build/install/smoke before claiming Android success | -## 6. SWE.5 DV Decision Rule +## 6. Android Runtime Verification Gate + +Android integration changes require a working Android target toolchain and a connected device or emulator. The minimum local gate is: + +1. The Android NDK compiler needed by the target build, including `aarch64-linux-android-clang` for arm64, is available. +2. `adb devices -l` shows one authorized target. +3. Android app builds for that target. +4. The app installs and launches. +5. Permission, connect-screen, audio-start/stop, and diagnostic-export smoke paths are exercised or explicitly marked not applicable to the change. + +If the NDK compiler is unavailable or no target is connected and authorized, Android verification is blocked rather than passed. + +## 7. SWE.5 DV Decision Rule SWE.5 can pass for DV documentation readiness if every integration path has an identified evidence method and every incomplete path has a waiver or follow-up. SWE.5 does not pass for public release until current candidate integration runs are attached to the release-readiness record. diff --git a/docs/verification/sys4-system-integration-verification-plan.md b/docs/verification/sys4-system-integration-verification-plan.md index cb86093..791add9 100644 --- a/docs/verification/sys4-system-integration-verification-plan.md +++ b/docs/verification/sys4-system-integration-verification-plan.md @@ -36,7 +36,7 @@ This plan verifies Chanora as an integrated application system, including softwa | Platform | Current candidate status | Required SYS.4 evidence before public/store release | |---|---|---| -| Android | Implemented features include permissions, foreground service, Oboe audio, MODE_IN_COMMUNICATION; Android Keystore-backed DEK deferred | Device smoke, permission flow, foreground voice, secure-storage limitation waiver, Play target SDK inspection | +| Android | Implemented features include permissions, foreground service, Oboe audio, MODE_IN_COMMUNICATION; Android Keystore-backed DEK deferred; local target compile/runtime smoke blocked by missing `aarch64-linux-android-clang` and no authorized ADB target | NDK target compilation, `adb devices -l` authorized target evidence, device smoke, permission flow, foreground voice, secure-storage limitation waiver, Play target SDK inspection | | iOS | Source-buildable and unsigned; AVAudioSession work exists; public artifact not ready | Unsigned build evidence, device audio session smoke, signing/TestFlight evidence before release | | Windows | Source-buildable; smoke procedure exists | Executed smoke result, PTT capability evidence, packaging/signing evidence before release | | macOS | Source-buildable; not in current release artifacts | Build evidence, PTT capability evidence, signing/notarization evidence before release | @@ -51,6 +51,7 @@ This plan verifies Chanora as an integrated application system, including softwa | Security/privacy/legal readiness | DEC-012 and privacy/security gates are signed off or explicitly block release | | Release artifact integrity | Build number, commit SHA, tag, artifact hashes, and signing status are recorded | | Environmental limitations | Source-build-only, unsigned, or platform-specific limitations are listed in release readiness | +| Android runtime claim control | No Android runtime, permission-flow, or audio-lifecycle success is claimed until target compile, install, and device/emulator smoke evidence are attached | ## 6. SYS.4 DV Decision Rule diff --git a/docs/verification/verification-master-plan.md b/docs/verification/verification-master-plan.md index dcbe3c6..4866a85 100644 --- a/docs/verification/verification-master-plan.md +++ b/docs/verification/verification-master-plan.md @@ -2,7 +2,7 @@ **Document status:** DV meeting baseline candidate **Date:** 2026-05-29 -**Applies to:** Chanora `0.2.0-beta.1` workspace / `v1.0.0-rc.1` release-candidate evidence +**Applies to:** Chanora Rust workspace `0.2.0-beta.1`, Flutter app `0.3.0+100`, and current DV/release-candidate evidence **Primary upstream documents:** `docs/sysrs.md`, `docs/sysdes.md`, `docs/srs.md`, `docs/architecture/sad.md`, `docs/architecture/sdd.md`, `docs/implementation-status-2026-05-28.md` ## 1. Purpose @@ -79,6 +79,7 @@ The DV meeting can pass the documentation baseline if reviewers agree that: |---|---|---|---| | DEC-012 legal/trademark/OSS sign-off | Blocked / open | Blocks public or store release | `docs/legal/trademark-and-attribution-review.md`, `docs/release/dv-waiver-register.md` | | Android Keystore-backed DEK | Deferred to v1.1 | Blocks claim that Android secrets use hardware-backed DEK protection | `docs/release/dv-waiver-register.md` | +| Android target compilation and runtime smoke | Blocked locally | Blocks Android runtime, permission-flow, and audio-lifecycle success claims until NDK compiler and authorized target evidence exist | `docs/governance/maintainability-review-2026-06-08.md`, `docs/release/dv-waiver-register.md` | | Full state reducer test suite | Partial | Blocks full claim for SysRS-235/SysDes-103/SRS-059 through SRS-061 | `docs/release/dv-waiver-register.md` | | Desktop and iOS release artifacts | Source-buildable / unsigned only | Blocks broad binary distribution claims | `docs/release/release-readiness-go-nogo-record.md` | | Store signing and notarization | Not complete for candidate | Blocks production release | `docs/release/release-readiness-go-nogo-record.md` |