@cero-base/core 1.9.0 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,
@@ -144,15 +144,15 @@
   },
   "dependencies": {
     "@hyperswarm/secret-stream": "^6.9.1",
-    "autobee": "1.0.10",
+    "autobee": "2.0.0-rc.6",
     "autobee-encryption": "0.1.3",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.15.3",
-    "bare-fs": "^4.7.4",
+    "bare-fs": "^4.8.0",
     "bare-path": "^3.1.1",
     "bip39-mnemonic": "^2.5.0",
     "blind-pairing": "^2.3.1",
-    "blind-peering": "^2.5.3",
+    "blind-peering": "^2.6.1",
     "compact-encoding": "^3.3.0",
     "corestore": "^7.12.0",
     "framed-stream": "^1.0.1",
@@ -181,8 +181,8 @@
     "bare-events": "^2.9.1",
     "bare-fetch": "^3.2.0",
     "bare-process": "^4.5.1",
-    "bare-url": "^2.4.6",
-    "blind-peer": "^3.12.5",
+    "bare-url": "^2.5.2",
+    "blind-peer": "^3.13.2",
     "brittle": "^4.1.0",
     "typescript": "^5.9.3",
     "which-runtime": "^1.4.0"

package/src/database/encryption.js

@@ -238,6 +238,11 @@ export class EpochAutobee extends Autobee {
   // step so an UNKNOWN_EPOCH surfacing from batch processing parks too
   // instead of crashing the bee.
   async _bumpPendingWriters() {
+    if (this._catchupMigratedNodes !== null) {
+      await this._bumpMigratedWriters()
+      this._catchupMigratedNodes = null
+    }
+
     let updated = false
 
     const pending = this.writers.pending.slice()

package/src/network/transports/ble.js

@@ -4,12 +4,20 @@ import { hash, randomBytes } from 'hypercore-crypto'
 import safetyCatch from 'safety-catch'
 
 import { GattStream } from './gatt.js'
+import { L2CAPStream, readIdPreamble } from './l2cap.js'
 
-// iOS never answers an L2CAP channel opened by a Mac central and gives no L2CAP
-// disconnect signal, so one data characteristic (write + notify) carries a
-// framed byte stream both ways instead.
+// 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
@@ -40,17 +48,19 @@ const DRAIN_MS = 300
 const EMPTY = b4a.alloc(0)
 
 /**
- * Build a wire frame [type][sessionId][payload].
+ * 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 {Uint8Array} sid  8-byte session id.
+ * @param {string} id  Session id (hex).
  * @param {Uint8Array} [payload]
  * @returns {Buffer}
  */
-function frame(type, sid, payload = EMPTY) {
+function frame(type, id, payload = EMPTY) {
   const out = b4a.allocUnsafe(HEADER + payload.byteLength)
   out[0] = type
-  b4a.copy(sid, out, 1)
+  b4a.write(out, id, 1, SID_LEN, 'hex')
   if (payload.byteLength) b4a.copy(payload, out, HEADER)
   return out
 }
@@ -59,15 +69,13 @@ function frame(type, sid, payload = EMPTY) {
  * Parse a wire frame. Short/empty buffers → null (caller drops).
  *
  * @param {Uint8Array} buf
- * @returns {{ type: number, sid: Uint8Array, sidHex: string, payload: Uint8Array } | null}
+ * @returns {{ type: number, id: string, payload: Uint8Array } | null}
  */
 function parseFrame(buf) {
   if (!buf || buf.byteLength < HEADER) return null
-  const sid = buf.subarray(1, HEADER)
   return {
     type: buf[0],
-    sid,
-    sidHex: b4a.toString(sid, 'hex'),
+    id: b4a.toString(buf.subarray(1, HEADER), 'hex'),
     payload: buf.subarray(HEADER)
   }
 }
@@ -132,6 +140,8 @@ export class BLETransport extends ReadyResource {
    * @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,
@@ -143,7 +153,9 @@ export class BLETransport extends ReadyResource {
     maxInbound = DEFAULT_MAX_INBOUND,
     scanOptions,
     keepLinks = false,
-    name
+    name,
+    pipe = 'l2cap',
+    l2cap = {}
   }) {
     super()
     this.backend = backend
@@ -156,12 +168,16 @@ export class BLETransport extends ReadyResource {
     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
-    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    /** 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 = []
@@ -170,9 +186,13 @@ export class BLETransport extends ReadyResource {
     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()
@@ -217,6 +237,7 @@ export class BLETransport extends ReadyResource {
     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
@@ -224,6 +245,10 @@ export class BLETransport extends ReadyResource {
     })
     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', () => {})
@@ -233,6 +258,7 @@ export class BLETransport extends ReadyResource {
     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))
@@ -250,6 +276,47 @@ export class BLETransport extends ReadyResource {
       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() {
@@ -273,64 +340,143 @@ export class BLETransport extends ReadyResource {
   _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 (this._sessions.has(f.sidHex)) return
+      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._enqueueNotify(frame(TYPE_CLOSE, f.sid)).catch(safetyCatch)
+        this._notifyClose(f.id)
         return
       }
-      const sid = b4a.from(f.sid) // copy: f.sid views the transient request buffer
-      const stream = new GattStream({
-        send: (payload) => this._enqueueNotify(frame(TYPE_DATA, sid, payload)),
-        onclose: () => this._closeServerSession(f.sidHex, sid)
-      })
-      const session = { stream, sid, conn: null, name: null }
-      this._sessions.set(f.sidHex, session)
-      session.conn = this._onChannel(stream, false, null)
-      this._enqueueNotify(frame(TYPE_HELLO, sid, this._helloPayload())).catch(safetyCatch)
+      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) {
-      const s = this._sessions.get(f.sidHex)
-      if (s) s.stream.receive(b4a.from(f.payload))
+      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) {
-      const s = this._sessions.get(f.sidHex)
       if (s) this._applyPeerName(s, f.payload)
     } else if (f.type === TYPE_CLOSE) {
-      const s = this._sessions.get(f.sidHex)
-      if (s) {
-        this._sessions.delete(f.sidHex)
-        s.stream.remoteEnd()
+      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)
   }
 
-  _closeServerSession(sidHex, sid) {
-    if (!this._sessions.has(sidHex)) return
-    this._sessions.delete(sidHex)
-    this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch)
+  _notifyClose(id) {
+    this._enqueueNotify(frame(TYPE_CLOSE, id)).catch(safetyCatch)
   }
 
   // ─── peer display name (hello frame) ──────────────────────────────────────
 
   _helloPayload() {
-    return b4a.from(JSON.stringify({ n: this.name || '' }))
+    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 } = JSON.parse(b4a.toString(payload))
-      return typeof n === 'string' ? n : ''
+      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 name = this._parseHello(payload)
-    if (name === null) return
-    session.name = name
-    if (session.conn) session.conn._peerName = name
+    const hello = this._parseHello(payload)
+    if (hello === null) return
+    session.name = hello.name
+    if (session.conn) session.conn._peerName = hello.name
     this.emit('update')
   }
 
@@ -408,6 +554,43 @@ export class BLETransport extends ReadyResource {
     }
   }
 
+  /**
+   * 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
@@ -425,7 +608,20 @@ export class BLETransport extends ReadyResource {
       if (d.timer) return // already connecting to this one
     }
     if (this.linkCount >= this.maxOutbound) return // gossip covers the rest
-    if (Date.now() - this._lastDial < DIAL_MIN_INTERVAL) return
+    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()
@@ -439,9 +635,29 @@ export class BLETransport extends ReadyResource {
     }
   }
 
+  // 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', () => this._abortDial(peripheral, 'peripheral-error'))
+    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])
@@ -468,50 +684,143 @@ export class BLETransport extends ReadyResource {
   // ─── central side ─────────────────────────────────────────────────────────
 
   _startCentralSession(peripheral, char) {
-    const sid = randomBytes(SID_LEN)
-    const sidHex = b4a.toString(sid, 'hex')
-    peripheral._session = { sidHex, sid }
+    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))
-    const stream = new GattStream({
-      send: (payload) => this._centralSend(peripheral, char, frame(TYPE_DATA, sid, payload)),
-      onclose: () => {
-        this._centralSend(peripheral, char, frame(TYPE_CLOSE, sid)).catch(safetyCatch)
-        const d = this._devices.get(peripheral.id)
-        if (d) d.peripheral = null
-        try {
-          this.central.disconnect(peripheral)
-        } catch (err) {
-          safetyCatch(err)
-        }
-      }
-    })
-    peripheral._stream = stream
     // open frame first: it registers the session on the server before any data
-    this._centralSend(peripheral, char, frame(TYPE_OPEN, sid)).catch(safetyCatch)
-    this._centralSend(peripheral, char, frame(TYPE_HELLO, sid, this._helloPayload())).catch(
+    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 || !peripheral._stream) return
+    if (!sess) return
     const f = parseFrame(data)
     if (!f) return
-    if (f.sidHex !== sess.sidHex) return // not our session
-    if (f.type === TYPE_DATA) peripheral._stream.receive(b4a.from(f.payload))
-    else if (f.type === TYPE_HELLO) {
-      const name = this._parseHello(f.payload)
-      if (name === null) return
-      peripheral._peerName = name
-      if (peripheral._conn) peripheral._conn._peerName = name
+    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
-      peripheral._stream.remoteEnd()
+      if (peripheral._stream) peripheral._stream.remoteEnd()
+      else this._abortDial(peripheral, 'refused')
     }
   }
 
@@ -665,14 +974,14 @@ export class BLETransport extends ReadyResource {
   // flush. Resolves regardless: suspend must never hang on a wedged radio.
   async _sayGoodbye() {
     const sent = []
-    for (const { sid } of this._sessions.values()) {
-      sent.push(this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch))
+    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.sid)
+      const f = frame(TYPE_CLOSE, sess.id)
       sent.push(this._centralSend(peripheral, peripheral._char, f).catch(safetyCatch))
     }
     if (!sent.length) return
@@ -689,7 +998,9 @@ export class BLETransport extends ReadyResource {
     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).
@@ -722,9 +1033,10 @@ export class BLETransport extends ReadyResource {
       }
     }
     this.peers.clear()
-    for (const { stream } of this._sessions.values()) {
+    for (const { stream, pipeTimer } of this._sessions.values()) {
+      if (pipeTimer) clearTimeout(pipeTimer)
       try {
-        stream.destroy()
+        if (stream) stream.destroy()
       } catch (err) {
         safetyCatch(err)
       }
@@ -732,6 +1044,9 @@ export class BLETransport extends ReadyResource {
     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')
   }
@@ -745,6 +1060,7 @@ export class BLETransport extends ReadyResource {
     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
@@ -759,6 +1075,7 @@ export class BLETransport extends ReadyResource {
     // 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) {
@@ -781,6 +1098,9 @@ export class BLETransport extends ReadyResource {
       // 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()

package/src/network/transports/gatt.js

@@ -15,12 +15,10 @@ export class GattStream extends Duplex {
   /**
    * @param {object} opts
    * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
-   * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
    */
-  constructor({ send, onclose } = {}) {
+  constructor({ send } = {}) {
     super()
     this._send = send
-    this._onclose = onclose || null
   }
 
   async _write(chunk, cb) {
@@ -41,17 +39,4 @@ export class GattStream extends Duplex {
   remoteEnd() {
     this.push(null)
   }
-
-  _destroy(cb) {
-    const onclose = this._onclose
-    this._onclose = null
-    if (onclose) {
-      try {
-        onclose()
-      } catch {
-        // teardown is best-effort
-      }
-    }
-    cb(null)
-  }
 }

package/src/network/transports/l2cap.js

@@ -0,0 +1,90 @@
+import { Duplex } from 'streamx'
+import b4a from 'b4a'
+
+/**
+ * Byte pipe over an L2CAP channel — the GattStream-shaped wrapper so
+ * BLETransport can treat both pipes identically. The channel is already a
+ * reliable ordered duplex with credit-based flow control, so no framing or
+ * fragmentation is needed.
+ *
+ * @extends Duplex
+ */
+export class L2CAPStream extends Duplex {
+  /**
+   * @param {any} channel  bare-bluetooth L2CAPChannel (a duplex).
+   */
+  constructor(channel) {
+    super()
+    this.channel = channel
+
+    channel.on('data', (data) => {
+      // propagate read backpressure: hold the channel while our buffer is full
+      if (!this.push(b4a.from(data))) channel.pause()
+    })
+    channel.on('end', () => this.push(null))
+    channel.on('error', () => this.destroy())
+    channel.on('close', () => this.destroy())
+  }
+
+  _read(cb) {
+    this.channel.resume()
+    cb(null)
+  }
+
+  _write(chunk, cb) {
+    if (this.channel.write(chunk)) cb(null)
+    else this.channel.once('drain', () => cb(null))
+  }
+
+  receive(buffer) {
+    this.push(buffer)
+  }
+
+  remoteEnd() {
+    this.push(null)
+  }
+
+  _destroy(cb) {
+    try {
+      this.channel.destroy()
+    } catch {
+      // channel may already be gone
+    }
+    cb(null)
+  }
+}
+
+/**
+ * Accumulate the session-id preamble a central writes first on a fresh
+ * channel. Resolves { id, rest } — id as a hex string and rest being any bytes
+ * delivered past it (the channel is a byte stream; the first payload bytes may
+ * arrive glued to the id). Owns the channel's data events until then so no
+ * bytes race past the switchover. Timeout resolves { id: null, rest: null }.
+ *
+ * @param {any} channel
+ * @param {number} idLen
+ * @param {number} timeout
+ * @returns {Promise<{ id: string | null, rest: Uint8Array | null }>}
+ */
+export function readIdPreamble(channel, idLen, timeout) {
+  return new Promise((resolve) => {
+    let buf = b4a.alloc(0)
+
+    const finish = (id, rest) => {
+      clearTimeout(timer)
+      channel.removeListener('data', onData)
+      resolve({ id, rest })
+    }
+
+    const onData = (data) => {
+      buf = b4a.concat([buf, b4a.from(data)])
+      if (buf.byteLength >= idLen) {
+        finish(b4a.toString(buf.subarray(0, idLen), 'hex'), buf.subarray(idLen))
+      }
+    }
+
+    const timer = setTimeout(() => finish(null, null), timeout)
+    if (timer.unref) timer.unref()
+    channel.on('data', onData)
+  })
+}

package/types/database/encryption.d.ts

@@ -84,6 +84,7 @@ export class EpochAutobee {
     _epochRetrySeen: number;
     _bootState(): Promise<void>;
     _bumpPendingWriters(): Promise<boolean>;
+    _catchupMigratedNodes: any;
     _scheduleEpochRetry(): void;
     _close(): Promise<any>;
 }

package/types/network/transports/ble.d.ts

@@ -33,8 +33,10 @@ export class BLETransport extends ReadyResource {
      * @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, maxOutbound, maxInbound, scanOptions, keepLinks, name }: {
+    constructor({ backend, network, uuid, nodeId, tag, maxOutbound, maxInbound, scanOptions, keepLinks, name, pipe, l2cap }: {
         backend: any;
         network: import("../index.js").Network;
         uuid: Uint8Array;
@@ -47,6 +49,10 @@ export class BLETransport extends ReadyResource {
         };
         keepLinks?: boolean;
         name?: string;
+        pipe?: "l2cap" | "gatt";
+        l2cap?: {
+            timeout?: number;
+        };
     });
     backend: any;
     network: import("../index.js").Network;
@@ -60,11 +66,15 @@ export class BLETransport extends ReadyResource {
         scanMode?: any;
     };
     keepLinks: boolean;
+    pipe: "l2cap" | "gatt";
+    _l2capTimeout: number;
     state: string;
     central: any;
     server: any;
     _dataChar: any;
-    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    /** the published l2cap listener's psm, advertised to centrals over hello */
+    _psm: any;
+    /** id → { id, stream, conn, name, pipeTimer } for server-side (peripheral) sessions */
     _sessions: Map<any, any>;
     /** serialized server notify queue: { frame, resolve, reject } */
     _notifyQueue: any[];
@@ -73,9 +83,13 @@ export class BLETransport extends ReadyResource {
     _serviceAdded: boolean;
     /** peripheral id → per-peer dial state { timer, linked, coolUntil, failures, peerKey, peripheral } */
     _devices: Map<any, any>;
+    /** rate-limited discoveries held for the next dial window */
+    _candidates: Map<any, any>;
+    _dialTimer: any;
     /** last central.connect timestamp — global inter-dial rate limit */
     _lastDial: number;
     _scanTimer: any;
+    _cyclePending: boolean;
     _suspended: boolean;
     /** live injected links keyed by remote node id hex */
     peers: Map<any, any>;
@@ -92,22 +106,52 @@ export class BLETransport extends ReadyResource {
     _device(id: any): any;
     _prune(id: any): void;
     _startServer(Service: any, Characteristic: any): void;
+    _publishListener(): void;
+    _unpublishListener(): void;
+    _cycleListener(): void;
     _maybeAdvertise(): void;
     _onWriteRequests(requests: any): void;
     _onServerFrame(data: any): void;
-    _closeServerSession(sidHex: any, sid: any): void;
+    _openServerGatt(session: any): void;
+    _onServerChannel(channel: any): Promise<void>;
+    _bindServerStream(session: any, stream: any): void;
+    _reapSession(id: any, session: any): void;
+    _closeServerSession(id: any): void;
+    _notifyClose(id: any): void;
     _helloPayload(): any;
-    _parseHello(payload: any): string;
+    /**
+     * @param {Uint8Array} payload
+     * @returns {{ name: string, psm: number | null } | null}
+     */
+    _parseHello(payload: Uint8Array): {
+        name: string;
+        psm: number | null;
+    } | null;
     _applyPeerName(session: any, payload: any): void;
     _enqueueNotify(f: any): Promise<any>;
     _drainNotify(): void;
     _startScan(): void;
     _armScanRestart(): void;
     _stopScan(): void;
+    /**
+     * 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(): void;
     _onState(raw: any): void;
     _onDiscover(peripheral: any): void;
+    _flushCandidates(): void;
+    _clearCandidates(): void;
     _onConnect(peripheral: any): void;
     _startCentralSession(peripheral: any, char: any): void;
+    _openCentralGatt(peripheral: any, sess: any): void;
+    _bindCentralStream(peripheral: any, sess: any, stream: any): void;
+    _closeCentralSession(peripheral: any, sess: any): void;
+    _openCentralL2CAP(peripheral: any, sess: any, psm: any): Promise<void>;
+    _openChannel(peripheral: any, psm: any): Promise<any>;
     _onCentralNotify(peripheral: any, data: any): void;
     _centralSend(peripheral: any, char: any, f: any): any;
     _writeOnce(peripheral: any, char: any, f: any): Promise<any>;

package/types/network/transports/gatt.d.ts

@@ -9,17 +9,13 @@ export class GattStream extends Duplex<import("streamx").DuplexEvents> {
     /**
      * @param {object} opts
      * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
-     * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
      */
-    constructor({ send, onclose }?: {
+    constructor({ send }?: {
         send: (buffer: Uint8Array) => Promise<void>;
-        onclose?: () => void;
     });
     _send: (buffer: Uint8Array) => Promise<void>;
-    _onclose: () => void;
     _write(chunk: any, cb: any): Promise<void>;
     receive(buffer: any): void;
     remoteEnd(): void;
-    _destroy(cb: any): void;
 }
 import { Duplex } from 'streamx';

package/types/network/transports/l2cap.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Accumulate the session-id preamble a central writes first on a fresh
+ * channel. Resolves { id, rest } — id as a hex string and rest being any bytes
+ * delivered past it (the channel is a byte stream; the first payload bytes may
+ * arrive glued to the id). Owns the channel's data events until then so no
+ * bytes race past the switchover. Timeout resolves { id: null, rest: null }.
+ *
+ * @param {any} channel
+ * @param {number} idLen
+ * @param {number} timeout
+ * @returns {Promise<{ id: string | null, rest: Uint8Array | null }>}
+ */
+export function readIdPreamble(channel: any, idLen: number, timeout: number): Promise<{
+    id: string | null;
+    rest: Uint8Array | null;
+}>;
+/**
+ * Byte pipe over an L2CAP channel — the GattStream-shaped wrapper so
+ * BLETransport can treat both pipes identically. The channel is already a
+ * reliable ordered duplex with credit-based flow control, so no framing or
+ * fragmentation is needed.
+ *
+ * @extends Duplex
+ */
+export class L2CAPStream extends Duplex<import("streamx").DuplexEvents> {
+    /**
+     * @param {any} channel  bare-bluetooth L2CAPChannel (a duplex).
+     */
+    constructor(channel: any);
+    channel: any;
+    _read(cb: any): void;
+    _write(chunk: any, cb: any): void;
+    receive(buffer: any): void;
+    remoteEnd(): void;
+    _destroy(cb: any): void;
+}
+import { Duplex } from 'streamx';