Ensure idempotent wrapper identity for CBPeripheral across retrieve / connect paths

[Linqa2]

Description

In real-world multi-device scenarios (automatic reconnects, background operation, periodic retrieval of known devices), the current implementation can end up creating multiple logical wrappers for the same CBPeripheral.identifier. When this happens, delegate ownership may be overwritten, leading to “zombie” sessions where: writes may still succeed, but notifications / delegate callbacks are no longer delivered to the original wrapper.

This issue was surfaced by a real production-like use case involving multiple devices connecting and disconnecting without direct user interaction.

Current behavior

• APIs such as retrieveConnectedPeripherals (and related connect paths) may create a new wrapper for a CBPeripheral even if an existing wrapper for the same identifier is already active.
• Creating a new wrapper can overwrite cbPeripheral.delegate, breaking an existing logical session.
• Repeated retrieval calls are therefore not idempotent and may disrupt active connections.

Desired behavior

• Within a single BluetoothCentral instance, there must be at most one live logical wrapper per CBPeripheral.identifier at any given time.
• Retrieval-style APIs should be idempotent.
• Repeated calls must not create duplicate wrappers for the same peripheral.
• Active sessions must not be disrupted by retrieval or reconnect paths.
• Wrapper identity and delegate ownership should be guaranteed consistently across: scan-based discovery, retrieve APIs, explicit connect flows.

The goal is to address this at the central/identity level, rather than patching individual call sites.

A related PR helped surface this problem in a concrete scenario and is linked here for context: #8

[Linqa2]

Proposed solution

Overview

Address the problem at the BluetoothCentral level by introducing a single identity source for peripheral wrappers.

The core idea is to guarantee that, within a single BluetoothCentral instance, there is at most one live logical wrapper per CBPeripheral.identifier at any given time. All public and internal code paths that produce or operate on a wrapper must respect this invariant.

This makes retrieval-style APIs idempotent and prevents delegate ownership from being unintentionally overwritten.

---

Wrapper identity / deduplication

• BluetoothCentral maintains an internal identity map keyed by CBPeripheral.identifier.
• The identity map stores weak references to existing wrappers, so it does not artificially extend wrapper lifetime.
• A single helper (e.g. getOrCreateWrapper(for:)) is responsible for:
  • returning an existing live wrapper if one already exists for the identifier
  • otherwise creating a new wrapper, registering it, and establishing delegate ownership

This helper becomes the only place where ConnectedPeripheral instances are created.

---

Idempotent retrieval semantics

With wrapper identity guaranteed:

• Retrieval-style APIs (retrieveConnectedPeripherals, related retrieve/connect paths) become idempotent.
• Repeated calls:
  • return existing wrappers when available
  • do not create duplicate logical sessions
  • do not overwrite CBPeripheral.delegate
• Active connections and subscriptions are not disrupted by retrieval or reconnect paths.

---

Scope of change

This approach intentionally avoids patching individual call sites with local filters or guards.

Instead, it establishes a central invariant that applies consistently across:

• scan-based discovery
• retrieve APIs
• explicit connect flows
• reconnect paths

Specific implementation details (e.g. exact caching structure, cleanup strategy) are left flexible, as long as the identity and idempotency guarantees are upheld.

---

Rationale

• The issue is fundamentally about logical identity and ownership, not about a single API.
• CoreBluetooth allows the same physical peripheral to surface through multiple entry points; the wrapper layer must therefore enforce its own identity guarantees.
• A central identity mechanism is simpler to reason about and harder to accidentally bypass than ad-hoc fixes.