ble-reticulum/migration/Codex_prompt_State2A_20250518_1433.md

Gate 2A task: BLEProtocolSession / PeerSessionManager design

Context: We are working in /usr/local/src/ble-reticulum.

Phase 1 is frozen and field accepted. The C++ protocol core already includes:

• BLEFragmenter
• BLEReassembler
• HDLCFramer
• identity helper equivalents for:
  • BLEInterface._get_fragmenter_key
  • BLEInterface._compute_identity_hash

Phase 1 evidence:

• C++ equivalence tests passed.
• backend shim tests passed.
• identity helper equivalence tests passed.
• ARM tests passed on zerodev1 and zerodev2.
• bilateral US Constitution transfer field test succeeded using the C++ backend.
• Phase 1 was documented and tagged.

Final goal: The final target is not “Python forever.” The final target is a C++ BLE protocol/session layer usable by microReticulum on ESP32-S3 / LilyGO T-Beam SUPREME. Python is currently a Linux test adapter and field-test harness.

Important comparative project: I have also had you inspect torlando-tech/pyxis: https://github.com/torlando-tech/pyxis

Use Pyxis as comparative prior art because it is C++ firmware built on microReticulum. However, do not assume Pyxis’s BLE implementation is complete or correct. Treat it as an architectural reference for how C++ microReticulum interfaces are organized, not as behavior to copy blindly.

Gate 2A objective: Design, but do not implement, a C++ BLEProtocolSession or PeerSessionManager.

Target reference behavior: src/ble_reticulum/BLEInterface.py BLEInterface._handle_identity_handshake

Important: Do not port _handle_identity_handshake line-for-line. Do not modify BLEInterface.py. Do not modify any source files. This is a design/report gate only.

The design should move the authoritative BLE peer/session model toward C++, while leaving Linux/Python and ESP32/microReticulum as adapters.

Please produce a Markdown report under:

migration/phase2/Gate2A_BLEProtocolSession_design_YYYYMMDD_HHMM.md

Use the current date/time in the filename.

Report requirements:

1. Executive summary

   • State whether Phase 2 should proceed.
   • State whether the correct C++ unit is BLEProtocolSession, PeerSessionManager, or another name.
   • State why _handle_identity_handshake should not be ported literally.

2. Reference behavior map Inspect BLEInterface._handle_identity_handshake and related functions:

   • _data_received_callback
   • _check_duplicate_identity
   • _spawn_peer_interface
   • _get_fragmenter_key
   • _compute_identity_hash
   • handle_peripheral_data, if it contains parallel/legacy handshake behavior

   For each relevant behavior, identify:

   • pure protocol/session decision
   • Linux/Python/Reticulum adapter action
   • ESP32/microReticulum adapter equivalent
   • state read
   • state mutated
   • risk if changed

3. Pyxis comparison Inspect the Pyxis C++ Reticulum/microReticulum interface structure. Identify:

   • relevant C++ interface/session classes
   • how Pyxis organizes transport/interface state
   • what design ideas can be reused
   • what should not be reused
   • whether Pyxis gives a useful pattern for ESP32-side adapter code
   • whether Pyxis has BLE-specific code and whether it is mature enough to guide us

4. Proposed C++ header Propose a header for the C++ session manager. Include:

   • namespace
   • types
   • enums
   • result structs
   • event/action structs
   • class declaration
   • methods
   • comments explaining ownership

   This header is only a proposal; do not create the actual .hpp file yet unless explicitly instructed later.

5. State ownership model Clearly define which state should move to C++:

   • address to identity mapping
   • identity to active session mapping
   • MTU per peer
   • pending identity state
   • last real data / zombie timing, if appropriate
   • fragmenter/reassembler ownership, if appropriate
   • peer-ready state

   Clearly define which state should stay in adapters:

   • RNS.Transport.interfaces
   • BLEPeerInterface Python object
   • BlueZ/Bleak/DBus objects
   • ESP32 NimBLE connection handles
   • logging mechanism
   • actual disconnect calls

6. Result/action model The C++ core should return explicit decisions and adapter actions, not directly call platform code.

   Include actions such as:

   • consume input
   • pass to reassembler
   • accept new identity
   • reject duplicate identity
   • disconnect current peer
   • disconnect old peer
   • create fragmentation state
   • mark peer ready
   • update peer address
   • remove pending identity
   • mark real data

