chanora/dev-docs/superpowers/plans/2026-06-08-core-internal-split.md

Core Internal Split Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Improve chanora_core maintainability by moving stable event DTOs and network diagnostic state out of the oversized lib.rs while preserving the public crate Interface.

Architecture: Keep lib.rs as the public Interface and session orchestration entry point. Move event-facing DTOs to events.rs and private network diagnostic ring-buffer state to network_diagnostics.rs; re-export public event types from lib.rs so downstream callers keep using chanora_core::SessionEvent and related names unchanged.

Tech Stack: Rust 2021, Tokio broadcast/watch channels, thiserror, existing Cargo workspace tests.

---

Task 1: Move Core Event DTOs

Files:

• Create: core/chanora_core/src/events.rs

• Modify: core/chanora_core/src/lib.rs

• Verify: cargo test -p chanora_core

• Step 1: Preserve current public Interface with tests

Run: cargo test -p chanora_core Expected: PASS. Existing bridge-facing tests and compile checks prove the current public event names are valid.

• Step 2: Create events.rs with the moved public event DTOs

Move these exact public types from lib.rs to events.rs:

• PttDescriptorSnapshot
• PersistedPttBinding
• SessionEvent
• VoiceJoinSyncState
• VoiceJoinErrorCode
• NetworkState

Use local imports in events.rs for chanora_audio::{AudioRoute, PttBackendDescriptor} and chanora_protocol::MessageTarget.

• Step 3: Re-export moved types from lib.rs

Add mod events; and pub use events::{...}; for all moved public types. Remove the original definitions from lib.rs.

• Step 4: Run tests

Run: cargo test -p chanora_core Expected: PASS with no public Interface break.

Task 2: Move Core Network Diagnostics State

Files:

• Create: core/chanora_core/src/network_diagnostics.rs

• Modify: core/chanora_core/src/lib.rs

• Verify: cargo test -p chanora_core network_diagnostics

• Step 1: Move NetworkDiagnostics into a private module

Move the private NetworkDiagnostics struct and its methods from lib.rs into network_diagnostics.rs. Keep methods pub(crate) because ChanoraSession records connection/loss events and exports summaries.

• Step 2: Move the regression test with the module

Move network_diagnostics_keeps_last_eight_loss_reasons from the lib.rs test module into network_diagnostics.rs so the behaviour test lives next to the Implementation it protects.

• Step 3: Import the private module from lib.rs

Add mod network_diagnostics; and use network_diagnostics::NetworkDiagnostics;. Remove VecDeque from the lib.rs imports.

• Step 4: Run targeted and workspace verification

Run: cargo test -p chanora_core network_diagnostics Expected: PASS.

Run: cargo test --workspace Expected: PASS.

Task 3: Format and Check Workspace

Files:

• Modify: Rust files touched above only, except existing formatter-only churn may remain from prior cargo fmt --all.

• Step 1: Format Rust code

Run: cargo fmt --all Expected: no command output.

• Step 2: Compile workspace

Run: cargo check --workspace Expected: finishes successfully.

• Step 3: Inspect diff

Run: git diff --stat Expected: new events.rs and network_diagnostics.rs; smaller core/chanora_core/src/lib.rs; no public API renames.

---

Self-review: This plan covers the recommended Core split first slice, avoids public Interface changes, has no placeholders, and keeps testing tied to the moved Implementations.