edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align review findings and verification gates

Browse Source
This commit is contained in:
Edison Jwa
2026-06-08 19:52:16 +09:00
parent 8606eb48c8
commit 8487acf167
12 changed files with 354 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-06-08-maintainability-continuation.md
+162 -2
View File
@@ -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:**
docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md
+49 -8
View File
@@ -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.