ble-reticulum/migration/Codex_response_20260616_1514.md

Read-only inspection completed. Note: the prompt’s Reticulum info path was not present as named; I used `/usr/local/src/ble-reticulum/reticulum_info_20260516_1444.txt`. Installed RNS is `rns 1.1.3` at `/home/jlpoole/rnsenv/lib/python3.13/site-packages/RNS`.

**BLEFragmentation.py**

| file path | symbol | line | tag | phase-1 C++ candidate | rationale | important callers | important callees |
|---|---:|---:|---|---|---|---|---|
| `src/ble_reticulum/BLEFragmentation.py` | `BLEFragmenter` | 52 | [CORE] | yes | Pure BLE packet fragmentation format; RNS only logging. | `BLEInterface._mtu_negotiated_callback`, `_handle_identity_handshake`, `BLEPeerInterface.process_outgoing` | `struct.pack` |
| same | `BLEFragmenter.__init__` | 68 | [CORE] | yes | MTU/header sizing logic. | fragmenter construction | none |
| same | `BLEFragmenter.fragment_packet` | 82 | [CORE] | yes | Core packet-to-fragments encoding. | `BLEPeerInterface.process_outgoing` | `struct.pack` |
| same | `BLEFragmenter.get_fragment_overhead` | 158 | [CORE] | yes | Pure sizing/overhead calculation. | tests/diagnostics likely | none |
| same | `BLEReassembler` | 176 | [CORE] | yes | Core fragment state machine; RNS only logging. | `BLEInterface` receive paths | `_reassemble`, `cleanup_stale_buffers` |
| same | `BLEReassembler.__init__` | 187 | [CORE] | yes | Protocol reassembly state. | reassembler construction | none |
| same | `BLEReassembler.receive_fragment` | 205 | [CORE] | yes | Core fragment validation/dedup/reassembly trigger. | `_handle_ble_data`, `handle_peripheral_data` | `struct.unpack`, `_reassemble` |
| same | `BLEReassembler._reassemble` | 380 | [CORE] | yes | Pure ordered fragment join. | `receive_fragment` | none |
| same | `BLEReassembler.cleanup_stale_buffers` | 402 | [CORE] | yes | Timeout policy for incomplete protocol frames. | cleanup timer, receive paths | `time.time` |
| same | `BLEReassembler.get_statistics` | 429 | [CORE] | yes | Protocol stats. | receive/logging paths | none |
| same | `BLEReassembler.reset_statistics` | 443 | [CORE] | yes | Protocol stats reset. | tests likely | none |
| same | `HDLCFramer` | 450 | [CORE] | yes | Pure byte-stuffing frame format. | not obviously used | static methods |
| same | `HDLCFramer.frame_packet` | 464 | [CORE] | yes | Pure HDLC-style escaping. | tests/possible future use | none |
| same | `HDLCFramer.deframe_packet` | 491 | [CORE] | yes | Pure HDLC-style unescaping/validation. | tests/possible future use | none |

**BLEInterface.py**

