chanora/docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md

Maintainability Continuation Design

Date: 2026-06-08 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, Android runtime verification requirements, and full code-review remediation for hidden bugs.

Recommended Approach

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, 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:

• Documentation-only audit: safer, but leaves clear simplifications unimplemented.
• Broad architectural cleanup: may produce long-term wins, but is too risky for this pass because bridge, protocol, audio, and Android behavior have high regression cost.

Architecture Boundaries

The existing responsibilities remain intact:

• Flutter owns presentation, navigation, Material 3 behavior, accessibility, localization presentation, and platform UI behavior.
• Flutter Rust Bridge owns typed DTO/API glue and generated bindings.
• Rust Core owns session orchestration, cross-crate coordination, bridge-facing public events, and stable public APIs.
• Protocol owns TeamSpeak-compatible protocol isolation behind tsclientlib.
• Audio owns capture, render, processing, PTT backends, platform audio behavior, and voice packet handling where explicitly documented.
• Diagnostics owns redaction, logs, export records, and bounded diagnostic history.

Public interfaces should stay stable unless a change clearly removes duplicated or unnecessary code and has direct verification.

Review Targets

The implementation review should inspect these areas first:

• core/chanora_core/src/lib.rs, events.rs, network_diagnostics.rs, and ptt.rs
• crates/chanora_audio, especially duplicated render, capture, PTT, and platform-audio helpers
• crates/chanora_state reducer paths
• crates/chanora_protocol adapter ordering, event, and DTO mapping paths
• crates/chanora_bridge/src/api.rs, excluding generated bridge files unless regeneration is intentionally part of a change
• crates/chanora_diagnostics/src/lib.rs
• crates/chanora_prefetch and crates/chanora_resolver as a documented follow-up seam decision unless a trivial cleanup appears
• 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:

• Prefer deletion, built-in APIs, derives, or reuse of existing helpers over new abstractions.
• Merge files or modules only when the merged unit has a clearer single responsibility.
• Split files only when it improves locality around a stable responsibility and preserves public API shape.
• Do not manually edit generated files unless the generation process is part of the verified change.
• 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:

• 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 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. 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

The review must identify fail-safe gaps and either verify them, fix them, or record the missing evidence.

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
• Diagnostic redaction and privacy-sensitive event export
• Bridge DTO drift between Core, Bridge, and Dart generated bindings
• Protocol isolation exceptions for voice packet handling
• Runtime behavior gaps not covered by unit tests

No release-readiness or production-safety claim should be made without matching evidence.

Documentation Design

The working review record remains docs/governance/maintainability-review-2026-06-08.md.

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.

Commit Policy

No commit is created automatically. A commit happens only when explicitly requested, after inspecting git status, git diff, and recent commits.

Success Criteria

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, 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.