@cero-base/cero 1.18.1 → 1.19.0

package/README.md

@@ -52,9 +52,8 @@ Ships with TypeScript declarations (`.d.ts`) generated from JSDoc.
 | `channel`           | Optional network-isolation label. Peers connect only to peers on the **same** channel (it salts every swarm topic); omit it for the global network. A storage remembers its channel and refuses to reopen under a different one. Any string works.                     |
 | `name` / `isMobile` | Stamped on the device's `add-writer` event.                                                                                                                                                                                                                            |
 | `seed` / `phrase`   | Restore from explicit 16-/32-byte entropy or a BIP-39 mnemonic. Without either, a stored identity is loaded if present, else a fresh one is generated.                                                                                                                 |
-| `key`               | Open against an existing bee key (multi-device flow).                                                                                                                                                                                                                  |
-| `recovery`          | `true` triggers `bootstrap({ recovering: true })` — for a second device opening with `key` + the same identity. Needed under autobee 1.0.3 so the second device swaps off the identity-keyed bootstrap-writer slot and starts applying remote appends.                 |
-| `recoveryTimeout`   | Bound on the recovery wait.                                                                                                                                                                                                                                            |
+| `key`               | Existing database key to recover into, skipping the pointer lookup.                                                                                                                                                                                                    |
+| `recoveryTimeout`   | Max wait to find another device and be admitted, in ms. Defaults to 30000. A supplied `seed`/`phrase` on a device with no writer recovers — there is no flag.                                                                                                          |
 | `routes`            | Custom action handlers keyed by route name.                                                                                                                                                                                                                            |
 | `encryptionKey`     | Override the per-identity encryption key.                                                                                                                                                                                                                              |
 | `storageKey`        | 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it, and the same key must be passed on every open. Without it, key material sits plaintext on disk: rely on full-disk encryption. |
@@ -496,7 +495,7 @@ import { spec } from './spec/index.js'
 
 // serve builds and owns the root cero — pass storage + the built spec, not a handle.
 // Returns a Server instance (call server.close() to shut down).
-const server = await serve(Bare.IPC, { storage: './data', spec, phrase: '…' })
+const server = await serve(Bare.IPC, spec, { storage: './data', phrase: '…' })
 ```
 
 ### Client (the UI process)
@@ -566,7 +565,7 @@ function streamPair() {
   return [a, b]
 }
 const [s, c] = streamPair()
-await serve(s, { storage: './data', spec })
+await serve(s, spec, { storage: './data' })
 const remote = await connect(c, spec)
 ```
 
@@ -661,7 +660,7 @@ Point your app's `mirrors` at that key. Storage grows with the rooms it holds; `
 | ---------------------------- | ------------------------------------------------------------------------ |
 | `@cero-base/cero`            | factory + operators + schema DSL + `define`/`bind`                       |
 | `@cero-base/cero/client`     | `connect(ipc, spec)` — talk to a cero running in another process         |
-| `@cero-base/cero/server`     | `serve(ipc, { storage, spec })` — run + expose a cero over an IPC stream |
+| `@cero-base/cero/server`     | `serve(ipc, spec, { storage })` — run + expose a cero over an IPC stream |
 | `@cero-base/cero/build`      | `build(specDir, schema)` — generate the on-disk spec                     |
 | `@cero-base/cero/extensions` | bundled extensions (`profileSync`, …)                                    |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -85,28 +85,29 @@
     }
   },
   "scripts": {
-    "build:test": "rm -rf test/fixture/spec && node test/fixture/build.js",
+    "build:test": "rm -rf test/fixtures/spec && node test/fixtures/build.js",
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
     "test": "npm run test:bare",
     "pretest:bare": "npm run build:test",
-    "test:bare": "ls test/*.test.js | xargs -P1 -n1 brittle-bare test/bare.js",
-    "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
+    "test:bare": "find test -name '*.test.js' | sort | xargs -P1 -n1 brittle-bare test/bare.js",
+    "test:node": "find test -name '*.test.js' | sort | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.18.1",
+    "@cero-base/core": "^1.19.0",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.8.1",
     "bare-path": "^3.1.2",
     "ble-swarm": "^2.3.0",
-    "compact-encoding": "^3.3.2",
-    "corestore": "^7.12.2",
+    "compact-encoding": "^3.4.0",
+    "corestore": "^7.12.3",
     "hrpc": "^4.3.1",
-    "hypercore": "^11.35.2",
+    "hypercore": "^11.35.4",
     "hypercore-crypto": "^3.7.0",
+    "hypercore-id-encoding": "^1.3.0",
     "hypercore-storage": "^3.2.1",
     "hyperdb": "^6.9.0",
     "hyperdispatch": "^1.6.0",
@@ -124,7 +125,7 @@
     "bare-process": "^4.5.1",
     "bare-url": "^2.5.4",
     "brittle": "^4.1.1",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "license": "Apache-2.0"
 }