7. Python adapter boundary Describe how current BLEInterface.py would use the C++ session manager during transition:

   • build ConnectionState from current Python dictionaries and driver state
   • call C++ session manager
   • mirror C++ state into Python dictionaries, initially
   • perform RNS.log
   • call driver.disconnect when requested
   • call _spawn_peer_interface when requested

8. ESP32/microReticulum adapter boundary Describe how the same session manager would be used on T-Beam Supreme / ESP32-S3:

   • BLE callback receives bytes
   • connection handle/address mapped into adapter state
   • call C++ session manager
   • create/use C++ fragmenter/reassembler
   • register peer/session with microReticulum interface abstraction
   • disconnect via ESP32 BLE stack when requested

9. Test matrix Provide a table of tests for Gate 2B and Gate 2C. Include at minimum:

   • non-16-byte payload
   • new 16-byte identity
   • known identity duplicate same
   • known identity duplicate mismatch
   • duplicate identity active elsewhere
   • duplicate identity with stale/pending detach
   • duplicate identity with zombie old connection
   • MTU provided
   • MTU missing fallback to 23
   • pending identity timeout
   • peer address update
   • consumed packet behavior
   • pass-to-reassembler behavior
   • exception/invalid state compatibility if applicable

10. Migration plan Give a staged plan: Gate 2A: design only Gate 2B: C++ session manager skeleton + pure unit tests Gate 2C: pybind11 binding + Python tests Gate 2D: Python equivalence harness with fake driver/state Gate 2E: optional Python integration behind environment flag Gate 2F: bilateral Constitution field test Gate 2G: ESP32/microReticulum adapter design

11. Risk register Include risks:

• accidentally changing current BLE behavior
• duplicate handshake logic in handle_peripheral_data
• MAC rotation assumptions
• identity collision/truncation assumptions
• consuming 16-byte real data
• Python and C++ state divergence during transition
• ESP32 memory constraints
• concurrency differences between Linux/BlueZ and ESP32 BLE callbacks

12. SQL output Generate SQL insert/update statements for the migration tracking database.

Tracking database context: The SQLite database is:

/usr/local/src/ble-reticulum/migration/ble_migration.sqlite

Tables known to exist:

symbols reviews

The symbols table includes at least these columns:

symbol_id source_file symbol_name symbol_type class_name line_number tag phase status cpp_candidate confidence rationale callers callees notes first_seen_at updated_at

The reviews table includes at least these columns:

review_id symbol_id reviewed_at reviewer old_tag new_tag old_status new_status note

Current Phase 1 state:

• 16 CORE symbols are FIELD_ACCEPTED.
• Remaining CORE symbols not accepted: none.
• Unknown or needs-review symbols: none.
• Candidate next tasks: none.

For Gate 2A, please generate SQL in the report, and also write it to:

migration/sql/start_gate2a_protocol_session_design_YYYYMMDD_HHMM.sql

SQL intent:

• Do not destroy Phase 1 records.
• Do not mark implementation as complete.
• Start Gate 2A as DESIGN only.
• Add or update a tracking record for: source_file = 'src/ble_reticulum/BLEInterface.py' class_name = 'BLEInterface' symbol_name = '_handle_identity_handshake' phase = '2_ble_protocol_session_manager' status = 'DESIGN' tag should remain GLUE unless you justify changing it. cpp_candidate should be 1 only if you define it as “reference behavior for C++ session manager,” not literal function port.
• Insert a review note explaining: Gate 2A opened as design-only. _handle_identity_handshake is reference behavior. Final target is C++ BLEProtocolSession usable from Python adapter and ESP32/microReticulum adapter. Pyxis was reviewed as C++ microReticulum prior art.
• Include a SELECT verification query at the end.

Preferred SQL style:

• Use BEGIN; ... COMMIT;
• Use UPDATE where the symbol already exists.
• Use INSERT INTO reviews SELECT ... FROM symbols WHERE ...
• Include comments and example command lines.
• Do not assume new tables exist.
• Do not modify Phase 1 FIELD_ACCEPTED rows.

Also provide a short suggested commit message for the Gate 2A report and SQL.