ble-reticulum/migration/phase2/Gate2E_BLEPeerSessionManager_optional_integration_20260518_1628.md

Gate 2E: BLEPeerSessionManager Optional Integration

Date: 2026-05-18 16:28 America/Los_Angeles

Scope: optional BLEPeerSessionManager integration behind BLE_RETICULUM_SESSION_BACKEND.

Summary

Gate 2E adds an optional C++ session-manager path for BLEInterface._handle_identity_handshake.

BLEInterface.py was modified in this gate. The existing Python handshake implementation was preserved as _handle_identity_handshake_python, and _handle_identity_handshake is now a dispatcher.

No live BLE field testing was performed.

Backend Flag

New environment variable:

BLE_RETICULUM_SESSION_BACKEND=auto|cpp|python

Behavior:

• python: always use the existing Python handshake logic.
• cpp: require ble_protocol_core_cpp.BLEPeerSessionManager; fail clearly if unavailable.
• auto: prefer C++ session manager if importable, otherwise use Python.

This is separate from:

BLE_RETICULUM_FRAGMENTATION_BACKEND

The fragmentation backend was not conflated with session backend selection.

Modified Source

• src/ble_reticulum/BLESessionBackend.py
• src/ble_reticulum/BLEInterface.py

handle_peripheral_data was not modified.

The C++ manager remains a decision engine only. Python still performs:

• RNS.log
• driver.disconnect
• Python fragmenter/reassembler creation
• _spawn_peer_interface
• address_to_identity / identity_to_address mirroring
• address_to_interface mirroring
• _pending_identity_connections cleanup
• _last_real_data updates

Tests Added

Added:

• migration/tests/test_ble_session_backend_integration.py

Coverage:

• default/auto backend selects C++ when available;
• auto falls back to Python when C++ is unavailable;
• Python backend forces Python even when C++ is available;
• C++ backend fails clearly when unavailable;
• Python backend still uses existing Python handshake behavior;
• C++ backend covers Gate 2D equivalence cases through the BLEInterface._handle_identity_handshake dispatcher:
  • non-16-byte payload;
  • new identity accepted;
  • duplicate same identity consumed;
  • duplicate mismatched identity consumed with warning intent;
  • duplicate active elsewhere disconnects current address;
  • stale/pending detach replacement accepted;
  • zombie old connection accepted and old peer disconnect requested;
  • MTU fallback to 23;
  • MTU provided honored;
  • pending identity removed;
  • existing spawned interface path updates address.

Verification

Backend shim regression:

pytest -q migration/tests/test_fragmentation_backend_shim.py

Result:

9 passed, 2 warnings in 0.59s

Gate 2C / Gate 2D / Gate 2E regression:

PYTHONPATH=migration/protocol_core pytest -q migration/tests/test_ble_peer_session_manager_pybind.py migration/tests/test_ble_peer_session_manager_python_equivalence.py migration/tests/test_ble_session_backend_integration.py

Result:

39 passed, 1 skipped, 2 warnings in 0.51s

Migration regression set:

PYTHONPATH=migration/protocol_core pytest -q migration/tests/test_fragmentation_cpp_equivalence.py migration/tests/test_identity_helpers_cpp_equivalence.py migration/tests/test_ble_peer_session_manager_pybind.py migration/tests/test_ble_peer_session_manager_python_equivalence.py migration/tests/test_ble_session_backend_integration.py

Result:

87 passed, 2 skipped, 2 warnings in 0.77s

The pybind11 extension was already current for Gate 2E; no rebuild was needed in this gate.

Notes

The default backend selector follows the Gate 2E requested auto behavior: prefer C++ when available and fall back to Python when unavailable. Operators can force the reference Python path with:

BLE_RETICULUM_SESSION_BACKEND=python

SQL

Companion SQL:

migration/sql/mark_gate2e_protocol_session_optional_integration_20260518_1628.sql

The SQL marks _handle_identity_handshake as OPTIONAL_INTEGRATION for phase 2_ble_protocol_session_manager, keeps tag GLUE, keeps cpp_candidate=1, and does not mark field acceptance.