@cero-base/core 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,
@@ -121,6 +121,10 @@
     "crypto": {
       "bare": "bare-crypto",
       "default": "crypto"
+    },
+    "events": {
+      "bare": "bare-events",
+      "default": "events"
     }
   },
   "scripts": {
@@ -129,28 +133,31 @@
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
-    "test": "brittle-node test/*.test.js",
-    "test:bare": "npx bare test/bare-smoke.js"
+    "test": "npm run test:node",
+    "test:bare": "brittle-bare test/bare.js test/*.test.js",
+    "pretest:bare": "npm run build:test",
+    "test:node": "brittle-node test/*.test.js"
   },
   "dependencies": {
     "@hyperswarm/secret-stream": "^6.9.1",
-    "autobee": "^1.0.9",
+    "autobee": "^1.0.10",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.15.3",
-    "bare-fs": "^4.7.2",
-    "bare-path": "^3.0.1",
+    "bare-fs": "^4.7.4",
+    "bare-path": "^3.1.1",
     "bip39-mnemonic": "^2.5.0",
     "blind-pairing": "^2.3.1",
-    "compact-encoding": "^3.2.0",
-    "corestore": "^7.10.1",
+    "blind-peering": "^2.5.0",
+    "compact-encoding": "^3.3.0",
+    "corestore": "^7.11.1",
     "framed-stream": "^1.0.1",
     "hrpc": "^4.3.0",
     "hyperblobs": "^2.12.1",
-    "hypercore": "^11.33.1",
-    "hypercore-blob-server": "^1.12.0",
+    "hypercore": "^11.34.1",
+    "hypercore-blob-server": "^1.15.0",
     "hypercore-crypto": "^3.7.0",
     "hypercore-id-encoding": "^1.3.0",
-    "hypercore-storage": "^3.1.1",
+    "hypercore-storage": "^3.2.0",
     "hyperdb": "^6.7.0",
     "hyperdispatch": "^1.6.0",
     "hyperschema": "^1.21.0",
@@ -165,7 +172,13 @@
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "brittle": "^4.0.2",
+    "bare-abort-controller": "^1.1.2",
+    "bare-events": "^2.9.1",
+    "bare-fetch": "^3.2.0",
+    "bare-process": "^4.5.1",
+    "bare-url": "^2.4.6",
+    "blind-peer": "^3.12.3",
+    "brittle": "^4.1.0",
     "typescript": "^5.9.3"
   },
   "license": "Apache-2.0"

package/src/database/bootstrap.js

