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.