| file path | symbol | line | tag | phase-1 C++ candidate | rationale | important callers | important callees |
|---|---:|---:|---|---|---|---|---|
| `src/ble_reticulum/BLEInterface.py` | `DiscoveredPeer` | 118 | [PLATFORM] | no | BLE discovery/connection scoring state. | `_device_discovered_callback`, `_select_peers_to_connect` | `time.time` |
| same | `DiscoveredPeer.__init__` | 146 | [PLATFORM] | no | Stores BLE address/RSSI/timing. | discovery callback | `time.time` |
| same | `update_rssi` | 167 | [PLATFORM] | no | Discovery cache update. | discovery callback | `time.time` |
| same | `record_connection_attempt` | 172 | [PLATFORM] | no | BLE connection policy state. | discovery callback | `time.time` |
| same | `record_connection_success` | 177 | [PLATFORM] | no | BLE connection policy state. | `_record_connection_success` | none |
| same | `record_connection_failure` | 181 | [PLATFORM] | no | BLE connection policy state. | `_record_connection_failure` | none |
| same | `get_success_rate` | 185 | [PLATFORM] | no | BLE peer scoring helper. | `_score_peer`, `__repr__` | none |
| same | `__repr__` | 196 | [TEST] | no | Diagnostic formatting only. | logging/debug | `get_success_rate` |
| same | `BLEInterface` | 202 | [GLUE] | no | Reticulum `Interface` implementation binding BLE driver to RNS Transport. | Reticulum external interface loader | many |
| same | `BLEInterface.__init__` | 267 | [GLUE] | no | Heavy RNS config, driver, locks, timers, callbacks. | Reticulum loader | `Interface.get_config_obj`, driver ctor |
| same | `start` | 479 | [GLUE] | no | Starts driver/scanning and touches Transport path workaround. | `__init__` | `driver.start`, `driver.start_scanning`, `_clear_stale_ble_paths` |
| same | `final_init` | 516 | [GLUE] | no | Reticulum lifecycle hook. | Reticulum | `_start_advertising_when_identity_ready` |
| same | `_setup_logging_redirect` | 529 | [GLUE] | no | RNS logging integration. | `__init__` | `logging`, `RNS.log` |
| same | `_start_advertising_when_identity_ready` | 583 | [GLUE] | no | Polls `RNS.Transport.identity`; starts platform advertising. | `final_init` thread | `driver.set_identity`, `driver.start_advertising` |
| same | `_clear_stale_ble_paths` | 630 | [GLUE] | no | Depends on `RNS.Transport.path_table` internals. | `start` | `Transport.path_table` |
| same | `_start_cleanup_timer` | 686 | [GLUE] | no | Thread timer around Python state. | `__init__`, cleanup task | `threading.Timer` |
| same | `_periodic_cleanup_task` | 701 | [GLUE] | no | Coordinates reassembly cleanup plus interface lifecycle. | timer | `cleanup_stale_buffers`, `_validate_spawned_interfaces` |
| same | `_cleanup_pending_identity_connections` | 741 | [GLUE] | no | Driver disconnect policy around identity handshake. | cleanup task | `driver.disconnect` |
| same | `_process_pending_detaches` | 771 | [GLUE] | no | Reticulum peer interface lifecycle. | cleanup task | `peer_if.detach`, `_get_fragmenter_key` |
| same | `_validate_spawned_interfaces` | 829 | [GLUE] | no | Compares RNS spawned interfaces to driver connections. | cleanup task | `driver.connected_peers`, `peer_if.detach` |
| same | `_device_discovered_callback` | 912 | [PLATFORM] | no | BLE scan callback and connection initiation. | driver callback | `DiscoveredPeer`, `_select_peers_to_connect`, `driver.connect` |
| same | `_device_connected_callback` | 964 | [GLUE] | no | Driver callback; maps identity to Reticulum peer interface. | driver callback | `_compute_identity_hash`, `_mtu_negotiated_callback` |
| same | `_check_duplicate_identity` | 1023 | [GLUE] | no | Identity dedup policy tied to driver state and MAC rotation. | driver callback | `_cleanup_stale_address`, `driver.disconnect` |
| same | `_mtu_negotiated_callback` | 1112 | [GLUE] | no | Creates protocol fragmenters but tied to driver/RNS interface spawn. | driver callback | `BLEFragmenter`, `BLEReassembler`, `_spawn_peer_interface` |
| same | `_handle_identity_handshake` | 1174 | [GLUE] | no | 16-byte identity handshake is protocol-ish, but intertwined with driver/RNS state. | `_data_received_callback` | `_check_duplicate_identity`, `_spawn_peer_interface` |
| same | `_data_received_callback` | 1281 | [GLUE] | no | Driver callback dispatch. | driver callback | `_handle_identity_handshake`, `_handle_ble_data` |
| same | `_device_disconnected_callback` | 1295 | [GLUE] | no | Reticulum/driver cleanup. | driver callback | `_compute_identity_hash`, detach scheduling |
| same | `_cleanup_stale_address` | 1380 | [GLUE] | no | MAC rotation mapping cleanup. | duplicate/address-change paths | dict cleanup |
| same | `_address_changed_callback` | 1411 | [GLUE] | no | Driver MAC rotation callback. | driver callback | `_get_fragmenter_key`, `_compute_identity_hash` |
| same | `_error_callback` | 1479 | [GLUE] | no | Driver error logging/blacklisting. | driver callback | `_record_connection_failure` |
| same | `_score_peer` | 1534 | [PLATFORM] | no | BLE RSSI/recency scoring policy. | `_select_peers_to_connect` | `peer.get_success_rate` |
| same | `_select_peers_to_connect` | 1620 | [PLATFORM] | no | BLE connection selection and MAC sorting. | discovery callback | `_score_peer`, `_is_blacklisted` |
| same | `_is_blacklisted` | 1761 | [PLATFORM] | no | BLE retry/backoff policy. | `_select_peers_to_connect` | `time.time` |
| same | `_record_connection_success` | 1785 | [PLATFORM] | no | BLE discovery/backoff state. | connection callback | `DiscoveredPeer.record_connection_success` |
| same | `_record_connection_failure` | 1800 | [PLATFORM] | no | BLE retry/backoff plus BlueZ cleanup hook. | error callback | `driver._remove_bluez_device` |
| same | `_get_fragmenter_key` | 1858 | [CORE] | yes | Pure identity-to-fragment-state key; cleanly separable. | many send/receive paths | `bytes.hex` |
| same | `_compute_identity_hash` | 1871 | [CORE] | yes | Pure identity truncation rule; cleanly separable. | identity mapping paths | `bytes.hex` |
| same | `_spawn_peer_interface` | 1892 | [GLUE] | no | Creates Reticulum `Interface`, mutates `RNS.Transport.interfaces`. | MTU/handshake paths | `BLEPeerInterface`, `RNS.Transport.interfaces.append` |
| same | `_handle_ble_data` | 1957 | [GLUE] | no | Uses core reassembly, but routes into Reticulum peer interfaces. | data callback | `BLEReassembler.receive_fragment`, `peer_if.process_incoming` |
| same | `handle_peripheral_data` | 2085 | [GLUE] | no | Older peripheral data path; handshake/reassembly/RNS routing mixed. | `BLEGATTServer` callback | `BLEFragmenter`, `BLEReassembler`, `_spawn_peer_interface` |
| same | `handle_central_connected` | 2188 | [GLUE] | no | GATT server to RNS interface lifecycle. | `BLEGATTServer` callback | `_spawn_peer_interface` |
| same | `handle_central_disconnected` | 2222 | [GLUE] | no | GATT server cleanup of Reticulum peer mapping. | `BLEGATTServer` callback | `_compute_identity_hash` |
| same | `process_incoming` | 2291 | [GLUE] | no | Calls Reticulum owner inbound. | peer interfaces | `owner.inbound` |
| same | `process_outgoing` | 2305 | [GLUE] | no | Broadcasts Reticulum packet to peer interfaces. | Reticulum Transport | `peer_if.process_outgoing` |
| same | `detach` | 2335 | [GLUE] | no | Reticulum/driver shutdown. | Reticulum | `driver.stop`, `peer_if.detach` |
| same | `should_ingress_limit` | 2365 | [GLUE] | no | Reticulum Interface policy. | Reticulum | none |
| same | `__str__` | 2376 | [TEST] | no | Diagnostic formatting. | logging | none |
| same | `BLEPeerInterface` | 2380 | [GLUE] | no | Reticulum per-peer interface wrapper. | `_spawn_peer_interface` | `Interface` |
| same | `BLEPeerInterface.__init__` | 2388 | [GLUE] | no | Reticulum interface fields/statistics. | `_spawn_peer_interface` | `Interface.__init__` |
| same | `BLEPeerInterface.process_incoming` | 2420 | [GLUE] | no | Hands data to `owner.inbound`. | `_handle_ble_data` | `owner.inbound` |
| same | `BLEPeerInterface.process_outgoing` | 2437 | [GLUE] | no | Calls core fragmenter, then platform driver send. | parent `process_outgoing`, Reticulum | `fragment_packet`, `driver.send` |
| same | `BLEPeerInterface.detach` | 2483 | [GLUE] | no | Removes interface from `RNS.Transport.interfaces`. | cleanup paths | `RNS.Transport.interfaces.remove` |
| same | `BLEPeerInterface.should_ingress_limit` | 2493 | [GLUE] | no | Delegates Reticulum policy. | Reticulum | parent method |
| same | `BLEPeerInterface.connection_id` | 2498 | [GLUE] | no | Reticulum/RNS identity display helper. | Reticulum/status | `RNS.Identity.full_hash` |
| same | `BLEPeerInterface.__str__` | 2510 | [TEST] | no | Diagnostic formatting. | logging | none |