package/src/handle/index.js

@@ -12,7 +12,8 @@ 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, can, isRank, addWriterPayload, REMOVE } from '@cero-base/core/utils'
+import hid from 'hypercore-id-encoding'
+import { grants, can, isRank, admission, REMOVE, onAbort } 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'
@@ -20,10 +21,10 @@ import { FileServer } from '@cero-base/core/blobs/server'
 
 import { NS, TIMEOUT } from '../lib/constants.js'
 
-import { attachRefs, onAbort } from '../lib/utils.js'
+import { Ref } from '../lib/refs.js'
 import { bind } from '../lib/operators.js'
 
-export { Ref } from '../lib/utils.js'
+export { Ref } from '../lib/refs.js'
 
 /**
  * @typedef {import('@cero-base/core/network').Network} Network
@@ -74,17 +75,14 @@ export { Ref } from '../lib/utils.js'
  * @property {string} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
  * @property {string | null} [name]
  *
- * @typedef {object} RecoverOpts
- * @property {number} [timeout]
- *
  * @typedef {object} HandleExtra
  * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
- * @property {import('../lib/utils.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
- * @property {import('../lib/utils.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
+ * @property {import('../lib/refs.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
+ * @property {import('../lib/refs.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
  *
  * @typedef {Handle & HandleExtra} Child  A child handle plus its dynamically-attached refs.
  *
- * @typedef {Handle & Record<string, import('../lib/utils.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
+ * @typedef {Handle & Record<string, import('../lib/refs.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
  */
 
 /**
@@ -171,7 +169,7 @@ export class Handle extends ReadyResource {
       this._invitesSync = () => this._syncInvites().catch(safetyCatch)
       this.store.on('update', this._invitesSync)
     }
-    attachRefs(this, this.store.refs)
+    Ref.attach(this, this.store.refs)
     this.root._coreKeys.set(b4a.toString(this.store.key, 'hex'), this.store.encryptionKey)
     if (!this.parent) await this.fileServer.listen()
   }
@@ -406,14 +404,14 @@ export class Handle extends ReadyResource {
   /** Canonical id — identity id for the root handle, store key for children. */
   get id() {
     if (!this.parent) return this.identity.id
-    return this.store?.key ? toId(this.store.key) : null
+    return this.store?.key ? hid.encode(this.store.key) : null
   }
 
   /** This device's id + name. `null` on child handles. */
   get device() {
     if (this.parent) return null
     const k = this.store?.writerKey
-    return k ? { id: toId(k), name: this._opts.name || null } : null
+    return k ? { id: hid.encode(k), name: this._opts.name || null } : null
   }
 
   get suspended() {
@@ -441,20 +439,6 @@ export class Handle extends ReadyResource {
     return this.store.claim()
   }
 
-  /**
-   * Claim + wait until this peer becomes a writer + bring the bee up to date.
-   * Used by `restore()` after wiping local state.
-   *
-   * @param {RecoverOpts} [opts]
-   * @returns {Promise<void>}
-   */
-  async recover({ timeout = TIMEOUT } = {}) {
-    if (this.store.writable) return
-    await this.store.claim()
-    await this.store.whenWritable({ timeout })
-    await this.store.bee.update()
-  }
-
   /**
    * Flip this handle's swarm announce mode — `setActive(false)` demotes an
    * idle/background room to server-only (still reachable, stops searching);
@@ -568,7 +552,7 @@ export class Handle extends ReadyResource {
     const ts = Date.now()
     const writerKey = Hypercore.key({ version: 2, signers: [{ publicKey: data.subarray(32, 64) }] })
     const member = {
-      id: toId(data.subarray(0, 32)),
+      id: hid.encode(data.subarray(0, 32)),
       key: writerKey,
       role,
       name: name || null,
@@ -581,9 +565,7 @@ export class Handle extends ReadyResource {
       return
     }
 
-    const sig = this.identity.sign(
-      addWriterPayload(this.store.key, writerKey, this.store.writerKey)
-    )
+    const sig = this.identity.sign(admission(this.store.key, writerKey, this.store.writerKey))
     await this.store.tx(async (tx) => {
       await tx.call('add-writer', {
         sig,
@@ -618,7 +600,7 @@ export class Handle extends ReadyResource {
    */
   async leave() {
     if (!this.parent) return
-    await this.parent.store.call('del-handle', { id: toId(this.store.key) })
+    await this.parent.store.call('del-handle', { id: hid.encode(this.store.key) })
     await this.close()
   }
 
@@ -652,7 +634,7 @@ export class Handle extends ReadyResource {
       await child.ready()
       child.name = name
 
-      const id = toId(child.store.key)
+      const id = hid.encode(child.store.key)
       // 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) => {
@@ -671,9 +653,7 @@ export class Handle extends ReadyResource {
         await tx.call('add-writer', {
           master: this.identity.publicKey,
           writer: writerKey,
-          sig: this.identity.sign(
-            addWriterPayload(child.store.key, writerKey, child.store.writerKey)
-          ),
+          sig: this.identity.sign(admission(child.store.key, writerKey, child.store.writerKey)),
           ts
         })
         await tx.call('add-member', {
@@ -758,7 +738,7 @@ export class Handle extends ReadyResource {
       if (existing) {
         const known = await this._load(type, existing.id)
         const { data: me } = await known.store.get('members', this.identity.id)
-        const { data: device } = await known.store.get('devices', toId(known.store.writerKey))
+        const { data: device } = await known.store.get('devices', hid.encode(known.store.writerKey))
         if (me && device) return known
         await known.close().catch(safetyCatch)
       }
@@ -784,7 +764,7 @@ export class Handle extends ReadyResource {
       await child.ready()
       if (!child.store.writable) await child.store.whenWritable({ timeout: deadline })
 
-      const id = toId(child.store.key)
+      const id = hid.encode(child.store.key)
       // same create/open race as _create, a concurrent _load must share this child
       const inflight = new Promise((resolve, reject) => {
         publish = resolve

package/src/index.js

@@ -2,6 +2,7 @@ import Hypercore from 'hypercore'
 import HypercoreStorage from 'hypercore-storage'
 import Corestore from 'corestore'
 import safetyCatch from 'safety-catch'
+import c from 'compact-encoding'
 import fs from 'fs'
 
 import { Identity } from '@cero-base/core/identity'
@@ -29,7 +30,7 @@ import {
 } from './lib/operators.js'
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
-import { FLUSH } from './lib/constants.js'
+import { FLUSH, TIMEOUT } from './lib/constants.js'
 import { internal } from './lib/internal.js'
 
 export { Handle, Ref, Local }
@@ -68,12 +69,11 @@ export { t, schema } from './lib/spec.js'
  * @property {number[]} [backoffs]                     Swarm reconnect backoff tiers in ms (testing/tuning).
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
  * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
- * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
+ * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
  * @property {(err: any) => void} [onerror]            Background-task error handler.
- * @property {boolean} [recovery]                      Recovery flow — wipe local state and re-claim a writer slot.
- * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
+ * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
  * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
@@ -115,6 +115,11 @@ export async function cero(dir, spec, opts = {}) {
 
     const { identity, fresh } = await resolveIdentity(opts, local)
     const writer = local ? (await local.store.get('keypair')).data : null
+    // a supplied identity on a device with no writer is recovering: it never
+    // authors the identity's pointer core or any core that exists elsewhere.
+    // Only an identity cero generated here creates a database
+    const recovering = !writer && (!!opts.key || !fresh)
+    const timeout = opts.recoveryTimeout || TIMEOUT
 
     // Channel stamp: a storage remembers its channel; reopening it under a different channel —
     // including no channel at all, which would silently rejoin the global network — is a
@@ -140,6 +145,20 @@ export async function cero(dir, spec, opts = {}) {
     // before proceeding only delays first onboarding
     if (!fresh) await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
 
+    // the pointer core: signed by the identity, written once by the device that
+    // created the identity, read by every device that recovers it. It holds the
+    // root database key, so a phrase alone finds the data
+    const manifest = pointerManifest(store, identity)
+    const pointer = store.get(
+      !writer && !recovering
+        ? { keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey }, manifest }
+        : { key: Hypercore.key(manifest) }
+    )
+    await pointer.ready()
+    network.attach(pointer)
+
+    const key = opts.key || (recovering ? await readPointer(pointer, timeout) : undefined)
+
     me = new Handle({
       storage,
       store,
@@ -151,57 +170,31 @@ export async function cero(dir, spec, opts = {}) {
       opts,
       dir,
       routes: opts.routes,
-      key: opts.key,
+      key,
       encryptionKey: opts.encryptionKey,
       keyPair: writer ? { publicKey: writer.publicKey, secretKey: writer.secretKey } : undefined,
       pair: false
     })
     await me.ready()
+    me.once('close', () => {
+      network.detach(pointer)
+      pointer.close().catch(safetyCatch)
+    })
 
-    // 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). 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 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))
-        }
-      } finally {
-        network.detach(genesis)
-        await genesis.close()
-      }
-    }
-    // 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)) {
+    if (!writer) {
       const result = await me.bootstrap({
         name: opts.name || null,
         isMobile: opts.isMobile === true,
-        recovering: opts.recovery === true,
-        ...(opts.recoveryTimeout ? { timeout: opts.recoveryTimeout } : {})
+        recovering,
+        timeout
       })
-      if (local && result?.writer) {
+      if (local) {
         await local.store.set('keypair', {
           publicKey: result.writer.publicKey,
           secretKey: result.writer.secretKey
         })
       }
-      if (!opts.recovery) {
+      if (!recovering) {
         const ts = Date.now()
         await me.store.call('add-member', {
           id: identity.id,
@@ -211,9 +204,9 @@ export async function cero(dir, spec, opts = {}) {
           createdAt: ts,
           updatedAt: ts
         })
+        if (pointer.length === 0) await pointer.append(c.encode(c.fixed32, me.store.key))
       }
     }
-    if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
 
     for (const ext of internal.extensions) {
       if (ext.bundled && opts.extensions === false) continue
@@ -263,8 +256,8 @@ export async function cero(dir, spec, opts = {}) {
 
 /**
  * Restore a cero instance from a mnemonic phrase. Closes the running
- * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
- * so the writer slot is re-claimed.
+ * instance, wipes the on-disk `main/` tree and re-opens with the phrase, which
+ * recovers so the writer slot is re-claimed.
  *
  * @param {Handle} me   Existing root handle to restore.
  * @param {string} phrase   BIP-39 mnemonic phrase.
@@ -278,39 +271,18 @@ export async function restore(me, phrase) {
   const current = await Identity.fromSeed(Identity.toSeed(phrase))
   if (current.id === me.identity.id) return me
 
-  const { _dir: dir, spec, _opts: opts } = me
-  // channel must carry over — without it the recovered instance rejoins the
-  // global identity topic and never meets its channeled peers (recovery timeout).
+  // everything carries over except the old identity — the channel in
+  // particular, or the recovered instance never meets its peers
   const {
-    name,
-    bootstrap,
-    isMobile,
-    onerror,
-    routes,
-    recoveryTimeout,
-    channel,
-    mirrors,
-    storageKey,
-    extensions
-  } = opts
+    _dir: dir,
+    spec,
+    _opts: { seed, identity, key, keyPair, ...opts }
+  } = me
 
   await me.close()
   await fs.promises.rm(`${dir}/main`, { recursive: true, force: true })
 
-  return cero(dir, spec, {
-    name,
-    bootstrap,
-    isMobile,
-    onerror,
-    routes,
-    recoveryTimeout,
-    channel,
-    mirrors,
-    storageKey,
-    extensions,
-    phrase,
-    recovery: true
-  })
+  return cero(dir, spec, { ...opts, phrase })
 }
 
 // Facade: expose the operators + helpers as properties on `cero` too, so both
@@ -349,6 +321,18 @@ cero.use = (...exts) => {
   }
 }
 
+function pointerManifest(store, identity) {
+  return { version: store.manifestVersion, signers: [{ publicKey: identity.publicKey }] }
+}
+
+async function readPointer(pointer, timeout) {
+  try {
+    return c.decode(c.fixed32, await pointer.get(0, { timeout }))
+  } catch {
+    throw CeroError.TIMED_OUT('recovery: finding a device of this identity')
+  }
+}
+
 async function resolveIdentity(opts, local) {
   if (opts.identity) return { identity: opts.identity, fresh: false }
 

package/src/lib/operators.js

@@ -3,10 +3,10 @@ import b4a from 'b4a'
 
 import { encodeId, decodeId } from '@cero-base/core/blobs/codec'
 import { CeroError } from '@cero-base/core/errors'
-import { onAbort } from './utils.js'
+import { onAbort } from '@cero-base/core/utils'
 
 /**
- * @typedef {import('./utils.js').Ref} Ref
+ * @typedef {import('./refs.js').Ref} Ref
  * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult

package/src/lib/refs.js

@@ -0,0 +1,49 @@
+import { CeroError } from '@cero-base/core/errors'
+
+/**
+ * @typedef {'collection' | 'single' | 'action' | 'handle'} RefKind
+ * @typedef {{ kind?: string, schema?: string }} RefInfo
+ *   Shape of the entries in `meta.refs` — describes a single ref name.
+ *   `kind` is one of {@link RefKind}, kept as `string` since it originates
+ *   from a generated spec.
+ */
+
+/**
+ * Typed pointer to a single ref (table or handle slot) on a `Handle` or
+ * `Local`. Operators (`put`/`get`/`open`/...) take a `Ref` as their first
+ * argument and dispatch through the owning handle's store.
+ */
+export class Ref {
+  /**
+   * @param {any} handle  Owner — a `Handle` (or `Local`) the ref lives on.
+   * @param {string} name  Ref name as declared in the schema.
+   * @param {string} kind  Ref kind: `'collection'`, `'single'`, `'action'`, or `'handle'`.
+   * @param {string | null} [schema]  Fully-qualified schema id, if any.
+   */
+  constructor(handle, name, kind, schema = null) {
+    this.handle = handle
+    this.name = name
+    this.kind = kind
+    this.schema = schema
+  }
+
+  /**
+   * Attach a `Ref` property to `target` for every entry in `refs`, so callers
+   * write `handle.someRef` instead of looking refs up by name.
+   *
+   * @param {any} target
+   * @param {Record<string, RefInfo>} refs
+   */
+  static attach(target, refs) {
+    for (const [name, info] of Object.entries(refs || {})) {
+      // fail loud rather than silently overwrite a method or property (close,
+      // on, store) when a schema declares a ref named like a reserved member
+      if (name in target) {
+        throw CeroError.INVALID(
+          `schema ref '${name}' collides with a reserved ${target.constructor?.name || 'handle'} member — rename it`
+        )
+      }
+      target[name] = new Ref(target, name, info.kind, info.schema)
+    }
+  }
+}

package/src/local/index.js

@@ -3,7 +3,7 @@ import ReadyResource from 'ready-resource'
 import { Storage } from '@cero-base/core/storage'
 import { CeroError } from '@cero-base/core/errors'
 
-import { attachRefs } from '../lib/utils.js'
+import { Ref } from '../lib/refs.js'
 
 /**
  * @typedef {object} LocalOpts
@@ -43,7 +43,7 @@ export class Local extends ReadyResource {
 
   async _open() {
     await this.store.ready()
-    attachRefs(this, this.store.refs)
+    Ref.attach(this, this.store.refs)
   }
 
   async _close() {

package/src/rpc/client.js

@@ -4,7 +4,7 @@ import c from 'compact-encoding'
 import z32 from 'z32'
 import { decodeId } from '@cero-base/core/blobs/codec'
 
-import { attachRefs } from '../lib/utils.js'
+import { Ref } from '../lib/refs.js'
 import {
   put,
   set,
@@ -12,6 +12,7 @@ import {
   del,
   count,
   watch,
+  changes,
   call,
   open,
   rotate,
@@ -20,7 +21,7 @@ import {
 } from '../lib/operators.js'
 import { t, schema } from '../lib/spec.js'
 
-export { put, set, get, del, count, watch, call, open, rotate, bind, define, t, schema }
+export { put, set, get, del, count, watch, changes, call, open, rotate, bind, define, t, schema }
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCClient} BaseRPCClient
@@ -449,7 +450,7 @@ class LocalRefs {
     this._local = true
     const refs = client.spec.meta.local?.refs || {}
     const exposed = Object.fromEntries(Object.entries(refs).filter(([, info]) => !info.builtin))
-    attachRefs(this, exposed)
+    Ref.attach(this, exposed)
   }
 
   /** Underlying RPC channel borrowed from the parent. */
@@ -491,7 +492,7 @@ export class Client extends RPCClient {
     this._fileBase = fileBase || ''
     this._fileToken = fileToken || ''
     this.identity = { id, toPhrase: async () => (await this.rpc.seed({})).phrase || null }
-    attachRefs(this, /** @type {Spec} */ (this.spec).meta.refs)
+    Ref.attach(this, /** @type {Spec} */ (this.spec).meta.refs)
     bind(this, null)
     if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
   }
@@ -560,7 +561,7 @@ class Handle {
     this.spec = /** @type {Spec} */ (parent.spec).handles[type]
     if (!this.spec.codec) bindCodec(this.spec)
     this.store = this
-    attachRefs(this, this.spec.meta.refs)
+    Ref.attach(this, this.spec.meta.refs)
     bind(this, this.type)
   }
 
@@ -618,6 +619,7 @@ cero.get = get
 cero.del = del
 cero.count = count
 cero.watch = watch
+cero.changes = changes
 cero.call = call
 cero.open = open
 cero.rotate = rotate

package/src/rpc/server.js

@@ -12,7 +12,6 @@ import { put, set, get, del, count, watch, changes, call } from '../lib/operator
  *
  * @typedef {object} ServerOpts
  * @property {string} storage   Directory passed to `cero()` for the local store.
- * @property {object} spec      Compiled cero spec (schema + rpc + handles).
  * @property {string} [name]    Optional display name forwarded to `cero()`.
  * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap.
  * @property {boolean} [isMobile]
@@ -36,11 +35,12 @@ import { put, set, get, del, count, watch, changes, call } from '../lib/operator
 export class Server extends RPCServer {
   /**
    * @param {any} ipc                Framed IPC stream (must be writable).
+   * @param {object} spec
    * @param {Partial<ServerOpts>} [opts]
    */
-  constructor(ipc, { storage, spec, ...opts } = {}) {
-    if (!storage) throw CeroError.REQUIRED('storage')
+  constructor(ipc, spec, { storage, ...opts } = {}) {
     if (!spec) throw CeroError.REQUIRED('spec')
+    if (!storage) throw CeroError.REQUIRED('storage')
     super(ipc, spec)
     if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     this.storage = storage
@@ -409,11 +409,12 @@ export class Server extends RPCServer {
  * Construct a `Server`, wait for it to be ready, and return it.
  *
  * @param {any} ipc
+ * @param {object} spec
  * @param {ServerOpts} opts
  * @returns {Promise<Server>}
  */
-export async function serve(ipc, opts) {
-  const server = new Server(ipc, opts)
+export async function serve(ipc, spec, opts) {
+  const server = new Server(ipc, spec, opts)
   await server.ready()
   return server
 }