@cero-base/core 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "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, readSidPreamble } 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
@@ -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,11 +168,15 @@ 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
+    /** the published l2cap listener's psm, advertised to centrals over hello */
+    this._psm = null
     /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
     this._sessions = new Map()
     /** serialized server notify queue: { frame, resolve, reject } */
@@ -217,6 +233,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 +241,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 +254,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 +272,39 @@ 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.
+  _cycleListener() {
+    if (this.pipe !== 'l2cap' || this._suspended || this.closing || this.closed) return
+    this._unpublishListener()
+    this._publishListener()
   }
 
   _maybeAdvertise() {
@@ -282,55 +337,136 @@ export class BLETransport extends ReadyResource {
         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 }
+      const session = { stream: null, sid, conn: null, name: null, pipeTimer: null }
       this._sessions.set(f.sidHex, session)
-      session.conn = this._onChannel(stream, false, null)
+      if (this.pipe === 'l2cap' && this._psm !== null) {
+        // the session has no stream until the central opens our channel and
+        // its sid preamble matches — reap it if that never happens
+        session.pipeTimer = setTimeout(() => {
+          session.pipeTimer = null
+          if (this._sessions.get(f.sidHex) !== session || session.stream) return
+          this._reapSession(f.sidHex, session)
+          this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch)
+        }, PIPE_PENDING_TIMEOUT)
+        if (session.pipeTimer.unref) session.pipeTimer.unref()
+      } else {
+        this._openServerGatt(f.sidHex, session)
+      }
       this._enqueueNotify(frame(TYPE_HELLO, sid, 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._reapSession(f.sidHex, s)
+        this._enqueueNotify(frame(TYPE_CLOSE, f.sid)).catch(safetyCatch)
+        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()
+        this._reapSession(f.sidHex, s)
+        if (s.stream) s.stream.remoteEnd()
       }
     }
   }
 
-  _closeServerSession(sidHex, sid) {
-    if (!this._sessions.has(sidHex)) return
+  _openServerGatt(sidHex, session) {
+    const sid = session.sid
+    session.stream = new GattStream({
+      send: (payload) => this._enqueueNotify(frame(TYPE_DATA, sid, payload)),
+      onclose: () => this._closeServerSession(sidHex, sid)
+    })
+    session.conn = this._onChannel(session.stream, false, null)
+  }
+
+  // Incoming l2cap channel: the central writes its 8-byte session id first,
+  // matching the channel to the session negotiated over the characteristic.
+  _onServerChannel(channel) {
+    if (this.closing || this.closed || this._suspended) {
+      try {
+        channel.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      return
+    }
+    readSidPreamble(
+      channel,
+      SID_LEN,
+      (sid, leftover) => {
+        const sidHex = sid !== null ? b4a.toString(sid, 'hex') : null
+        const session = sidHex !== null ? this._sessions.get(sidHex) : undefined
+        if (!session || session.stream) {
+          try {
+            channel.destroy()
+          } catch (err) {
+            safetyCatch(err)
+          }
+          return
+        }
+        if (session.pipeTimer) clearTimeout(session.pipeTimer)
+        session.pipeTimer = null
+        session.stream = new L2CAPStream(channel, {
+          onclose: () => this._closeServerSession(sidHex, session.sid)
+        })
+        session.conn = this._onChannel(session.stream, false, null)
+        if (session.name && session.conn) session.conn._peerName = session.name
+        if (leftover.byteLength) session.stream.receive(leftover)
+      },
+      this._l2capTimeout
+    )
+  }
+
+  _reapSession(sidHex, session) {
+    if (session.pipeTimer) clearTimeout(session.pipeTimer)
+    session.pipeTimer = null
     this._sessions.delete(sidHex)
+    this._cycleListener()
+  }
+
+  _closeServerSession(sidHex, sid) {
+    const session = this._sessions.get(sidHex)
+    if (!session) return
+    this._reapSession(sidHex, session)
     this._enqueueNotify(frame(TYPE_CLOSE, sid)).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 +544,41 @@ 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
+    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
+    this._devices.clear()
+    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
@@ -441,7 +612,13 @@ export class BLETransport extends ReadyResource {
 
   _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])
@@ -470,48 +647,144 @@ export class BLETransport extends ReadyResource {
   _startCentralSession(peripheral, char) {
     const sid = randomBytes(SID_LEN)
     const sidHex = b4a.toString(sid, 'hex')
-    peripheral._session = { sidHex, sid }
+    peripheral._session = { sidHex, sid, 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(
       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.sid, payload)),
+      onclose: () => 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.sid)).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
+      }
+      // sid preamble first: the server matches the channel to the session
+      channel.write(sess.sid)
+      const stream = new L2CAPStream(channel, {
+        onclose: () => 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
+      }
+    } 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.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')
     }
   }
 