**BLEAgent.py, BLEGATTServer.py, bluetooth_driver.py**

| file path | symbol | line | tag | phase-1 C++ candidate | rationale | important callers | important callees |
|---|---:|---:|---|---|---|---|---|
| `src/ble_reticulum/BLEAgent.py` | `BLEAgent` + all methods | 55 | [PLATFORM] | no | BlueZ DBus pairing agent. | `register_agent`, GATT servers | `dbus.service`, `RNS.log` |
| same | `register_agent` | 202 | [PLATFORM] | no | Registers BlueZ agent on system DBus. | GATT server startup | `DBusGMainLoop`, `dbus.SystemBus` |
| same | `unregister_agent` | 262 | [PLATFORM] | no | Unregisters BlueZ agent. | GATT server shutdown | `dbus.SystemBus` |
| `src/ble_reticulum/BLEGATTServer.py` | `BLEGATTServer` + all methods | 51 | [PLATFORM] | no | bluezero GATT server, threads, callbacks, notifications. | older/alternate peripheral path | `bluezero.peripheral`, `register_agent` |
| same | `set_transport_identity` | 484 | [GLUE] | no | Validates Reticulum identity bytes but serves them over GATT. | startup | none |
| `src/ble_reticulum/bluetooth_driver.py` | `BLEDevice` | 10 | [PLATFORM] | no | BLE discovery DTO. | Linux driver scan | dataclass |
| same | `DriverState` | 18 | [PLATFORM] | no | Driver state enum. | driver state property | enum |
| same | `BLEDriverInterface` + all abstract methods | 29 | [PLATFORM] | no | Platform BLE backend contract, not protocol core. | `BLEInterface` | abstract methods |

