@cero-base/cero 1.19.0 → 2.0.0

package/src/index.js

@@ -31,7 +31,7 @@ import {
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
 import { FLUSH, TIMEOUT } from './lib/constants.js'
-import { internal } from './lib/internal.js'
+import { registry } from './extensions/index.js'
 
 export { Handle, Ref, Local }
 export {
@@ -80,9 +80,7 @@ export { t, schema } from './lib/spec.js'
  */
 
 /**
- * Open (or create) a cero handle at `dir`. Sets up storage, network and
- * identity, then returns a ready root `Handle` with all schema refs
- * attached as properties.
+ * Open (or create) a cero handle at `dir`.
  *
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
@@ -99,9 +97,7 @@ export async function cero(dir, spec, opts = {}) {
   let network = null
   let discovery = null
   let me = null
-  // Any failure during open (bad phrase, network/bootstrap error, recovery
-  // timeout, extension setup) must close whatever opened — else the corestore
-  // lock leaks and a retry in the same process hits locked storage.
+  // any failure during open must close what opened, or the storage lock leaks
   try {
     await storage.ready()
     await fs.promises.chmod(`${dir}/main`, 0o700)
@@ -115,15 +111,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
+    // a supplied identity on a device with no writer recovers; only a cero-minted identity creates
     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
-    // misconfiguration that could leak data across networks, so reject it.
+    // a storage remembers its channel; reopening under another would silently rejoin the global network
     if (local) {
       const stored = (await local.store.get('environment')).data?.channel ?? null
       const wanted = opts.channel ?? null
@@ -141,13 +133,10 @@ export async function cero(dir, spec, opts = {}) {
     })
     await network.ready()
     discovery = network.join(identity.topic)
-    // a freshly minted identity has no peers yet — flushing the announce
-    // before proceeding only delays first onboarding
+    // a fresh identity has no peers yet, flushing the announce would only delay 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
+    // the pointer core: identity-signed, written once by the creating device, holds the root key
     const manifest = pointerManifest(store, identity)
     const pointer = store.get(
       !writer && !recovering
@@ -208,25 +197,16 @@ export async function cero(dir, spec, opts = {}) {
       }
     }
 
-    for (const ext of internal.extensions) {
+    for (const ext of registry) {
       if (ext.bundled && opts.extensions === false) continue
       const off = await ext.setup?.(me)
       if (typeof off === 'function') me.once('close', off)
     }
 
     if (opts.bluetooth) {
-      // `true` → defaults; `{ autoStart, backend }` → options. A bare backend
-      // object (pre-1.3 shape, has Central/Server) is still accepted.
-      const bt =
-        opts.bluetooth === true
-          ? {}
-          : opts.bluetooth.Central
-            ? { backend: opts.bluetooth }
-            : opts.bluetooth
+      const bt = opts.bluetooth === true ? {} : opts.bluetooth
       me.bluetooth = new Bluetooth(me, {
-        // pass the backend through untouched: `|| null` turned an omitted
-        // backend (= lazy-load bare-bluetooth) into an explicit null
-        // (= disabled), leaving BLE 'unsupported' on every platform
+        // an omitted backend lazy-loads bare-bluetooth, null disables it
         backend: bt.backend,
         autoStart: bt.autoStart !== false,
         maxOutbound: bt.maxOutbound,
@@ -240,8 +220,7 @@ export async function cero(dir, spec, opts = {}) {
     bind(me, null)
     return me
   } catch (err) {
-    // once the root Handle exists it owns (and closes) everything; before that,
-    // tear the raw resources down in reverse order.
+    // before the root Handle exists, tear the raw resources down in reverse order
     if (me) await me.close().catch(safetyCatch)
     else {
       await discovery?.destroy().catch(safetyCatch)
@@ -255,9 +234,7 @@ 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 the phrase, which
- * recovers so the writer slot is re-claimed.
+ * Restore a cero instance from a mnemonic phrase.
  *
  * @param {Handle} me   Existing root handle to restore.
  * @param {string} phrase   BIP-39 mnemonic phrase.
@@ -267,12 +244,10 @@ export async function restore(me, phrase) {
   if (!me?._dir) throw CeroError.INVALID('me must be a cero instance')
   if (!phrase || typeof phrase !== 'string') throw CeroError.INVALID('phrase must be a string')
 
-  // Already this identity? Nothing to restore — return the running instance.
   const current = await Identity.fromSeed(Identity.toSeed(phrase))
   if (current.id === me.identity.id) return me
 
-  // everything carries over except the old identity — the channel in
-  // particular, or the recovered instance never meets its peers
+  // everything carries over except the identity, the channel above all
   const {
     _dir: dir,
     spec,
@@ -285,9 +260,7 @@ export async function restore(me, phrase) {
   return cero(dir, spec, { ...opts, phrase })
 }
 
-// Facade: expose the operators + helpers as properties on `cero` too, so both
-// `import { define }` and `cero.define(...)` work. Explicit assignments (not
-// `Object.assign`) so tsc reflects them onto the `cero` namespace in the .d.ts.
+// the facade: cero.put and import { put } are the same function
 cero.t = t
 cero.put = put
 cero.set = set
@@ -306,18 +279,14 @@ cero.restore = restore
 cero.schema = schema
 cero.bind = bind
 cero.define = define
-// test-only escape hatch (cross-package tests reset/seed the registry)
-cero._internal = internal
-// A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.
-// Accepts both `use(a, b)` and `use([a, b])` (and a mix) for easier composition.
-// A named extension replaces any registered one with the same name — so
-// `use(profileSync({ fields }))` reconfigures the bundled default instead of
-// doubling it.
+// test-only
+cero._registry = registry
+// a bare function is shorthand for { setup }; a named extension replaces one of the same name
 cero.use = (...exts) => {
   for (const e of exts.flat().map((e) => (typeof e === 'function' ? { setup: e } : e))) {
-    const i = e.name ? internal.extensions.findIndex((x) => x.name === e.name) : -1
-    if (i >= 0) internal.extensions[i] = e
-    else internal.extensions.push(e)
+    const i = e.name ? registry.findIndex((x) => x.name === e.name) : -1
+    if (i >= 0) registry[i] = e
+    else registry.push(e)
   }
 }
 

package/src/lib/bluetooth.js

@@ -8,19 +8,8 @@ import { Pairing } from '@cero-base/core/pairing'
 import { Invite } from '@cero-base/core/invite'
 
 /**
- * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
- * facade over ble-swarm. Bluetooth only changes how peers meet and carry
- * bytes; capability-gated replication still decides what syncs. Discovery is
- * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
- * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
- *
- * ```js
- * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
- * await me.bluetooth.start()
- * me.bluetooth.peers          // Map of live BLE links
- * me.bluetooth.on('update', () => {})
- * ```
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin facade over
+ * ble-swarm.
  *
  * @extends ReadyResource
  */
@@ -43,14 +32,11 @@ export class Bluetooth extends ReadyResource {
     this._restorePending = false
 
     const identity = handle.identity
-    // the mesh topic: one per channel, or a fixed global topic when
-    // channelless — any nearby cero device links (global nearby; strangers
-    // still sync zero bytes, replication is capability-gated)
+    // one mesh topic per channel, or a global one when channelless; strangers still sync nothing
     this._topic = crypto.hash(b4a.from(handle.network.channel || 'cero-ble'))
     this.swarm = new BluetoothSwarm({
       backend,
-      // injected links authenticate with the same long-lived identity as the
-      // swarm, so one person reached over Wi-Fi and BLE dedupes to one peer
+      // the swarm identity, so one person over Wi-Fi and BLE dedupes to one peer
       keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey },
       topic: this._topic,
       tag: 'cero-ble',
@@ -59,9 +45,7 @@ export class Bluetooth extends ReadyResource {
       maxInbound
     })
     this.swarm.on('update', () => {
-      // an ended rendezvous retunes back to the mesh only once its links
-      // drain — retuning drops links, and the pairing link still carries
-      // the joiner's initial replication
+      // retune to the mesh only once the pairing link's initial replication drained
       if (this._restorePending && this.swarm.peers.size === 0) {
         this._restorePending = false
         this.swarm.setTopic(this._topic).catch(safetyCatch)
@@ -69,7 +53,6 @@ export class Bluetooth extends ReadyResource {
       this.emit('update')
     })
     this.swarm.on('connection', (conn) => {
-      // the same treatment as any transport: wakeup, replication, pairing
       this._handle.network.inject(conn)
     })
   }
@@ -88,6 +71,11 @@ export class Bluetooth extends ReadyResource {
     if (this._autoStart) await this.start()
   }
 
+  async _close() {
+    this._clearAnnounce()
+    await this.swarm.destroy()
+  }
+
   /**
    * Begin advertising + scanning. Idempotent; no-op when unsupported.
    *
@@ -98,34 +86,20 @@ export class Bluetooth extends ReadyResource {
   }
 
   /**
-   * Stop advertising/scanning and drop links; open invite rendezvous end with
-   * the radio. Idempotent. Local data and the rest of the network (DHT) are
-   * untouched.
+   * Stop advertising/scanning and drop links; open invite rendezvous end with the radio.
    *
    * @returns {Promise<void>}
    */
   async stop() {
     this._clearAnnounce()
     await this.swarm.stop()
-    // while stopped setTopic just sticks — the next start() is back on the
-    // mesh. A start() + announce() that landed during the await wins.
+    // while stopped setTopic sticks; a start() + announce() during the await wins
     if (!this._announce) await this.swarm.setTopic(this._topic)
   }
 
   /**
-   * Offline join rendezvous: retune the radio to the invite-derived topic so
-   * holder and joiner find each other with zero DHT. One topic at a time —
-   * announcing a new invite replaces the previous rendezvous. Returns a stop
-   * function — closing the QR must stop the rendezvous so a photographed
-   * invite doesn't stay an ambient discovery beacon (admission itself is
-   * always gated by blind-pairing verifying the invite). The retune back to
-   * the mesh topic waits for live links to drain: the link a join just
-   * established survives and carries the joiner's initial replication.
-   * Auto-stops at the invite's expiry, on `stop()`, and on close.
-   *
-   * Only active while nearby sync is on: before `start()` (and after `stop()`)
-   * this is a no-op — the user controls the radio, and a join must not touch
-   * Bluetooth (OS permissions, GATT server) they never enabled.
+   * Offline join rendezvous: retune the radio to the invite-derived topic so holder and
+   * joiner find each other with zero DHT.
    *
    * @param {string} invite  Z32 invite string.
    * @returns {() => void}
@@ -161,20 +135,6 @@ export class Bluetooth extends ReadyResource {
     }
   }
 
-  _stopAnnounce() {
-    this._clearAnnounce()
-    if (this.swarm.peers.size > 0) this._restorePending = true
-    else this.swarm.setTopic(this._topic).catch(safetyCatch)
-  }
-
-  _clearAnnounce() {
-    const e = this._announce
-    if (!e) return
-    if (e.timer) clearTimeout(e.timer)
-    this._announce = null
-    this._restorePending = false
-  }
-
   /**
    * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
    *
@@ -193,8 +153,17 @@ export class Bluetooth extends ReadyResource {
     await this.swarm.resume()
   }
 
-  async _close() {
+  _stopAnnounce() {
     this._clearAnnounce()
-    await this.swarm.destroy()
+    if (this.swarm.peers.size > 0) this._restorePending = true
+    else this.swarm.setTopic(this._topic).catch(safetyCatch)
+  }
+
+  _clearAnnounce() {
+    const e = this._announce
+    if (!e) return
+    if (e.timer) clearTimeout(e.timer)
+    this._announce = null
+    this._restorePending = false
   }
 }

package/src/lib/constants.js

@@ -1,5 +1,3 @@
-// Shared cero constants.
-
 export const NS = 'cero'
 export const COUNTERS = 'counters'
 export const EPOCHS = 'epochs'
@@ -7,16 +5,3 @@ export const EPOCHS = 'epochs'
 // Writer-admission / pairing timeout (ms), and the initial discovery-flush wait (ms).
 export const TIMEOUT = 30000
 export const FLUSH = 500
-
-// schema-DSL primitive → HyperDB type (used by the builder).
-export const DB_TYPE = {
-  string: 'string',
-  uint: 'uint',
-  int: 'int',
-  bool: 'bool',
-  bytes: 'buffer',
-  json: 'json',
-  fixed32: 'fixed32',
-  fixed64: 'fixed64',
-  file: 'string'
-}

package/src/lib/operators.js

@@ -30,9 +30,7 @@ export function resolveFile(handle, id, name) {
 }
 
 /**
- * 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.
+ * Insert (or overwrite by id) a row on `ref`.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
@@ -55,9 +53,7 @@ async function putFile(ref, row) {
 }
 
 /**
- * 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).
+ * Upsert a row on `ref` — merges with the existing row and preserves `createdAt`.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
@@ -101,13 +97,10 @@ 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'] }
 
 /**
- * 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.
+ * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path (awaited).
  *
  * @param {Ref} ref
  * @param {(ctx: { op: string, name: string, row: any }) => any} fn
@@ -130,9 +123,8 @@ export function before(ref, fn, opts) {
 }
 
 /**
- * Subscribe to writes on `ref` — fires after each committed write,
- * non-blocking (observe only). Returns an unsubscribe fn; pass `{ signal }`
- * to unsubscribe on abort.
+ * Subscribe to writes on `ref` — fires after each committed write, non-blocking (observe
+ * only).
  *
  * @param {Ref} ref
  * @param {(ctx: { op: string, name: string, row: any }) => void} fn
@@ -153,10 +145,7 @@ export function after(ref, fn, opts) {
   return off
 }
 
-// get/watch on a handle-kind ref list its rows from the `handles` collection
-// filtered by type (handle types are stored there with their { id, key,
-// encryptionKey, name }). Data-kind refs go straight to the store.
-// For handle-kind refs on the facade, the parent store lives on `root`.
+// handle refs read their rows from the parent's `handles` collection, filtered by type
 const parentStore = (ref) => (ref.handle.root ? ref.handle.root.store : ref.handle.store)
 
 const normalize = (rows, name) => {
@@ -195,9 +184,7 @@ function resolveRow(ref, row) {
 }
 
 /**
- * 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.
+ * Read from `ref`. For data refs, dispatches to the underlying store.
  *
  * @param {Ref} ref
  * @param {string | Record<string, any>} [q]
@@ -212,22 +199,17 @@ export async function get(ref, q) {
   return resolveResult(ref, res)
 }
 
-// Tie a fresh watch stream to its handle's lifecycle (destroyed on close) and
-// to an optional `{ signal }` (destroyed on abort). Local refs have no
-// close-cascade, so they keep managing their own streams.
+// a watch stream dies with its handle, or with the signal
 const bindStream = (owner, stream, opts) => {
   const stopAbort = onAbort(opts?.signal, () => stream.destroy())
-  // drop the abort listener once the stream ends, so it doesn't linger on a
-  // long-lived signal after the stream is gone
+  // drop the abort listener once the stream ends
   if (stopAbort) stream.once('close', stopAbort)
   return owner.own ? owner.own(stream) : stream
 }
 
 /**
- * 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.
+ * Live snapshot stream on `ref` — re-emits the latest `get()` result on every underlying
+ * mutation.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} [q]
@@ -247,10 +229,9 @@ export function watch(ref, q, opts) {
 }
 
 /**
- * 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.
+ * 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.
  */
 export function changes(ref, q, opts) {
   const owner = ref.handle
@@ -297,9 +278,7 @@ export function changes(ref, q, opts) {
   return bindStream(owner, out, opts)
 }
 
-// Snapshots are idempotent — under a slow consumer hold only the NEWEST one
-// instead of queueing every intermediate (a busy room + un-drained reader
-// used to buffer full result sets without bound).
+// snapshots are idempotent: a slow consumer gets only the newest
 function snapshotStream(src, map) {
   let pending
   let wanted = false
@@ -329,19 +308,8 @@ function snapshotStream(src, map) {
   return out
 }
 
-// Universal signal instantiator. Dispatch on the second arg:
-//   string                  → join via invite
-//   { invite: string }      → join via invite (object form)
-//   { id: string }          → load an existing handle by id
-//   object | undefined      → create (opts)
 /**
- * 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
+ * Open (or create / join / load) a child handle through a `handle`-kind ref.
  *
  * @param {Ref} ref
  * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
@@ -355,13 +323,9 @@ export function open(ref, arg) {
 }
 
 /**
- * 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)
+ * 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.
  *
  * @param {any} handle
  * @returns {Promise<{ epoch: number }>}
@@ -370,16 +334,8 @@ export function rotate(handle) {
   return handle.store.rotate()
 }
 
-// ─── custom operators ──────────────────────────────────────────────────────
-// App business logic lives as custom operators: pure functions whose first arg
-// is the handle they act on, composed from the operators above. `define`
-// registers them by scope; `bind` puts them on a handle — either an explicit
-// `{ ns: module }` map, or (given a scope) the registered operators for that
-// scope, which is how cero auto-binds the root and each child as it opens.
-
 const registry = {}
 
-// Curry `handle` as arg 0 of every function in `fns`, under `handle[ns]`.
 function attach(handle, ns, fns) {
   const bound = {}
   for (const key of Object.keys(fns)) {
@@ -390,12 +346,7 @@ function attach(handle, ns, fns) {
 
 /**
  * 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.
+ * `handle.ns.fn(args)` calls `fn(handle, args)`.
  *
  * @param {any} handle
  * @param {Record<string, any> | string | null} arg
@@ -418,9 +369,8 @@ export function bind(handle, arg) {
 }
 
 /**
- * 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.
+ * 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.
  *
  * @param {Record<string, any>} map
  */

package/src/lib/peek.js

@@ -6,14 +6,11 @@ import { CeroError } from '@cero-base/core/errors'
 
 import { Local } from '../local/index.js'
 
-// Lives outside operators.js so the storage deps stay off the RPC client's
-// module graph — bundlers follow even dynamic imports, and a browser build
-// must never reach hypercore/sodium.
+// outside operators.js so storage deps stay off the client's module graph
 
 /**
- * Quickly check whether the on-disk directory at `dir` already holds an
- * initialised cero identity (i.e. a stored master seed). Opens the local store
- * read-only and closes everything before returning.
+ * Quickly check whether the on-disk directory at `dir` already holds an initialised cero
+ * identity (i.e. a stored master seed).
  *
  * @param {string} dir   Cero data directory.
  * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
@@ -23,8 +20,7 @@ export async function peek(dir, spec) {
   if (typeof dir !== 'string' || !dir) throw CeroError.INVALID('dir must be a non-empty string')
   if (!spec) throw CeroError.REQUIRED('spec')
 
-  // Construct first (cheap), ready inside the try — a corrupt dir that throws in
-  // any ready() must still close root + store + local, not leak the storage lock.
+  // construct first, ready inside the try: a corrupt dir must still close everything
   const root = new HypercoreStorage(`${dir}/main`)
   const store = new Corestore(root, { manifestVersion: 2 })
   const local = new Local(null, spec, { store })

package/src/lib/refs.js

@@ -9,9 +9,7 @@ import { CeroError } from '@cero-base/core/errors'
  */
 
 /**
- * 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.
+ * Typed pointer to a single ref (table or handle slot) on a `Handle` or `Local`.
  */
 export class Ref {
   /**
@@ -36,8 +34,7 @@ export class Ref {
    */
   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
+      // a ref named like a reserved member must fail loud, not overwrite it
       if (name in target) {
         throw CeroError.INVALID(
           `schema ref '${name}' collides with a reserved ${target.constructor?.name || 'handle'} member — rename it`

package/src/lib/spec.js

@@ -1,6 +1,5 @@
 /**
- * Re-exports of the schema DSL (`t`) and `schema()` wrapper from
- * `@cero-base/core/schema`, so cero apps can describe their tables without
- * pulling in the core package directly.
+ * Re-exports of the schema DSL (`t`) and `schema()` wrapper from `@cero-base/core/schema`,
+ * so cero apps can describe their tables without pulling in the core package directly.
  */
 export { t, schema } from '@cero-base/core/schema'

package/src/local/index.js

@@ -13,9 +13,8 @@ import { Ref } from '../lib/refs.js'
  */
 
 /**
- * Per-device, single-writer storage for cero — holds the master seed,
- * device keypair and any per-handle keypairs. Wraps a hyperbee-backed
- * `Storage` and exposes each local ref as a property of the instance.
+ * Per-device, single-writer storage for cero — holds the master seed, device keypair and
+ * any per-handle keypairs.
  */
 export class Local extends ReadyResource {
   /**