@@ -722,9 +995,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 +1006,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 +1022,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
@@ -781,6 +1059,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/l2cap.js

@@ -0,0 +1,100 @@
+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).
+   * @param {object} [opts]
+   * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+   */
+  constructor(channel, { onclose } = {}) {
+    super()
+    this.channel = channel
+    this._onclose = onclose || null
+
+    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) {
+    const onclose = this._onclose
+    this._onclose = null
+    if (onclose) {
+      try {
+        onclose()
+      } catch {
+        // teardown is best-effort
+      }
+    }
+    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, then hand (sid, leftover) to the callback exactly once. Owns the
+ * channel's data events until then so no bytes race past the switchover.
+ * Timeout → callback with (null, null).
+ *
+ * @param {any} channel
+ * @param {number} sidLen
+ * @param {(sid: Uint8Array | null, leftover: Uint8Array | null) => void} onSid
+ * @param {number} timeout
+ */
+export function readSidPreamble(channel, sidLen, onSid, timeout) {
+  let buf = b4a.alloc(0)
+  let done = false
+
+  const finish = (sid, leftover) => {
+    if (done) return
+    done = true
+    clearTimeout(timer)
+    channel.removeListener('data', onData)
+    onSid(sid, leftover)
+  }
+
+  const onData = (data) => {
+    buf = b4a.concat([buf, b4a.from(data)])
+    if (buf.byteLength >= sidLen) finish(buf.subarray(0, sidLen), buf.subarray(sidLen))
+  }
+
+  const timer = setTimeout(() => finish(null, null), timeout)
+  if (timer.unref) timer.unref()
+  channel.on('data', onData)
+}

package/src/pairing/index.js

@@ -69,7 +69,8 @@ export class Pairing extends ReadyResource {
     host = true,
     inviteEncoding = null,
     joinerEncoding = null,
-    onerror = safetyCatch
+    onerror = safetyCatch,
+    onconsume = null
   } = {}) {
     super()
     if (!network) throw CeroError.REQUIRED('network')
@@ -82,6 +83,9 @@ export class Pairing extends ReadyResource {
     this.inviteEncoding = inviteEncoding
     this.joinerEncoding = joinerEncoding
     this._onerror = onerror
+    // Fired with an invite's hex id when this instance stops serving it
+    // (single-use settled, or expired) — lets the owner drop its persisted row.
+    this.onconsume = onconsume
 
     this._blind = null
     this._member = null
@@ -168,12 +172,68 @@ export class Pairing extends ReadyResource {
       seed: blind.seed,
       publicKey: blind.publicKey,
       invite,
-      reuse
+      reuse,
+      // minted here and possibly not yet persisted/replicated — syncRows must
+      // never drop it for being absent from the store
+      local: true
     })
 
     return invite.toString()
   }
 
+  /**
+   * Look up the in-memory record for a minted invite by its string form.
+   *
+   * @param {string} inviteStr
+   * @returns {{ id: Uint8Array, seed: Uint8Array, publicKey: Uint8Array, invite: import('./invite.js').Invite, reuse: boolean } | null}
+   */
+  recordOf(inviteStr) {
+    for (const record of this._invites.values()) {
+      if (record.invite.toString() === inviteStr) return record
+    }
+    return null
+  }
+
+  /**
+   * Reconcile the served-invite set with persisted rows (the room's `invites`
+   * collection). Adds unknown rows so ANY member replica can serve them across
+   * restarts; drops replicated records whose row disappeared (revoked or
+   * consumed elsewhere). Locally-minted records not yet visible as rows are
+   * kept.
+   *
+   * @param {Array<{ id: string, invite: Uint8Array, publicKey: Uint8Array, seed: Uint8Array, reuse?: boolean }>} rows
+   */
+  syncRows(rows) {
+    const seen = new Set()
+    for (const row of rows) {
+      if (!row?.id || !row.invite || !row.publicKey || !row.seed) continue
+      seen.add(row.id)
+      const existing = this._invites.get(row.id)
+      if (existing) {
+        existing.local = false
+        continue
+      }
+      let invite
+      try {
+        invite = Invite.parse(b4a.toString(row.invite))
+      } catch {
+        continue
+      }
+      if (invite.expired) continue
+      this._invites.set(row.id, {
+        id: b4a.from(row.id, 'hex'),
+        seed: row.seed,
+        publicKey: row.publicKey,
+        invite,
+        reuse: !!row.reuse,
+        local: false
+      })
+    }
+    for (const [id, record] of this._invites) {
+      if (!seen.has(id) && !record.local) this._invites.delete(id)
+    }
+  }
+
   /**
    * Forget a previously-minted invite. New candidates carrying it will be
    * dropped silently.
@@ -273,6 +333,7 @@ export class Pairing extends ReadyResource {
     if (!record) return
     if (record.invite.expired) {
       this._invites.delete(id)
+      this.onconsume?.(id)
       return
     }
 
@@ -292,7 +353,10 @@ export class Pairing extends ReadyResource {
       seed: record.seed,
       userData,
       onsettle: () => {
-        if (!record.reuse) this._invites.delete(id)
+        if (!record.reuse) {
+          this._invites.delete(id)
+          this.onconsume?.(id)
+        }
       }
     })
 

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,10 +66,14 @@ export class BLETransport extends ReadyResource {
         scanMode?: any;
     };
     keepLinks: boolean;
+    pipe: "l2cap" | "gatt";
+    _l2capTimeout: number;
     state: string;
     central: any;
     server: any;
     _dataChar: any;
+    /** the published l2cap listener's psm, advertised to centrals over hello */
+    _psm: any;
     /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
     _sessions: Map<any, any>;
     /** serialized server notify queue: { frame, resolve, reject } */
