@cero-base/core 1.12.0 → 1.14.0

package/src/network/transports/ble.js

@@ -1,1109 +0,0 @@
-import ReadyResource from 'ready-resource'
-import b4a from 'b4a'
-import { hash, randomBytes } from 'hypercore-crypto'
-import safetyCatch from 'safety-catch'
-
-import { GattStream } from './gatt.js'
-import { L2CAPStream, readIdPreamble } from './l2cap.js'
-
-// One data characteristic (write + notify) carries the framed control traffic
-// both ways — and, on the gatt pipe, the data too.
-const DATA_UUID = 'ce1a0004-0000-1000-8000-00805f9b34fb'
-
-// The l2cap open historically hangs forever on some platform pairs (no error,
-// no disconnect) — every open runs under this deadline instead.
-const L2CAP_OPEN_TIMEOUT = 3000
-// a pending server session must see its channel within this window or be reaped
-const PIPE_PENDING_TIMEOUT = 20000
-
-const PLATFORM = typeof Bare !== 'undefined' ? Bare.platform : process.platform
-
-// Wire frame both directions: [type:1][sessionId:8][payload].
-const TYPE_OPEN = 1
-const TYPE_DATA = 2
-const TYPE_CLOSE = 3
-const TYPE_HELLO = 4
-const SID_LEN = 8
-const HEADER = 1 + SID_LEN
-
-const DEFAULT_MAX_OUTBOUND = 4
-const DEFAULT_MAX_INBOUND = 8
-const CONNECT_TIMEOUT = 15000
-// per-peer dial backoff: eager while unlinked, patient once linked; the cooldown
-// grows exponentially per consecutive failure.
-const DIAL_COOLDOWN_BASE = 8000
-const DIAL_COOLDOWN_BASE_LONELY = 2000
-const DIAL_COOLDOWN_MAX = 30000
-// one radio can't usefully dial faster than this
-const DIAL_MIN_INTERVAL = 500
-// iOS reports a peripheral once per scan session; restart to re-report a
-// re-advertised peer.
-const SCAN_RESTART_LONELY = 5000
-// linked: continuous scanning is the dominant battery cost, so duty-cycle it.
-const SCAN_DUTY_ON = 5000
-const SCAN_DUTY_OFF = 25000
-// suspend() drain window: let goodbye frames flush before hanging up.
-const DRAIN_MS = 300
-
-const EMPTY = b4a.alloc(0)
-
-/**
- * Build a wire frame [type][sessionId][payload]. The session id is a hex
- * string end to end — the one canonical form (it is also the sessions map
- * key); the codec is the only place it touches bytes.
- *
- * @param {number} type
- * @param {string} id  Session id (hex).
- * @param {Uint8Array} [payload]
- * @returns {Buffer}
- */
-function frame(type, id, payload = EMPTY) {
-  const out = b4a.allocUnsafe(HEADER + payload.byteLength)
-  out[0] = type
-  b4a.write(out, id, 1, SID_LEN, 'hex')
-  if (payload.byteLength) b4a.copy(payload, out, HEADER)
-  return out
-}
-
-/**
- * Parse a wire frame. Short/empty buffers → null (caller drops).
- *
- * @param {Uint8Array} buf
- * @returns {{ type: number, id: string, payload: Uint8Array } | null}
- */
-function parseFrame(buf) {
-  if (!buf || buf.byteLength < HEADER) return null
-  return {
-    type: buf[0],
-    id: b4a.toString(buf.subarray(1, HEADER), 'hex'),
-    payload: buf.subarray(HEADER)
-  }
-}
-
-/**
- * Derive a stable 128-bit BLE service UUID from a topic. Only devices that
- * compute the same UUID (same channel / same invite) ever discover each other.
- *
- * @param {Uint8Array} topic
- * @param {string} [tag]  Namespace so channel and invite meshes never collide.
- * @returns {string}
- */
-export function toServiceUUID(topic, tag = 'cero-ble') {
-  const h = hash([b4a.from(tag), topic])
-  const hex = b4a.toString(h.subarray(0, 16), 'hex')
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
-}
-
-// Backend adapter state → the app-facing state the facade exposes.
-const STATE = {
-  poweredOn: 'on',
-  poweredOff: 'waiting',
-  unauthorized: 'unauthorized',
-  unsupported: 'unsupported',
-  resetting: 'waiting',
-  unknown: 'waiting'
-}
-
-const uuidEq = (a, b) =>
-  String(a || '')
-    .toLowerCase()
-    .replace(/-/g, '') ===
-  String(b || '')
-    .toLowerCase()
-    .replace(/-/g, '')
-
-const findByUUID = (items, uuid) => (items || []).find((i) => uuidEq(i.uuid, uuid)) || null
-
-/**
- * Dual-role BLE transport: advertises + scans one service UUID, opens a GATT
- * byte-stream to each discovered peer, and feeds it into `network.inject`. From
- * there replication and pairing are transport-agnostic (see Network.inject).
- *
- * The server adds one data characteristic (write + notify) and advertises. The
- * central connects, discovers the characteristic, subscribes, then framed bytes
- * flow both ways — central→server as GATT writes, server→central as
- * notifications — each tagged with an 8-byte session id. `backend` is
- * bare-bluetooth in production and a mock in tests.
- *
- * @extends ReadyResource
- */
-export class BLETransport extends ReadyResource {
-  /**
-   * @param {object} opts
-   * @param {any} opts.backend            bare-bluetooth-shaped module (Central, Server, Service, Characteristic).
-   * @param {import('../index.js').Network} opts.network
-   * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
-   * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
-   * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
-   * @param {number} [opts.maxOutbound]   Max concurrent outbound dials/links; gossip covers the rest.
-   * @param {number} [opts.maxInbound]    Max concurrent inbound sessions; newcomers past this are refused.
-   * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
-   * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
-   * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
-   * @param {'l2cap' | 'gatt'} [opts.pipe]  Data pipe: 'l2cap' (default — a real channel per session, several times faster) or 'gatt' (framed characteristic stream). Both peers must match.
-   * @param {{ timeout?: number }} [opts.l2cap]  Deadline for an l2cap channel open.
-   */
-  constructor({
-    backend,
-    network,
-    uuid,
-    nodeId,
-    tag = 'cero-ble',
-    maxOutbound = DEFAULT_MAX_OUTBOUND,
-    maxInbound = DEFAULT_MAX_INBOUND,
-    scanOptions,
-    keepLinks = false,
-    name,
-    pipe = 'l2cap',
-    l2cap = {}
-  }) {
-    super()
-    this.backend = backend
-    this.network = network
-    this.name = name || ''
-    this.nodeId = nodeId
-    this.nodeHex = b4a.toString(nodeId, 'hex')
-    this.serviceUUID = toServiceUUID(uuid, tag)
-    this.maxOutbound = maxOutbound
-    this.maxInbound = maxInbound
-    this.scanOptions = scanOptions
-    this.keepLinks = keepLinks
-    this.pipe = pipe
-    this._l2capTimeout = l2cap.timeout ?? L2CAP_OPEN_TIMEOUT
-
-    this.state = 'off'
-    this.central = null
-    this.server = null
-    this._dataChar = null
-    /** the published l2cap listener's psm, advertised to centrals over hello */
-    this._psm = null
-    /** id → { id, stream, conn, name, pipeTimer } for server-side (peripheral) sessions */
-    this._sessions = new Map()
-    /** serialized server notify queue: { frame, resolve, reject } */
-    this._notifyQueue = []
-    this._scanning = false
-    this._advertising = false
-    this._serviceAdded = false
-    /** peripheral id → per-peer dial state { timer, linked, coolUntil, failures, peerKey, peripheral } */
-    this._devices = new Map()
-    /** rate-limited discoveries held for the next dial window */
-    this._candidates = new Map()
-    this._dialTimer = null
-    /** last central.connect timestamp — global inter-dial rate limit */
-    this._lastDial = 0
-    this._scanTimer = null
-    this._cyclePending = false
-    this._suspended = false
-    /** live injected links keyed by remote node id hex */
-    this.peers = new Map()
-  }
-
-  /**
-   * Whether we should be the one to open the connection to `peerNodeId`. The
-   * lexicographically smaller id initiates; the larger waits — so a pair
-   * connects once, not twice. Equal (our own reflection) → false.
-   *
-   * @param {Uint8Array} peerNodeId
-   * @returns {boolean}
-   */
-  shouldInitiate(peerNodeId) {
-    return b4a.compare(this.nodeId, peerNodeId) < 0
-  }
-
-  get linkCount() {
-    return this.peers.size
-  }
-
-  _device(id) {
-    let d = this._devices.get(id)
-    if (!d) {
-      d = { timer: null, linked: false, coolUntil: 0, failures: 0, peerKey: null, peripheral: null }
-      this._devices.set(id, d)
-    }
-    return d
-  }
-
-  _prune(id) {
-    const d = this._devices.get(id)
-    if (d && !d.timer && !d.linked && !d.coolUntil && !d.failures && !d.peerKey && !d.peripheral) {
-      this._devices.delete(id)
-    }
-  }
-
-  async _open() {
-    const { Central, Server, Service, Characteristic } = this.backend
-
-    this.server = new Server()
-    this.server.on('stateChange', (s) => {
-      this._onState(s)
-      if (s === 'poweredOn') this._startServer(Service, Characteristic)
-      else if (s === 'poweredOff' || s === 'resetting') this._onRadioDown()
-    })
-    this.server.on('serviceAdd', () => {
-      this._serviceAdded = true
-      this._maybeAdvertise()
-    })
-    this.server.on('writeRequest', (reqs) => this._onWriteRequests(reqs))
-    this.server.on('readyToUpdate', () => this._drainNotify())
-    this.server.on('channelPublish', (psm) => {
-      this._psm = psm
-    })
-    this.server.on('channelOpen', (channel) => this._onServerChannel(channel))
-    // writeRequests carry no central identifier, so an unsubscribe can't be
-    // mapped to a session; teardown is left to _onChannel's keepalive/timeout.
-    this.server.on('unsubscribe', () => {})
-    this.server.on('error', safetyCatch)
-
-    this.central = new Central()
-    this.central.on('stateChange', (s) => {
-      this._onState(s)
-      if (s === 'poweredOn') this._startScan()
-      else if (s === 'poweredOff' || s === 'resetting') this._onRadioDown()
-    })
-    this.central.on('discover', (peripheral) => this._onDiscover(peripheral))
-    this.central.on('connect', (peripheral) => this._onConnect(peripheral))
-    this.central.on('disconnect', () => {})
-    this.central.on('error', (err) => this._onCentralError(err))
-
-    this._startServer(Service, Characteristic)
-    this._startScan()
-    this.state = 'starting'
-  }
-
-  _startServer(Service, Characteristic) {
-    if (this.server.state !== 'poweredOn') return
-    if (!this._serviceAdded) {
-      this._dataChar = new Characteristic(DATA_UUID, { write: true, notify: true })
-      this.server.addService(new Service(this.serviceUUID, [this._dataChar]))
-    }
-    if (this.pipe === 'l2cap') this._publishListener()
-  }
-
-  _publishListener() {
-    if (this._psm !== null || typeof this.server.publishChannel !== 'function') return
-    try {
-      // unencrypted: cero's own protocols provide the crypto; encryption here
-      // would demand BLE pairing and stall centrals that never trigger it
-      this.server.publishChannel({})
-    } catch (err) {
-      safetyCatch(err)
-    }
-  }
-
-  _unpublishListener() {
-    if (this._psm === null) return
-    if (typeof this.server?.unpublishChannel === 'function') {
-      try {
-        this.server.unpublishChannel(this._psm)
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    this._psm = null
-  }
-
-  // Fresh listener, fresh psm — the next hello advertises it. A dead session
-  // leaves its channel state on the shared radio link, and the OS refuses a
-  // second open to a psm it remembers there. Never yank the psm out from under
-  // a session still opening its channel — hold the rotation until the last
-  // pending session resolves (bind or reap).
-  _cycleListener() {
-    if (this.pipe !== 'l2cap' || this._suspended || this.closing || this.closed) return
-    for (const s of this._sessions.values()) {
-      if (s.stream) continue
-      this._cyclePending = true
-      return
-    }
-    this._cyclePending = false
-    this._unpublishListener()
-    this._publishListener()
-  }
-
-  _maybeAdvertise() {
-    if (this._advertising || !this._serviceAdded) return
-    this._advertising = true
-    this.server.startAdvertising({ serviceUUIDs: [this.serviceUUID] })
-  }
-
-  // ─── server (peripheral) side ─────────────────────────────────────────────
-
-  _onWriteRequests(requests) {
-    const ok = this.server.constructor.ATT_SUCCESS ?? 0
-    for (const req of requests) {
-      // must respond within ms or the central times out — before any parsing
-      if (req.responseNeeded !== false) this.server.respondToRequest(req, ok)
-      if (this._suspended) continue
-      this._onServerFrame(req.data)
-    }
-  }
-
-  _onServerFrame(data) {
-    const f = parseFrame(data)
-    if (!f) return
-    // an OPEN for a live session is a dup; every other type needs one
-    const s = this._sessions.get(f.id)
-    if (f.type === TYPE_OPEN) {
-      if (s) return
-      if (this._sessions.size >= this.maxInbound) {
-        // established links win: refuse newcomers with a CLOSE so the dialer's
-        // stream ends cleanly and backs off — the mesh converges transitively.
-        this._notifyClose(f.id)
-        return
-      }
-      const session = { id: f.id, stream: null, conn: null, name: null, pipeTimer: null }
-      this._sessions.set(f.id, session)
-      if (this.pipe === 'l2cap' && this._psm !== null) {
-        // the session has no stream until the central opens our channel and
-        // its id preamble matches — reap it if that never happens
-        session.pipeTimer = setTimeout(() => {
-          session.pipeTimer = null
-          if (this._sessions.get(f.id) !== session || session.stream) return
-          this._reapSession(f.id, session)
-          this._notifyClose(f.id)
-        }, PIPE_PENDING_TIMEOUT)
-        if (session.pipeTimer.unref) session.pipeTimer.unref()
-      } else {
-        this._openServerGatt(session)
-      }
-      this._enqueueNotify(frame(TYPE_HELLO, f.id, this._helloPayload())).catch(safetyCatch)
-    } else if (f.type === TYPE_DATA) {
-      if (!s) return
-      if (!s.stream) {
-        // gatt data on a session awaiting its l2cap channel is a pipe
-        // mismatch — close instead of silently degrading
-        this._closeServerSession(f.id)
-        return
-      }
-      s.stream.receive(b4a.from(f.payload))
-    } else if (f.type === TYPE_HELLO) {
-      if (s) this._applyPeerName(s, f.payload)
-    } else if (f.type === TYPE_CLOSE) {
-      if (!s) return
-      this._reapSession(f.id, s)
-      if (s.stream) s.stream.remoteEnd()
-    }
-  }
-
-  _openServerGatt(session) {
-    const stream = new GattStream({
-      send: (payload) => this._enqueueNotify(frame(TYPE_DATA, session.id, payload))
-    })
-    this._bindServerStream(session, stream)
-  }
-
-  // Incoming l2cap channel: the central writes its 8-byte session id first,
-  // matching the channel to the session negotiated over the characteristic.
-  async _onServerChannel(channel) {
-    if (this.closing || this.closed || this._suspended) {
-      try {
-        channel.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-      return
-    }
-    const { id, rest } = await readIdPreamble(channel, SID_LEN, this._l2capTimeout)
-    const session = id !== null ? this._sessions.get(id) : undefined
-    if (!session || session.stream) {
-      try {
-        channel.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-      return
-    }
-    const stream = new L2CAPStream(channel)
-    this._bindServerStream(session, stream)
-    if (rest.byteLength) stream.receive(rest)
-  }
-
-  // A pipe stream binds here — session wiring and close-time cleanup are
-  // transport concerns shared by both pipes.
-  _bindServerStream(session, stream) {
-    if (session.pipeTimer) clearTimeout(session.pipeTimer)
-    session.pipeTimer = null
-    session.stream = stream
-    stream.on('close', () => this._closeServerSession(session.id))
-    session.conn = this._onChannel(stream, false, null)
-    if (session.name && session.conn) session.conn._peerName = session.name
-    if (this._cyclePending) this._cycleListener()
-  }
-
-  _reapSession(id, session) {
-    if (session.pipeTimer) clearTimeout(session.pipeTimer)
-    session.pipeTimer = null
-    this._sessions.delete(id)
-    this._cycleListener()
-  }
-
-  _closeServerSession(id) {
-    const session = this._sessions.get(id)
-    if (!session) return
-    this._reapSession(id, session)
-    this._notifyClose(id)
-  }
-
-  _notifyClose(id) {
-    this._enqueueNotify(frame(TYPE_CLOSE, id)).catch(safetyCatch)
-  }
-
-  // ─── peer display name (hello frame) ──────────────────────────────────────
-
-  _helloPayload() {
-    const hello = { n: this.name || '' }
-    // servers advertise their l2cap listener so the central can open a channel
-    if (this.pipe === 'l2cap' && this._psm !== null) hello.p = this._psm
-    return b4a.from(JSON.stringify(hello))
-  }
-
-  /**
-   * @param {Uint8Array} payload
-   * @returns {{ name: string, psm: number | null } | null}
-   */
-  _parseHello(payload) {
-    try {
-      const { n, p } = JSON.parse(b4a.toString(payload))
-      return {
-        name: typeof n === 'string' ? n : '',
-        psm: Number.isInteger(p) ? p : null
-      }
-    } catch {
-      return null
-    }
-  }
-
-  _applyPeerName(session, payload) {
-    const hello = this._parseHello(payload)
-    if (hello === null) return
-    session.name = hello.name
-    if (session.conn) session.conn._peerName = hello.name
-    this.emit('update')
-  }
-
-  // Serialize notifications through the single characteristic: updateValue
-  // returns false when the peripheral's queue is full — hold the head frame and
-  // retry on the next 'readyToUpdate', preserving order.
-  _enqueueNotify(f) {
-    return new Promise((resolve, reject) => {
-      this._notifyQueue.push({ frame: f, resolve, reject })
-      this._drainNotify()
-    })
-  }
-
-  _drainNotify() {
-    while (this._notifyQueue.length) {
-      const item = this._notifyQueue[0]
-      let ok
-      try {
-        ok = this.server.updateValue(this._dataChar, item.frame)
-      } catch (err) {
-        this._notifyQueue.shift()
-        item.reject(err)
-        continue
-      }
-      if (!ok) return
-      this._notifyQueue.shift()
-      item.resolve()
-    }
-  }
-
-  _startScan() {
-    if (this._scanning || this.central.state !== 'poweredOn') return
-    this._scanning = true
-    this.central.startScan([this.serviceUUID], this.scanOptions)
-    this._armScanRestart()
-  }
-
-  // Lonely: cycle the scan every SCAN_RESTART_LONELY so a re-advertised peer is
-  // re-reported. Linked: duty-cycle SCAN_DUTY_ON on / SCAN_DUTY_OFF dark to save
-  // battery. One timer drives the whole cycle; the next delay derives from phase.
-  _armScanRestart() {
-    if (this._scanTimer) clearTimeout(this._scanTimer)
-    const delay =
-      this.linkCount > 0 ? (this._scanning ? SCAN_DUTY_ON : SCAN_DUTY_OFF) : SCAN_RESTART_LONELY
-    this._scanTimer = setTimeout(() => {
-      this._scanTimer = null
-      if (this.closing || this.closed || this._suspended) return
-      // never toggle the scan mid-dial (would kill the connect) — defer a phase
-      if (this._isDialing()) {
-        this._armScanRestart()
-        return
-      }
-      if (this.linkCount > 0) {
-        if (this._scanning) {
-          this._stopScan()
-          this._armScanRestart()
-        } else {
-          this._startScan()
-        }
-      } else {
-        this._stopScan()
-        this._startScan()
-      }
-    }, delay)
-    if (this._scanTimer.unref) this._scanTimer.unref()
-  }
-
-  _stopScan() {
-    if (!this._scanning) return
-    this._scanning = false
-    try {
-      this.central.stopScan()
-    } catch (err) {
-      safetyCatch(err)
-    }
-  }
-
-  /**
-   * A radio power cycle invalidates the GATT service, advertising, scans,
-   * subscriptions and every open link, but the bookkeeping flags survive —
-   * without a reset the device never re-registers or re-advertises and goes
-   * dark until the app-level toggle is cycled. Reset so the poweredOn
-   * handlers bootstrap everything from scratch.
-   */
-  _onRadioDown() {
-    this._serviceAdded = false
-    this._advertising = false
-    this._scanning = false
-    // the power cycle wiped the GATT db — the listener is gone with it
-    this._psm = null
-    this._cyclePending = false
-    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
-    this._devices.clear()
-    this._clearCandidates()
-    for (const conn of this.peers.values()) {
-      try {
-        conn.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    for (const { stream, pipeTimer } of this._sessions.values()) {
-      if (pipeTimer) clearTimeout(pipeTimer)
-      try {
-        if (stream) stream.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    this._sessions.clear()
-    for (const item of this._notifyQueue) item.reject(new Error('radio down'))
-    this._notifyQueue = []
-  }
-
-  _onState(raw) {
-    const next = STATE[raw] ?? 'waiting'
-    if (next === this.state) return
-    this.state = next
-    this.emit('update')
-  }
-
-  _onDiscover(peripheral) {
-    if (this.closing || this.closed || this._suspended) return
-    const d = this._devices.get(peripheral.id)
-    if (d) {
-      if (d.linked) return
-      if (d.peerKey && this.peers.has(d.peerKey)) return // linked via another channel
-      if (d.coolUntil > Date.now()) return // failed recently — back off
-      if (d.timer) return // already connecting to this one
-    }
-    if (this.linkCount >= this.maxOutbound) return // gossip covers the rest
-    const wait = DIAL_MIN_INTERVAL - (Date.now() - this._lastDial)
-    if (wait > 0) {
-      // hold rate-limited discoveries (the radio may not re-report them until
-      // the next scan cycle) and dial the strongest signal when the window opens
-      this._candidates.set(peripheral.id, peripheral)
-      if (!this._dialTimer) {
-        this._dialTimer = setTimeout(() => {
-          this._dialTimer = null
-          this._flushCandidates()
-        }, wait)
-        if (this._dialTimer.unref) this._dialTimer.unref()
-      }
-      return
-    }
-    // dial every discovery and open a session; a redundant link is dropped by
-    // _track's dedup
-    this._lastDial = Date.now()
-    const timer = setTimeout(() => this._abortDial(peripheral, 'timeout'), CONNECT_TIMEOUT)
-    this._device(peripheral.id).timer = timer
-    try {
-      this._stopScan()
-      this.central.connect(peripheral)
-    } catch (err) {
-      this._abortDial(peripheral, err)
-    }
-  }
-
-  // strongest signal first — the nearest peer makes the best link. The first
-  // dial re-rate-limits the rest, so each window dials the strongest remaining.
-  _flushCandidates() {
-    const held = [...this._candidates.values()].sort((a, b) => (b.rssi ?? -100) - (a.rssi ?? -100))
-    this._candidates.clear()
-    for (const peripheral of held) this._onDiscover(peripheral)
-  }
-
-  _clearCandidates() {
-    if (this._dialTimer) clearTimeout(this._dialTimer)
-    this._dialTimer = null
-    this._candidates.clear()
-  }
-
-  _onConnect(peripheral) {
-    this._device(peripheral.id).peripheral = peripheral
-    peripheral.on('error', (err) => {
-      // platforms emit benign error events during openL2CAPChannel — aborting
-      // would hang up the link under the in-flight open. The open's own
-      // deadline covers a genuinely dead link.
-      if (peripheral._session?.upgrading) return
-      this._abortDial(peripheral, err?.message ?? 'peripheral-error')
-    })
-    peripheral.once('servicesDiscover', (services) => {
-      const svc = findByUUID(services, this.serviceUUID)
-      if (svc) peripheral.discoverCharacteristics(svc, [DATA_UUID])
-      else this._abortDial(peripheral, 'no-service')
-    })
-    peripheral.once('characteristicsDiscover', (_svc, chars) => {
-      const dataChar = findByUUID(chars, DATA_UUID)
-      if (dataChar) peripheral.subscribe(dataChar)
-      else this._abortDial(peripheral, 'no-data-char')
-    })
-    peripheral.once('notifyState', (char, isNotifying) => {
-      if (!isNotifying) {
-        this._abortDial(peripheral, 'subscribe-failed')
-        return
-      }
-      this._startCentralSession(peripheral, char)
-    })
-    // both sides open a session: on iOS the peer id isn't known until after
-    // connect, so a tie-break yields only post-handshake and deadlocks if the
-    // other side never dials back. _track keeps the first, drops the dup.
-    peripheral.discoverServices([this.serviceUUID])
-  }
-
-  // ─── central side ─────────────────────────────────────────────────────────
-
-  _startCentralSession(peripheral, char) {
-    const id = b4a.toString(randomBytes(SID_LEN), 'hex')
-    peripheral._session = { id, upgrading: false }
-    peripheral._char = char // suspend's goodbye writes reuse it
-    peripheral.on('notify', (_char, data) => this._onCentralNotify(peripheral, data))
-    // open frame first: it registers the session on the server before any data
-    this._centralSend(peripheral, char, frame(TYPE_OPEN, id)).catch(safetyCatch)
-    this._centralSend(peripheral, char, frame(TYPE_HELLO, id, this._helloPayload())).catch(
-      safetyCatch
-    )
-    if (this.pipe === 'l2cap') {
-      // no stream yet — the server's hello carries the psm to open a channel
-      // to; the dial timer keeps running until the channel binds
-      return
-    }
-    this._openCentralGatt(peripheral, peripheral._session)
-  }
-
-  _openCentralGatt(peripheral, sess) {
-    const stream = new GattStream({
-      send: (payload) =>
-        this._centralSend(peripheral, peripheral._char, frame(TYPE_DATA, sess.id, payload))
-    })
-    this._bindCentralStream(peripheral, sess, stream)
-  }
-
-  // A pipe stream binds here — dial state, peripheral refs and close-time
-  // cleanup are transport concerns shared by both pipes.
-  _bindCentralStream(peripheral, sess, stream) {
-    stream.on('close', () => this._closeCentralSession(peripheral, sess))
-    peripheral._stream = stream
-    this._clearDial(peripheral.id)
-    peripheral._conn = this._onChannel(stream, true, peripheral.id)
-    if (peripheral._peerName && peripheral._conn) peripheral._conn._peerName = peripheral._peerName
-  }
-
-  _closeCentralSession(peripheral, sess) {
-    this._centralSend(peripheral, peripheral._char, frame(TYPE_CLOSE, sess.id)).catch(safetyCatch)
-    // platforms reuse peripheral objects across reconnects — stale refs here
-    // would make the next session look live and get dropped
-    peripheral._stream = null
-    peripheral._session = null
-    const d = this._devices.get(peripheral.id)
-    if (d) d.peripheral = null
-    try {
-      this.central.disconnect(peripheral)
-    } catch (err) {
-      safetyCatch(err)
-    }
-  }
-
-  // One open attempt under a deadline; failure aborts the dial and the
-  // cooldown/redial cycle tries again.
-  async _openCentralL2CAP(peripheral, sess, psm) {
-    const gone = () =>
-      peripheral._session !== sess || this.closing || this.closed || this._suspended
-    sess.upgrading = true
-    try {
-      const channel = await this._openChannel(peripheral, psm)
-      if (gone()) {
-        if (channel) {
-          try {
-            channel.destroy()
-          } catch (err) {
-            safetyCatch(err)
-          }
-        }
-        return
-      }
-      if (!channel) {
-        this._abortDial(peripheral, 'l2cap-failed')
-        return
-      }
-      // id preamble first: the server matches the channel to the session
-      channel.write(b4a.from(sess.id, 'hex'))
-      this._bindCentralStream(peripheral, sess, new L2CAPStream(channel))
-    } finally {
-      sess.upgrading = false
-    }
-  }
-
-  _openChannel(peripheral, psm) {
-    return new Promise((resolve) => {
-      let done = false
-      const finish = (channel) => {
-        if (done) {
-          if (channel) {
-            try {
-              channel.destroy()
-            } catch (err) {
-              safetyCatch(err)
-            }
-          }
-          return
-        }
-        done = true
-        clearTimeout(timer)
-        peripheral.removeListener('channelOpen', finish)
-        resolve(channel || null)
-      }
-      const timer = setTimeout(() => finish(null), this._l2capTimeout)
-      if (timer.unref) timer.unref()
-      peripheral.once('channelOpen', finish)
-      try {
-        peripheral.openL2CAPChannel(psm)
-      } catch (err) {
-        safetyCatch(err)
-        finish(null)
-      }
-    })
-  }
-
-  _onCentralNotify(peripheral, data) {
-    const sess = peripheral._session
-    if (!sess) return
-    const f = parseFrame(data)
-    if (!f) return
-    if (f.id !== sess.id) return // not our session
-    if (f.type === TYPE_DATA) {
-      if (peripheral._stream) peripheral._stream.receive(b4a.from(f.payload))
-    } else if (f.type === TYPE_HELLO) {
-      const hello = this._parseHello(f.payload)
-      if (hello === null) return
-      peripheral._peerName = hello.name
-      if (peripheral._conn) peripheral._conn._peerName = hello.name
-      this.emit('update')
-      if (this.pipe === 'l2cap' && !peripheral._stream && !sess.upgrading) {
-        if (hello.psm === null) {
-          // the server has no l2cap listener — pipe mismatch, never degrade
-          this._abortDial(peripheral, 'no-l2cap')
-          return
-        }
-        this._openCentralL2CAP(peripheral, sess, hello.psm).catch(safetyCatch)
-      }
-    } else if (f.type === TYPE_CLOSE) {
-      peripheral._session = null
-      if (peripheral._stream) peripheral._stream.remoteEnd()
-      else this._abortDial(peripheral, 'refused')
-    }
-  }
-
-  // One write in flight per peripheral: chain each write behind the previous,
-  // resolving on the 'write' completion event before the next is issued.
-  _centralSend(peripheral, char, f) {
-    const prev = peripheral._writeChain || Promise.resolve()
-    const next = prev.then(() => this._writeOnce(peripheral, char, f))
-    peripheral._writeChain = next.catch(safetyCatch) // keep the chain alive
-    return next
-  }
-
-  _writeOnce(peripheral, char, f) {
-    return new Promise((resolve, reject) => {
-      const cleanup = () => {
-        peripheral.removeListener('write', onWrite)
-        peripheral.removeListener('error', onErr)
-      }
-      const onWrite = () => {
-        cleanup()
-        resolve()
-      }
-      const onErr = (err) => {
-        cleanup()
-        reject(err)
-      }
-      peripheral.once('write', onWrite)
-      peripheral.once('error', onErr)
-      try {
-        peripheral.write(char, f, true)
-      } catch (err) {
-        cleanup()
-        reject(err)
-      }
-    })
-  }
-
-  _abortDial(peripheral, _reason) {
-    const id = peripheral?.id
-    if (id != null) {
-      const d = this._device(id)
-      d.failures += 1
-      const base = this.linkCount === 0 ? DIAL_COOLDOWN_BASE_LONELY : DIAL_COOLDOWN_BASE
-      d.coolUntil =
-        Date.now() + Math.min(DIAL_COOLDOWN_MAX, base * 2 ** Math.min(4, d.failures - 1))
-      d.peripheral = null
-    }
-    this._clearDial(id)
-    try {
-      this.central.disconnect(peripheral)
-    } catch (err) {
-      safetyCatch(err)
-    }
-    this._startScan()
-  }
-
-  _clearDial(id) {
-    if (id == null) return
-    const d = this._devices.get(id)
-    if (!d) return
-    if (d.timer) clearTimeout(d.timer)
-    d.timer = null
-    this._prune(id)
-  }
-
-  _isDialing() {
-    for (const d of this._devices.values()) if (d.timer) return true
-    return false
-  }
-
-  // iOS & Android report errored connects as 'error' with a code, not
-  // 'disconnect' — without this a failed dial pins the peripheral forever.
-  _onCentralError(err) {
-    safetyCatch(err)
-    const code = err && err.code
-    if (code === 'CONNECTION_FAILED' || code === 'DISCONNECT') {
-      for (const [id, d] of this._devices) if (d.timer) this._clearDial(id)
-    }
-  }
-
-  _onChannel(stream, isInitiator, peripheralId) {
-    if (this.closing || this.closed || this._suspended) {
-      stream.destroy()
-      return
-    }
-    const conn = this.network.inject(stream, { isInitiator })
-    // iOS never signals a disconnect for a vanished peer: keepalive pings and the
-    // timeout are the liveness detector (keepalive refreshes the timeout).
-    conn.setKeepAlive(5000)
-    conn.setTimeout(15000)
-    stream.on('error', safetyCatch)
-    // marked at channel-open (not handshake-open): rediscovery must not dial a
-    // peripheral whose channel is still handshaking
-    if (peripheralId != null) {
-      const d = this._device(peripheralId)
-      d.linked = true
-      d.coolUntil = 0
-      d.failures = 0 // reached a live session — reset backoff
-      conn.once('close', () => {
-        const rec = this._devices.get(peripheralId)
-        if (rec) {
-          rec.linked = false
-          this._prune(peripheralId)
-        }
-      })
-    }
-    conn.on('open', () => this._track(conn, peripheralId, isInitiator))
-    conn.on('close', () => this._untrack(conn))
-    this._startScan()
-    return conn
-  }
-
-  _track(conn, peripheralId, isInitiator) {
-    if (peripheralId != null && conn.remotePublicKey) {
-      this._device(peripheralId).peerKey = b4a.toString(conn.remotePublicKey, 'hex')
-    }
-    if (this.closing || this.closed) return
-    const key = b4a.toString(conn.remotePublicKey, 'hex')
-    const existing = this.peers.get(key)
-    if (existing && existing !== conn) {
-      // Both sides dial, so a pair links twice. Dropping a channel closes it for
-      // BOTH devices, so both must retire the SAME channel. Deterministic winner:
-      // keep the channel whose initiator has the smaller static key — computed
-      // identically on both ends, so the loser drops on both and never cascades.
-      const initiatorIsUsSmaller = b4a.compare(conn.publicKey, conn.remotePublicKey) < 0
-      const preferred = isInitiator === initiatorIsUsSmaller
-      if (!preferred) {
-        conn.destroy()
-        return
-      }
-    }
-    conn._peripheralId = peripheralId
-    conn._peerKey = key
-    this.peers.set(key, conn)
-    if (existing && existing !== conn) existing.destroy() // retire the loser channel
-    this.emit('update')
-  }
-
-  _untrack(conn) {
-    const key = conn._peerKey
-    if (key && this.peers.get(key) === conn) this.peers.delete(key)
-    if (!this.closing && !this.closed) {
-      // last link gone → hunt immediately instead of waiting out a dark window
-      if (this.linkCount === 0 && !this._suspended) this._startScan()
-      this.emit('update')
-    }
-  }
-
-  // Best-effort TYPE_CLOSE to every live session — server sessions over notify,
-  // central sessions over write — then wait up to DRAIN_MS for the frames to
-  // flush. Resolves regardless: suspend must never hang on a wedged radio.
-  async _sayGoodbye() {
-    const sent = []
-    for (const id of this._sessions.keys()) {
-      sent.push(this._enqueueNotify(frame(TYPE_CLOSE, id)).catch(safetyCatch))
-    }
-    for (const d of this._devices.values()) {
-      const peripheral = d.peripheral
-      const sess = peripheral && peripheral._session
-      if (!sess || !peripheral._char) continue
-      const f = frame(TYPE_CLOSE, sess.id)
-      sent.push(this._centralSend(peripheral, peripheral._char, f).catch(safetyCatch))
-    }
-    if (!sent.length) return
-    await Promise.race([Promise.all(sent), new Promise((r) => setTimeout(r, DRAIN_MS))])
-  }
-
-  /**
-   * Pause radio activity but KEEP the Server/Central instances and the
-   * registered GATT service alive — the toggle-friendly counterpart to _close.
-   * CoreBluetooth managers can't be destroy()ed (native double-free), so one
-   * transport is reused across toggles rather than recreated. Idempotent.
-   */
-  async suspend() {
-    this._suspended = true
-    if (this._scanTimer) clearTimeout(this._scanTimer)
-    this._scanTimer = null
-    this._cyclePending = false // suspend tears the sessions down; resume republishes fresh
-    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
-    this._clearCandidates()
-    // say goodbye BEFORE teardown so the remote reacts in <1s instead of waiting
-    // out the 15s keepalive: close frames, a short drain, then an ACL disconnect
-    // (an instant OS-level signal on both roles).
-    await this._sayGoodbye()
-    for (const d of this._devices.values()) {
-      if (!d.peripheral) continue
-      try {
-        this.central.disconnect(d.peripheral)
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    this._devices.clear()
-    try {
-      this._stopScan()
-    } catch (err) {
-      safetyCatch(err)
-    }
-    try {
-      this.server?.stopAdvertising()
-    } catch (err) {
-      safetyCatch(err)
-    }
-    this._advertising = false
-    for (const conn of this.peers.values()) {
-      try {
-        conn.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    this.peers.clear()
-    for (const { stream, pipeTimer } of this._sessions.values()) {
-      if (pipeTimer) clearTimeout(pipeTimer)
-      try {
-        if (stream) stream.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-    this._sessions.clear()
-    for (const item of this._notifyQueue) item.reject(new Error('suspended'))
-    this._notifyQueue = []
-    // macOS only: a listener that lives through destroyed channels wedges the
-    // resumed manager. iOS tolerates no manager surgery — keep its listener.
-    if (PLATFORM === 'darwin') this._unpublishListener()
-    this.state = 'off'
-    this.emit('update')
-  }
-
-  /**
-   * Restart advertising + scanning on the SAME Server/Central. `_serviceAdded`
-   * is still true (the service was never removed) so advertising resumes
-   * immediately. Safe to call repeatedly; no-op once closing/closed.
-   */
-  resume() {
-    this._suspended = false
-    if (this.closing || this.closed) return
-    this._advertising = false
-    if (this.pipe === 'l2cap') this._publishListener()
-    this._maybeAdvertise()
-    this._startScan()
-    const raw = this.central?.state ?? this.server?.state
-    this.state = STATE[raw] ?? 'waiting'
-    this.emit('update')
-  }
-
-  async _close() {
-    if (this._scanTimer) clearTimeout(this._scanTimer)
-    this._scanTimer = null
-    // never call central/server.destroy() — it double-frees in native teardown;
-    // stop advertising/scanning and let the runtime reclaim.
-    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
-    this._devices.clear()
-    this._clearCandidates()
-    try {
-      this.central?.stopScan()
-    } catch (err) {
-      safetyCatch(err)
-    }
-    try {
-      this.server?.stopAdvertising()
-    } catch (err) {
-      safetyCatch(err)
-    }
-    if (!this.keepLinks) {
-      for (const conn of this.peers.values()) {
-        try {
-          conn.destroy()
-        } catch (err) {
-          safetyCatch(err)
-        }
-      }
-      // kept links keep carrying frames through their sessions/notify queue; only
-      // tear this down when we're actually dropping the links
-      for (const item of this._notifyQueue) item.reject(new Error('closed'))
-      this._notifyQueue = []
-      for (const { pipeTimer } of this._sessions.values()) {
-        if (pipeTimer) clearTimeout(pipeTimer)
-      }
-      this._sessions.clear()
-    }
-    this.peers.clear()
-    this.state = 'off'
-  }
-}