@cero-base/cero 1.17.0 → 1.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -95,12 +95,12 @@
     "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.17.0",
+    "@cero-base/core": "^1.18.1",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.8.1",
-    "bare-path": "^3.1.1",
+    "bare-path": "^3.1.2",
     "ble-swarm": "^2.3.0",
     "compact-encoding": "^3.3.2",
     "corestore": "^7.12.2",
@@ -110,7 +110,7 @@
     "hypercore-storage": "^3.2.1",
     "hyperdb": "^6.9.0",
     "hyperdispatch": "^1.6.0",
-    "hyperschema": "^1.22.0",
+    "hyperschema": "^1.23.0",
     "ready-resource": "^1.2.0",
     "safety-catch": "^1.0.3",
     "streamx": "^2.28.1",
@@ -120,10 +120,10 @@
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
     "bare-events": "^2.9.2",
-    "bare-fetch": "^3.2.0",
+    "bare-fetch": "^3.2.1",
     "bare-process": "^4.5.1",
-    "bare-url": "^2.5.2",
-    "brittle": "^4.1.0",
+    "bare-url": "^2.5.4",
+    "brittle": "^4.1.1",
     "typescript": "^5.9.3"
   },
   "license": "Apache-2.0"

package/src/build/builtins.js

@@ -24,7 +24,9 @@ export const refs = {
   }
 }
 
-export const getHyperdbType = (prim) => DB_TYPE[prim] || 'string'
+export function getHyperdbType(prim) {
+  return DB_TYPE[prim] || 'string'
+}
 
 const at = (ns, n) => `@${ns}/${n}`
 const keyOf = (def) => (def.kind === 'single' ? [] : ['id'])
@@ -39,9 +41,11 @@ const fields = (map) =>
 // Merge app `t.extend` fields into a builtin's base fields — base can't be redeclared.
 const merge = (type, base, extra) => {
   if (!extra) return base
-  for (const k in extra)
-    if (k in base)
+  for (const k in extra) {
+    if (k in base) {
       throw CeroError.INVALID(`'${k}' is a base field of '${type}' and cannot be redeclared`)
+    }
+  }
   return { ...base, ...extra }
 }
 
@@ -53,8 +57,8 @@ const descriptors = (group, extend = {}) =>
   }))
 
 // meta.refs entries for a scope's builtins.
