@cero-base/core 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,
@@ -41,14 +41,6 @@
       "types": "./types/network/index.d.ts",
       "default": "./src/network/index.js"
     },
-    "./network/transports/ble": {
-      "types": "./types/network/transports/ble.d.ts",
-      "default": "./src/network/transports/ble.js"
-    },
-    "./network/transports/dht": {
-      "types": "./types/network/transports/dht.d.ts",
-      "default": "./src/network/transports/dht.js"
-    },
     "./database": {
       "types": "./types/database/index.d.ts",
       "default": "./src/database/index.js"
@@ -144,7 +136,7 @@
   },
   "dependencies": {
     "@hyperswarm/secret-stream": "^6.9.1",
-    "autobee": "2.0.0-rc.19",
+    "autobee": "2.0.0-rc.21",
     "autobee-encryption": "0.1.3",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.15.3",

package/src/database/bootstrap.js

@@ -110,9 +110,13 @@ async function saveWriter(db, writerKey, { name, isMobile }) {
   ])
 }
 
+// Writer rotation by reboot: close the bee and boot again with the device
+// keyPair — autobee's fully-supported path (a fresh boot re-drains the log
+// and rebuilds its own state, no upstream userData is touched). setLocal is
+// not usable here: appends made through the base right after a live rotation
+// queue without ever flushing (keet pre-writes the first op raw instead,
+// which needs autobee's private oplog encoding).
 async function swapWriter(db, keyPair, manifest) {
-  const head = await db.bee.local.getUserData('autobee/head')
-  const enc = await db.bee.local.getUserData('autobee/encryption')
   const epochs = await db.bee.local.getUserData('cero/epochs')
 
   if (db.network) db.network.detach(db.bee)
@@ -121,8 +125,6 @@ async function swapWriter(db, keyPair, manifest) {
 
   const deviceCore = db.store.namespace(db.namespace).get({ keyPair, manifest })
   await deviceCore.ready()
-  if (head) await deviceCore.setUserData('autobee/head', head)
-  if (enc) await deviceCore.setUserData('autobee/encryption', enc)
   if (epochs) await deviceCore.setUserData('cero/epochs', epochs)
   await deviceCore.close()
 

package/src/database/changes.js

@@ -1,18 +1,14 @@
 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`.
+ * pairs diffed between per-stream head cursors (`db.diff(col, { from })`).
+ * 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).
@@ -39,9 +35,6 @@ export function makeChanges(db, name, col, matches) {
     },
     predestroy() {
       if (off) off()
-    },
-    destroy(cb) {
-      release().then(() => cb(null), cb)
     }
   })
 
@@ -69,51 +62,32 @@ export function makeChanges(db, name, col, matches) {
   }
 
   const diff = async () => {
-    const snap = db.view.snapshot()
+    const view = db.view
+    // snapshot() and engine.head() are synchronous — captured back to back
+    // they describe the same state, so the cursor is exactly-once
+    const snap = view.snapshot()
+    const head = view.engine.head()
     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) {
+      const fresh = !cursor || cursorView !== view || !head || !b4a.equals(cursor.key, head.key)
+      const changes = []
+      if (fresh) {
+        for (const next of await snap.find(col, {}).toArray()) {
+          if (matches(next)) changes.push({ prev: null, next })
+        }
+      } else {
+        for await (const { left, right } of snap.diff(col, { from: cursor })) {
+          const prev = left && matches(left) ? left : null
+          const next = right && matches(right) ? right : null
+          if (prev || next) changes.push({ prev, next })
+        }
+      }
+      cursor = head
+      cursorView = view
+      if (fresh) return { changes, reset: true }
+      return changes.length ? { changes, reset: false } : null
+    } finally {
       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/encryption.js

@@ -43,24 +43,23 @@ AutobeeEncryption.prototype.getKeys = async function (id, ctx) {
   if (!id) return baseGetKeys.call(this, id, ctx)
 
   const keyring = this.auto?.keyring
-  if (!keyring) throw CeroError.UNKNOWN_EPOCH(id)
-
-  let entropy = keyring.entropy(id)
-  if (!entropy && !keyring.primed && this.auto.local) {
-    // first epoch miss of a session may happen inside autobee's own boot
-    // (reading back this device's post-rotation state) — prime lazily from
-    // the local core's userData, once
-    keyring.primed = true
-    await primeKeyring(keyring, this.auto.local)
-    entropy = keyring.entropy(id)
+  const entropy = keyring && keyring.entropy(id)
+  if (!entropy) {
+    // record which core stalled and arm the retry — a writer autobee freezes
+    // over this throw detaches silently, and only a wakeup() re-adds it
+    if (ctx?.key && this.auto?._epochStalled) {
+      this.auto._epochStalled.add(b4a.toString(ctx.key, 'hex'))
+      this.auto._scheduleEpochRetry()
+    }
+    throw CeroError.UNKNOWN_EPOCH(id)
   }
-  if (!entropy) throw CeroError.UNKNOWN_EPOCH(id)
 
   const block = this.blockKey(entropy, ctx)
   return { id, block, hash: crypto.hash([NS_HASH_KEY, block]) }
 }
 
-async function primeKeyring(keyring, local) {
+/** Prime a keyring from a local core's persisted epoch stash. */
+export async function loadEpochs(keyring, local) {
   const saved = await local.getUserData('cero/epochs').catch(() => null)
   if (!saved) return
   try {
@@ -140,7 +139,6 @@ export class Keyring {
     this.seq = 0
     /** bumped on every add/remove — cheap change detection for retries */
     this.version = 0
-    this.primed = false
   }
 
   /** @returns {Array<{ epoch: number, stamp: number, entropy: Uint8Array }>} ascending by seq */
@@ -216,28 +214,17 @@ export class EpochAutobee extends Autobee {
   constructor(store, key, handlers = {}) {
     super(store, key, handlers)
     this.keyring = handlers.keyring || null
+    this._epochStalled = new Set()
     this._epochRetry = null
     this._epochRetryDelay = 1000
     this._epochRetrySeen = 0
   }
 
-  // Prime the keyring from local userData as soon as boot resolves the local
-  // core (in-boot epoch misses are covered by the provider's lazy prime).
-  async _bootState() {
-    await super._bootState()
-    if (!this.keyring || this.keyring.primed || !this.local) return
-    this.keyring.primed = true
-    await primeKeyring(this.keyring, this.local)
-  }
-
-  // A writer whose next blocks sit at an epoch we haven't learned yet parks:
-  // its next() reports "nothing to offer" instead of throwing, so upstream's
-  // drain keeps selecting among the other writers — the announcement carrying
-  // the missing epoch lives in one of THEIR cores and unlocks the parked
-  // writer on a later bump (the scheduled retry pokes the drain). The outer
-  // catch backstops an UNKNOWN_EPOCH surfacing from batch processing itself.
+  // An UNKNOWN_EPOCH surfacing from the drain (a system read at an epoch we
+  // haven't learned yet) parks the whole pass — the scheduled retry wakes the
+  // stalled cores once the announcement lands. Oplog blocks at unknown epochs
+  // never reach here: autobee's own reader freezes that writer.
   async _bumpPendingWriters() {
-    for (const w of this.writers.pending) this._parkOnUnknownEpoch(w)
     try {
       return await super._bumpPendingWriters()
     } catch (err) {
@@ -247,25 +234,22 @@ export class EpochAutobee extends Autobee {
     }
   }
 
-  _parkOnUnknownEpoch(w) {
-    if (w._epochParking) return
-    w._epochParking = true
-    const next = w.next.bind(w)
-    w.next = async () => {
-      try {
-        return await next()
-      } catch (err) {
-        if (err?.code !== 'UNKNOWN_EPOCH') throw err
-        this._scheduleEpochRetry()
-        return null
-      }
+  // hints read the system bee outside upstream's guarded drain — an escaping
+  // UNKNOWN_EPOCH would close the bee; park and retry like everything else
+  async _applyWakeupHints() {
+    try {
+      return await super._applyWakeupHints()
+    } catch (err) {
+      if (err?.code !== 'UNKNOWN_EPOCH') throw err
+      this._scheduleEpochRetry()
+      return new Map()
     }
   }
 
-  // a parked writer produces no wake-up of its own — poke the bee until the
-  // pending announcement applies and the parked blocks decrypt. Exponential
-  // backoff (reset when the keyring advances) so a removed member, who will
-  // never learn the epoch, settles into a slow idle poll instead of a hot loop
+  // a stalled core produces no wake-up of its own — and a writer autobee froze
+  // over one only comes back through wakeup(), update() never re-adds it.
+  // Exponential backoff (reset when the keyring advances) so a removed member,
+  // who will never learn the epoch, settles into a slow idle poll
   _scheduleEpochRetry() {
     if (this._epochRetry || this.closing) return
     const version = this.keyring ? this.keyring.version : 0
@@ -275,7 +259,12 @@ export class EpochAutobee extends Autobee {
     }
     this._epochRetry = setTimeout(() => {
       this._epochRetry = null
-      if (!this.closing) this.update().catch(noop)
+      if (this.closing) return
+      for (const hex of this._epochStalled) {
+        this.wakeup({ key: b4a.from(hex, 'hex'), length: 0 }).catch(noop)
+      }
+      this._epochStalled.clear()
+      this.update().catch(noop)
     }, this._epochRetryDelay)
     this._epochRetryDelay = Math.min(this._epochRetryDelay * 2, 60000)
   }

package/src/database/index.js

@@ -6,7 +6,16 @@ import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
 import b4a from 'b4a'
 
-import { NAMESPACE, SINGLE, COLLECTION, ACTION, ACTIVE, PASSIVE, REMOVE } from '../lib/constants.js'
+import {
+  NAMESPACE,
+  SINGLE,
+  COLLECTION,
+  ACTION,
+  ACTIVE,
+  PASSIVE,
+  REMOVE,
+  QUERY_RESERVED
+} from '../lib/constants.js'
 import {
   genId,
   toId,
@@ -14,10 +23,11 @@ import {
   can,
   subscribe,
   addWriterPayload,
-  claimWriterPayload
+  claimWriterPayload,
+  searchHit
 } from '../lib/utils.js'
 import { wrap, unwrap } from './envelope.js'
-import { EpochAutobee, Keyring, wraps, epochEntries } from './encryption.js'
+import { EpochAutobee, Keyring, wraps, epochEntries, loadEpochs } from './encryption.js'
 import { Identity } from '../identity/index.js'
 import { CeroError } from '../lib/errors.js'
 import { bootstrap } from './bootstrap.js'
@@ -133,6 +143,20 @@ export class Database extends ReadyResource {
 
   /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
   async openBee() {
+    // prime the keyring from the local core's epoch stash BEFORE boot — the
+    // bee's own boot reads post-rotation state through the epoch provider
+    const local = this.store.namespace(this.namespace).get({
+      keyPair: this.keyPair,
+      manifest: {
+        version: this.store.manifestVersion,
+        signers: [{ publicKey: this.keyPair.publicKey }]
+      },
+      active: false
+    })
+    await local.ready()
+    await loadEpochs(this.keyring, local)
+    await local.close()
+
     this.dispatcher = makeDispatcher(
       this.spec,
       this.ns,
@@ -676,7 +700,7 @@ export class Database extends ReadyResource {
     try {
       const rows = await this.view.find(`@${this.ns}/epochs`, {}).toArray()
       for (const row of rows) {
-        if (this.keyring.entropy(row.epoch)) continue
+        if (this.keyring.entropy(row.stamp)) continue
         await this._onEpoch(row)
       }
     } catch {
@@ -735,31 +759,33 @@ export class Database extends ReadyResource {
   }
 
   /**
-   * Batch every write performed inside `fn` into a single autobee append.
-   * Nested calls reuse the outer queue.
+   * Batch every write made through the transaction handle passed to `fn`
+   * into a single autobee append. The handle is this database with its own
+   * write queue — same surface (`put`/`set`/`del`/`call`), but writes buffer
+   * until `fn` returns, and are discarded if it throws. Writes made on the
+   * database itself meanwhile append normally: an unrelated concurrent write
+   * can never be swallowed into (and rolled back with) a transaction.
+   * Nested `tx()` on the handle joins the same batch.
    *
    * @template T
-   * @param {() => Promise<T> | T} fn
+   * @param {(tx: Database) => Promise<T> | T} fn
    * @returns {Promise<T>}
    */
   async tx(fn) {
-    // Nested tx() (called while an outer tx's fn is running) joins the outer queue.
-    if (this.txQueue) return fn()
-    // Outer transactions serialize — the run is deferred onto a chain so two
-    // concurrent tx() calls each get their own queue instead of the second
-    // buffering into the first's (and being dropped if the first rolls back).
+    // The old form batched ambiently — writes on the database itself would
+    // silently lose atomicity now, so refuse a fn that ignores the handle.
+    if (typeof fn !== 'function' || fn.length < 1) {
+      throw CeroError.INVALID('tx(fn) — fn must accept the transaction handle: tx((tx) => ...)')
+    }
+    // Nested tx() (called on a transaction handle) joins the same batch.
+    if (this.txQueue) return fn(this)
+    // Outer transactions serialize so their appends land in call order.
     const run = async () => {
-      const queue = []
-      this.txQueue = queue
-      try {
-        const result = await fn()
-        this.txQueue = null
-        if (queue.length) await this.write(queue)
-        return result
-      } catch (err) {
-        this.txQueue = null
-        throw err
-      }
+      const batch = Object.create(this)
+      batch.txQueue = []
+      const result = await fn(batch)
+      if (batch.txQueue.length) await this.write(batch.txQueue)
+      return result
     }
     const prev = this._txChain || Promise.resolve()
     // chain past prev's outcome so one failure doesn't wedge later transactions
@@ -1139,7 +1165,7 @@ export class Database extends ReadyResource {
   matchIndex(name, query) {
     const indexes = this.refs[name]?.indexes
     if (!indexes || !query) return null
-    const fields = Object.keys(query).filter((k) => !INDEX_RESERVED.has(k))
+    const fields = Object.keys(query).filter((k) => !QUERY_RESERVED.has(k))
     if (fields.length === 0) return null
     for (const [idx, idxFields] of Object.entries(indexes)) {
       if (idxFields.length === fields.length && idxFields.every((f) => fields.includes(f))) {
@@ -1182,17 +1208,6 @@ export class Database extends ReadyResource {
   }
 }
 
-const INDEX_RESERVED = new Set([
-  'gt',
-  'gte',
-  'lt',
-  'lte',
-  'limit',
-  'reverse',
-  'search',
-  'fields',
-  'total'
-])
 // Fields the write path stamps itself — always allowed even if not user-declared.
 const SYSTEM_FIELDS = new Set(['id', 'memberId', 'index', 'createdAt', 'updatedAt'])
 
@@ -1232,7 +1247,7 @@ function paginate(rows, query) {
   // index is an optimization, not a correctness gate — so an unindexed field, or
   // one passed alongside search/range, still filters instead of silently dropping.
   for (const key of Object.keys(query)) {
-    if (INDEX_RESERVED.has(key)) continue
+    if (QUERY_RESERVED.has(key)) continue
     out = out.filter((r) => valueEq(r[key], query[key]))
   }
   if (query.gt !== undefined) out = out.filter((r) => r.id > query.gt)
@@ -1244,22 +1259,3 @@ function paginate(rows, query) {
   if (query.limit !== undefined) out = out.slice(0, query.limit)
   return out
 }
-
-// Lowercase, fold diacritics ('jose' → 'José'), drop whitespace.
-const fold = (s) =>
-  s
-    .normalize('NFD')
-    .replace(/\p{Diacritic}/gu, '')
-    .toLowerCase()
-    .replace(/\s/g, '')
-
-// keet's message-search style: every term must be a substring of `fields` (or
-// every string field). 'smith' → 'John Smith', 'jo sm' → both must appear.
-function searchHit(row, term, fields) {
-  const terms = String(term).split(/\s+/).map(fold).filter(Boolean)
-  // default to all fields except memberId — a framework-stamped random z32 whose value would
-  // otherwise produce spurious, non-deterministic search hits (user-set id/code stay searchable)
-  const keys = fields && fields.length ? fields : Object.keys(row).filter((k) => k !== 'memberId')
-  const hay = keys.map((k) => (typeof row[k] === 'string' ? fold(row[k]) : '')).join(' ')
-  return terms.every((t) => hay.includes(t))
-}

package/src/lib/constants.js

@@ -40,6 +40,20 @@ export const RANK = { [OWNER]: 3, [ADMIN]: 2, [MEMBER]: 1, [READER]: 0 }
 // Identity / hypercore namespace
 export const NAMESPACE = 'cero'
 
+// Query-grammar keys — everything else in a query object is an equality field.
+// One set shared by both backends (Database and Storage) so they cannot drift.
+export const QUERY_RESERVED = new Set([
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'limit',
+  'reverse',
+  'search',
+  'fields',
+  'total'
+])
+
 // Internal counter collection (assigns monotonic `index` to every row in every collection)
 export const COUNTERS = 'counters'
 // Internal key-rotation epoch collection (rotation announcements with sealed envelopes)

package/src/lib/utils.js

@@ -115,3 +115,22 @@ export function subscribe({ get, watch }) {
   push()
   return stream
 }
+
+// Lowercase, fold diacritics ('jose' → 'José'), drop whitespace.
+const fold = (s) =>
+  s
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase()
+    .replace(/\s/g, '')
+
+// keet's message-search style: every term must be a substring of `fields` (or
+// every string field). 'smith' → 'John Smith', 'jo sm' → both must appear.
+export function searchHit(row, term, fields) {
+  const terms = String(term).split(/\s+/).map(fold).filter(Boolean)
+  // default to all fields except memberId — a framework-stamped random z32 whose value would
+  // otherwise produce spurious, non-deterministic search hits (user-set id/code stay searchable)
+  const keys = fields && fields.length ? fields : Object.keys(row).filter((k) => k !== 'memberId')
+  const hay = keys.map((k) => (typeof row[k] === 'string' ? fold(row[k]) : '')).join(' ')
+  return terms.every((t) => hay.includes(t))
+}