fix: BLE architecture review fixes and documentation

[torlando-tech]

Summary

Fixes and documentation improvements discovered during meticulous review of BLE architecture diagrams against source code.

Bug Fixes

• Duplicate identity check in peripheral mode: _handle_identity_handshake now calls _check_duplicate_identity before accepting connections, preventing the same identity from connecting via two MACs simultaneously
• Blacklist bypass for duplicate rejections: When rejecting duplicate identity connections, use "info" severity with safe message format that doesn't trigger the connection blacklist

Documentation

• Identity cache race condition: Added comment documenting the narrow race window where data could arrive from an old MAC before onAddressChanged callback invalidates the cache
• Collision risk documentation: Expanded _compute_identity_hash docstring to explain truncated 64-bit keys and birthday collision risk (astronomically safe for BLE mesh networks)

Test plan

• Existing tests pass
• New tests added for peripheral mode duplicate rejection
• New tests added for MAC rotation blacklist behavior

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.75000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/ble_reticulum/BLEInterface.py	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Fixes critical bugs in MAC rotation handling and adds comprehensive documentation.

Bug Fixes:

• Peripheral mode duplicate identity check: _handle_identity_handshake now calls _check_duplicate_identity before accepting connections (src/ble_reticulum/BLEInterface.py:1137-1149), preventing simultaneous connections from the same identity via different MACs during rotation
• Blacklist bypass fix: Driver now uses severity "info" with safe message format "Duplicate identity rejected for {address} (MAC rotation)" that doesn't match the blacklist regex pattern (?:Connection (?:failed|timeout) to|to) (src/ble_reticulum/linux_bluetooth_driver.py:1208-1240), preventing incorrect blacklisting during legitimate MAC rotation

Documentation Improvements:

• Identity cache race condition: Documents narrow race window where data from old MAC could arrive before onAddressChanged callback fires (src/ble_reticulum/BLEInterface.py:1897-1901)
• Collision risk analysis: Expanded _compute_identity_hash docstring explaining 64-bit truncated hash birthday collision risk (~2^32 identities) and safety margin for BLE mesh networks (src/ble_reticulum/BLEInterface.py:1796-1801)

Test Coverage:

• Comprehensive test suite (455 lines) validates both bug fixes and documents expected behavior with clear test names and extensive inline documentation

Confidence Score: 5/5

• Safe to merge - well-tested fixes for race conditions in MAC rotation handling with excellent documentation
• The changes are surgical and well-understood: adds missing duplicate check in peripheral mode (mirrors existing central mode logic), fixes blacklist bypass with simple message format change, and adds documentation for edge cases. Comprehensive 455-line test suite validates both fixes. No breaking changes or risky refactoring.
• No files require special attention

Important Files Changed

Filename	Overview
src/ble_reticulum/BLEInterface.py	Added duplicate identity check to peripheral mode handshake and documented collision risks in identity hash computation and potential race condition in identity cache
src/ble_reticulum/linux_bluetooth_driver.py	Fixed blacklist bypass by using safe message format (severity "info" with "Duplicate identity rejected for") that doesn't match blacklist regex
tests/test_mac_rotation_blacklist_bug.py	Comprehensive test suite verifying duplicate identity rejection doesn't trigger blacklist and validates both central and peripheral mode behavior

Sequence Diagram

sequenceDiagram
    participant Central as Central Device<br/>(MAC_NEW)
    participant Peripheral as Peripheral Device
    participant Check as _check_duplicate_identity
    participant Driver as linux_bluetooth_driver
    participant ErrorCB as _error_callback
    participant Blacklist as Blacklist Mechanism

    Note over Central,Peripheral: Scenario: MAC Rotation During Active Connection
    Note over Peripheral: MAC_OLD already connected<br/>with identity X

    Central->>Driver: connect(MAC_NEW)
    Driver->>Peripheral: GATT connect
    Driver->>Peripheral: Read identity characteristic
    Peripheral-->>Driver: identity X (16 bytes)
    Driver->>Check: on_duplicate_identity_detected(MAC_NEW, identity X)
    Check->>Check: identity_to_address[hash(X)] == MAC_OLD
    Check-->>Driver: True (duplicate detected)
    
    Note over Driver: Central mode: Raise exception
    Driver->>Driver: disconnect client
    Driver->>Driver: raise RuntimeError("Duplicate identity...")
    
    Driver->>Driver: except Exception as e:<br/>is_duplicate = "Duplicate identity" in str(e)
    
    alt Duplicate Identity (AFTER FIX)
        Driver->>ErrorCB: on_error("info", "Duplicate identity rejected for MAC_NEW", e)
        Note over ErrorCB: severity="info" → should_blacklist=False
        Note over Blacklist: NO blacklist triggered ✓
    else Real Connection Failure
        Driver->>ErrorCB: on_error("error", "Connection failed to MAC_X", e)
        Note over ErrorCB: severity="error" → should_blacklist=True
        ErrorCB->>Blacklist: _record_connection_failure(MAC_X)
        Note over Blacklist: Blacklist after 3 failures ✓
    end

    Note over Central,Peripheral: Scenario: Peripheral Mode Duplicate Identity

    Central->>Peripheral: GATT connect (MAC_NEW)
    Central->>Peripheral: Write identity X to handshake characteristic
    Peripheral->>Peripheral: _handle_identity_handshake(MAC_NEW, identity X)
    Peripheral->>Check: _check_duplicate_identity(MAC_NEW, identity X)
    Check->>Check: identity_to_address[hash(X)] == MAC_OLD
    Check-->>Peripheral: True (duplicate detected)
    
    Note over Peripheral: Peripheral mode (AFTER FIX):<br/>Check before accepting connection
    Peripheral->>Peripheral: driver.disconnect(MAC_NEW)
    Peripheral->>Peripheral: return True (consumed, rejected)
    Note over Peripheral: Connection rejected,<br/>no blacklist triggered ✓

Loading