ble-reticulum/migration/Codex_prompt_20260518_1504_Phase2_Gate_2C.md

Gate 2C task: pybind11 binding for BLEPeerSessionManager plus Python tests

Context: Gate 2B is complete. BLEPeerSessionManager compiles and native C++ tests pass on jp and zerodev1.

Goal: Expose BLEPeerSessionManager to Python through the existing protocol_core / pybind11 module so Python tests can instantiate the manager, call its methods, and inspect result/action values.

Restrictions:

• Do not modify BLEInterface.py.
• Do not modify live BLE behavior.
• Do not add environment-flag integration yet.
• Do not run bilateral field tests yet.
• Keep this as binding + Python unit tests only.

Implement:

1. pybind11 bindings for:

   • BLEPeerSessionManager
   • ConnectionId
   • ConnectionSnapshot
   • HandshakeResult
   • SessionAction
   • PeerSessionView if useful
   • relevant enums:
     • LocalRole
     • InputDecision
     • SessionActionType

2. Bind static helpers:

   • isIdentityHandshakePayload
   • identityFromPayload
   • computeIdentityKey
   • computeFragmenterKey

3. Python tests under: migration/tests/test_ble_peer_session_manager_pybind.py

Test cases:

• import module succeeds
• non-16-byte payload returns PassToReassembler and consumed=false
• new 16-byte identity returns AcceptedNewIdentity and consumed=true
• identity_key equals first 8 bytes as 16 lowercase hex chars
• fragmenter_key equals full 16-byte identity as 32 lowercase hex chars
• known identity duplicate same returns ConsumedDuplicateSameIdentity
• known identity duplicate mismatch returns ConsumedDuplicateMismatchedIdentity
• MTU provided is preserved
• MTU missing falls back to 23
• duplicate identity active elsewhere requests DisconnectCurrentPeer
• pending identity timeout can be marked and expired
• peer address update preserves identity/fragmenter key

Also run existing tests:

• migration/tests/test_fragmentation_cpp_equivalence.py
• migration/tests/test_fragmentation_backend_shim.py
• migration/tests/test_identity_helpers_cpp_equivalence.py
• migration/tests/test_ble_peer_session_manager_pybind.py

Deliverables:

1. Updated pybind11 binding source.
2. Python tests.
3. Gate 2C report: migration/phase2/Gate2C_BLEPeerSessionManager_pybind_tests_YYYYMMDD_HHMM.md
4. SQL: migration/sql/mark_gate2c_protocol_session_pybind_tests_YYYYMMDD_HHMM.sql

SQL requirements:

• Do not modify Phase 1 FIELD_ACCEPTED records.
• Do not mark Gate 2F / FIELD_ACCEPTED.
• Update _handle_identity_handshake tracking row: phase = '2_ble_protocol_session_manager' status = 'PYTHON_BOUND' cpp_candidate = 1
• Insert a reviews row describing: Gate 2C completed pybind11 exposure and Python unit tests.
• Include a SELECT verification query.

Before final response:

• Run the Python tests.
• Report exact commands and results.