@@ -92,22 +102,47 @@ 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;
+    _openServerGatt(sidHex: any, session: any): void;
+    _onServerChannel(channel: any): void;
+    _reapSession(sidHex: any, session: any): void;
     _closeServerSession(sidHex: any, sid: 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;
     _onConnect(peripheral: any): void;
     _startCentralSession(peripheral: any, char: any): void;
+    _openCentralGatt(peripheral: any, sess: 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/l2cap.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Accumulate the session-id preamble a central writes first on a fresh
+ * channel, then hand (sid, leftover) to the callback exactly once. Owns the
+ * channel's data events until then so no bytes race past the switchover.
+ * Timeout → callback with (null, null).
+ *
+ * @param {any} channel
+ * @param {number} sidLen
+ * @param {(sid: Uint8Array | null, leftover: Uint8Array | null) => void} onSid
+ * @param {number} timeout
+ */
+export function readSidPreamble(channel: any, sidLen: number, onSid: (sid: Uint8Array | null, leftover: Uint8Array | null) => void, timeout: number): void;
+/**
+ * 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).
+     * @param {object} [opts]
+     * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+     */
+    constructor(channel: any, { onclose }?: {
+        onclose?: () => void;
+    });
+    channel: any;
+    _onclose: () => void;
+    _read(cb: any): void;
+    _write(chunk: any, cb: any): void;
+    receive(buffer: any): void;
+    remoteEnd(): void;
+    _destroy(cb: any): void;
+}
+import { Duplex } from 'streamx';

package/types/pairing/index.d.ts

@@ -57,7 +57,7 @@ export class Pairing extends ReadyResource {
      */
     static isInvite(str: unknown): boolean;
     /** @param {PairingOpts} [opts] */
-    constructor({ network, identity, topic, host, inviteEncoding, joinerEncoding, onerror }?: PairingOpts);
+    constructor({ network, identity, topic, host, inviteEncoding, joinerEncoding, onerror, onconsume }?: PairingOpts);
     network: import("../index.js").Network;
     identity: import("../index.js").Identity;
     topic: Uint8Array<ArrayBufferLike>;
@@ -65,6 +65,7 @@ export class Pairing extends ReadyResource {
     inviteEncoding: any;
     joinerEncoding: any;
     _onerror: (err: Error) => void;
+    onconsume: any;
     _blind: any;
     _member: any;
     _invites: Map<any, any>;
@@ -76,6 +77,35 @@ export class Pairing extends ReadyResource {
      * @returns {Promise<string>}
      */
     createInvite({ role, expiresIn, data, reuse }?: CreateInviteOpts): Promise<string>;
+    /**
+     * Look up the in-memory record for a minted invite by its string form.
+     *
+     * @param {string} inviteStr
+     * @returns {{ id: Uint8Array, seed: Uint8Array, publicKey: Uint8Array, invite: import('./invite.js').Invite, reuse: boolean } | null}
+     */
+    recordOf(inviteStr: string): {
+        id: Uint8Array;
+        seed: Uint8Array;
+        publicKey: Uint8Array;
+        invite: import("./invite.js").Invite;
+        reuse: boolean;
+    } | null;
+    /**
+     * Reconcile the served-invite set with persisted rows (the room's `invites`
+     * collection). Adds unknown rows so ANY member replica can serve them across
+     * restarts; drops replicated records whose row disappeared (revoked or
+     * consumed elsewhere). Locally-minted records not yet visible as rows are
+     * kept.
+     *
+     * @param {Array<{ id: string, invite: Uint8Array, publicKey: Uint8Array, seed: Uint8Array, reuse?: boolean }>} rows
+     */
+    syncRows(rows: Array<{
+        id: string;
+        invite: Uint8Array;
+        publicKey: Uint8Array;
+        seed: Uint8Array;
+        reuse?: boolean;
+    }>): void;
     /**
      * Forget a previously-minted invite. New candidates carrying it will be
      * dropped silently.