**linux_bluetooth_driver.py**

| file path | symbol | line | tag | phase-1 C++ candidate | rationale | important callers | important callees |
|---|---:|---:|---|---|---|---|---|
| `src/ble_reticulum/linux_bluetooth_driver.py` | `_rns_showwarning` | 142 | [GLUE] | no | Routes Python warnings to RNS logging. | `warnings.showwarning` | `RNS.log` |
| same | `apply_bluez_services_resolved_patch` | 220 | [PLATFORM] | no | Monkey-patches Bleak BlueZ manager. | `LinuxBluetoothDriver.__init__` | `BlueZManager._wait_for_services_discovery` |
| same | `PeerConnection` | 287 | [PLATFORM] | no | BLE connection runtime DTO with `BleakClient`. | driver connection state | dataclass |
| same | `LinuxBluetoothDriver` + lifecycle/scanning/connection/GATT methods | 297 | [PLATFORM] | no | Linux BLE backend using Bleak, bluezero, DBus, asyncio, threads. | `BLEInterface` | `BleakScanner`, `BleakClient`, DBus, `BluezeroGATTServer` |
| same | `_connect_to_peer` | 988 | [PLATFORM] | no | Central connection flow, service discovery, GATT reads/writes. | `connect` | `BleakClient`, `_negotiate_mtu`, callbacks |
| same | `_connect_via_dbus_le` | 1253 | [PLATFORM] | no | BlueZ DBus LE-only workaround. | `_connect_to_peer` | `MessageBus`, `Adapter1.ConnectDevice` |
| same | `_negotiate_mtu` | 1291 | [PLATFORM] | no | Bleak/BlueZ MTU probing. | `_connect_to_peer` | `client._backend`, `client.mtu_size` |
| same | `_handle_notification` | 1332 | [PLATFORM] | no | Bleak notification callback adapter. | `start_notify` callback | `on_data_received` |
| same | `BluezeroGATTServer` + all methods | 1578 | [PLATFORM] | no | bluezero peripheral server, DBus monitoring, stale polling. | `LinuxBluetoothDriver.start_advertising` | `bluezero`, DBus, threads |
| same | `_handle_write_rx` | 2328 | [PLATFORM] | no | GATT write callback; forwards bytes upward. | bluezero | driver callbacks |
| same | `_handle_read_identity` | 2374 | [PLATFORM] | no | GATT identity characteristic read. | bluezero | none |
| same | `_handle_central_connected` | 2388 | [PLATFORM] | no | Peripheral connection state plus callbacks. | `_handle_write_rx` | `PeerConnection`, driver callbacks |
| same | `_handle_central_disconnected` | 2430 | [PLATFORM] | no | DBus/poll disconnect cleanup. | DBus monitor, stale poll | driver callback |
| same | `send_notification` | 2479 | [PLATFORM] | no | bluezero notification send. | `LinuxBluetoothDriver.send` | `tx_characteristic.set_value` |

