@cero-base/cero 1.4.0 → 1.5.1

package/README.md

@@ -178,6 +178,23 @@ const ac = new AbortController()
 cero.watch(room.messages, null, { signal: ac.signal }) // ac.abort() ⇒ destroyed
 ```
 
+### `cero.changes(ref, q?, opts?)`
+
+Delta subscription: instead of full snapshots, batches of `{ prev, next }` row pairs — insert (`prev: null`), update (both), delete (`next: null`). Self-contained: the first batch (and any batch after recovery or an upgrade rebuild) replays the current matching rows as inserts with `reset: true`, so folding every batch into a Map always reconstructs current state — no separate `get`, no attach race:
+
+```js
+const rows = new Map()
+for await (const { changes, reset } of cero.changes(room.messages)) {
+  if (reset) rows.clear()
+  for (const { prev, next } of changes) {
+    if (next) rows.set(next.id, next)
+    else rows.delete(prev.id)
+  }
+}
+```
+
+Lossless under backpressure — a slow consumer gets fewer, bigger batches, never dropped ones. Query `gt/gte/lt/lte`, equality fields, and `search` scope the deltas (a row updated out of the filter arrives as `prev`-only); `limit`/`reverse` are not applied — deltas are unwindowed, windowing is `watch`'s job. Over RPC the wire carries only the changed rows, not the result set. Prefer `changes` for accumulating UIs (chat logs, ever-growing lists); prefer `watch` for windowed views. File-typed fields resolve on both sides. Handle refs are not supported.
+
 ### `cero.call(actionRef, data)`
 
 Invoke an action defined in your schema with `t.action({ … })`. Custom write paths; the dispatcher handles encoding/decoding.
@@ -515,6 +532,60 @@ const room = await cero.open(me.room, invite) // rendezvouses over BLE automatic
 
 The advertisement auto-stops at the invite's `expiresIn` — a photographed QR must not stay an ambient admission ticket.
 
+## App versions & rollouts
+
+Rooms are permanent replicated logs, and after release your users will run
+different app versions side by side. Every op cero writes carries the app's
+contract version (stamped into the generated spec by `build` — it advances
+automatically whenever the schema changes). Peers handle version skew
+deterministically:
+
+- Ops from a **newer** version are skipped — they stay in the log, they are
+  not errors, and nothing diverges. The store reports it:
+
+```js
+me.store.behind // highest future version seen, or null
+me.store.on('behind', (version) => showUpdatePrompt())
+```
+
+- After the app **upgrades** past everything it skipped, the next open
+  rebuilds the local view from the log through the new handlers — the
+  previously-skipped ops apply, nothing is lost, and the store emits
+  `'rebuild'` once.
+- Apps built before versioned ops existed read as version 0 and interoperate
+  unchanged.
+
+Ship gradual rollouts freely; old peers keep working on everything they
+understand and know when to prompt for an update.
+
+## Mirrors (offline sync)
+
+Two peers can only sync while both are online. A **blind peer** is an always-on relay that holds your rooms' encrypted blocks and serves them to other members — so a peer can pick up messages that were sent while it was offline. It's _blind_: rooms are end-to-end encrypted, so the mirror stores ciphertext and never sees your data.
+
+Pass mirror public keys and every room and file is mirrored automatically:
+
+```js
+const me = await cero(dir, spec, {
+  mirrors: ['<blind-peer-public-key>'] // hex or z32
+})
+```
+
+Nothing else changes — the operators, invites, and roles work exactly as before; mirrors only add availability. Keys carry through account recovery (`cero.restore`).
+
+**Running a mirror.** The `blind-peer` package is the server (a library — see `holepunchto/blind-peer-cli` for a turnkey host). A minimal self-hosted mirror:
+
+```js
+import Hyperswarm from 'hyperswarm'
+import BlindPeer from 'blind-peer'
+
+const swarm = new Hyperswarm()
+const mirror = new BlindPeer('./mirror-store', { swarm })
+await mirror.listen()
+console.log('mirror key:', mirror.publicKey.toString('hex')) // give this to cero({ mirrors })
+```
+
+Point your app's `mirrors` at that key. Storage grows with the rooms it holds; `blind-peer` GCs least-recently-used data past its `maxBytes` limit.
+
 ## Exports
 
 | Path                         | What you get                                                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -74,6 +74,14 @@
     "crypto": {
       "bare": "bare-crypto",
       "default": "crypto"
+    },
+    "url": {
+      "bare": "bare-url",
+      "default": "url"
+    },
+    "events": {
+      "bare": "bare-events",
+      "default": "events"
     }
   },
   "scripts": {
@@ -81,23 +89,24 @@
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
-    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node",
+    "test": "npm run test:node",
     "pretest:bare": "npm run build:test",
-    "test:bare": "npx bare test/bare-smoke.js"
+    "test:bare": "ls test/*.test.js | xargs -P1 -n1 brittle-bare test/bare.js",
+    "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.4.0",
+    "@cero-base/core": "^1.5.1",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
-    "bare-fs": "^4.7.2",
-    "bare-path": "^3.0.1",
-    "compact-encoding": "^3.2.0",
-    "corestore": "^7.10.1",
+    "bare-fs": "^4.7.4",
+    "bare-path": "^3.1.1",
+    "compact-encoding": "^3.3.0",
+    "corestore": "^7.11.1",
     "hrpc": "^4.3.0",
-    "hypercore": "^11.33.1",
+    "hypercore": "^11.34.1",
     "hypercore-crypto": "^3.7.0",
-    "hypercore-storage": "^3.1.1",
+    "hypercore-storage": "^3.2.0",
     "hyperdb": "^6.7.0",
     "hyperdispatch": "^1.6.0",
     "hyperschema": "^1.21.0",
@@ -108,7 +117,11 @@
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "brittle": "^4.0.2",
+    "bare-events": "^2.9.1",
+    "bare-fetch": "^3.2.0",
+    "bare-process": "^4.5.1",
+    "bare-url": "^2.4.6",
+    "brittle": "^4.1.0",
     "typescript": "^5.9.3"
   },
   "license": "Apache-2.0",

package/src/bluetooth.js

@@ -41,12 +41,18 @@ export class Bluetooth extends ReadyResource {
    * @param {object} [opts]
    * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); lazy-loaded when absent.
    * @param {boolean} [opts.autoStart]  Start on handle open (from `cero({ bluetooth: true })`).
+   * @param {number} [opts.maxOutbound]  Max concurrent outbound links; gossip covers the rest.
+   * @param {number} [opts.maxInbound]   Max concurrent inbound sessions; newcomers past this are refused.
    */
-  constructor(handle, { backend, autoStart } = {}) {
+  constructor(handle, { backend, autoStart, maxOutbound, maxInbound } = {}) {
     super()
     this._handle = handle
+    // explicit null/false disables bluetooth; only an omitted backend lazy-loads
     this._backend = backend || null
+    this._lazy = backend === undefined
     this._autoStart = autoStart === true
+    this._maxOutbound = maxOutbound
+    this._maxInbound = maxInbound
     this._transport = null
     this._name = null
     this._announces = new Set()
@@ -101,7 +107,7 @@ export class Bluetooth extends ReadyResource {
   }
 
   async _open() {
-    if (this._backend === null) this._backend = await loadBackend()
+    if (this._backend === null && this._lazy) this._backend = await loadBackend()
     if (!this._backend) {
       this.state = 'unsupported'
       return
@@ -139,14 +145,19 @@ export class Bluetooth extends ReadyResource {
         : handle.identity.publicKey,
       nodeId: handle.identity.publicKey,
       name: this._name || '',
+      maxOutbound: this._maxOutbound,
+      maxInbound: this._maxInbound,
       // Android scans in a battery-saver mode by default — too slow for a mesh
       scanOptions:
         typeof Bare !== 'undefined' && Bare.platform === 'android'
           ? { scanMode: this._backend.Central.SCAN_MODE_LOW_LATENCY }
           : undefined
     })
-    this._transport.on('update', () => {
-      this.state = this._transport.state
+    const transport = this._transport
+    transport.on('update', () => {
+      // a torn-down or replaced transport can still emit late adapter events
+      if (this._transport !== transport) return
+      this.state = transport.state
       this.emit('update')
     })
     try {

package/src/build/builtins.js

@@ -140,6 +140,11 @@ export const rpcCommands = (ns) => {
       request: { name: ref('req-handle') },
       response: { name: ref('res-ok') }
     },
-    { name: 'leave', request: { name: ref('req-handle') }, response: { name: ref('res-ok') } }
+    { name: 'leave', request: { name: ref('req-handle') }, response: { name: ref('res-ok') } },
+    {
+      name: 'changes',
+      request: { name: ref('req-query') },
+      response: { name: ref('res-changes'), stream: true }
+    }
   ]
 }

package/src/build/index.js

@@ -85,6 +85,7 @@ export async function build(specDir, schema, { ns = NS, extensions = true } = {}
 
   const meta = {
     ...main.meta,
+    version: await contractVersion(join(specDir, 'main')),
     local: local.meta,
     handles: Object.fromEntries(
       Object.entries(handles).map(([n, h]) => [n, { ...h.meta, type: n }])
@@ -231,6 +232,22 @@ function fieldsFor(fields) {
   }))
 }
 
+// The contract version is the highest of the three auto-bumped artifact
+// versions — any schema/db/dispatch change advances it, so a peer can tell
+// whether an op predates or postdates its own build.
+async function contractVersion(mainDir) {
+  const read = async (rel) => {
+    const j = JSON.parse(await fs.readFile(join(mainDir, rel), 'utf-8'))
+    return j.version || 1
+  }
+  const versions = await Promise.all([
+    read('schema/schema.json'),
+    read('db/db.json'),
+    read('dispatch/dispatch.json')
+  ])
+  return Math.max(...versions)
+}
+
 function emitMain(dir, ns, { types, collections, dispatches, indexes = [] }, { rpc, extend = {} }) {
   const schemaDir = join(dir, 'schema')
   const dbDir = join(dir, 'db')

package/src/build/schemas.js

@@ -13,7 +13,8 @@ export const main = {
     master: required(bytes),
     writer: required(bytes),
     sig: required(bytes),
-    isIndexer: bool
+    isIndexer: bool,
+    ts: int
   },
   counter: {
     name: required(string),
@@ -70,7 +71,8 @@ export const main = {
   claim: {
     identity: required(bytes),
     writer: required(bytes),
-    sig: required(bytes)
+    sig: required(bytes),
+    ts: int
   }
 }
 
@@ -154,6 +156,10 @@ export const rpc = {
     total: required(int),
     size: required(int)
   },
+  'res-changes': {
+    changes: required(bytes),
+    reset: bool
+  },
   'res-count': {
     count: required(int)
   },

package/src/handle/index.js

@@ -451,7 +451,8 @@ export class Handle extends ReadyResource {
       await this.store.call('add-writer', {
         sig,
         master: this.identity.publicKey,
-        writer: writerKey
+        writer: writerKey,
+        ts: member.updatedAt || Date.now()
       })
       await this.store.call('add-member', member)
     })
@@ -503,7 +504,10 @@ export class Handle extends ReadyResource {
       await child.store.call('add-writer', {
         master: this.identity.publicKey,
         writer: writerKey,
-        sig: this.identity.sign(addWriterPayload(child.store.key, writerKey, child.store.writerKey))
+        sig: this.identity.sign(
+          addWriterPayload(child.store.key, writerKey, child.store.writerKey)
+        ),
+        ts
       })
       await child.store.call('add-member', {
         id: this.identity.id,

package/src/index.js

@@ -17,6 +17,7 @@ import {
   del,
   count,
   watch,
+  changes,
   call,
   open,
   before,
@@ -37,6 +38,7 @@ export {
   del,
   count,
   watch,
+  changes,
   call,
   open,
   before,
@@ -61,6 +63,7 @@ export { t, schema } from './lib/spec.js'
  * @property {boolean} [isMobile]                      Marks this device as mobile.
  * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap nodes.
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
+ * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
  * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
@@ -69,7 +72,7 @@ export { t, schema } from './lib/spec.js'
  * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
- * @property {boolean | { autoStart?: boolean, backend?: any }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests); absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+ * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 
 /**
@@ -120,7 +123,12 @@ export async function cero(dir, spec, opts = {}) {
       else if (stored != null && stored !== wanted) throw CeroError.CHANNEL_MISMATCH()
     }
 
-    network = new Network({ bootstrap: opts.bootstrap, channel: opts.channel })
+    network = new Network({
+      bootstrap: opts.bootstrap,
+      channel: opts.channel,
+      store,
+      mirrors: opts.mirrors
+    })
     await network.ready()
     discovery = network.join(identity.topic)
     await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
@@ -187,7 +195,9 @@ export async function cero(dir, spec, opts = {}) {
             : opts.bluetooth
       me.bluetooth = new Bluetooth(me, {
         backend: bt.backend || null,
-        autoStart: bt.autoStart !== false
+        autoStart: bt.autoStart !== false,
+        maxOutbound: bt.maxOutbound,
+        maxInbound: bt.maxInbound
       })
       me.once('close', () => me.bluetooth.close().catch(safetyCatch))
       await me.bluetooth.ready()
@@ -238,6 +248,7 @@ export async function restore(me, phrase) {
     routes,
     recoveryTimeout,
     channel,
+    mirrors,
     storageKey,
     extensions
   } = opts
@@ -253,6 +264,7 @@ export async function restore(me, phrase) {
     routes,
     recoveryTimeout,
     channel,
+    mirrors,
     storageKey,
     extensions,
     phrase,
@@ -270,6 +282,7 @@ cero.get = get
 cero.del = del
 cero.count = count
 cero.watch = watch
+cero.changes = changes
 cero.call = call
 cero.open = open
 cero.before = before

package/src/lib/operators.js

@@ -2,6 +2,7 @@ import { Readable } from 'streamx'
 import b4a from 'b4a'
 
 import { encodeId, decodeId } from '@cero-base/core/blobs/codec'
+import { CeroError } from '@cero-base/core/errors'
 import { onAbort } from './utils.js'
 
 /**
@@ -251,6 +252,57 @@ export const watch = (ref, q, opts) => {
   return bindStream(owner, out, opts)
 }
 
+/**
+ * Delta subscription: batches of `{ prev, next }` row pairs instead of
+ * full snapshots — lossless under backpressure, self-contained (the first
+ * batch, and any batch after a view swap, replays current state as inserts
+ * with `reset: true`). File-typed fields resolve on both sides.
+ */
+export const changes = (ref, q, opts) => {
+  const owner = ref.handle
+  if (ref.kind === 'handle') throw CeroError.INVALID('changes does not support handle refs')
+  const src = owner.store.changes(ref.name, q)
+  let resume = null
+  const wake = () => {
+    const r = resume
+    resume = null
+    if (r) r()
+  }
+  const out = new Readable({
+    read(cb) {
+      wake()
+      cb(null)
+    },
+    destroy(cb) {
+      wake()
+      src.destroy()
+      cb(null)
+    }
+  })
+  const pump = async () => {
+    for await (const batch of src) {
+      const changes = []
+      for (const { prev, next } of batch.changes) {
+        changes.push({
+          prev: prev && resolveRow(ref, prev),
+          next: next && resolveRow(ref, next)
+        })
+      }
+      if (out.push({ ...batch, changes }) === false) {
+        await new Promise((r) => {
+          resume = r
+        })
+        if (out.destroyed) return
+      }
+    }
+    out.push(null)
+  }
+  pump().catch((err) => {
+    if (!out.destroyed) out.destroy(err)
+  })
+  return bindStream(owner, out, opts)
+}
+
 // Snapshots are idempotent — under a slow consumer hold only the NEWEST one
 // instead of queueing every intermediate (a busy room + un-drained reader
 // used to buffer full result sets without bound).

package/src/rpc/client.js

@@ -304,7 +304,52 @@ const operators = {
     }
     wire.on('end', end)
     wire.on('close', end)
-    wire.on('error', (err) => out.destroy(err))
+    // the channel tears the stream down on client close — that is an end,
+    // not a failure (bare-rpc ≥1.3.2 errors every in-flight op on teardown)
+    wire.on('error', (err) => (err.code === 'CHANNEL_CLOSED' ? end() : out.destroy(err)))
+    return out
+  },
+
+  /**
+   * Delta subscription over the wire — same contract as the local operator:
+   * batches of `{ prev, next }` with file fields resolved, `reset` marks
+   * a full replay. Lossless: server-side the cursor folds under backpressure.
+   */
+  changes(name, query) {
+    const refInfo = this._refInfo(name)
+    const codec = this._codec()
+    const schema = refInfo?.schema
+    const wire = this.rpc.changes({
+      handle: this.id,
+      ref: name,
+      query: codec.encodeQuery(query),
+      local: this._local
+    })
+    const out = new Readable({
+      predestroy() {
+        wire.destroy()
+      }
+    })
+    const pump = async () => {
+      for await (const frame of wire) {
+        const changes = []
+        for (const { prev, next } of codec.decodeChanges(schema, frame.changes)) {
+          changes.push({
+            prev: prev && this._resolveFiles(name, prev),
+            next: next && this._resolveFiles(name, next)
+          })
+        }
+        out.push({ changes, reset: frame.reset === true })
+      }
+      if (!out.destroyed) out.push(null)
+    }
+    pump().catch((err) => {
+      if (out.destroyed) return
+      // the server tears the stream down on handle close, and the channel on
+      // client close — both are ends, not failures (same contract as watch)
+      if (err.code === 'PREMATURE_CLOSE' || err.code === 'CHANNEL_CLOSED') out.push(null)
+      else out.destroy(err)
+    })
     return out
   },
 

package/src/rpc/server.js

@@ -1,9 +1,11 @@
+import safetyCatch from 'safety-catch'
+
 import { RPCServer, bindCodec } from '@cero-base/core/rpc'
 import { CeroError } from '@cero-base/core/errors'
 import { encodeId } from '@cero-base/core/blobs/codec'
 
 import { cero, restore } from '../index.js'
-import { put, set, get, del, count, watch, call } from '../lib/operators.js'
+import { put, set, get, del, count, watch, changes, call } from '../lib/operators.js'
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCServer} BaseRPCServer
@@ -209,6 +211,9 @@ export class Server extends RPCServer {
       if (!set) this._watchStreams.set(handle, (set = new Set()))
       set.add(stream)
       live.on('data', onData)
+      // channel teardown destroys the stream with CHANNEL_CLOSED — 'close'
+      // below does the cleanup; the error itself must not crash the server
+      stream.on('error', safetyCatch)
       stream.on('close', () => {
         live.off('data', onData)
         live.destroy()
@@ -216,6 +221,40 @@ export class Server extends RPCServer {
       })
     })
 
+    this.rpc.onChanges((stream) => {
+      const { handle, ref, query, local } = stream.data
+      let r, codec, live
+      try {
+        ;({ ref: r, codec } = this._refOf(handle, ref, local))
+        live = changes(r, codec.decodeQuery(query))
+      } catch (err) {
+        stream.once('error', () => {})
+        stream.writeStream.destroy(err)
+        stream.destroy()
+        return
+      }
+      let set = this._watchStreams.get(handle)
+      if (!set) this._watchStreams.set(handle, (set = new Set()))
+      set.add(stream)
+      // no keep-latest: delta batches are not idempotent — hold the iteration
+      // on wire backpressure instead; the cursor folds everything missed
+      const pump = async () => {
+        for await (const batch of live) {
+          const ok = stream.write({
+            changes: codec.encodeChanges(r.schema, batch.changes),
+            reset: batch.reset === true
+          })
+          if (ok === false) await new Promise((resolve) => stream.once('drain', resolve))
+        }
+      }
+      pump().catch(safetyCatch)
+      stream.on('error', safetyCatch)
+      stream.on('close', () => {
+        live.destroy()
+        this._watchStreams.get(handle)?.delete(stream)
+      })
+    })
+
     this.rpc.onCall(async ({ handle, op, data }) => {
       const h = this._resolve(handle)
       const r = h[op]

package/types/bluetooth.d.ts

@@ -19,14 +19,21 @@ export class Bluetooth extends ReadyResource {
      * @param {object} [opts]
      * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); lazy-loaded when absent.
      * @param {boolean} [opts.autoStart]  Start on handle open (from `cero({ bluetooth: true })`).
+     * @param {number} [opts.maxOutbound]  Max concurrent outbound links; gossip covers the rest.
+     * @param {number} [opts.maxInbound]   Max concurrent inbound sessions; newcomers past this are refused.
      */
-    constructor(handle: object, { backend, autoStart }?: {
+    constructor(handle: object, { backend, autoStart, maxOutbound, maxInbound }?: {
         backend?: any;
         autoStart?: boolean;
+        maxOutbound?: number;
+        maxInbound?: number;
     });
     _handle: any;
     _backend: any;
+    _lazy: boolean;
     _autoStart: boolean;
+    _maxOutbound: number;
+    _maxInbound: number;
     _transport: BLETransport;
     _name: any;
     _announces: Set<any>;

package/types/build/schemas.d.ts

@@ -7,6 +7,7 @@ export const main: {
         writer: import("@cero-base/core").Prim;
         sig: import("@cero-base/core").Prim;
         isIndexer: import("@cero-base/core").Prim;
+        ts: import("@cero-base/core").Prim;
     };
     counter: {
         name: import("@cero-base/core").Prim;
@@ -64,6 +65,7 @@ export const main: {
         identity: import("@cero-base/core").Prim;
         writer: import("@cero-base/core").Prim;
         sig: import("@cero-base/core").Prim;
+        ts: import("@cero-base/core").Prim;
     };
 };
 export const local: {
@@ -145,6 +147,10 @@ export const rpc: {
         total: import("@cero-base/core").Prim;
         size: import("@cero-base/core").Prim;
     };
+    'res-changes': {
+        changes: import("@cero-base/core").Prim;
+        reset: import("@cero-base/core").Prim;
+    };
     'res-count': {
         count: import("@cero-base/core").Prim;
     };

package/types/index.d.ts

@@ -11,6 +11,7 @@
  * @property {boolean} [isMobile]                      Marks this device as mobile.
  * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap nodes.
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
+ * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
  * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
@@ -19,7 +20,7 @@
  * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
- * @property {boolean | { autoStart?: boolean, backend?: any }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests); absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+ * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 /**
  * Open (or create) a cero handle at `dir`. Sets up storage, network and
@@ -40,6 +41,7 @@ export namespace cero {
     export { del };
     export { count };
     export { watch };
+    export { changes };
     export { call };
     export { open };
     export { before };
@@ -100,6 +102,10 @@ export type CeroOpts = {
      * Optional network-isolation label; only same-channel peers connect.
      */
     channel?: string;
+    /**
+     * Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
+     */
+    mirrors?: Array<string | Uint8Array>;
     /**
      * Pre-existing database key (skip bootstrap).
      */
@@ -133,11 +139,13 @@ export type CeroOpts = {
      */
     extensions?: boolean;
     /**
-     * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests); absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+     * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
      */
     bluetooth?: boolean | {
         autoStart?: boolean;
         backend?: any;
+        maxOutbound?: number;
+        maxInbound?: number;
     };
 };
 import { t } from './lib/spec.js';
@@ -147,6 +155,7 @@ import { get } from './lib/operators.js';
 import { del } from './lib/operators.js';
 import { count } from './lib/operators.js';
 import { watch } from './lib/operators.js';
+import { changes } from './lib/operators.js';
 import { call } from './lib/operators.js';
 import { open } from './lib/operators.js';
 import { before } from './lib/operators.js';
@@ -161,5 +170,5 @@ import { Ref } from './handle/index.js';
 import { Local } from './local/index.js';
 import { Identity } from '@cero-base/core/identity';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, call, open, before, after, bind, define } from "./lib/operators.js";
+export { put, set, get, del, count, watch, changes, call, open, before, after, bind, define } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/operators.d.ts

@@ -72,6 +72,7 @@ export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleR
 export function watch(ref: Ref, q?: Record<string, any>, opts?: {
     signal?: AbortSignal;
 }): import("streamx").Readable;
+export function changes(ref: any, q: any, opts: any): any;
 export function open(ref: Ref, arg?: string | {
     invite?: string;
     id?: string;