@@ -21,16 +21,39 @@ export async function bootstrap(db, { name, isMobile, recovering = false, timeou
   }
   const writerKey = Hypercore.key(manifest)
 
-  if (recovering) await waitForFirstPeerAppend(db, timeout)
-  await saveWriter(db, writerKey, { name, isMobile })
+  if (recovering) {
+    await waitForFirstPeerAppend(db, timeout)
+    // reopen so the bee's writer state is built over the replicated genesis
+    // core — a writer opened before replication stamps ops at stale lengths
+    // and autobee silently drops them
+    await reopenBee(db)
+  }
+  if (recovering) {
+    // gate the swap on the admission actually applying: write() can resolve
+    // with the ops stalled in the drain (update() bumps heal that) or dropped
+    // outright when they were stamped behind a mid-replication core — each
+    // retry stamps past the collision, and the ops are idempotent
+    await admitWriter(db, writerKey, { name, isMobile }, timeout)
+  } else {
+    await saveWriter(db, writerKey, { name, isMobile })
+  }
   await swapWriter(db, keyPair, manifest)
 
   return { id: writerKey, writer: keyPair }
 }
 
 async function waitForFirstPeerAppend(db, timeout = 30000) {
-  if (db.bee.local.length > 0 || !db.network?.swarm) return
-  await new Promise((resolve, reject) => {
+  if (!db.network?.swarm) return
+  if (db.bee.local.length === 0) await waitForLength(db, 1, timeout)
+  await db.bee.update()
+  // the first block may not be the whole core — writes stamped below the
+  // length the system already attributes to this writer are silently dropped
+  const info = await db.bee.system.get(db.bee.local.key).catch(() => null)
+  if (info && info.length > db.bee.local.length) await waitForLength(db, info.length, timeout)
+}
+
+function waitForLength(db, length, timeout) {
+  return new Promise((resolve, reject) => {
     let done = false
     const finish = (err) => {
       if (done) return
@@ -43,7 +66,7 @@ async function waitForFirstPeerAppend(db, timeout = 30000) {
     }
     // timeout + close handling so a peer that never replicates can't hang the
     // recovery forever, and the append listener is always removed.
-    const onAppend = () => db.bee.local.length > 0 && finish()
+    const onAppend = () => db.bee.local.length >= length && finish()
     const onClose = () => finish(CeroError.CLOSED('Database'))
     const timer = setTimeout(
       () => finish(CeroError.TIMED_OUT('recovery — no peer append')),
@@ -52,17 +75,46 @@ async function waitForFirstPeerAppend(db, timeout = 30000) {
     db.bee.local.on('append', onAppend)
     db.on('close', onClose)
   })
-  await db.bee.update()
+}
+
+async function admitWriter(db, writerKey, opts, timeout) {
+  const deadline = Date.now() + timeout
+  const id = toId(writerKey)
+  while (true) {
+    await saveWriter(db, writerKey, opts)
+    if (await deviceApplied(db, id, Math.min(3000, deadline - Date.now()))) return
+    if (Date.now() >= deadline) throw CeroError.TIMED_OUT('recovery — writer not admitted')
+  }
+}
+
+async function deviceApplied(db, id, timeout) {
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    const { data } = await db.get('devices', id)
+    if (data) return true
+    await db.bee.update()
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+  return false
+}
+
+async function reopenBee(db) {
+  if (db.network) db.network.detach(db.bee)
+  await db.bee.close()
+  db.bee = null
+  await db.openBee()
 }
 
 async function saveWriter(db, writerKey, { name, isMobile }) {
+  const ts = Date.now()
   await db.write([
     [
       'add-writer',
       {
         master: db.identity.publicKey,
         writer: writerKey,
-        sig: db.identity.sign(addWriterPayload(db.key, writerKey, db.writerKey))
+        sig: db.identity.sign(addWriterPayload(db.key, writerKey, db.writerKey)),
+        ts
       }
     ],
     [
@@ -70,7 +122,9 @@ async function saveWriter(db, writerKey, { name, isMobile }) {
       {
         id: toId(writerKey),
         name: name || null,
-        isMobile: isMobile === true
+        isMobile: isMobile === true,
+        createdAt: ts,
+        updatedAt: ts
       }
     ]
   ])

package/src/database/changes.js

@@ -0,0 +1,120 @@
+import { Readable } from 'streamx'
+import b4a from 'b4a'
+
+// the pinned hyperbee2 snapshot inside a hyperdb snapshot — internals reach
+// (pear-sdk does the same); kept in one helper so an upstream rename is a
+// one-line fix
+const beeOf = (snap) => snap.engineSnapshot.snapshot
+
+/**
+ * Pull-driven delta stream over a collection: batches of `{ prev, next }`
+ * pairs diffed between per-stream snapshot cursors. Update ticks only mark
+ * the stream dirty — the diff runs when the reader demands, so backpressure
+ * folds bursts into one bigger batch and nothing is ever dropped. The first
+ * batch, and any batch after the view is swapped or fast-forwarded to a new
+ * core, carries the full matching state as inserts with `reset: true`.
+ *
+ * @param {import('./index.js').Database} db
+ * @param {string} name    Ref name (scopes the update ticks).
+ * @param {string} col     Collection path (`@ns/name`).
+ * @param {(row: any) => boolean} matches
+ * @returns {import('streamx').Readable}
+ */
+export function makeChanges(db, name, col, matches) {
+  let cursor = null
+  let cursorView = null
+  let dirty = true
+  let busy = false
+  let off = null
+
+  const stream = new Readable({
+    open(cb) {
+      off = db.onUpdate(mark, name)
+      pump()
+      cb(null)
+    },
+    read(cb) {
+      pump()
+      cb(null)
+    },
+    predestroy() {
+      if (off) off()
+    },
+    destroy(cb) {
+      release().then(() => cb(null), cb)
+    }
+  })
+
+  const mark = () => {
+    dirty = true
+    pump()
+  }
+
+  const pump = () => {
+    if (busy || !dirty || stream.destroyed) return
+    busy = true
+    run()
+      .catch((err) => stream.destroy(err))
+      .finally(() => {
+        busy = false
+      })
+  }
+
+  const run = async () => {
+    while (dirty && !stream.destroyed) {
+      dirty = false
+      const batch = await diff()
+      if (batch && stream.push(batch) === false) return
+    }
+  }
+
+  const diff = async () => {
+    const snap = db.view.snapshot()
+    try {
+      const fresh =
+        !cursor ||
+        cursorView !== db.view ||
+        !b4a.equals(beeOf(cursor).core.key, beeOf(snap).core.key)
+      const batch = fresh ? await initial(snap) : await delta(snap)
+      if (cursor) await cursor.close()
+      cursor = snap
+      cursorView = db.view
+      return batch
+    } catch (err) {
+      await snap.close().catch(() => {})
+      throw err
+    }
+  }
+
+  const initial = async (snap) => {
+    const changes = []
+    for (const next of await snap.find(col, {}).toArray()) {
+      if (matches(next)) changes.push({ prev: null, next })
+    }
+    return { changes, reset: true }
+  }
+
+  const delta = async (snap) => {
+    const collection = db.view.definition.resolveCollection(col)
+    const range = collection.encodeKeyRange({})
+    const changes = []
+    for await (const { left, right } of beeOf(cursor).createDiffStream(beeOf(snap), range)) {
+      const prev = left ? collection.reconstruct(db.view.versions, left.key, left.value) : null
+      const next = right ? collection.reconstruct(db.view.versions, right.key, right.value) : null
+      const from = prev && matches(prev) ? prev : null
+      const to = next && matches(next) ? next : null
+      if (!from && !to) continue
+      changes.push({ prev: from, next: to })
+    }
+    return changes.length ? { changes, reset: false } : null
+  }
+
+  const release = async () => {
+    if (!cursor) return
+    const held = cursor
+    cursor = null
+    await held.close().catch(() => {})
+  }
+
+  return stream
+}

package/src/database/dispatch.js

@@ -105,7 +105,7 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
     if (!Identity.verify(op.master, addWriterPayload(ctx.dbKey, op.writer, ctx.key), op.sig)) return
     if (!(await isGenesis(ctx.view)) && !can(await getRole(ctx.view, op.master), INVITE)) return
     await ctx.host.addWriter(op.writer, { isIndexer: op.isIndexer !== false })
-    const ts = Date.now()
+    const ts = op.ts || 0
     await insert(ctx.view, 'devices', `@${ns}/devices`, {
       id: toId(op.writer),
       memberId: toId(op.master),
@@ -131,7 +131,7 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
     const memberId = toId(op.identity)
     if (!can(await getRole(ctx.view, op.identity), WRITE)) return
     await ctx.host.addWriter(op.writer, { isIndexer: true })
-    const ts = Date.now()
+    const ts = op.ts || 0
     await insert(ctx.view, 'devices', `@${ns}/devices`, {
       id: toId(op.writer),
       memberId,
@@ -149,13 +149,13 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
     await insert(ctx.view, 'members', `@${ns}/members`, op)
     const deviceId = toId(op.key)
     const existingDevice = await getDevice(ctx.view, deviceId)
-    const ts = Date.now()
+    const ts = op.updatedAt || 0
     await insert(ctx.view, 'devices', `@${ns}/devices`, {
       id: deviceId,
       memberId: op.id,
       name: existingDevice?.name ?? null,
       isMobile: existingDevice?.isMobile ?? false,
-      createdAt: existingDevice?.createdAt ?? ts,
+      createdAt: existingDevice?.createdAt || op.createdAt || ts,
       updatedAt: ts
     })
   })
@@ -203,11 +203,11 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
       })
       add(`set-${b.verb}`, async (op, ctx) => {
         const existing = await getDevice(ctx.view, op.id)
-        const ts = Date.now()
+        const ts = op.updatedAt || 0
         await insert(ctx.view, b.name, col, {
           ...op,
           memberId: existing?.memberId ?? op.memberId ?? null,
-          createdAt: existing?.createdAt ?? ts,
+          createdAt: existing?.createdAt || op.createdAt || ts,
           updatedAt: ts
         })
       })

package/src/database/envelope.js

@@ -0,0 +1,32 @@
+import b4a from 'b4a'
+import c from 'compact-encoding'
+
+// 0xff is the c.uint prefix for a 64-bit route id — unreachable for real
+// hyperdispatch routes, so it safely marks a version-enveloped op. Peers too
+// old to know the envelope throw on it and skip deterministically.
+const SENTINEL = 0xff
+
+/**
+ * Prefix an encoded op with the app's contract version.
+ *
+ * @param {number} version
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function wrap(version, body) {
+  return b4a.concat([b4a.from([SENTINEL]), c.encode(c.uint, version), body])
+}
+
+/**
+ * Split an op into contract version and payload. Ops written before the
+ * envelope existed carry no sentinel and read as version 0.
+ *
+ * @param {Uint8Array} buf
+ * @returns {{ version: number, body: Uint8Array }}
+ */
+export function unwrap(buf) {
+  if (buf.byteLength === 0 || buf[0] !== SENTINEL) return { version: 0, body: buf }
+  const state = { buffer: buf, start: 1, end: buf.byteLength }
+  const version = c.uint.decode(state)
+  return { version, body: buf.subarray(state.start) }
+}

package/src/database/index.js

@@ -1,5 +1,6 @@
 import Autobee from 'autobee'
 import HyperDB from 'hyperdb'
+import c from 'compact-encoding'
 import Hypercore from 'hypercore'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
@@ -7,8 +8,10 @@ import b4a from 'b4a'
 
 import { NAMESPACE, SINGLE, COLLECTION, ACTION, ACTIVE, PASSIVE } from '../lib/constants.js'
 import { genId, subscribe, addWriterPayload, claimWriterPayload } from '../lib/utils.js'
+import { wrap, unwrap } from './envelope.js'
 import { CeroError } from '../lib/errors.js'
 import { bootstrap } from './bootstrap.js'
+import { makeChanges } from './changes.js'
 import { makeDispatcher } from './dispatch.js'
 
 /**
@@ -57,6 +60,8 @@ export class Database extends ReadyResource {
     this.meta = opts.spec.meta || { ns: NAMESPACE, refs: {} }
     this.ns = this.meta.ns || NAMESPACE
     this.refs = this.meta.refs || {}
+    this.version = this.meta.version || 1
+    this.behind = null
     this.routes = opts.routes || {}
     this.namespace = opts.namespace || NAMESPACE
     this.encryptionKey = opts.encryptionKey || opts.identity.encryptionKey || null
@@ -124,9 +129,21 @@ export class Database extends ReadyResource {
       wakeup: wakeup || undefined,
       open: (b) => HyperDB.bee2(b, this.spec.database, { autoUpdate: true }),
       apply: async (nodes, view, host) => {
-        const result = await (this.applyOverride || this.dispatcher.apply)(nodes, view, host)
-        if (this.updaters.size) this._touch(nodes)
-        if (this.onApplyHooks.size) this._observe(nodes)
+        // envelope handling lives here, once: unwrap every node and skip ops
+        // from a newer app version (deterministic — they stay in the log), so
+        // the dispatcher AND custom apply overrides see plain op bytes
+        const ready = []
+        for (const node of nodes) {
+          const { version, body } = unwrap(node.value)
+          if (version > this.version) {
+            this._onFuture(version)
+            continue
+          }
+          ready.push(version === 0 ? node : { ...node, value: body })
+        }
+        const result = await (this.applyOverride || this.dispatcher.apply)(ready, view, host)
+        if (this.updaters.size) this._touch(ready)
+        if (this.onApplyHooks.size) this._observe(ready)
         return result
       },
       update: async (db) => {
@@ -149,6 +166,21 @@ export class Database extends ReadyResource {
     this.bee = bee
     this.key = bee.key
 
+    const behind = await bee.local.getUserData('cero/behind')
+    this.behind = behind ? c.decode(c.uint, behind) : null
+
+    // ops we once skipped are now within our contract — wipe the boot record
+    // so the next open replays the whole log through the current handlers
+    if (this.behind !== null && this.behind <= this.version) {
+      await bee.local.setUserData('autobee/head', null)
+      await bee.local.setUserData('cero/behind', null)
+      await bee.close()
+      this.behind = null
+      await this.openBee()
+      this.emit('rebuild')
+      return
+    }
+
     bee.on('writable', () => this.emit('writable'))
     // without a listener autobee escalates apply/view errors to a process crash
     bee.on('error', this._onerror)
@@ -503,7 +535,49 @@ export class Database extends ReadyResource {
     const encoded = ops.map(([op, payload]) =>
       this.spec.dispatch.encode(`@${this.ns}/${op}`, payload)
     )
-    await this.bee.append(encoded.length === 1 ? encoded[0] : encoded)
+    await this._dryRun(encoded)
+    const wrapped = encoded.map((value) => wrap(this.version, value))
+    await this.bee.append(wrapped.length === 1 ? wrapped[0] : wrapped)
+  }
+
+  /**
+   * Record that the log contains ops from a newer app version than this
+   * peer understands. Fires `'behind'` once per version so apps can prompt
+   * an upgrade; the marker survives restarts via local core userData.
+   *
+   * @param {number} version
+   */
+  _onFuture(version) {
+    if (this.behind !== null && version <= this.behind) return
+    this.behind = version
+    this.bee.local.setUserData('cero/behind', c.encode(c.uint, version)).catch(this._onerror)
+    this.emit('behind', version)
+  }
+
+  /**
+   * Validate ops against the committed view before appending: each op runs in
+   * a throwaway transaction with host effects stubbed, so a throwing handler
+   * rejects the write and nothing enters the permanent log. Permission gates
+   * that `return` are not rejections — apply stays the authority at
+   * linearization time.
+   *
+   * @param {Uint8Array[]} encoded
+   */
+  async _dryRun(encoded) {
+    const tx = this.view.transaction()
+    const host = { addWriter: async () => {}, removeWriter: async () => {} }
+    try {
+      for (const value of encoded) {
+        await this.dispatcher.dispatcher.dispatch(value, {
+          view: tx,
+          host,
+          key: this.writerKey,
+          dbKey: this.key
+        })
+      }
+    } finally {
+      await tx.close()
+    }
   }
 
   /**
@@ -634,6 +708,31 @@ export class Database extends ReadyResource {
     })
   }
 
+  /**
+   * Delta subscription: batches of `{ prev, next }` row pairs instead of
+   * full snapshots. The first batch (and any batch after a view swap) carries
+   * the current matching rows as inserts with `reset: true` — replaying every
+   * batch into a Map keyed by row id always reconstructs current state.
+   * `limit`/`reverse` are not applied; deltas are unwindowed by design.
+   *
+   * @param {string} name
+   * @param {Query} [query]
+   * @returns {import('streamx').Readable}
+   */
+  changes(name, query = {}) {
+    this.guard()
+    const col = `@${this.ns}/${name}`
+    if (!this.view.definition.resolveCollection(col)) {
+      throw CeroError.UNKNOWN('collection', name)
+    }
+    const filter = { ...query }
+    delete filter.limit
+    delete filter.reverse
+    delete filter.total
+    const matches = (row) => paginate([row], filter).length > 0
+    return makeChanges(this, name, col, matches)
+  }
+
   /**
    * First-run bootstrap: create the device writer, save it, and swap into it.
    *
@@ -661,9 +760,10 @@ export class Database extends ReadyResource {
     const encoded = this.spec.dispatch.encode(`@${this.ns}/claim-writer`, {
       identity: this.identity.publicKey,
       writer: writerKey,
-      sig
+      sig,
+      ts: Date.now()
     })
-    await this.bee.append(encoded, { optimistic: true })
+    await this.bee.append(wrap(this.version, encoded), { optimistic: true })
     await this.bee.update()
     if (!this.bee.writable) await this.whenWritable()
   }
@@ -826,7 +926,9 @@ export class Database extends ReadyResource {
       signers: [{ publicKey }]
     })
     const sig = this.identity.sign(addWriterPayload(this.key, writerKey, this.writerKey))
-    await this.write([[verb, { master: this.identity.publicKey, writer: writerKey, sig }]])
+    await this.write([
+      [verb, { master: this.identity.publicKey, writer: writerKey, sig, ts: Date.now() }]
+    ])
     await this.runAfter(hook, ctx)
   }
 }

package/src/lib/spec/index.js

@@ -1,12 +1,12 @@
 // This file is autogenerated by the hyperschema compiler
-// Schema Version: 1
+// Schema Version: 2
 /* eslint-disable camelcase */
 /* eslint-disable quotes */
 /* eslint-disable space-before-function-paren */
 
 import { c } from 'hyperschema/runtime'
 
-const VERSION = 1
+const VERSION = 2
 
 // eslint-disable-next-line no-unused-vars
 let version = VERSION
@@ -274,6 +274,37 @@ const encoding6 = {
   }
 }
 
+// @cero/changes.prev
+const encoding7_0 = encoding3_0
+// @cero/changes.next
+const encoding7_1 = encoding3_0
+
+// @cero/changes
+const encoding7 = {
+  preencode(state, m) {
+    state.end++ // max flag is 2 so always one byte
+
+    if (version >= 2 && m.prev) encoding7_0.preencode(state, m.prev)
+    if (version >= 2 && m.next) encoding7_1.preencode(state, m.next)
+  },
+  encode(state, m) {
+    const flags = ((version >= 2 && m.prev) ? 1 : 0) | ((version >= 2 && m.next) ? 2 : 0)
+
+    c.uint.encode(state, flags)
+
+    if (version >= 2 && m.prev) encoding7_0.encode(state, m.prev)
+    if (version >= 2 && m.next) encoding7_1.encode(state, m.next)
+  },
+  decode(state) {
+    const flags = c.uint.decode(state)
+
+    return {
+      prev: (version >= 2 && (flags & 1) !== 0) ? encoding7_0.decode(state) : null,
+      next: (version >= 2 && (flags & 2) !== 0) ? encoding7_1.decode(state) : null
+    }
+  }
+}
+
 function setVersion(v) {
   version = v
 }
@@ -311,6 +342,8 @@ function getEncoding(name) {
       return encoding5
     case '@cero/blob-id':
       return encoding6
+    case '@cero/changes':
+      return encoding7
     default:
       throw new Error('Encoder not found ' + name)
   }

package/src/lib/spec/schema.json

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "schema": [
     {
       "name": "invite-body",
@@ -273,6 +273,28 @@
           "version": 1
         }
       ]
+    },
+    {
+      "name": "changes",
+      "namespace": "cero",
+      "compact": false,
+      "flagsPosition": 0,
+      "fields": [
+        {
+          "name": "prev",
+          "required": false,
+          "array": true,
+          "type": "buffer",
+          "version": 2
+        },
+        {
+          "name": "next",
+          "required": false,
+          "array": true,
+          "type": "buffer",
+          "version": 2
+        }
+      ]
     }
   ]
 }

package/src/network/index.js

@@ -1,8 +1,10 @@
 import NoiseSecretStream from '@hyperswarm/secret-stream'
 import BlindPairing from 'blind-pairing'
+import BlindPeering from 'blind-peering'
 import ProtomuxWakeup from 'protomux-wakeup'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
+import { decode as decodeKey } from 'hypercore-id-encoding'
 import b4a from 'b4a'
 
 import { ACTIVE, PASSIVE } from '../lib/constants.js'
@@ -19,6 +21,8 @@ export { channelTopic }
  * @property {(remotePublicKey: Uint8Array, payload: any) => boolean} [firewall]  Incoming-connection filter.
  * @property {Uint8Array[]} [relayThrough]                          Relay public keys to tunnel through.
  * @property {string} [channel]                                     Optional network-isolation label; only same-channel peers meet.
+ * @property {any} [store]                                          Corestore; required for mirrors (blind peers replicate its cores).
+ * @property {Array<string | Uint8Array>} [mirrors]                Blind-peer public keys; each attached room/blob core is mirrored through them for offline sync.
  *
  * @typedef {{ replicate: (stream: any) => any }} Replicable
  */
@@ -29,13 +33,15 @@ export { channelTopic }
  */
 export class Network extends ReadyResource {
   /** @param {NetworkOpts} [opts] */
-  constructor({ identity, bootstrap, firewall, relayThrough, channel } = {}) {
+  constructor({ identity, bootstrap, firewall, relayThrough, channel, store, mirrors } = {}) {
     super()
     this.identity = identity || null
     this.bootstrap = bootstrap || null
     this.firewall = firewall || null
     this.relayThrough = relayThrough || null
     this.channel = channel || null
+    this.store = store || null
+    this.mirrors = (mirrors || []).map((k) => (typeof k === 'string' ? decodeKey(k) : k))
 
     this._dht = null
     this.wakeup = new ProtomuxWakeup()
@@ -44,6 +50,7 @@ export class Network extends ReadyResource {
     this._discoveries = new Set()
     this._injected = new Set()
     this._blind = null
+    this._blindPeering = null
   }
 
   /** @returns {any} The underlying hyperswarm, or null before ready / after close. */
@@ -171,6 +178,14 @@ export class Network extends ReadyResource {
     })
     swarm.on('peer-add', (peer) => this.emit('peer-add', peer))
     swarm.on('peer-remove', (peer) => this.emit('peer-remove', peer))
+
+    if (this.store && this.mirrors.length) {
+      this._blindPeering = new BlindPeering(swarm.dht, this.store, {
+        keys: this.mirrors,
+        wakeup: this.wakeup,
+        pick: 2
+      })
+    }
   }
 
   /**
@@ -190,6 +205,7 @@ export class Network extends ReadyResource {
    */
   async suspend() {
     if (this.closing || this.closed) return
+    await this._blindPeering?.suspend()
     await this._dht?.suspend()
   }
 
@@ -201,6 +217,7 @@ export class Network extends ReadyResource {
   async resume() {
     if (this.closing || this.closed) return
     await this._dht?.resume()
+    await this._blindPeering?.resume()
   }
 
   async _close() {
@@ -221,6 +238,15 @@ export class Network extends ReadyResource {
       }
     }
 
+    if (this._blindPeering) {
+      try {
+        await this._blindPeering.close()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      this._blindPeering = null
+    }
+
     if (this._blind) {
       try {
         await (await this._blind).close()
@@ -284,6 +310,12 @@ export class Network extends ReadyResource {
     if (!core) throw CeroError.REQUIRED('core')
     this._replicateables.add(core)
     for (const stream of this.connections) replicateInto(core, stream)
+    // mirror the core so it stays available when its writers are offline —
+    // autobees announce their whole writer set, plain cores (blobs) just themselves
+    if (this._blindPeering) {
+      if (core.wakeupCapability) this._blindPeering.addAutobaseBackground(core)
+      else this._blindPeering.addCoreBackground(core)
+    }
   }
 
   /**

package/src/network/transports/ble.js

@@ -18,7 +18,8 @@ const TYPE_HELLO = 4
 const SID_LEN = 8
 const HEADER = 1 + SID_LEN
 
-const DEFAULT_CAP = 4
+const DEFAULT_MAX_OUTBOUND = 4
+const DEFAULT_MAX_INBOUND = 8
 const CONNECT_TIMEOUT = 15000
 // per-peer dial backoff: eager while unlinked, patient once linked; the cooldown
 // grows exponentially per consecutive failure.
@@ -126,7 +127,8 @@ export class BLETransport extends ReadyResource {
    * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
    * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
    * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
-   * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
+   * @param {number} [opts.maxOutbound]   Max concurrent outbound dials/links; gossip covers the rest.
+   * @param {number} [opts.maxInbound]    Max concurrent inbound sessions; newcomers past this are refused.
    * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
    * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
    * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
@@ -137,7 +139,8 @@ export class BLETransport extends ReadyResource {
     uuid,
     nodeId,
     tag = 'cero-ble',
-    cap = DEFAULT_CAP,
+    maxOutbound = DEFAULT_MAX_OUTBOUND,
+    maxInbound = DEFAULT_MAX_INBOUND,
     scanOptions,
     keepLinks = false,
     name
@@ -149,7 +152,8 @@ export class BLETransport extends ReadyResource {
     this.nodeId = nodeId
     this.nodeHex = b4a.toString(nodeId, 'hex')
     this.serviceUUID = toServiceUUID(uuid, tag)
-    this.cap = cap
+    this.maxOutbound = maxOutbound
+    this.maxInbound = maxInbound
     this.scanOptions = scanOptions
     this.keepLinks = keepLinks
 
@@ -271,6 +275,12 @@ export class BLETransport extends ReadyResource {
     if (!f) return
     if (f.type === TYPE_OPEN) {
       if (this._sessions.has(f.sidHex)) 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)
+        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)),
@@ -414,7 +424,7 @@ export class BLETransport extends ReadyResource {
       if (d.coolUntil > Date.now()) return // failed recently — back off
       if (d.timer) return // already connecting to this one
     }
-    if (this.linkCount >= this.cap) return // gossip covers the rest
+    if (this.linkCount >= this.maxOutbound) return // gossip covers the rest
     if (Date.now() - this._lastDial < DIAL_MIN_INTERVAL) return
     // dial every discovery and open a session; a redundant link is dropped by
     // _track's dedup

package/src/rpc/index.js

@@ -12,6 +12,7 @@ const EMPTY = b4a.alloc(0)
 // Default envelope encodings for the @cero namespace, used when the supplied
 // spec does not provide its own rows/query/create types in its schema.
 const DEFAULT_ROWS = getEncoding('@cero/rows')
+const DEFAULT_CHANGES = getEncoding('@cero/changes')
 const DEFAULT_QUERY = getEncoding('@cero/query')
 const DEFAULT_CREATE = getEncoding('@cero/create')
 
@@ -26,6 +27,8 @@ const DEFAULT_CREATE = getEncoding('@cero/create')
  * @property {(type: string, row: any) => Uint8Array} encodeRow
  * @property {(type: string, buf: Uint8Array) => any} decodeRow
  * @property {(type: string, rows: any[]) => Uint8Array} encodeRows
+ * @property {(type: string, changes: Array<{ prev: any, next: any }>) => Uint8Array} encodeChanges
+ * @property {(type: string, buf: Uint8Array) => Array<{ prev: any, next: any }>} decodeChanges
  * @property {(type: string, buf: Uint8Array) => any[]} decodeRows
  * @property {(q: any) => Uint8Array} encodeQuery
  * @property {(buf: Uint8Array) => any} decodeQuery
@@ -51,6 +54,7 @@ export function bindCodec(spec) {
 
   const ns = spec.meta?.ns
   const ROWS = ns ? `@${ns}/rows` : null
+  const CHANGES = ns ? `@${ns}/changes` : null
   const QUERY = ns ? `@${ns}/query` : null
   const CREATE = ns ? `@${ns}/create` : null
 
@@ -73,6 +77,25 @@ export function bindCodec(spec) {
       const data = env?.data || []
       return data.map((b) => schema.decode(type, b))
     },
+    encodeChanges(type, changes) {
+      const prev = changes.map((x) => (x.prev ? schema.encode(type, x.prev) : EMPTY))
+      const next = changes.map((x) => (x.next ? schema.encode(type, x.next) : EMPTY))
+      return encodeEnvelope(schema, CHANGES, DEFAULT_CHANGES, { prev, next })
+    },
+    decodeChanges(type, buf) {
+      if (!buf || buf.length === 0) return []
+      const env = decodeEnvelope(schema, CHANGES, DEFAULT_CHANGES, buf)
+      const prev = env?.prev || []
+      const next = env?.next || []
+      const out = []
+      for (let i = 0; i < Math.max(prev.length, next.length); i++) {
+        out.push({
+          prev: prev[i]?.length ? schema.decode(type, prev[i]) : null,
+          next: next[i]?.length ? schema.decode(type, next[i]) : null
+        })
+      }
+      return out
+    },
     encodeQuery(q) {
       if (q == null) return encodeEnvelope(schema, QUERY, DEFAULT_QUERY, {})
       const { gt, gte, lt, lte, limit, reverse, ...rest } = q

package/types/database/changes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pull-driven delta stream over a collection: batches of `{ prev, next }`
+ * pairs diffed between per-stream snapshot cursors. Update ticks only mark
+ * the stream dirty — the diff runs when the reader demands, so backpressure
+ * folds bursts into one bigger batch and nothing is ever dropped. The first
+ * batch, and any batch after the view is swapped or fast-forwarded to a new
+ * core, carries the full matching state as inserts with `reset: true`.
+ *
+ * @param {import('./index.js').Database} db
+ * @param {string} name    Ref name (scopes the update ticks).
+ * @param {string} col     Collection path (`@ns/name`).
+ * @param {(row: any) => boolean} matches
+ * @returns {import('streamx').Readable}
+ */
+export function makeChanges(db: import("./index.js").Database, name: string, col: string, matches: (row: any) => boolean): import("streamx").Readable;

package/types/database/envelope.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prefix an encoded op with the app's contract version.
+ *
+ * @param {number} version
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function wrap(version: number, body: Uint8Array): Uint8Array;
+/**
+ * Split an op into contract version and payload. Ops written before the
+ * envelope existed carry no sentinel and read as version 0.
+ *
+ * @param {Uint8Array} buf
+ * @returns {{ version: number, body: Uint8Array }}
+ */
+export function unwrap(buf: Uint8Array): {
+    version: number;
+    body: Uint8Array;
+};

package/types/database/index.d.ts

@@ -54,6 +54,8 @@ export class Database extends ReadyResource {
         kind?: string;
         verb?: string;
     }>;
+    version: any;
+    behind: any;
     routes: Record<string, Function>;
     namespace: string;
     encryptionKey: Uint8Array<ArrayBufferLike>;
@@ -216,6 +218,24 @@ export class Database extends ReadyResource {
      * @returns {Promise<void>}
      */
     write(ops: Array<[string, any]>): Promise<void>;
+    /**
+     * Record that the log contains ops from a newer app version than this
+     * peer understands. Fires `'behind'` once per version so apps can prompt
+     * an upgrade; the marker survives restarts via local core userData.
+     *
+     * @param {number} version
+     */
+    _onFuture(version: number): void;
+    /**
+     * Validate ops against the committed view before appending: each op runs in
+     * a throwaway transaction with host effects stubbed, so a throwing handler
+     * rejects the write and nothing enters the permanent log. Permission gates
+     * that `return` are not rejections — apply stays the authority at
+     * linearization time.
+     *
+     * @param {Uint8Array[]} encoded
+     */
+    _dryRun(encoded: Uint8Array[]): Promise<void>;
     /**
      * Read a row. With no `query`: list all (collection) or fetch the one
      * record (single). With a string id: fetch that specific row.
@@ -247,6 +267,18 @@ export class Database extends ReadyResource {
      * @returns {import('streamx').Readable}
      */
     watch(name: string, query?: Query): import("streamx").Readable;
+    /**
+     * Delta subscription: batches of `{ prev, next }` row pairs instead of
+     * full snapshots. The first batch (and any batch after a view swap) carries
+     * the current matching rows as inserts with `reset: true` — replaying every
+     * batch into a Map keyed by row id always reconstructs current state.
+     * `limit`/`reverse` are not applied; deltas are unwindowed by design.
+     *
+     * @param {string} name
+     * @param {Query} [query]
+     * @returns {import('streamx').Readable}
+     */
+    changes(name: string, query?: Query): import("streamx").Readable;
     /**
      * First-run bootstrap: create the device writer, save it, and swap into it.
      *

package/types/lib/spec/index.d.ts

@@ -2,12 +2,8 @@ export function resolveStruct(name: any, v?: number): {
     preencode(state: any, m: any): void;
     encode(state: any, m: any): void;
     decode(state: any): {
-        coreKey: any;
-        blockOffset: any;
-        blockLength: any;
-        byteOffset: any;
-        byteLength: any;
-        type: any;
+        prev: any;
+        next: any;
     } | {
         status: any;
         reason: any;
@@ -21,18 +17,21 @@ export function resolveStruct(name: any, v?: number): {
         name: any;
         role: any;
         noAccept: boolean;
-    };
-};
-export function getStruct(name: any, v?: number): {
-    preencode(state: any, m: any): void;
-    encode(state: any, m: any): void;
-    decode(state: any): {
+    } | {
         coreKey: any;
         blockOffset: any;
         blockLength: any;
         byteOffset: any;
         byteLength: any;
         type: any;
+    };
+};
+export function getStruct(name: any, v?: number): {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        prev: any;
+        next: any;
     } | {
         status: any;
         reason: any;
@@ -46,6 +45,13 @@ export function getStruct(name: any, v?: number): {
         name: any;
         role: any;
         noAccept: boolean;
+    } | {
+        coreKey: any;
+        blockOffset: any;
+        blockLength: any;
+        byteOffset: any;
+        byteLength: any;
+        type: any;
     };
 };
 export function getEnum(name: any): void;
@@ -85,6 +91,13 @@ export function getEncoding(name: any): {
         byteLength: any;
         type: any;
     };
+} | {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        prev: any;
+        next: any;
+    };
 };
 export function encode(name: any, value: any, v?: number): any;
 export function decode(name: any, buffer: any, v?: number): any;

package/types/network/index.d.ts

@@ -6,6 +6,8 @@ export { channelTopic };
  * @property {(remotePublicKey: Uint8Array, payload: any) => boolean} [firewall]  Incoming-connection filter.
  * @property {Uint8Array[]} [relayThrough]                          Relay public keys to tunnel through.
  * @property {string} [channel]                                     Optional network-isolation label; only same-channel peers meet.
+ * @property {any} [store]                                          Corestore; required for mirrors (blind peers replicate its cores).
+ * @property {Array<string | Uint8Array>} [mirrors]                Blind-peer public keys; each attached room/blob core is mirrored through them for offline sync.
  *
  * @typedef {{ replicate: (stream: any) => any }} Replicable
  */
@@ -15,7 +17,7 @@ export { channelTopic };
  */
 export class Network extends ReadyResource {
     /** @param {NetworkOpts} [opts] */
-    constructor({ identity, bootstrap, firewall, relayThrough, channel }?: NetworkOpts);
+    constructor({ identity, bootstrap, firewall, relayThrough, channel, store, mirrors }?: NetworkOpts);
     identity: import("../index.js").Identity;
     bootstrap: {
         host: string;
@@ -24,12 +26,15 @@ export class Network extends ReadyResource {
     firewall: (remotePublicKey: Uint8Array, payload: any) => boolean;
     relayThrough: Uint8Array<ArrayBufferLike>[];
     channel: string;
+    store: any;
+    mirrors: any[];
     _dht: DHTTransport;
     wakeup: any;
     _replicateables: Set<any>;
     _discoveries: Set<any>;
     _injected: Set<any>;
     _blind: any;
+    _blindPeering: any;
     /** @returns {any} The underlying hyperswarm, or null before ready / after close. */
     get swarm(): any;
     /**
@@ -151,6 +156,14 @@ export type NetworkOpts = {
      * Optional network-isolation label; only same-channel peers meet.
      */
     channel?: string;
+    /**
+     * Corestore; required for mirrors (blind peers replicate its cores).
+     */
+    store?: any;
+    /**
+     * Blind-peer public keys; each attached room/blob core is mirrored through them for offline sync.
+     */
+    mirrors?: Array<string | Uint8Array>;
 };
 export type Replicable = {
     replicate: (stream: any) => any;

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

@@ -28,18 +28,20 @@ export class BLETransport extends ReadyResource {
      * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
      * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
      * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
-     * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
+     * @param {number} [opts.maxOutbound]   Max concurrent outbound dials/links; gossip covers the rest.
+     * @param {number} [opts.maxInbound]    Max concurrent inbound sessions; newcomers past this are refused.
      * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
      * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
      * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
      */
-    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks, name }: {
+    constructor({ backend, network, uuid, nodeId, tag, maxOutbound, maxInbound, scanOptions, keepLinks, name }: {
         backend: any;
         network: import("../index.js").Network;
         uuid: Uint8Array;
         nodeId: Uint8Array;
         tag?: string;
-        cap?: number;
+        maxOutbound?: number;
+        maxInbound?: number;
         scanOptions?: {
             scanMode?: any;
         };
@@ -52,7 +54,8 @@ export class BLETransport extends ReadyResource {
     nodeId: Uint8Array<ArrayBufferLike>;
     nodeHex: any;
     serviceUUID: string;
-    cap: number;
+    maxOutbound: number;
+    maxInbound: number;
     scanOptions: {
         scanMode?: any;
     };

package/types/rpc/index.d.ts

@@ -9,6 +9,8 @@
  * @property {(type: string, row: any) => Uint8Array} encodeRow
  * @property {(type: string, buf: Uint8Array) => any} decodeRow
  * @property {(type: string, rows: any[]) => Uint8Array} encodeRows
+ * @property {(type: string, changes: Array<{ prev: any, next: any }>) => Uint8Array} encodeChanges
+ * @property {(type: string, buf: Uint8Array) => Array<{ prev: any, next: any }>} decodeChanges
  * @property {(type: string, buf: Uint8Array) => any[]} decodeRows
  * @property {(q: any) => Uint8Array} encodeQuery
  * @property {(buf: Uint8Array) => any} decodeQuery
@@ -57,6 +59,14 @@ export type Codec = {
     encodeRow: (type: string, row: any) => Uint8Array;
     decodeRow: (type: string, buf: Uint8Array) => any;
     encodeRows: (type: string, rows: any[]) => Uint8Array;
+    encodeChanges: (type: string, changes: Array<{
+        prev: any;
+        next: any;
+    }>) => Uint8Array;
+    decodeChanges: (type: string, buf: Uint8Array) => Array<{
+        prev: any;
+        next: any;
+    }>;
     decodeRows: (type: string, buf: Uint8Array) => any[];
     encodeQuery: (q: any) => Uint8Array;
     decodeQuery: (buf: Uint8Array) => any;