feat: diagnose selected PC discovery resolution (#151)

Author: enaboapps

docs/ble-connection-diagnostics.md

@@ -9,14 +9,21 @@ An updated native/development app build from this branch is needed; the installe
 | `ble_probe_connect` | Temporary GATT connection used during discovery |
 | `ble_probe_services` | Service discovery for a status probe |
 | `ble_status_read` | Discovery status-characteristic read |
+| `ble_status_parse` | Decode and parse the status; empty or invalid status fails |
+| `ble_selected_match` | Compare parsed status with the selected PC; `succeeded` or `not_matched` |
+| `ble_resolution` | Find and prepare the selected connection; `started`, `succeeded`, `failed`, or `timed_out` |
 | `ble_connect` | Connection to the selected device |
 | `ble_priority` | Optional Android priority request; failure is nonfatal |
 | `ble_mtu` | Android MTU negotiation |
 | `ble_services` | Service discovery for the control connection |
 | `ble_notifications` | Local notification listener registration, or a listener error |
 | `ble_notification_ready` | Android CCCD read and enabled-value check |
 
-Each stage has `_started`, `_succeeded` and `_failed` outcomes. Listener registration success does not prove that the peripheral enabled notifications; Android checks its descriptor separately. Status-read success records a completed GATT read, not successful parsing. Scan probes can interleave; no device identifiers are included. Stop discovery and make one selected-device attempt for diagnosis.
+Unless noted above, stages have `_started`, `_succeeded` and `_failed` outcomes. Listener registration success does not prove that the peripheral enabled notifications; Android checks its descriptor separately. Status-read success records a completed GATT read, not successful parsing. Scan probes can interleave; no device identifiers are included. Stop discovery and make one selected-device attempt for diagnosis.
+
+Resolution spans both discovery and connection preparation, including priority, MTU and service setup. Its timeout is the overall deadline, not necessarily a missing device. A successful selected match means identity equality, not authentication or completed handoff. Nonmatching candidates are informational and normal when other PCs are nearby. A parse failure after a successful read distinguishes invalid/empty status from a native read failure, but does not expose the rejected value or parsing reason. Cancellation may leave only `ble_resolution_started`; stale operations do not report terminal outcomes into newer attempts.
+
+The S26 beta.22 test showed successful reads but no priority/MTU/notification stages for the selected probe, while the Linux probe recorded no writes or notification channel. Its log had no explicit resolution outcome, so timeout and matching/parsing causes were not distinguishable. These new events require an updated app build; the test does not establish a root cause or completed Linux support.
 
 Cancelled operations cannot later append success/failure into a newer operation. Unsubscribed notification callbacks cannot append stage diagnostics. Cancellation may leave a started entry without an outcome; that is not proof of Bluetooth failure. Native rejection and timeout both count as failure of the relevant stage. Raw errors/codes, addresses, PC names, descriptor values, payloads and credentials are never added to stage diagnostics.
 

src/diagnostics/DiagnosticLog.ts

@@ -9,11 +9,14 @@ const connectionStages = {
   probe_connect: 'Connect for discovery status',
   probe_services: 'Discover status services',
   status_read: 'Read discovery status',
+  status_parse: 'Parse discovery status',
+  selected_match: 'Match discovery status to the selected PC',
+  resolution: 'Resolve and prepare the selected PC connection',
   notifications: 'Register notification listener',
   notification_ready: 'Verify Android notification descriptor',
 } as const;
 export type ConnectionStage = keyof typeof connectionStages;
-export type ConnectionStageOutcome = 'started' | 'succeeded' | 'failed';
+export type ConnectionStageOutcome = 'started' | 'succeeded' | 'failed' | 'not_matched' | 'timed_out';
 
 const messages = {
   scan_started: 'Looking for nearby PCs.',
@@ -46,7 +49,7 @@ export class DiagnosticLog {
   }
   addConnectionStage(stage: ConnectionStage, outcome: ConnectionStageOutcome): void {
     // Only fixed vocabulary crosses this boundary: no native error, address or payload.
-    this.#append(`ble_${stage}_${outcome}`, `${connectionStages[stage]}: ${outcome}.`, outcome === 'failed' ? 'warning' : 'info');
+    this.#append(`ble_${stage}_${outcome}`, `${connectionStages[stage]}: ${outcome}.`, outcome === 'failed' || outcome === 'timed_out' ? 'warning' : 'info');
   }
   #append(code: string, message: string, level: DiagnosticLevel): void {
     this.#entries = [{ id: this.#nextId++, timestamp: Date.now(), level, code, message }, ...this.#entries].slice(0, 200);

src/transport/ReactNativeBleTransport.test.ts

@@ -30,6 +30,65 @@ function manager(overrides: Record<string, unknown> = {}): BleManager {
 }
 
 describe('ReactNativeBleTransport', () => {
+  it.each(['', 'private malformed', '{"protocolVersion":2}', '{"protocolVersion":1,"desktopId":"other-private"}'])('diagnoses rejected or nonmatching status (%s)', async (raw) => {
+    const log = new DiagnosticLog();
+    let callback!: (error: Error | null, value: Device | null) => void;
+    const transport = new ReactNativeBleTransport(manager({ startDeviceScan: jest.fn((_u, _o, cb) => { callback = cb; }) }), 'ios', 100, undefined, log);
+    const result = transport.resolveAndConnect('pc-1');
+    const rejected = expect(result).rejects.toThrow('timed out');
+    await waitFor(() => !!callback);
+    callback(null, device({ readCharacteristicForService: jest.fn(async () => ({ value: fromByteArray(new TextEncoder().encode(raw)) } as Characteristic)) }));
+    await rejected;
+    const codes = log.snapshot().map((entry) => entry.code);
+    expect(codes).toContain(raw.includes('other-private') ? 'ble_selected_match_not_matched' : 'ble_status_parse_failed');
+    expect(codes.filter((code) => code === 'ble_resolution_timed_out')).toHaveLength(1);
+    expect(codes).not.toContain('ble_resolution_succeeded');
+    expect(log.export()).not.toMatch(/private|pc-1/);
+    const before = log.export();
+    callback(null, device());
+    await Promise.resolve();
+    expect(log.export()).toBe(before);
+    await transport.disconnect();
+  });
+
+  it('records a matching handoff even with throwing diagnostic observers', async () => {
+    const log = new DiagnosticLog();
+    log.subscribe(() => { throw new Error('observer'); });
+    let callback!: (error: Error | null, value: Device | null) => void;
+    const transport = new ReactNativeBleTransport(manager({ startDeviceScan: jest.fn((_u, _o, cb) => { callback = cb; }) }), 'android', 1000, undefined, log);
+    const result = transport.resolveAndConnect('pc-1');
+    await waitFor(() => !!callback);
+    callback(null, device());
+    await result;
+    const codes = log.snapshot().map((entry) => entry.code);
+    expect(codes).toContain('ble_status_parse_succeeded');
+    expect(codes).toContain('ble_selected_match_succeeded');
+    expect(codes[0]).toBe('ble_resolution_succeeded');
+    await transport.disconnect();
+  });
+
+  it('does not report cancelled resolution as a timeout or failure', async () => {
+    const log = new DiagnosticLog();
+    let callback!: (error: Error | null, value: Device | null) => void;
+    const transport = new ReactNativeBleTransport(manager({ startDeviceScan: jest.fn((_u, _o, cb) => { callback = cb; }) }), 'ios', 1000, undefined, log);
+    const result = transport.resolveAndConnect('pc-1');
+    const rejected = expect(result).rejects.toThrow('cancelled');
+    await waitFor(() => !!callback);
+    await transport.disconnect();
+    await rejected;
+    callback(null, device());
+    await Promise.resolve();
+    expect(log.snapshot().map((entry) => entry.code)).toEqual(['ble_resolution_started']);
+  });
+
+  it('records scan startup failure without native error details', async () => {
+    const log = new DiagnosticLog();
+    const transport = new ReactNativeBleTransport(manager({ startDeviceScan: jest.fn(() => { throw new Error('private'); }) }), 'ios', 100, undefined, log);
+    await expect(transport.resolveAndConnect('pc-1')).rejects.toThrow('discovery failed');
+    expect(log.snapshot().map((entry) => entry.code)).toEqual(['ble_resolution_failed', 'ble_resolution_started']);
+    expect(log.export()).not.toContain('private');
+    await transport.disconnect();
+  });
   it('records discovery status separately from the selected-PC connection', async () => {
     const log = new DiagnosticLog();
     let scanCallback!: (error: Error | null, value: Device | null) => void;
@@ -43,6 +102,7 @@ describe('ReactNativeBleTransport', () => {
       'ble_probe_connect_started', 'ble_probe_connect_succeeded',
       'ble_probe_services_started', 'ble_probe_services_succeeded',
       'ble_status_read_started', 'ble_status_read_succeeded',
+      'ble_status_parse_started', 'ble_status_parse_succeeded',
     ]);
     stop();
   });

src/transport/ReactNativeBleTransport.ts

@@ -92,21 +92,24 @@ export class ReactNativeBleTransport implements BleTransport {
   async resolveAndConnect(desktopId: string): Promise<DiscoveredDesktop> {
     await this.disconnect();
     const operation = ++this.#operation;
+    this.#recordStage('resolution', 'started', operation);
     return new Promise<DiscoveredDesktop>((resolve, reject) => {
       let active = true;
       let claimedDeviceId: string | null = null;
       let cancellation: Promise<void> | null = null;
       const succeed = (desktop: DiscoveredDesktop) => {
         if (!active) return;
+        this.#recordStage('resolution', 'succeeded', operation);
         active = false;
         clearTimeout(timer);
         this.#managerOrCreate().stopDeviceScan();
         this.#scanKeys.clear();
         if (this.#resolutionCancel === cancel) this.#resolutionCancel = null;
         resolve(desktop);
       };
-      const cancel = (error: Error): Promise<void> => {
+      const cancel = (error: Error, outcome: 'failed' | 'timed_out' = 'failed'): Promise<void> => {
         if (!active) return cancellation ?? Promise.resolve();
+        this.#recordStage('resolution', outcome, operation);
         active = false;
         clearTimeout(timer);
         this.#managerOrCreate().stopDeviceScan();
@@ -127,14 +130,16 @@ export class ReactNativeBleTransport implements BleTransport {
         return cancellation;
       };
       this.#resolutionCancel = cancel;
-      const timer = setTimeout(() => { void cancel(new Error('Saved PC discovery timed out.')); }, this.nativeTimeoutMs);
+      const timer = setTimeout(() => { void cancel(new Error('Saved PC discovery timed out.'), 'timed_out'); }, this.nativeTimeoutMs);
       const onAdvertisement = (error: Error | null, device: Device | null) => {
         if (!active || operation !== this.#operation) return;
         if (error) { void cancel(new Error('Saved PC discovery failed.')); return; }
         if (!device || this.#scanDevices.has(device.id) || this.#scanKeys.has(this.#scanKey(device)) || this.#scanDevices.size >= 4) return;
         this.#scanDevices.set(device.id, device);
         this.#scanKeys.add(this.#scanKey(device));
         const task = this.#readStatus(device, (desktop) => {
+          if (!active || operation !== this.#operation) return false;
+          this.#recordStage('selected_match', desktop.desktopId === desktopId ? 'succeeded' : 'not_matched', operation);
           if (desktop.desktopId !== desktopId || claimedDeviceId !== null) return false;
           claimedDeviceId = device.id;
           return true;
@@ -347,9 +352,15 @@ export class ReactNativeBleTransport implements BleTransport {
       }
       await this.#stage('probe_services', () => this.#bounded(target.discoverAllServicesAndCharacteristics()), operation);
       const characteristic = await this.#stage('status_read', () => this.#bounded(target.readCharacteristicForService(BLE_UUIDS.service, BLE_UUIDS.status)), operation);
-      if (!characteristic.value) return null;
-      const raw = new TextDecoder().decode(toByteArray(characteristic.value));
-      const status = parseStatus(raw);
+      this.#recordStage('status_parse', 'started', operation);
+      let status;
+      try {
+        status = characteristic.value ? parseStatus(new TextDecoder().decode(toByteArray(characteristic.value))) : null;
+      } catch (error) {
+        this.#recordStage('status_parse', 'failed', operation);
+        throw error;
+      }
+      this.#recordStage('status_parse', status ? 'succeeded' : 'failed', operation);
       const desktop = status ? {
         ...status,
         displayName: desktopDisplayName(status, { name: device.name, localName: device.localName }, this.platform),