bitchat-android/docs/device-transport-test-matrix.md

# Physical transport validation matrix

This is the device-only companion to the deterministic Milestone 4 transport
suite. It validates that the fake adapters, Robolectric behavior, and pure
state machines match Android framework behavior. It is also consumed by the
Milestone 10 release gate.

## Required device set

- Two physical Android devices from different manufacturers.
- At least one Android 13+ device for `NEARBY_WIFI_DEVICES`.
- At least one device that supports Wi-Fi Aware.
- Bluetooth LE central and peripheral support on both devices.
- A build from the exact commit under test installed on both devices.
- Clean app data before the first run; retain a second run for restart tests.

Record device models, API levels, build commit, negotiated MTUs, and timestamps
in the release artifact. Do not record user names, device serials, Bluetooth
addresses, IP addresses, peer IDs, message contents, or other identifying
values.

## BLE discovery and recovery

- [ ] Start both clients and confirm each begins scanning and advertising.
- [ ] Stop and restart the foreground service; confirm exactly one scanner and
  advertiser generation remains active.
- [ ] Toggle Bluetooth off during scanning, then on; confirm scanning,
  advertising, announcements, and peer discovery recover without process
  restart.
- [ ] Disable and re-enable the BLE debug transport; confirm the same service
  instance can recover without duplicate callbacks.
- [ ] Rotate the observed BLE address by restarting advertising; confirm the
  canonical peer remains singular.
- [ ] Trigger a transient scan failure or Android Bluetooth process restart;
  confirm bounded retry and watchdog recovery.
- [ ] Confirm permission denial reports unavailable state without a crash,
  prompt loop, or active radio work.

## GATT setup and teardown

- [ ] Connect in both directions simultaneously and confirm one canonical link
  survives.
- [ ] Record the negotiated MTU and repeat at 23, 247, and 517 where the device
  or test peripheral allows it.
- [ ] Remove the service, characteristic, or CCCD in a test peripheral and
  confirm setup fails closed.
- [ ] Reject notification registration and descriptor writes; confirm the peer
  is never published ready.
- [ ] Disconnect during MTU negotiation, service discovery, subscription,
  client write, and server notification; confirm no stale ready callback.
- [ ] Leave setup incomplete for more than 30 seconds; confirm timeout and
  resource closure.
- [ ] Connect beyond configured client, server, and total limits; confirm
  deterministic oldest-link eviction.

## Packet delivery and fragmentation

- [ ] Send directed and broadcast packets over client and server roles.
- [ ] Saturate each link faster than radio completion callbacks; confirm one
  outstanding operation, bounded backpressure, and no reordered frames.
- [ ] Inject a failed `onCharacteristicWrite` and `onNotificationSent`; confirm
  queued work is discarded and the failed generation is cleaned up.
- [ ] Transfer payloads immediately below and above the fragmentation boundary.
- [ ] Transfer a maximum admitted private-media payload at negotiated MTU 517.
- [ ] At MTU 247 and 23, confirm oversized frames are rejected rather than
  partially sent. Adaptive per-link fragmentation remains tracked as
  `TDB-023`.
- [ ] Disconnect and reconnect halfway through a fragmented transfer; confirm
  incomplete state expires and a fresh transfer can finish.
- [ ] Cancel a queued transfer and stop the service during another; confirm no
  later fragments or progress callbacks.

## Wi-Fi Aware

- [ ] Confirm unsupported hardware and temporarily unavailable radio states are
  distinct.
- [ ] Deny and grant `NEARBY_WIFI_DEVICES`; confirm publish/subscribe work only
  after grant.
- [ ] Start and stop publish and subscribe sessions repeatedly; confirm no
  duplicate discovery callbacks.
- [ ] Authenticate a provisional socket and promote it to the canonical peer.
- [ ] Replace a socket while authentication is in flight; confirm the stale
  socket cannot promote or deliver.
- [ ] Toggle Wi-Fi, location, and airplane mode; confirm rediscovery and bounded
  reconnect after availability returns.
- [ ] Stop the service with active sockets, server sockets, and network
  callbacks; confirm all are closed or unregistered.

## Unified transport and failover

- [ ] Connect the same peer over BLE and Wi-Fi Aware; confirm one peer-list row.
- [ ] Send with both transports active; confirm the preferred transport is used.
- [ ] Drop the preferred transport during a transfer and confirm defined
  failover behavior without duplicate application delivery.
- [ ] Relay between transports and confirm TTL decreases once per hop.
- [ ] Reflect a bridged packet back over the other transport; confirm loop and
  duplicate suppression.
- [ ] Stop the foreground service; confirm scans, advertisements, sessions,
  sockets, operation queues, transfer jobs, and callbacks all terminate.

## Evidence template

| Field | Value |
|---|---|
| Commit | |
| Device/API classes | |
| BLE central/peripheral | Pass / Fail |
| MTU cases | Pass / Fail / Unsupported |
| BLE recovery | Pass / Fail |
| Wi-Fi Aware lifecycle | Pass / Fail / Unsupported |
| Cross-transport failover | Pass / Fail |
| Shutdown leak check | Pass / Fail |
| Bugs filed | |