For `linux_bluetooth_driver.py`, the inventory includes many individual platform methods under `LinuxBluetoothDriver` and `BluezeroGATTServer`; all are [PLATFORM]/no for the same reason: they directly touch Bleak, bluezero, DBus, BlueZ, sockets/processes, asyncio event loops, or threads.

**Phase 1 C++ Extraction Candidates**
- `BLEFragmenter`
- `BLEFragmenter.fragment_packet`
- `BLEFragmenter.get_fragment_overhead`
- `BLEReassembler`
- `BLEReassembler.receive_fragment`
- `BLEReassembler.cleanup_stale_buffers`
- `BLEReassembler.get_statistics`
- `BLEReassembler.reset_statistics`
- `HDLCFramer.frame_packet`
- `HDLCFramer.deframe_packet`
- Extracted pure equivalents of `BLEInterface._get_fragmenter_key`
- Extracted pure equivalents of `BLEInterface._compute_identity_hash`

**Do Not Port Yet**
- `BLEInterface` and `BLEPeerInterface` as classes.
- All BlueZ/Bleak/bluezero/DBus code: `BLEAgent`, `BLEGATTServer`, `LinuxBluetoothDriver`, `BluezeroGATTServer`.
- `bluetooth_driver.py` driver abstraction unless designing a cross-language platform backend API later.
- Peer discovery/scoring/backoff/MAC-rotation orchestration in `BLEInterface`; it is BLE transport policy and Reticulum glue, not a clean protocol core.
- `ble_dual_node_echo.py`: treat as acceptance harness, as requested.

**Likely Python/C++ Boundary**
The clean first boundary is a small protocol library that accepts/returns bytes and simple metadata only: fragment packet, parse fragment, reassemble by sender/session key, timeout stale buffers, and compute identity-derived keys. Python should continue owning Reticulum `Interface` integration, `RNS.Transport` mutation, driver callbacks, scanning, advertising, GATT characteristics, DBus pairing, threading, timers, and logging.

**Classification Depends On Reticulum Internals**
- `BLEInterface.__init__`, `start`, `final_init`
- `_start_advertising_when_identity_ready`
- `_clear_stale_ble_paths`
- `_spawn_peer_interface`
- `_handle_ble_data`
- `handle_peripheral_data`
- `process_incoming`
- `process_outgoing`
- `detach`
- `BLEPeerInterface.process_incoming`
- `BLEPeerInterface.detach`
- `BLEPeerInterface.connection_id`

The strongest dependency is `_clear_stale_ble_paths`, which assumes `RNS.Transport.path_table` tuple indexes and BLE interface type names.