@cero-base/core 1.1.0 → 1.2.0

package/README.md

@@ -92,7 +92,7 @@ db.before('put', (ctx) => {
 
 ## Blobs
 
-Content-addressed Hyperblobs store. Returns z32 ids you can hand back to `get`/`read`/`has`.
+Content-addressed Hyperblobs store. `put(bytes)` returns a blob id you hand back to `get` (or `clear` to reclaim space).
 
 ```js
 import { Blobs } from '@cero-base/core/blobs'
@@ -186,17 +186,19 @@ try {
 
 Generic:
 
-| Code           | Thrown when                                                                    |
-| -------------- | ------------------------------------------------------------------------------ |
-| `REQUIRED`     | A constructor or function arg is missing (`store`, `identity`, `spec`, …)      |
-| `INVALID`      | Arg has the wrong shape/type (`publicKey must be a 32-byte buffer`)            |
-| `CLOSED`       | You called a method on a closed `Database`, `Storage`, `Network`, `Pairing`, … |
-| `NOT_READY`    | You called a method before `await x.ready()`                                   |
-| `DESTROYED`    | A `Discovery` is destroyed                                                     |
-| `UNKNOWN`      | Asked for a `ref`, `handle`, or other thing that doesn't exist                 |
-| `NOT_WRITABLE` | Tried to write to a `Database` whose local writer isn't admitted yet           |
-| `TIMED_OUT`    | A bounded wait elapsed (`until(...)` etc.)                                     |
-| `UNSUPPORTED`  | Feature not yet wired (nested handles, …)                                      |
+| Code               | Thrown when                                                                    |
+| ------------------ | ------------------------------------------------------------------------------ |
+| `REQUIRED`         | A constructor or function arg is missing (`store`, `identity`, `spec`, …)      |
+| `INVALID`          | Arg has the wrong shape/type (`publicKey must be a 32-byte buffer`)            |
+| `CLOSED`           | You called a method on a closed `Database`, `Storage`, `Network`, `Pairing`, … |
+| `NOT_READY`        | You called a method before `await x.ready()`                                   |
+| `DESTROYED`        | A `Discovery` is destroyed                                                     |
+| `UNKNOWN`          | Asked for a `ref`, `handle`, or other thing that doesn't exist                 |
+| `NOT_WRITABLE`     | Tried to write to a `Database` whose local writer isn't admitted yet           |
+| `TIMED_OUT`        | A bounded wait elapsed (`until(...)` etc.)                                     |
+| `UNSUPPORTED`      | Feature not yet wired (nested handles, …)                                      |
+| `CHANNEL_MISMATCH` | Storage stamped with one `channel` reopened under another (or none)            |
+| `CONFLICT`         | The operation raced an existing state (e.g. double init)                       |
 
 Pairing-specific:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,
@@ -18,7 +18,8 @@
     "src",
     "types",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -40,6 +41,10 @@
       "types": "./types/network/index.d.ts",
       "default": "./src/network/index.js"
     },
+    "./network/bluetooth": {
+      "types": "./types/network/bluetooth.d.ts",
+      "default": "./src/network/bluetooth.js"
+    },
     "./database": {
       "types": "./types/database/index.d.ts",
       "default": "./src/database/index.js"
@@ -49,9 +54,11 @@
       "default": "./src/blobs/index.js"
     },
     "./blobs/codec": {
+      "types": "./types/blobs/codec.d.ts",
       "default": "./src/blobs/codec.js"
     },
     "./blobs/server": {
+      "types": "./types/blobs/server.d.ts",
       "default": "./src/blobs/server.js"
     },
     "./rpc": {
@@ -118,9 +125,11 @@
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
-    "test": "brittle-node test/*.test.js"
+    "test": "brittle-node test/*.test.js",
+    "test:bare": "npx bare test/bare-smoke.js"
   },
   "dependencies": {
+    "@hyperswarm/secret-stream": "^6.9.1",
     "autobee": "^1.0.9",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.15.3",
@@ -133,8 +142,8 @@
     "framed-stream": "^1.0.1",
     "hrpc": "^4.3.0",
     "hyperblobs": "^2.12.1",
-    "hypercore-blob-server": "^1.12.0",
     "hypercore": "^11.33.1",
+    "hypercore-blob-server": "^1.12.0",
     "hypercore-crypto": "^3.7.0",
     "hypercore-id-encoding": "^1.3.0",
     "hypercore-storage": "^3.1.1",

package/src/blobs/index.js

@@ -103,7 +103,7 @@ export class Blobs extends ReadyResource {
   async put(input) {
     this._guard()
     if (input == null) throw CeroError.REQUIRED('input')
-    if (b4a.isBuffer(input)) return this.hyperblobs.put(b4a.from(input))
+    if (b4a.isBuffer(input)) return this.hyperblobs.put(b4a.toBuffer(input))
     if (isReadable(input)) return this._putStream(input)
     throw CeroError.INVALID('input must be a buffer or a Readable stream')
   }

package/src/database/bootstrap.js

@@ -2,7 +2,7 @@ import b4a from 'b4a'
 import Hypercore from 'hypercore'
 import { Identity } from '../identity/index.js'
 import { CeroError } from '../lib/errors.js'
-import { toId } from '../lib/utils.js'
+import { toId, addWriterPayload } from '../lib/utils.js'
 
 /**
  * First-run device provisioning: mint a device writer keypair, persist it as a
@@ -62,7 +62,7 @@ async function saveWriter(db, writerKey, { name, isMobile }) {
       {
         master: db.identity.publicKey,
         writer: writerKey,
-        sig: db.identity.sign(b4a.concat([writerKey, db.writerKey]))
+        sig: db.identity.sign(addWriterPayload(db.key, writerKey, db.writerKey))
       }
     ],
     [

package/src/database/dispatch.js

@@ -1,4 +1,5 @@
 import b4a from 'b4a'
+import safetyCatch from 'safety-catch'
 
 import {
   SINGLE,
@@ -10,7 +11,16 @@ import {
   ASSIGN,
   WRITE
 } from '../lib/constants.js'
-import { toId, toKey, can, grants, outranks } from '../lib/utils.js'
+import {
+  toId,
+  toKey,
+  can,
+  grants,
+  outranks,
+  addWriterPayload,
+  claimWriterPayload
+} from '../lib/utils.js'
+import { CeroError } from '../lib/errors.js'
 import { Identity } from '../identity/index.js'
 
 // Built-in collections wired into every cero spec.
@@ -22,6 +32,11 @@ export const BUILTINS = [
   { name: 'files', verb: 'file' }
 ]
 
+// Remote op fields are variable-length buffers on the wire — reject wrong sizes
+// before they reach sodium/toId, which throw instead of returning false.
+const isKey = (b) => b?.byteLength === 32
+const isSig = (b) => b?.byteLength === 64
+
 /**
  * Build the hyperdispatch router for a spec: wires membership, builtin, and
  * spec-defined collection/action ops, returning the router plus an apply loop.
@@ -29,9 +44,10 @@ export const BUILTINS = [
  * @param {{ dispatch: { Router: Function }, meta?: { refs?: Record<string, { kind?: string, builtin?: boolean, verb?: string }> } }} spec  Generated hyperdispatch spec.
  * @param {string} ns  Namespace prefix for collection and op names.
  * @param {Record<string, Function>} routes  Custom action handlers keyed by route name.
+ * @param {(err: Error) => void} [onerror]  Called when a malformed node is skipped.
  * @returns {{ dispatcher: object, apply: (nodes: Array<{ value: Buffer, key: Buffer }>, view: object, host: object) => Promise<void> }}
  */
-export function makeDispatcher(spec, ns, routes) {
+export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey = () => null) {
   const dispatcher = new spec.dispatch.Router()
 
   const countersCol = `@${ns}/${COUNTERS}`
@@ -85,7 +101,8 @@ export function makeDispatcher(spec, ns, routes) {
   const add = (verb, fn) => dispatcher.add(`@${ns}/${verb}`, fn)
 
   add('add-writer', async (op, ctx) => {
-    if (!Identity.verify(op.master, b4a.concat([op.writer, ctx.key]), op.sig)) return
+    if (!isKey(op.master) || !isKey(op.writer) || !isSig(op.sig)) return
+    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()
@@ -98,6 +115,7 @@ export function makeDispatcher(spec, ns, routes) {
   })
 
   add('del-writer', async (op, ctx) => {
+    if (!isKey(op.writer)) return
     const target = await getDevice(ctx.view, toId(op.writer))
     if (target?.memberId !== (await getSignerMember(ctx.view, ctx.key))) {
       if (!(await canRemoveMember(ctx.view, ctx.key, target?.memberId))) return
@@ -107,7 +125,8 @@ export function makeDispatcher(spec, ns, routes) {
   })
 
   add('claim-writer', async (op, ctx) => {
-    if (!Identity.verify(op.identity, op.writer, op.sig)) return
+    if (!isKey(op.identity) || !isKey(op.writer) || !isSig(op.sig)) return
+    if (!Identity.verify(op.identity, claimWriterPayload(ctx.dbKey, op.writer), op.sig)) return
     if (!b4a.equals(ctx.key, op.writer)) return
     const memberId = toId(op.identity)
     if (!can(await getRole(ctx.view, op.identity), WRITE)) return
@@ -122,6 +141,7 @@ export function makeDispatcher(spec, ns, routes) {
   })
 
   add('add-member', async (op, ctx) => {
+    if (!isKey(op.key)) return
     if (!(await isGenesis(ctx.view))) {
       const r = await getSignerRole(ctx.view, ctx.key)
       if (!can(r, INVITE) || !grants(r, op.role)) return
@@ -210,7 +230,15 @@ export function makeDispatcher(spec, ns, routes) {
     if (info.builtin) continue
     if (info.kind === 'handle') continue
     if (info.kind === ACTION) {
-      add(name, routes[name] || (async () => {}))
+      // a replicated action with no local route is a peer misconfiguration —
+      // surface it instead of silently diverging from peers that ran it
+      add(
+        name,
+        routes[name] ||
+          (async () => {
+            onerror(CeroError.UNKNOWN('route', name))
+          })
+      )
       continue
     }
     const col = `@${ns}/${name}`
@@ -228,8 +256,15 @@ export function makeDispatcher(spec, ns, routes) {
   return {
     dispatcher,
     async apply(nodes, view, host) {
+      const dbKey = getDbKey()
       for (const node of nodes) {
-        await dispatcher.dispatch(node.value, { view, host, key: node.key })
+        try {
+          await dispatcher.dispatch(node.value, { view, host, key: node.key, dbKey })
+        } catch (err) {
+          // deterministic skip: dispatch depends only on node.value and view
+          // state, so every peer drops the same bad node and stays convergent
+          onerror(err)
+        }
       }
       await view.flush()
     }

package/src/database/index.js

@@ -5,8 +5,8 @@ import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
 import b4a from 'b4a'
 
-import { NAMESPACE, SINGLE, COLLECTION, ACTION } from '../lib/constants.js'
-import { genId, subscribe } from '../lib/utils.js'
+import { NAMESPACE, SINGLE, COLLECTION, ACTION, ACTIVE, PASSIVE } from '../lib/constants.js'
+import { genId, subscribe, addWriterPayload, claimWriterPayload } from '../lib/utils.js'
 import { CeroError } from '../lib/errors.js'
 import { bootstrap } from './bootstrap.js'
 import { makeDispatcher } from './dispatch.js'
@@ -22,12 +22,13 @@ import { makeDispatcher } from './dispatch.js'
  * @property {Uint8Array | null} [encryptionKey]                      Optional encryption key; falls back to identity's key.
  * @property {(nodes: any, view: any, host: any) => Promise<void>} [apply]  Override the default apply function.
  * @property {Uint8Array | null} [key]                                Existing autobee key to reopen.
+ * @property {boolean} [passive]                                      Join discovery server-only (reachable but not searching). Flip at runtime with `setActive`.
  * @property {import('../identity/index.js').KeyPair} [keyPair]       Device writer keypair; defaults to identity's keypair.
- * @property {(err: Error) => void} [onerror]                         Called when a background after-hook or onApply callback fails.
+ * @property {(err: Error) => void} [onerror]                         Called when a background after-hook or onApply callback fails, a malformed node is skipped, or the bee errors.
  *
  * @typedef {{ data: any | null }} SingleResult
- * @typedef {{ data: any[], total: number, size: number }} ListResult
- * @typedef {{ gt?: string, gte?: string, lt?: string, lte?: string, reverse?: boolean, limit?: number, search?: string, fields?: string[] }} Query
+ * @typedef {{ data: any[], total: number | null, size: number }} ListResult  `total` is null when a limited read skipped the full count — pass `{ total: true }` to force it.
+ * @typedef {{ gt?: string, gte?: string, lt?: string, lte?: string, reverse?: boolean, limit?: number, search?: string, fields?: string[], total?: boolean }} Query
  * @typedef {{ kind: string, verb: string, name: string }} Ref
  * @typedef {(ctx: any) => any | Promise<any>} HookFn
  */
@@ -61,6 +62,7 @@ export class Database extends ReadyResource {
     this.encryptionKey = opts.encryptionKey || opts.identity.encryptionKey || null
     this.applyOverride = opts.apply || null
     this.key = opts.key || null
+    this.passive = opts.passive === true
     this.keyPair = opts.keyPair || {
       publicKey: opts.identity.publicKey,
       secretKey: opts.identity.secretKey
@@ -72,9 +74,10 @@ export class Database extends ReadyResource {
 
     this.beforeHooks = new Map()
     this.afterHooks = new Map()
-    this.updaters = new Set()
+    this.updaters = new Map()
     this.onApplyHooks = new Set()
     this._applySeq = 0
+    this._touched = new Set()
     this.txQueue = null
   }
 
@@ -101,22 +104,41 @@ export class Database extends ReadyResource {
 
   /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
   async openBee() {
-    this.dispatcher = makeDispatcher(this.spec, this.ns, this.routes)
+    this.dispatcher = makeDispatcher(this.spec, this.ns, this.routes, this._onerror, () => this.key)
+
+    // autobee-wakeup destroys whatever wakeup it is handed (its _owner guard is
+    // computed but never consulted upstream) — closing one bee must not tear
+    // down the network-shared protocol, so each bee gets a non-owning facade.
+    // Drop the facade once upstream honors _owner.
+    const shared = this.network?.wakeup
+    const wakeup = shared && {
+      addStream: (s) => shared.addStream(s),
+      session: (...args) => shared.session(...args),
+      destroy: () => {}
+    }
 
     const bee = new Autobee(this.store.namespace(this.namespace), this.key, {
       keyPair: this.keyPair,
       encryptionKey: this.encryptionKey,
       optimistic: true,
-      wakeup: this.network?.wakeup || undefined,
+      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)
         return result
       },
       update: async (db) => {
         await db.update()
-        for (const fn of this.updaters) fn()
+        // fire only watchers whose ref was touched by this apply batch —
+        // unscoped watchers (and undecodable nodes, '*') fire everything
+        const touched = this._touched
+        this._touched = new Set()
+        const all = touched.size === 0 || touched.has('*')
+        for (const [fn, scope] of this.updaters) {
+          if (all || !scope || touched.has(scope)) fn()
+        }
         this.emit('update')
       }
     })
@@ -128,16 +150,32 @@ export class Database extends ReadyResource {
     this.key = bee.key
 
     bee.on('writable', () => this.emit('writable'))
+    // without a listener autobee escalates apply/view errors to a process crash
+    bee.on('error', this._onerror)
 
     if (this.network) {
       this.network.attach(bee)
       // a writer swap re-opens the bee — tear down the prior discovery session
       // first so it isn't orphaned by the reassignment below
       if (this._discovery) await this._discovery.destroy()
-      this._discovery = this.network.join(bee.discoveryKey)
+      this._discovery = this.network.join(bee.discoveryKey, {
+        mode: this.passive ? PASSIVE : ACTIVE
+      })
     }
   }
 
+  /**
+   * Flip announce mode at runtime — passive stays reachable (server) but
+   * stops actively looking (client). Cheap; use it to demote idle rooms.
+   *
+   * @param {boolean} active
+   * @returns {Promise<void>}
+   */
+  async setActive(active) {
+    if (!this._discovery) return
+    await (active ? this._discovery.activate() : this._discovery.deactivate())
+  }
+
   /** @returns {Uint8Array | null} discovery key of the underlying bee */
   get discoveryKey() {
     return this.bee?.discoveryKey || null
@@ -186,16 +224,43 @@ export class Database extends ReadyResource {
   }
 
   /**
-   * Subscribe to local apply notifications. Fires whenever the view updates.
+   * Subscribe to local apply notifications. Fires whenever the view updates;
+   * pass `scope` (a ref name) to fire only when that ref was touched.
    *
    * @param {() => void} fn
+   * @param {string} [scope]
    * @returns {() => void} disposer
    */
-  onUpdate(fn) {
-    this.updaters.add(fn)
+  onUpdate(fn, scope) {
+    this.updaters.set(fn, scope || null)
     return () => this.updaters.delete(fn)
   }
 
+  // record which refs an apply batch mutated, so update only wakes their watchers
+  _touch(nodes) {
+    if (!this._byVerb) {
+      this._byVerb = new Map()
+      for (const [name, info] of Object.entries(this.refs)) {
+        this._byVerb.set(info.verb || name, name)
+        this._byVerb.set(name, name)
+      }
+    }
+    for (const node of nodes) {
+      try {
+        const { name } = this.spec.dispatch.decode(node.value)
+        const verb = name.slice(name.indexOf('/') + 1)
+        const dash = verb.indexOf('-')
+        const target = dash < 0 ? verb : verb.slice(dash + 1)
+        const ref = this._byVerb.get(target)
+        // an action's route handler writes wherever it wants — widen to all
+        if (!ref || this.refs[ref]?.kind === ACTION) this._touched.add('*')
+        else this._touched.add(ref)
+      } catch {
+        this._touched.add('*')
+      }
+    }
+  }
+
   /**
    * Observe every applied op — local AND replicated (apply processes the merged
    * log). The callback receives `{ op, name, row, writerKey, seq }` and runs
@@ -469,6 +534,34 @@ export class Database extends ReadyResource {
       return { data, total: rows.length, size: data.length }
     }
 
+    // Hot path — reverse/limit only ("latest 50 messages"): read straight off
+    // the implicit `index` order index, touching ≤ limit rows instead of the
+    // whole collection. `total` is then lazy: pass { total: true } to pay for
+    // the full count, otherwise it's null when unknowable for free.
+    if (this.refs[name]?.orderIndex && pushable(query) && (await this._orderReady(name, col))) {
+      const rows = await this.view
+        .find(`@${this.ns}/${name}-index`, {
+          reverse: query?.reverse === true,
+          limit: query?.limit
+        })
+        .toArray()
+      const total = await this._total(col, query, rows)
+      return { data: rows, total, size: rows.length }
+    }
+
+    // id-range cursor: push the range down (bounded read), keep index order.
+    if (this.refs[name]?.orderIndex && pushableRange(query)) {
+      const range = {}
+      for (const k of ['gt', 'gte', 'lt', 'lte']) {
+        if (query[k] !== undefined) range[k] = { id: query[k] }
+      }
+      const rows = await this.view.find(col, range).toArray()
+      rows.sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+      if (query.reverse) rows.reverse()
+      const data = query.limit !== undefined ? rows.slice(0, query.limit) : rows
+      return { data, total: rows.length, size: data.length }
+    }
+
     const all = await this.view.find(col, {}).toArray()
     // collections carry an auto-increment `index`; return them in that order
     all.sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
@@ -477,6 +570,40 @@ export class Database extends ReadyResource {
     return { data, total, size: data.length }
   }
 
+  // hyperdb never backfills an index added after rows were written — a store
+  // upgraded to a spec with the implicit order index would silently drop its
+  // legacy rows from pushed-down reads. Verify completeness ONCE per open
+  // (two scans, cached), then trust the index; incomplete → fall back + warn.
+  async _orderReady(name, col) {
+    if (!this._orderOk) this._orderOk = new Map()
+    let ok = this._orderOk.get(name)
+    if (ok === undefined) {
+      const [rows, indexed] = await Promise.all([
+        this.view.find(col, {}).toArray(),
+        this.view.find(`@${this.ns}/${name}-index`, {}).toArray()
+      ])
+      ok = rows.length === indexed.length
+      this._orderOk.set(name, ok)
+      if (!ok) {
+        this._onerror(
+          CeroError.INVALID(
+            `order index for '${name}' is incomplete (store predates it) — reads fall back to full scans; recreate the store to accelerate`
+          )
+        )
+      }
+    }
+    return ok
+  }
+
+  // total for a pushed-down read: free when the page IS the whole set (no
+  // limit, or a non-full page), a full count only when explicitly requested
+  // via { total: true }, null otherwise.
+  async _total(col, query, rows) {
+    if (query?.total) return (await this.view.find(col, {}).toArray()).length
+    if (query?.limit === undefined || rows.length < query.limit) return rows.length
+    return null
+  }
+
   /**
    * Number of rows that match `query` (or total if omitted).
    *
@@ -503,7 +630,7 @@ export class Database extends ReadyResource {
     this.guard()
     return subscribe({
       get: () => this.get(name, query),
-      watch: (fn) => this.onUpdate(fn)
+      watch: (fn) => this.onUpdate(fn, name)
     })
   }
 
@@ -530,7 +657,7 @@ export class Database extends ReadyResource {
     if (this.bee.writable) return
 
     const writerKey = this.writerKey
-    const sig = this.identity.sign(writerKey)
+    const sig = this.identity.sign(claimWriterPayload(this.key, writerKey))
     const encoded = this.spec.dispatch.encode(`@${this.ns}/claim-writer`, {
       identity: this.identity.publicKey,
       writer: writerKey,
@@ -698,13 +825,23 @@ export class Database extends ReadyResource {
       version: this.store.manifestVersion,
       signers: [{ publicKey }]
     })
-    const sig = this.identity.sign(b4a.concat([writerKey, this.writerKey]))
+    const sig = this.identity.sign(addWriterPayload(this.key, writerKey, this.writerKey))
     await this.write([[verb, { master: this.identity.publicKey, writer: writerKey, sig }]])
     await this.runAfter(hook, ctx)
   }
 }
 
-const INDEX_RESERVED = new Set(['gt', 'gte', 'lt', 'lte', 'limit', 'reverse', 'search', 'fields'])
+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'])
 
@@ -714,6 +851,29 @@ const valueEq = (a, b) => {
   return a === b
 }
 
+// reverse/limit (+ the total flag) only — safe to serve straight off the order index
+function pushable(query) {
+  if (!query) return true
+  return Object.keys(query).every((k) => k === 'reverse' || k === 'limit' || k === 'total')
+}
+
+// an id-range with no equality/search — the range pushes down, order stays in memory
+function pushableRange(query) {
+  if (!query) return false
+  const keys = Object.keys(query)
+  if (!keys.some((k) => k === 'gt' || k === 'gte' || k === 'lt' || k === 'lte')) return false
+  return keys.every(
+    (k) =>
+      k === 'gt' ||
+      k === 'gte' ||
+      k === 'lt' ||
+      k === 'lte' ||
+      k === 'reverse' ||
+      k === 'limit' ||
+      k === 'total'
+  )
+}
+
 function paginate(rows, query) {
   if (!query) return rows
   let out = rows

package/src/identity/index.js

@@ -52,6 +52,20 @@ export class Identity {
     Object.freeze(this)
   }
 
+  /**
+   * Redacted — secretKey/encryptionKey/seed must never reach JSON.stringify
+   * or a structured logger.
+   *
+   * @returns {{ id: string }}
+   */
+  toJSON() {
+    return { id: this.id }
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return `Identity(${this.id})`
+  }
+
   /**
    * Detached Ed25519 signature over `message`.
    *
@@ -220,7 +234,7 @@ export class Identity {
    * @returns {Uint8Array}
    */
   static randomSeed(words = 12) {
-    if (words !== 12 && words !== 24) throw new RangeError('words must be 12 or 24')
+    if (words !== 12 && words !== 24) throw CeroError.INVALID('words must be 12 or 24')
     return Identity.randomBytes((words / 3) * 4)
   }
 }

package/src/lib/errors.js

@@ -72,6 +72,14 @@ export class CeroError extends Error {
   static NOT_READY(resource, name) {
     return new CeroError('NOT_READY', `${resource} is not ready — await ${name}.ready() first`)
   }
+  /**
+   * Operation raced an existing state (e.g. double init).
+   *
+   * @param {string} msg
+   */
+  static CONFLICT(msg) {
+    return new CeroError('CONFLICT', msg)
+  }
   /**
    * Resource has been destroyed.
    *