-export const builtinRefs = (ns, scope) =>
-  Object.fromEntries(
+export function builtinRefs(ns, scope) {
+  return Object.fromEntries(
     Object.entries(refs[scope]).map(([name, def]) => [
       name,
       {
@@ -66,14 +70,19 @@ export const builtinRefs = (ns, scope) =>
       }
     ])
   )
+}
 
 // hyperschema type descriptors. scope is 'main' | 'local' | 'rpc'; `extend`
 // merges app `t.extend` fields into the matching type.
-export const builtinTypes = (scope, extend) => descriptors(schemas[scope], extend)
-export const rpcTypes = () => descriptors(schemas.rpc)
+export function builtinTypes(scope, extend) {
+  return descriptors(schemas[scope], extend)
+}
+export function rpcTypes() {
+  return descriptors(schemas.rpc)
+}
 
 // hyperdb collection descriptors for a scope.
-export const builtinCollections = (ns, scope) => {
+export function builtinCollections(ns, scope) {
   const out = Object.entries(refs[scope]).map(([name, def]) => ({
     name,
     schema: at(ns, def.type),
@@ -87,25 +96,29 @@ export const builtinCollections = (ns, scope) => {
 }
 
 // hyperdispatch descriptors (main scope only).
-export const builtinDispatches = (ns) => [
-  { name: 'add-writer', requestType: at(ns, 'writer') },
-  { name: 'del-writer', requestType: at(ns, 'writer') },
-  { name: 'claim-writer', requestType: at(ns, 'claim') },
-  ...Object.values(refs.main).flatMap(({ type }) => [
-    { name: `add-${type}`, requestType: at(ns, type) },
-    { name: `set-${type}`, requestType: at(ns, type) },
-    { name: `del-${type}`, requestType: at(ns, 'del-by-id') }
-  ])
-]
+export function builtinDispatches(ns) {
+  return [
+    { name: 'add-writer', requestType: at(ns, 'writer') },
+    { name: 'del-writer', requestType: at(ns, 'writer') },
+    { name: 'claim-writer', requestType: at(ns, 'claim') },
+    ...Object.values(refs.main).flatMap(({ type }) => [
+      { name: `add-${type}`, requestType: at(ns, type) },
+      { name: `set-${type}`, requestType: at(ns, type) },
+      { name: `del-${type}`, requestType: at(ns, 'del-by-id') }
+    ])
+  ]
+}
 
 // Registered AFTER the app's own dispatches (see build/index.js): hyperdispatch
 // numbers routes positionally and persists them, so a spec built before
 // rotation must see rotate-key appended at the end — inserting it into the
 // builtin group would collide with the app's persisted route ids on an
 // incremental rebuild.
-export const rotateDispatch = (ns) => ({ name: 'rotate-key', requestType: at(ns, 'epoch') })
+export function rotateDispatch(ns) {
+  return { name: 'rotate-key', requestType: at(ns, 'epoch') }
+}
 
-export const rpcCommands = (ns) => {
+export function rpcCommands(ns) {
   const ref = (n) => at(ns, n)
   return [
     { name: 'init', request: { name: ref('req-empty') }, response: { name: ref('res-identity') } },

package/src/handle/index.js

@@ -12,7 +12,7 @@ import { Identity } from '@cero-base/core/identity'
 import { Database } from '@cero-base/core/database'
 import { epochEntries, blobEpochKey } from '@cero-base/core/database/encryption'
 import { Pairing } from '@cero-base/core/pairing'
-import { toId, grants, isRank, addWriterPayload } from '@cero-base/core/utils'
+import { toId, grants, can, isRank, addWriterPayload, REMOVE } from '@cero-base/core/utils'
 import { CeroError } from '@cero-base/core/errors'
 import { Blobs } from '@cero-base/core/blobs'
 import { decodeId } from '@cero-base/core/blobs/codec'
@@ -128,7 +128,7 @@ export class Handle extends ReadyResource {
     this._fileServer = null
     this._blobs = null
     this._epochBlobs = null
-    // root only — serializes suspend/resume, converges rapid bounces
+    // root only, serializes suspend/resume and converges rapid bounces
     this._sus = parent
       ? null
       : new Suspendify({ suspend: () => this._suspend(), resume: () => this._resume() })
@@ -165,9 +165,8 @@ export class Handle extends ReadyResource {
         }
       })
       await this.pair.ready()
-      // Serve invites persisted by any member — and keep the served set in
-      // step as rows replicate in (minted elsewhere) or disappear (revoked
-      // or consumed elsewhere).
+      // serve invites persisted by any member, and keep the set in step as rows
+      // replicate in or disappear (minted, revoked or consumed elsewhere)
       await this._syncInvites().catch(safetyCatch)
       this._invitesSync = () => this._syncInvites().catch(safetyCatch)
       this.store.on('update', this._invitesSync)
@@ -353,8 +352,7 @@ export class Handle extends ReadyResource {
     blobs
       .ready()
       .then(() => {
-        // close prunes _coreKeys first — a ready() resolving after that must
-        // not re-insert the entry (it would outlive the handle on the root)
+        // close prunes _coreKeys first, a late ready() must not re-insert the entry
         if (this.closing || this.closed || !blobs.key) return
         this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
       })
@@ -377,8 +375,7 @@ export class Handle extends ReadyResource {
       const { coreKey } = decodeId(id)
       const hex = b4a.toString(coreKey, 'hex')
       if (!this.root._coreKeys.has(hex)) {
-        // a file-field value carries no stamp — look it up from the files row
-        // (fire-and-forget: idempotent, resolution happens again per request)
+        // no stamp on a file-field value, look it up (fire-and-forget, idempotent)
         if (stamp === undefined) {
           this.store
             .get('files', id)
@@ -392,16 +389,14 @@ export class Handle extends ReadyResource {
         if (!key) return // unknown epoch — this device is not entitled to the core
         this.root._coreKeys.set(hex, key)
       }
-      // remember which handle read it, so close prunes the entry (re-registered
-      // on the next read if another handle still serves the same core)
+      // remember which handle read it, so close prunes the entry
       if (this !== this.root) (this._blobKeys ??= new Set()).add(hex)
     } catch {
       // ignore invalid ids
     }
   }
 
-  // Base-era blob cores use the OWNING handle's key (not the root's — rooms
-  // have their own keys); rotated-era cores derive from the epoch entropy.
+  // base-era cores use the OWNING handle's key, rooms have their own
   _blobCoreKey(stamp) {
     if (!stamp) return this.store.encryptionKey
     const entropy = this.store.keyring.entropy(stamp)
@@ -479,20 +474,17 @@ export class Handle extends ReadyResource {
    * @returns {Promise<string>}  Z32-encoded invite string.
    */
   async invite(opts) {
-    if (!this.pair)
+    if (!this.pair) {
       throw CeroError.INVALID(
         'invite() is not available on the root handle — open a child handle first'
       )
-    // An invite is a capability: whoever holds it is admitted. Cap it here or
-    // a member mints one above their own rank, and the mismatch only surfaces
-    // at apply — as a silent drop that still leaves the joiner admitted.
+    }
+    // an invite is a capability, cap the rank or apply drops the mismatch silently
     if (opts?.role !== undefined && opts.role !== '') await this._checkGrant(opts.role)
     const str = await this.pair.createInvite(opts)
     const record = this.pair.recordOf(str)
     if (record) {
-      // Persist so every member replica serves this invite across restarts —
-      // the in-memory record keeps working this session even if the write
-      // fails.
+      // persist so every member replica serves it across restarts
       await this.store
         .call('add-invite', {
           id: b4a.toString(record.id, 'hex'),
@@ -519,15 +511,20 @@ export class Handle extends ReadyResource {
    * Revoke a previously-minted invite by its string form.
    *
    * @param {string} invite
-   * @returns {boolean}  `true` if the invite was found and removed.
+   * @returns {Promise<boolean>}  `true` if the invite was found and removed.
    */
-  revoke(invite) {
+  async revoke(invite) {
     if (!this.pair) throw CeroError.INVALID('revoke() is not available on the root handle')
+    // apply refuses revoke below REMOVE, and other members would keep serving it
+    const { data: me } = await this.store.get('members', this.identity.id)
+    if (me && !can(me.role, REMOVE)) {
+      throw CeroError.DENIED(null, 'revoking an invite needs the remove permission')
+    }
     const record = this.pair.recordOf(invite)
     const revoked = this.pair.revoke(invite)
     if (revoked && record) {
       // drop the persisted row so every other member stops serving it too
-      this.store.call('del-invite', { id: b4a.toString(record.id, 'hex') }).catch(safetyCatch)
+      await this.store.call('del-invite', { id: b4a.toString(record.id, 'hex') })
     }
     return revoked
   }
@@ -552,20 +549,14 @@ export class Handle extends ReadyResource {
     if (candidate.invite.role && !grants(candidate.invite.role, role)) {
       throw CeroError.INVALID(`role '${role}' exceeds the invite role '${candidate.invite.role}'`)
     }
-    // Refuse BEFORE confirm() — but without awaiting: confirm has to answer
-    // inside the pairing request's lifetime, and any read here drops it. Rank
-    // validation is synchronous and catches the dangerous case (an app role
-    // name silently grants nothing); the cap against our own rank is enforced
-    // at apply, where add-writer refuses to admit what it cannot grant.
+    // synchronous on purpose, the cap against our own rank is enforced at apply
     if (!isRank(role)) {
       throw CeroError.INVALID(`role '${role}' is not a rank (owner, admin, member, reader)`)
     }
 
-    // confirm must answer within the incoming pairing request's lifetime —
-    // any await before it (even ~100ms) and the response is dropped, the
-    // joiner times out. So the key is revealed before the membership writes
-    // land; if they fail the joiner holds the key un-admitted, which is
-    // recoverable (re-pair) and surfaced via onerror in _wireAccept.
+    // confirm must answer within the pairing request's lifetime, any await before
+    // it (even ~100ms) drops the response. So the key is revealed before the
+    // membership writes land, and a failure there is recoverable by re-pairing.
     // Epoch secrets ride along so a post-rotation joiner reads full history.
     const epochs = this.store.keyring.all()
     await candidate.confirm({
@@ -598,8 +589,7 @@ export class Handle extends ReadyResource {
         sig,
         master: this.identity.publicKey,
         writer: writerKey,
-        // the device binds to the joiner; add-member in the same transaction
-        // decides the rank, and a refusal discards both
+        // add-member in the same transaction decides the rank, a refusal discards both
         memberId: member.id,
         ts: member.updatedAt || Date.now()
       })
@@ -607,15 +597,13 @@ export class Handle extends ReadyResource {
     })
   }
 
-  // Throws unless this handle may grant `role`: it must be a real rank, and
-  // never above our own. `grants` treats an unknown role as "no" everywhere,
-  // so an app role name must fail loudly here rather than silently downstream.
+  // `grants` treats an unknown role as "no", so an app role name must fail loudly
   async _checkGrant(role) {
     if (!isRank(role)) {
       throw CeroError.INVALID(`role '${role}' is not a rank (owner, admin, member, reader)`)
     }
     const { data: me } = await this.store.get('members', this.identity.id)
-    // no member row yet = genesis (we are creating the room) — nothing to cap
+    // no member row yet = genesis, nothing to cap
     if (!me) return
     if (!grants(me.role, role)) {
       throw CeroError.DENIED(null, `role '${role}' exceeds your own role '${me.role}'`)
@@ -652,13 +640,11 @@ export class Handle extends ReadyResource {
         namespace: `${NS}/handle/${type}/${writer.id}`,
         routes,
         keyPair: writer,
-        // each room gets its own key — inheriting identity.encryptionKey would let
-        // any member decrypt every room this identity ever created, plus its root db
+        // inheriting identity.encryptionKey would let any member decrypt every room
         encryptionKey: Identity.randomBytes(32)
       })
     )
-    // a failure after the child opens must close it — else it leaks its Database,
-    // swarm session and attached bee, never reaped by the parent (not yet a child)
+    // a failure after the child opens leaks its Database, swarm session and bee
     let publish = null
     let abort = null
     let inflightId = null
@@ -667,10 +653,8 @@ export class Handle extends ReadyResource {
       child.name = name
 
       const id = toId(child.store.key)
-      // Close the create/open race: the `add-handle` write below makes the row
-      // visible before this create finishes, so a concurrent _load for the id
-      // must share this child — a duplicate Handle over the same core
-      // deadlocks in ready().
+      // add-handle makes the row visible before this create finishes, and a
+      // duplicate Handle over the same core deadlocks in ready()
       const inflight = new Promise((resolve, reject) => {
         publish = resolve
         abort = reject
@@ -682,8 +666,7 @@ export class Handle extends ReadyResource {
 
       const ts = Date.now()
       const writerKey = child.store.writerKey
-      // admit the core and seat the owner in one append — the same shape as
-      // accept(), so a room's first two ops land together like every later pair
+      // same shape as accept(), so a room's first two ops land together
       await child.store.tx(async (tx) => {
         await tx.call('add-writer', {
           master: this.identity.publicKey,
@@ -738,10 +721,7 @@ export class Handle extends ReadyResource {
    * @returns {Promise<Handle>}
    */
   async _join(invite, type, opts = {}) {
-    // Coalesce concurrent joins of the same room (a retry racing a pending
-    // join, a double tap): the pairing layer allows one candidate per invite,
-    // so the second attempt must attach to the in-flight join, not start
-    // another handshake.
+    // the pairing layer allows one candidate per invite, attach to the in-flight join
     const target = Pairing.inviteTopic(invite)
     const key = target && `${type}/${b4a.toString(target, 'hex')}`
     if (!key) return this._pair(invite, type, opts, target)
@@ -766,14 +746,10 @@ export class Handle extends ReadyResource {
   async _pair(invite, type, { routes, timeout } = {}, target = null) {
     const deadline = timeout || TIMEOUT
 
-    // Idempotent: if the invite targets a handle we already have AND our
-    // stored writer is still admitted, return it — without pairing, so
-    // there's no waiting on a peer to confirm. A removed writer's core is
-    // frozen: the old session can never become writable again, and reusing
-    // its keypair would only get it re-removed. Holding a fresh invite is
-    // exactly the re-admission path, so fall through to a real pairing —
-    // which mints a fresh keypair the host admits. Our member row can outlive
-    // our writer (one revoked device), so the device row is the real test.
+    // idempotent while our stored writer is still admitted, so no waiting on a
+    // peer to confirm. A removed writer's core is frozen and reusing its keypair
+    // only gets it re-removed, so fall through to a real pairing, which mints a
+    // fresh keypair. A member row outlives a revoked device, so test the device.
     if (target) {
       const { data: joined } = await this.store.get('handles')
       const existing = joined.find(
@@ -788,8 +764,7 @@ export class Handle extends ReadyResource {
       }
     }
 
-    // offline join: with nearby sync on, also rendezvous on the invite-derived
-    // BLE UUID for the duration of the join — pairing rides the injected link
+    // offline join: rendezvous on the invite-derived BLE UUID for the join
     const stopNearby = this.root.bluetooth ? this.root.bluetooth.announce(invite) : null
 
     const child = /** @type {Child} */ (
@@ -801,8 +776,7 @@ export class Handle extends ReadyResource {
         timeout
       }).finally(() => stopNearby?.())
     )
-    // whenWritable timing out (host offline) is a normal failure — close the
-    // fully-opened child rather than leak its Database/pairing/swarm session
+    // whenWritable timing out (host offline) is normal, don't leak the opened child
     let publish = null
     let abort = null
     let inflightId = null
@@ -811,8 +785,7 @@ export class Handle extends ReadyResource {
       if (!child.store.writable) await child.store.whenWritable({ timeout: deadline })
 
       const id = toId(child.store.key)
-      // same create/open race as _create: the add-handle row is visible before
-      // this join finishes — a concurrent _load must share this child
+      // same create/open race as _create, a concurrent _load must share this child
       const inflight = new Promise((resolve, reject) => {
         publish = resolve
         abort = reject
@@ -880,8 +853,9 @@ export class Handle extends ReadyResource {
   async _reopen(type, id, opts) {
     const { data } = await this.store.get('handles', id)
     if (!data) throw CeroError.UNKNOWN('handle', id)
-    if (data.type !== type)
+    if (data.type !== type) {
       throw CeroError.INVALID(`handle ${id} is type ${data.type}, not ${type}`)
+    }
     let writer = await this._loadKeyPair(id)
     const firstTime = !writer
     if (firstTime) {
@@ -902,9 +876,7 @@ export class Handle extends ReadyResource {
     if (firstTime) {
       await this._saveKeyPair(id, writer)
     }
-    // a reopen must not silently re-arm auto-accept: `accept: false` is a
-    // host-approval gate, and one that comes back on the next open is worse
-    // than none at all
+    // `accept: false` is a host-approval gate, re-arming it silently is worse
     if (opts?.accept !== false) this._wireAccept(child, { role: opts?.role })
     bind(child, type)
     this.children.add(child)
@@ -989,9 +961,7 @@ export class Handle extends ReadyResource {
 
     let epochs = null
     if (additional?.byteLength) {
-      // the epoch set is load-bearing for a rotated room — a malformed
-      // delivery must fail the join loudly, not produce a silently inert
-      // member (hosts predating rotation send no additional payload at all)
+      // the epoch set is load-bearing, a malformed delivery must fail the join
       try {
         epochs = c.decode(epochEntries, additional)
       } catch {

package/src/index.js

@@ -1,3 +1,4 @@
+import Hypercore from 'hypercore'
 import HypercoreStorage from 'hypercore-storage'
 import Corestore from 'corestore'
 import safetyCatch from 'safety-catch'
@@ -121,9 +122,9 @@ export async function cero(dir, spec, opts = {}) {
     if (local) {
       const stored = (await local.store.get('environment')).data?.channel ?? null
       const wanted = opts.channel ?? null
-      if (stored == null && wanted != null)
+      if (stored == null && wanted != null) {
         await local.store.set('environment', { channel: wanted })
-      else if (stored != null && stored !== wanted) throw CeroError.CHANNEL_MISMATCH()
+      } else if (stored != null && stored !== wanted) throw CeroError.CHANNEL_MISMATCH()
     }
 
     network = new Network({
@@ -159,20 +160,35 @@ export async function cero(dir, spec, opts = {}) {
 
     // a supplied or stored identity may already have history elsewhere —
     // authoring genesis twice forks the seed-derived writer core (a writable
-    // core has one author, ever). Give discovery a moment; any replicated
-    // history means the caller wanted { recovery: true }. Offline reuse is
-    // undetectable — this catches the reachable-peer case loudly.
+    // core has one author, ever). Ask the peers directly with a plain session
+    // on the genesis core: the base never replicates an empty local core.
+    // Offline reuse is undetectable — this catches the reachable-peer case.
     if (!writer && !opts.key && !opts.recovery && !fresh) {
-      const until = Date.now() + 1500
-      while (Date.now() < until) {
-        if (network.connections.size > 0) await me.store.bee.update().catch(safetyCatch)
-        if (me.store.length > 0 || me.store.bee.local.length > 0) {
-          throw CeroError.CONFLICT('identity already has history — open with { recovery: true }')
+      const genesis = store.get({
+        key: Hypercore.key({
+          version: store.manifestVersion,
+          signers: [{ publicKey: identity.publicKey }]
+        })
+      })
+      await genesis.ready()
+      network.attach(genesis)
+      try {
+        const until = Date.now() + 1500
+        while (Date.now() < until) {
+          if (genesis.length > 0 || genesis.peers.some((p) => p.remoteLength > 0)) {
+            throw CeroError.CONFLICT('identity already has history — open with { recovery: true }')
+          }
+          await new Promise((r) => setTimeout(r, 100))
         }
-        await new Promise((r) => setTimeout(r, 100))
+      } finally {
+        network.detach(genesis)
+        await genesis.close()
       }
     }
-    if (!writer && me.store.length === 0 && (!opts.key || opts.recovery)) {
+    // decided by the stored writer and the caller's intent, never by the local
+    // core's length: a same-identity device opens on the genesis core, which
+    // fills with the first device's blocks as soon as a peer connects
+    if (!writer && (!opts.key || opts.recovery)) {
       const result = await me.bootstrap({
         name: opts.name || null,
         isMobile: opts.isMobile === true,

package/src/lib/operators.js

@@ -38,8 +38,9 @@ export function resolveFile(handle, id, name) {
  * @param {Record<string, any>} row
  * @returns {Promise<SingleResult>}
  */
-export const put = (ref, row) =>
-  ref.name === 'files' ? putFile(ref, row) : ref.handle.store.put(ref.name, row)
+export function put(ref, row) {
+  return ref.name === 'files' ? putFile(ref, row) : ref.handle.store.put(ref.name, row)
+}
 
 async function putFile(ref, row) {
   const handle = ref.handle
@@ -63,7 +64,9 @@ async function putFile(ref, row) {
  * @param {{ upsert?: boolean }} [opts]
  * @returns {Promise<SingleResult>}
  */
-export const set = (ref, row, opts) => ref.handle.store.set(ref.name, row, opts)
+export function set(ref, row, opts) {
+  return ref.handle.store.set(ref.name, row, opts)
+}
 
 /**
  * Delete a row by id (collection refs), or wipe the row (single refs).
@@ -72,7 +75,9 @@ export const set = (ref, row, opts) => ref.handle.store.set(ref.name, row, opts)
  * @param {string} [id]
  * @returns {Promise<void>}
  */
-export const del = (ref, id) => ref.handle.store.del(ref.name, id)
+export function del(ref, id) {
+  return ref.handle.store.del(ref.name, id)
+}
 
 /**
  * Count rows on `ref`, optionally filtered.
@@ -81,7 +86,9 @@ export const del = (ref, id) => ref.handle.store.del(ref.name, id)
  * @param {Record<string, any>} [q]
  * @returns {Promise<{ data: number }>}
  */
-export const count = (ref, q) => ref.handle.store.count(ref.name, q)
+export function count(ref, q) {
+  return ref.handle.store.count(ref.name, q)
+}
 
 /**
  * Invoke an `action`-kind ref (a custom mutation declared in the schema).
@@ -90,7 +97,9 @@ export const count = (ref, q) => ref.handle.store.count(ref.name, q)
  * @param {Record<string, any>} [d]
  * @returns {Promise<any>}
  */
-export const call = (ref, d) => ref.handle.store.call(ref.name, d)
+export function call(ref, d) {
+  return ref.handle.store.call(ref.name, d)
+}
 
 // Write ops per ref kind, for `before`/`after` subscriptions.
 const WRITES = { single: ['set'], collection: ['put', 'set', 'del'] }
@@ -105,7 +114,7 @@ const WRITES = { single: ['set'], collection: ['put', 'set', 'del'] }
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
-export const before = (ref, fn, opts) => {
+export function before(ref, fn, opts) {
   const db = ref.handle.store
   const ops = WRITES[ref.kind] || ['set']
   const offs = ops.map((op) =>
@@ -130,7 +139,7 @@ export const before = (ref, fn, opts) => {
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
-export const after = (ref, fn, opts) => {
+export function after(ref, fn, opts) {
   const db = ref.handle.store
   const ops = WRITES[ref.kind] || ['set']
   const handler = (ctx) => ctx.name === ref.name && fn(ctx)
@@ -194,7 +203,7 @@ function resolveRow(ref, row) {
  * @param {string | Record<string, any>} [q]
  * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
  */
-export const get = async (ref, q) => {
+export async function get(ref, q) {
   if (ref.kind === 'handle') {
     const { data } = await parentStore(ref).get('handles', q)
     return normalize(data, ref.name)
@@ -225,7 +234,7 @@ const bindStream = (owner, stream, opts) => {
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {import('streamx').Readable}
  */
-export const watch = (ref, q, opts) => {
+export function watch(ref, q, opts) {
   const owner = ref.handle
   if (ref.kind !== 'handle') {
     const src = owner.store.watch(ref.name, q)
@@ -243,7 +252,7 @@ export const watch = (ref, q, opts) => {
  * 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) => {
+export function 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)
@@ -338,7 +347,7 @@ function snapshotStream(src, map) {
  * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
  * @returns {Promise<CeroHandle>}  The resolved child handle.
  */
-export const open = (ref, arg) => {
+export function open(ref, arg) {
   if (typeof arg === 'string') return ref.handle._join(arg, ref.name)
   if (arg && typeof arg.invite === 'string') return ref.handle._join(arg.invite, ref.name)
   if (arg && typeof arg.id === 'string') return ref.handle._load(ref.name, arg.id, arg)
@@ -357,7 +366,9 @@ export const open = (ref, arg) => {
  * @param {any} handle
  * @returns {Promise<{ epoch: number }>}
  */
-export const rotate = (handle) => handle.store.rotate()
+export function rotate(handle) {
+  return handle.store.rotate()
+}
 
 // ─── custom operators ──────────────────────────────────────────────────────
 // App business logic lives as custom operators: pure functions whose first arg

package/src/local/index.js

@@ -25,8 +25,9 @@ export class Local extends ReadyResource {
    */
   constructor(dir, spec, { root, store, storageKey } = {}) {
     super()
-    if (!root && !store && (typeof dir !== 'string' || !dir))
+    if (!root && !store && (typeof dir !== 'string' || !dir)) {
       throw CeroError.REQUIRED('dir, root, or store')
+    }
     if (!spec?.local?.database) throw CeroError.REQUIRED('spec.local.database')
     if (!spec?.meta?.local) throw CeroError.REQUIRED('spec.meta.local')
 

package/src/rpc/server.js

@@ -278,7 +278,7 @@ export class Server extends RPCServer {
     })
 
     this.rpc.onRevoke(async ({ handle, invite }) => {
-      const ok = this._resolve(handle).revoke(invite)
+      const ok = await this._resolve(handle).revoke(invite)
       return { ok }
     })
 

package/types/build/builtins.d.ts

@@ -1,43 +1,3 @@
-export namespace refs {
-    namespace main {
-        namespace members {
-            let type: string;
-        }
-        namespace devices {
-            let type_1: string;
-            export { type_1 as type };
-        }
-        namespace invites {
-            let type_2: string;
-            export { type_2 as type };
-        }
-        namespace handles {
-            let type_3: string;
-            export { type_3 as type };
-        }
-        namespace files {
-            let type_4: string;
-            export { type_4 as type };
-        }
-    }
-    let local: {
-        master: {
-            type: string;
-            kind: string;
-        };
-        keypair: {
-            type: string;
-            kind: string;
-        };
-        'handle-keypairs': {
-            type: string;
-        };
-        environment: {
-            type: string;
-            kind: string;
-        };
-    };
-}
 export function getHyperdbType(prim: any): any;
 export function builtinRefs(ns: any, scope: any): {
     [k: string]: {
@@ -98,3 +58,43 @@ export function rpcCommands(ns: any): ({
         stream: boolean;
     };
 })[];
+export namespace refs {
+    namespace main {
+        namespace members {
+            let type: string;
+        }
+        namespace devices {
+            let type_1: string;
+            export { type_1 as type };
+        }
+        namespace invites {
+            let type_2: string;
+            export { type_2 as type };
+        }
+        namespace handles {
+            let type_3: string;
+            export { type_3 as type };
+        }
+        namespace files {
+            let type_4: string;
+            export { type_4 as type };
+        }
+    }
+    let local: {
+        master: {
+            type: string;
+            kind: string;
+        };
+        keypair: {
+            type: string;
+            kind: string;
+        };
+        'handle-keypairs': {
+            type: string;
+        };
+        environment: {
+            type: string;
+            kind: string;
+        };
+    };
+}

package/types/handle/index.d.ts

@@ -242,9 +242,9 @@ export class Handle extends ReadyResource {
      * Revoke a previously-minted invite by its string form.
      *
      * @param {string} invite
-     * @returns {boolean}  `true` if the invite was found and removed.
+     * @returns {Promise<boolean>}  `true` if the invite was found and removed.
      */
-    revoke(invite: string): boolean;
+    revoke(invite: string): Promise<boolean>;
     /**
      * Accept a paired candidate — adds them as a writer (or read-only member)
      * and confirms the pairing so they receive this handle's keys.

package/types/lib/operators.d.ts

@@ -22,38 +22,64 @@ export function resolveFile(handle: object, id: string, name?: string): {
     name?: string;
 };
 /**
- * Put custom operators on `handle`, currying it as their first argument so
- * `handle.ns.fn(args)` calls `fn(handle, args)`. `arg` is either:
- *   - a `{ ns: module }` map  → bind exactly those, or
- *   - `null`                  → the registered root operators, or
- *   - a child-handle type     → the registered operators for that type.
- * The scope forms are how cero binds handles automatically; pass a map yourself
- * for manual binding.
+ * Insert (or overwrite by id) a row on `ref`. The `files` builtin is special:
+ * `put(handle.files, { data, type, name? })` uploads the bytes to this handle's
+ * blob store, records `{ id, name }`, and resolves the file.
  *
- * @param {any} handle
- * @param {Record<string, any> | string | null} arg
- * @returns {any} handle
+ * @param {Ref} ref
+ * @param {Record<string, any>} row
+ * @returns {Promise<SingleResult>}
  */
-export function bind(handle: any, arg: Record<string, any> | string | null): any;
+export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
 /**
- * Register custom operators by scope. A bare key binds on the root handle; a key
- * that names a child-handle type binds on every handle of that type. Call once
- * at startup, before `cero()` / `connect()`, in both processes.
+ * Upsert a row on `ref` — merges with the existing row and preserves
+ * `createdAt`. Pass `{ upsert: false }` to update-only: a missing row is left
+ * untouched instead of created (atomic — never resurrects a deleted row).
  *
- * @param {Record<string, any>} map
+ * @param {Ref} ref
+ * @param {Record<string, any>} row
+ * @param {{ upsert?: boolean }} [opts]
+ * @returns {Promise<SingleResult>}
  */
-export function define(map: Record<string, any>): void;
-/** Test seam: clear all registered operators. */
-export function _clearDefined(): void;
-export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
 export function set(ref: Ref, row: Record<string, any>, opts?: {
     upsert?: boolean;
 }): Promise<SingleResult>;
+/**
+ * Delete a row by id (collection refs), or wipe the row (single refs).
+ *
+ * @param {Ref} ref
+ * @param {string} [id]
+ * @returns {Promise<void>}
+ */
 export function del(ref: Ref, id?: string): Promise<void>;
+/**
+ * Count rows on `ref`, optionally filtered.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [q]
+ * @returns {Promise<{ data: number }>}
+ */
 export function count(ref: Ref, q?: Record<string, any>): Promise<{
     data: number;
 }>;
+/**
+ * Invoke an `action`-kind ref (a custom mutation declared in the schema).
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [d]
+ * @returns {Promise<any>}
+ */
 export function call(ref: Ref, d?: Record<string, any>): Promise<any>;
+/**
+ * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path
+ * (awaited). Return `false` to cancel the write, or mutate `ctx.row`.
+ * Returns an unsubscribe fn; pass `{ signal }` to unsubscribe on abort.
+ *
+ * @param {Ref} ref
+ * @param {(ctx: { op: string, name: string, row: any }) => any} fn
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {() => void}
+ */
 export function before(ref: Ref, fn: (ctx: {
     op: string;
     name: string;
@@ -61,6 +87,16 @@ export function before(ref: Ref, fn: (ctx: {
 }) => any, opts?: {
     signal?: AbortSignal;
 }): () => void;
+/**
+ * Subscribe to writes on `ref` — fires after each committed write,
+ * non-blocking (observe only). Returns an unsubscribe fn; pass `{ signal }`
+ * to unsubscribe on abort.
+ *
+ * @param {Ref} ref
+ * @param {(ctx: { op: string, name: string, row: any }) => void} fn
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {() => void}
+ */
 export function after(ref: Ref, fn: (ctx: {
     op: string;
     name: string;
@@ -68,11 +104,50 @@ export function after(ref: Ref, fn: (ctx: {
 }) => void, opts?: {
     signal?: AbortSignal;
 }): () => void;
+/**
+ * Read from `ref`. For data refs, dispatches to the underlying store. For
+ * `handle`-kind refs, lists existing child handles of that type from the
+ * parent's `handles` collection.
+ *
+ * @param {Ref} ref
+ * @param {string | Record<string, any>} [q]
+ * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
+ */
 export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
+/**
+ * Live snapshot stream on `ref` — re-emits the latest `get()` result on
+ * every underlying mutation. Tied to `ref.handle`'s lifecycle: closing the
+ * handle destroys it. Pass `{ signal }` to bind it to a finer scope, or
+ * destroy the stream directly to stop watching sooner.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [q]
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {import('streamx').Readable}
+ */
 export function watch(ref: Ref, q?: Record<string, any>, opts?: {
     signal?: AbortSignal;
 }): import("streamx").Readable;
+/**
+ * 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 function changes(ref: any, q: any, opts: any): any;
+/**
+ * Open (or create / join / load) a child handle through a `handle`-kind
+ * ref. Dispatches on the normalize of `arg`:
+ *
+ *   - `string`                → join via an invite string
+ *   - `{ invite: string }`    → join via invite (object form)
+ *   - `{ id: string }`        → load an existing handle by id
+ *   - `object | undefined`    → create a new handle with the given opts
+ *
+ * @param {Ref} ref
+ * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
+ * @returns {Promise<CeroHandle>}  The resolved child handle.
+ */
 export function open(ref: Ref, arg?: string | {
     invite?: string;
     id?: string;
@@ -81,9 +156,45 @@ export function open(ref: Ref, arg?: string | {
     role?: string;
     accept?: boolean;
 } | undefined): Promise<CeroHandle>;
+/**
+ * Rotate a handle's encryption epoch. A fresh secret is sealed to every
+ * current member and announced through the log — members removed before the
+ * rotation cannot decrypt anything written after it. Requires the remove
+ * permission (admin or owner). Compose with removal:
+ *
+ *   await cero.del(room.members, memberId)
+ *   await cero.rotate(room)
+ *
+ * @param {any} handle
+ * @returns {Promise<{ epoch: number }>}
+ */
 export function rotate(handle: any): Promise<{
     epoch: number;
 }>;
+/**
+ * Put custom operators on `handle`, currying it as their first argument so
+ * `handle.ns.fn(args)` calls `fn(handle, args)`. `arg` is either:
+ *   - a `{ ns: module }` map  → bind exactly those, or
+ *   - `null`                  → the registered root operators, or
+ *   - a child-handle type     → the registered operators for that type.
+ * The scope forms are how cero binds handles automatically; pass a map yourself
+ * for manual binding.
+ *
+ * @param {any} handle
+ * @param {Record<string, any> | string | null} arg
+ * @returns {any} handle
+ */
+export function bind(handle: any, arg: Record<string, any> | string | null): any;
+/**
+ * Register custom operators by scope. A bare key binds on the root handle; a key
+ * that names a child-handle type binds on every handle of that type. Call once
+ * at startup, before `cero()` / `connect()`, in both processes.
+ *
+ * @param {Record<string, any>} map
+ */
+export function define(map: Record<string, any>): void;
+/** Test seam: clear all registered operators. */
+export function _clearDefined(): void;
 export type Ref = import("./utils.js").Ref;
 export type CeroHandle = import("../handle/index.js").CeroHandle;
 export type SingleResult = {