bitchat-android/docs/CODEX_MESH_CORE_REFACTOR_PLAN.md

Mesh Core Refactor Plan

Goal: unify BLE + Wi-Fi Aware mesh services behind a shared core to reduce duplication, improve readability, and make auditing easier without changing runtime behavior.

Phase 0: Inventory + Guardrails

• Capture current public API surface used by UI/services (identify required methods/properties).
• Identify transport-specific responsibilities vs shared mesh-core logic.
• Decide how to share GossipSyncManager (keep existing holder behavior unless explicitly improved).

Phase 1: Shared Types + Utilities

• Introduce MeshDelegate in com.bitchat.android.mesh and make both BLE/Wi‑Fi delegates type-alias it.
• Add MeshTransport interface to abstract local transport send/unicast and optional info hooks.
• Extract MeshPacketUtils (hex id parsing, sha256 helper) used by both services.
• Add unit tests for MeshPacketUtils (hex parsing + sha256 stability).

Phase 2: MeshCore (Shared Coordinator)

• Create MeshCore with shared managers (Peer/Fragment/Security/StoreForward/Message/Packet).
• Move shared delegate wiring into MeshCore with hooks for transport-specific behavior:
  • onMessageReceived (BLE notification / AppStateStore)
  • onPeerIdBinding (BLE favorites mapping)
  • onAnnounceProcessed (BLE first-announce address map)
• Centralize shared packet signing + announce/leave creation.
• Centralize message/file/read-receipt senders (public + private).
• Expose helper methods for peer info, session state, debug info, and panic-mode clearing.

Phase 3: BluetoothMeshService Integration

• Replace duplicated core fields with a single MeshCore instance.
• Wire BluetoothConnectionManager callbacks into MeshCore packet ingestion.
• Move periodic announce + gossip start/stop into MeshCore usage.
• Preserve BLE-only behaviors (connection manager control, background notifications).
• Keep MeshServiceHolder semantics intact (reusability + shared gossip manager).

Phase 4: WifiAwareMeshService Integration

• Replace duplicated core fields with a MeshCore instance.
• Route Wi‑Fi socket RX into MeshCore packet ingestion.
• Keep Wi‑Fi aware discovery/connection logic transport-specific.
• Ensure gossip sync usage matches current shared behavior.

Phase 5: Cleanup + Consistency

• Remove legacy duplicate helpers + delegates from both services.
• Ensure debug status output stays consistent (core + transport sections).
• Confirm behavior parity for announce/leave + handshake flows.

Phase 6: Tests + Verification

• Run unit tests: ./gradlew test (or targeted if full suite is too slow).
• If new tests fail, iterate until green.

Status Tracking

• Phase 0 complete
• Phase 1 complete
• Phase 2 complete
• Phase 3 complete
• Phase 4 complete
• Phase 5 complete
• Phase 6 complete

Post-Refactor Review Findings (2025-02-XX)

Findings (confirmed issues to fix):

• Shared GossipSyncManager is stopped when Wi‑Fi Aware stops, even if BLE is still active.
• Shared GossipSyncManager unicast (sendPacketToPeer) only reaches BLE peers; Wi‑Fi Aware peers miss initial sync.
• Read receipts are sent only via BLE in UI paths; Wi‑Fi Aware-only sessions never send receipts.

TODO (fix plan):

• MeshCore: guard gossipSyncManager.start/stop so only the owner transport controls lifecycle.
• TransportBridgeService: add unicast forwarding across transports; update BLE/Wi‑Fi transport layers to support it.
• MeshCore: when owning gossip manager, forward unicast sync packets to other transports via bridge.
• UI: route read receipts via BLE if session established, else via Wi‑Fi Aware when available.
• Tests: add unit tests for TransportBridgeService unicast forwarding and run them.