@cero-base/cero 0.6.0 → 0.8.0

package/README.md

@@ -140,16 +140,18 @@ const { data: n } = await cero.count(room.messages)
 const { data: n } = await cero.count(room.messages, { gt: 'm-2025' })
 ```
 
-### `cero.watch(ref, q?)`
+### `cero.watch(ref, q?, opts?)`
 
-A Readable stream that re-emits the latest snapshot on every change. Always emits an initial snapshot.
+A Readable stream that re-emits the latest snapshot on every change. Always emits an initial snapshot. The stream is **tied to the ref's handle** — closing the handle destroys it, so a watch never outlives its store and you don't track cleanup. Pass `{ signal }` to bind it to a finer scope instead.
 
 ```js
 const stream = cero.watch(room.messages, { limit: 50, reverse: true })
 stream.on('data', ({ data, total, size }) => {
   /* render */
 })
-// stream.destroy() to stop
+// stops on room.close(), on stream.destroy(), or on `signal` abort:
+const ac = new AbortController()
+cero.watch(room.messages, null, { signal: ac.signal }) // ac.abort() ⇒ destroyed
 ```
 
 ### `cero.call(actionRef, data)`
@@ -173,6 +175,112 @@ await cero.open(me.room, { id: existingRoomId }) // load an existing room by id
 
 Returns the child handle, ready to operate on (`cero.put(joined.messages, …)` etc.).
 
+### `cero.before(ref, fn, opts?)` / `cero.after(ref, fn, opts?)`
+
+Hook into writes to a ref. `before` runs **in-path** before the write commits — return `false` to cancel, or mutate `ctx.row`. `after` is a non-blocking **event** that fires once the write has committed. Both return an unsubscribe fn — call it to stop early, ignore it for a subscription that lives as long as the handle, or pass `{ signal }` to unsubscribe when an `AbortSignal` fires (e.g. `{ signal: me.signal }` to stop on close).
+
+```js
+const off = cero.before(room.messages, (ctx) => {
+  if (!ctx.row.text?.trim()) return false // reject empty messages
+})
+
+cero.after(me.profile, ({ row }) => {
+  /* react to your profile changing */
+})
+```
+
+`ctx` is `{ op, name, row }` (plus `result` in `after`).
+
+## Extensions
+
+An extension bundles **schema** (build-time) with **behavior** (runtime). Register it with `cero.use()` — `build()` folds in its schema and `cero()` runs its `setup` once the handle is ready. cero core stays schema-agnostic; apps opt into the behaviors they want.
+
+```js
+import { profileSync } from '@cero-base/cero/extensions'
+
+cero.use(profileSync()) // before build() (for the schema) and before cero() (for the behavior)
+await build('./spec', schema)
+```
+
+An extension is two optional parts:
+
+```js
+function myExtension() {
+  return {
+    schema: { members: cero.t.extend({ status: cero.t.string }) }, // merged into your schema
+    setup(me) {
+      const onHandle = (room, opts) => {
+        /* opts carries the open args (e.g. opts.name on create); me.children is the set of open rooms */
+      }
+      me.on('handle', onHandle, { signal: me.signal }) // dropped on me.close()
+    }
+  }
+}
+```
+
+For a behavior-only extension (no schema), pass a function directly — it's shorthand for `{ setup }`:
+
+```js
+cero.use((me) => {
+  me.on('handle', (room) => {
+    /* … */
+  })
+})
+```
+
+Build and the running app are separate processes, so `cero.use()` runs in both — your build script (for the schema) and once at app startup before `cero()` (for the behavior).
+
+### Cleanup
+
+You rarely write teardown — a handle's subscriptions follow the same "dies with the node" model as DOM events:
+
+- **`cero.watch(ref)` streams** are destroyed automatically when the ref's handle closes.
+- **`me.on(...)`, `before`, `after`** take `{ signal }` to drop themselves when an `AbortSignal` fires.
+- **`me.signal`** is an `AbortSignal` that aborts on `me.close()`. Pass it to tie a subscription to the handle's life, or use your own `AbortController` for a finer scope (drop it before the handle closes):
+
+```js
+setup(me) {
+  me.on('handle', onHandle, { signal: me.signal }) // dropped when me closes
+  cero.after(me.profile, onProfile, { signal: me.signal })
+}
+```
+
+For anything the close cascade won't reach — a timer, an external connection, a stream you made yourself — hand it to **`me.own(resource)`** (destroyed on close) or return a disposer from `setup`:
+
+```js
+setup(me) {
+  const timer = setInterval(() => ping(me), 30_000)
+  me.own({ destroy: () => clearInterval(timer) }) // tied to me.close()
+  // …or: return () => clearInterval(timer)
+}
+```
+
+### `profileSync` (bundled)
+
+Mirrors your `profile` onto your `member` row in every room, so others see your name and avatar. It **declares its own `profile` single** (`name` + the synced fields) and extends `member` with them — no app schema required. Defaults to syncing `avatar`:
+
+```js
+cero.use(profileSync())
+cero.use(profileSync({ fields: { status: cero.t.string } })) // sync extra fields
+```
+
+Want a richer profile (e.g. a `bio` that doesn't sync)? Declare your own `profile` single — the app schema wins, and `profileSync` still adds the member side.
+
+### `handleSync` (bundled)
+
+Mirrors a child handle's `profile` (name + avatar) onto its row in the parent's `handles` list — so a handle/room list renders names and photos without opening each handle. Adds `avatar` (or your `fields`) to the `handle` builtin and reflects the handle's own `profile` (which your app owns) onto the row.
+
+```js
+cero.use(handleSync())
+
+// your handle type declares a `profile`; your app sets it:
+const room = await cero.open(me.room)
+await cero.set(room.profile, { name: 'general', avatar: 'pic.png' })
+// → the me.handles row now carries name + avatar — render the room list, no opens
+```
+
+Requires your handle types to declare a `profile` single; handles without one are left untouched.
+
 ## RPC
 
 cero runs in one process; your UI runs in another. Connect them with any duplex stream (Bare IPC, Electron `contextBridge`, a worker port, even a TCP socket).
@@ -263,12 +371,13 @@ const remote = await connect(c, spec)
 
 ## Exports
 
-| Path                     | What you get                                                             |
-| ------------------------ | ------------------------------------------------------------------------ |
-| `@cero-base/cero`        | factory + operators + schema DSL                                         |
-| `@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/build`  | `build(specDir, schema)` — generate the on-disk spec                     |
+| Path                         | What you get                                                             |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `@cero-base/cero`            | factory + operators + schema DSL                                         |
+| `@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/build`      | `build(specDir, schema)` — generate the on-disk spec                     |
+| `@cero-base/cero/extensions` | bundled extensions (`profileSync`, …)                                    |
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "main": "./src/index.js",
@@ -30,6 +30,10 @@
     "./client": {
       "types": "./types/rpc/client.d.ts",
       "default": "./src/rpc/client.js"
+    },
+    "./extensions": {
+      "types": "./types/extensions/index.d.ts",
+      "default": "./src/extensions/index.js"
     }
   },
   "typesVersions": {
@@ -42,6 +46,9 @@
       ],
       "client": [
         "types/rpc/client.d.ts"
+      ],
+      "extensions": [
+        "types/extensions/index.d.ts"
       ]
     }
   },
@@ -67,7 +74,7 @@
     "test": "ls test/*.test.js | xargs -P2 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^0.6.0",
+    "@cero-base/core": "^0.8.0",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.13.7",
     "bare-fs": "^4.7.1",

package/src/build/index.js

@@ -9,6 +9,7 @@ import HRPCBuilder from 'hrpc'
 import { CeroError } from '@cero-base/core/errors'
 
 import { NS } from '../lib/constants.js'
+import { internal } from '../lib/internal.js'
 import {
   refs,
   builtinRefs,
@@ -45,19 +46,23 @@ export async function build(specDir, schema, { ns = NS } = {}) {
   const raw = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
   if (!raw || typeof raw !== 'object') throw CeroError.REQUIRED('schema')
 
-  // Pull out `t.extend(...)` entries (keyed by builtin ref name) and map them
-  // to the builtin's type name, to merge into builtin types across every scope.
+  // Pull out `t.extend(...)` entries (keyed by builtin ref name) → builtin type
+  // name, merged across scopes. App schema first, then each `cero.use()` extension.
   const extend = {}
   const defs = {}
-  for (const [k, v] of Object.entries(raw)) {
-    if (v && v.kind === 'extend') {
-      const type = refs.main[k]?.type
-      if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
-      extend[type] = v.fields
-    } else {
-      defs[k] = v
+  const collect = (entries, fromExt = false) => {
+    for (const [k, v] of Object.entries(entries)) {
+      if (v && v.kind === 'extend') {
+        const type = refs.main[k]?.type
+        if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
+        extend[type] = { ...extend[type], ...v.fields }
+      } else if (!fromExt || !(k in defs)) {
+        defs[k] = v // app schema wins over an extension's default
+      }
     }
   }
+  collect(raw)
+  for (const ext of internal.extensions) if (ext.schema) collect(ext.schema, true)
 
   const main = compile(splitMain(defs), ns, 'main')
   const local = compile(defs.local || {}, ns, 'local')

package/src/extensions/handle-sync.js

@@ -0,0 +1,31 @@
+import { t } from '../lib/spec.js'
+import { set, watch } from '../lib/operators.js'
+
+/**
+ * Mirror a child handle's `profile` (name + avatar) onto its row in the parent's
+ * `handles` list — so a handle list shows names + avatars without opening each
+ * one. Adds the synced `fields` to the `handle` builtin.
+ *
+ * On create it seeds the handle's `profile.name` from the open `{ name }`, then
+ * reflects the (app-owned) `profile` onto the row. Requires your handle types to
+ * declare a `profile` single — handles without one are left untouched.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function handleSync({ fields = { avatar: t.string } } = {}) {
+  return {
+    schema: { handles: t.extend(fields) },
+    setup(me) {
+      const onHandle = (child, opts) => {
+        if (!child.profile) return
+        if (opts.name) set(child.profile, { name: opts.name }).catch(me._onerror)
+        watch(child.profile).on('data', ({ data }) => {
+          if (!data?.name) return
+          child.name = data.name
+          set(me.handles, { id: child.id, ...data }, { upsert: false }).catch(me._onerror)
+        })
+      }
+      me.on('handle', onHandle, { signal: me.signal })
+    }
+  }
+}

package/src/extensions/index.js

@@ -0,0 +1,2 @@
+export * from './profile-sync.js'
+export * from './handle-sync.js'

package/src/extensions/profile-sync.js

@@ -0,0 +1,36 @@
+import { t } from '../lib/spec.js'
+import { get, set, after } from '../lib/operators.js'
+
+/**
+ * Mirror your `profile` onto your `member` row in every handle you're in.
+ * Declares a `profile` single (`name`, `avatar`, plus any extra `fields`) and
+ * mirrors them onto the `member` builtin, then publishes when you open/join a
+ * handle and whenever your profile changes. An app may declare its own richer
+ * `profile` instead — the app schema wins.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function profileSync({ fields = { avatar: t.string } } = {}) {
+  return {
+    schema: {
+      profile: t.single({ name: t.string, ...fields }),
+      members: t.extend(fields)
+    },
+    setup(me) {
+      const publish = (child, profile) =>
+        set(child.members, { id: me.identity.id, ...profile }, { upsert: false }).catch(me._onerror)
+
+      const onHandle = async (child) => {
+        const { data: profile } = await get(me.profile)
+        if (profile) publish(child, profile)
+      }
+
+      const onProfile = (ctx) => {
+        if (ctx.row) me.children.forEach((child) => publish(child, ctx.row))
+      }
+
+      me.on('handle', onHandle, { signal: me.signal })
+      after(me.profile, onProfile, { signal: me.signal })
+    }
+  }
+}

package/src/handle/index.js

@@ -13,7 +13,7 @@ import { CeroError } from '@cero-base/core/errors'
 
 import { NS, TIMEOUT } from '../lib/constants.js'
 
-import { attachRefs } from '../lib/utils.js'
+import { attachRefs, onAbort } from '../lib/utils.js'
 
 export { Ref } from '../lib/utils.js'
 
@@ -110,6 +110,7 @@ export class Handle extends ReadyResource {
     this._opts = opts.opts || {}
     this._onerror = this._opts.onerror || safetyCatch
     this.children = parent ? null : new Set()
+    this._owned = new Set()
 
     this.store = new Database({
       store: store,
@@ -137,16 +138,11 @@ export class Handle extends ReadyResource {
       await this.pair.ready()
     }
     attachRefs(this, this.store.refs)
-    if (!this.children) return
-
-    this._offUpdate = this.store.onUpdate(() => {
-      if (this.closing || this.closed) return
-      for (const c of this.children) this._syncMember(c).catch(this._onerror)
-    })
   }
 
   async _close() {
-    this._offUpdate?.()
+    for (const r of [...this._owned]) r.destroy?.()
+    this._owned.clear()
     if (this.children) {
       for (const c of [...this.children]) await c.close()
       this.children.clear()
@@ -168,6 +164,56 @@ export class Handle extends ReadyResource {
     if (this._storage) await this._storage.close()
   }
 
+  /**
+   * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`)
+   * to this handle's lifecycle — it's destroyed automatically on close, so
+   * callers don't track cleanup. De-registers itself if destroyed earlier.
+   *
+   * @template {{ destroy?: Function, once?: Function }} T
+   * @param {T} resource
+   * @returns {T}
+   */
+  own(resource) {
+    if (this.closing || this.closed) {
+      resource.destroy?.()
+      return resource
+    }
+    this._owned.add(resource)
+    resource.once?.('close', () => this._owned.delete(resource))
+    return resource
+  }
+
+  /**
+   * An `AbortSignal` that fires when this handle closes. Pass it as
+   * `{ signal }` to `on`/`after`/`before`/`watch` to drop a subscription on
+   * close — or use your own `AbortController` for a finer scope.
+   *
+   * @returns {AbortSignal}
+   */
+  get signal() {
+    if (!this._ac) {
+      this._ac = new AbortController()
+      if (this.closed) this._ac.abort()
+      else this.once('close', () => this._ac.abort())
+    }
+    return this._ac.signal
+  }
+
+  /**
+   * `EventEmitter.on` plus an optional `{ signal }` that removes the listener
+   * when the signal aborts — e.g. `me.on('handle', fn, { signal: me.signal })`.
+   *
+   * @param {string} event
+   * @param {(...args: any[]) => void} fn
+   * @param {{ signal?: AbortSignal }} [opts]
+   * @returns {this}
+   */
+  on(event, fn, opts) {
+    super.on(event, fn)
+    onAbort(opts?.signal, () => super.off(event, fn))
+    return this
+  }
+
   /** Canonical id — identity id for the root handle, store key for children. */
   get id() {
     if (!this.parent) return this.identity.id
@@ -340,7 +386,6 @@ export class Handle extends ReadyResource {
       createdAt: ts,
       updatedAt: ts
     })
-    if (name && child.profile) await child.store.set('profile', { name })
     await this.store.call('add-handle', {
       id,
       type,
@@ -353,7 +398,7 @@ export class Handle extends ReadyResource {
 
     if (accept !== false) this._wireAccept(child, { role })
     this.children.add(child)
-    await this._syncMember(child)
+    this.emit('handle', child, { name, role })
     return child
   }
 
@@ -396,20 +441,19 @@ export class Handle extends ReadyResource {
     const id = toId(child.store.key)
     await this._saveKeyPair(id, child.store.keyPair)
 
-    const name = child.profile ? await waitForProfileName(child, deadline) : null
     const ts = Date.now()
     await this.store.call('add-handle', {
       id,
       type,
       key: child.store.key,
       encryptionKey: child.store.encryptionKey,
-      name,
+      name: null,
       createdAt: ts,
       updatedAt: ts
     })
     this._wireAccept(child)
     this.children.add(child)
-    await this._syncMember(child)
+    this.emit('handle', child, {})
     return child
   }
 
@@ -452,6 +496,7 @@ export class Handle extends ReadyResource {
     }
     this._wireAccept(child)
     this.children.add(child)
+    this.emit('handle', child, {})
     return child
   }
 
@@ -534,20 +579,6 @@ export class Handle extends ReadyResource {
     })
   }
 
-  async _syncMember(child) {
-    if (!child.store.writable) return
-    const { data: profile } = await this.store.get('profile')
-    if (!profile) return
-    const { data: existing } = await child.store.get('members', this.identity.id)
-    if (!existing) return
-    await child.store.call('set-member', {
-      ...existing,
-      ...profile,
-      id: existing.id,
-      updatedAt: Date.now()
-    })
-  }
-
   /**
    * @param {Handle} child
    * @param {{ role?: string }} [opts]
@@ -597,13 +628,3 @@ function pickHandle(spec, type) {
 function randomNs() {
   return z32.encode(Identity.randomBytes(8))
 }
-
-async function waitForProfileName(child, timeout) {
-  const deadline = Date.now() + timeout
-  while (Date.now() < deadline) {
-    const { data } = await child.store.get('profile')
-    if (data?.name) return data.name
-    await new Promise((r) => setTimeout(r, 100))
-  }
-  return null
-}

package/src/index.js

@@ -8,13 +8,14 @@ import { CeroError } from '@cero-base/core/errors'
 
 import { Handle, Ref } from './handle/index.js'
 import { Local } from './local/index.js'
-import { put, set, get, del, count, watch, call, open } from './lib/operators.js'
+import { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
 import { FLUSH } from './lib/constants.js'
+import { internal } from './lib/internal.js'
 
 export { Handle, Ref, Local }
-export { put, set, get, del, count, watch, call, open } from './lib/operators.js'
+export { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
 export { peek } from './lib/peek.js'
 export { t, schema } from './lib/spec.js'
 
@@ -112,6 +113,11 @@ export async function cero(dir, spec, opts = {}) {
   }
   if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
 
+  for (const ext of internal.extensions) {
+    const off = await ext.setup?.(me)
+    if (typeof off === 'function') me.once('close', off)
+  }
+
   return me
 }
 
@@ -150,7 +156,26 @@ export async function restore(me, phrase) {
   })
 }
 
-Object.assign(cero, { put, set, get, del, count, watch, call, open, peek, restore, t, schema })
+Object.assign(cero, {
+  t,
+  put,
+  set,
+  get,
+  del,
+  count,
+  watch,
+  call,
+  open,
+  before,
+  after,
+  peek,
+  restore,
+  schema
+})
+cero._internal = internal
+// A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.
+cero.use = (...exts) =>
+  internal.extensions.push(...exts.map((e) => (typeof e === 'function' ? { setup: e } : e)))
 
 async function resolveIdentity(opts, local) {
   if (opts.identity) return opts.identity

package/src/lib/internal.js

@@ -0,0 +1,3 @@
+// Process-wide registry for extensions registered via `cero.use()`.
+// `build()` folds in each extension's schema; `cero()` runs each setup.
+export const internal = { extensions: [] }

package/src/lib/operators.js

@@ -1,5 +1,7 @@
 import { Readable } from 'streamx'
 
+import { onAbort } from './utils.js'
+
 /**
  * @typedef {import('./utils.js').Ref} Ref
  * @typedef {{ data: any }} SingleResult
@@ -18,13 +20,15 @@ export const put = (ref, row) => ref.handle.store.put(ref.name, row)
 
 /**
  * Upsert a row on `ref` — merges with the existing row and preserves
- * `createdAt`.
+ * `createdAt`. Pass `{ upsert: false }` to update-only: a missing row is left
+ * untouched instead of created (atomic — never resurrects a deleted row).
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
+ * @param {{ upsert?: boolean }} [opts]
  * @returns {Promise<SingleResult>}
  */
-export const set = (ref, row) => ref.handle.store.set(ref.name, row)
+export const set = (ref, row, opts) => ref.handle.store.set(ref.name, row, opts)
 
 /**
  * Delete a row by id (collection refs), or wipe the row (single refs).
@@ -53,6 +57,50 @@ export const count = (ref, q) => ref.handle.store.count(ref.name, q)
  */
 export const call = (ref, d) => 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.
+ *
+ * @param {Ref} ref
+ * @param {(ctx: { op: string, name: string, row: any }) => any} fn
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {() => void}
+ */
+export const before = (ref, fn, opts) => {
+  const db = ref.handle.store
+  const ops = WRITES[ref.kind] || ['set']
+  const offs = ops.map((op) =>
+    db.before(op, (ctx) => (ctx.name === ref.name ? fn(ctx) : undefined))
+  )
+  const off = () => offs.forEach((unsub) => unsub())
+  onAbort(opts?.signal, off)
+  return off
+}
+
+/**
+ * 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 const after = (ref, fn, opts) => {
+  const db = ref.handle.store
+  const ops = WRITES[ref.kind] || ['set']
+  const handler = (ctx) => ctx.name === ref.name && fn(ctx)
+  for (const op of ops) db.on(`after:${op}`, handler)
+  const off = () => ops.forEach((op) => db.off(`after:${op}`, handler))
+  onAbort(opts?.signal, off)
+  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.
@@ -79,16 +127,28 @@ export const get = async (ref, q) => {
   return normalize(all, ref.name)
 }
 
+// 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.
+const bindStream = (owner, stream, opts) => {
+  onAbort(opts?.signal, () => stream.destroy())
+  return owner.own ? owner.own(stream) : stream
+}
+
 /**
  * Live snapshot stream on `ref` — re-emits the latest `get()` result on
- * every underlying mutation. Destroy the stream to stop watching.
+ * 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 const watch = (ref, q) => {
-  if (ref.kind !== 'handle') return ref.handle.store.watch(ref.name, q)
+export const watch = (ref, q, opts) => {
+  const owner = ref.handle
+  if (ref.kind !== 'handle') return bindStream(owner, owner.store.watch(ref.name, q), opts)
   const source = parentStore(ref).watch('handles', q)
   const out = new Readable({
     destroy(cb) {
@@ -99,7 +159,7 @@ export const watch = (ref, q) => {
   source.on('data', (snap) => out.push(normalize(snap?.data, ref.name)))
   source.on('end', () => out.push(null))
   source.on('error', (err) => out.destroy(err))
-  return out
+  return bindStream(owner, out, opts)
 }
 
 // Universal signal instantiator. Dispatch on the second arg:

package/src/lib/utils.js

@@ -39,3 +39,16 @@ export function attachRefs(target, refs) {
     target[name] = new Ref(target, name, info.kind, info.schema)
   }
 }
+
+/**
+ * Run `cb` when `signal` aborts — or immediately if it already has. No-op
+ * without a signal. The listener removes itself on fire.
+ *
+ * @param {AbortSignal} [signal]
+ * @param {() => void} cb
+ */
+export function onAbort(signal, cb) {
+  if (!signal) return
+  if (signal.aborted) return cb()
+  signal.addEventListener('abort', cb, { once: true })
+}

package/types/build/schemas.d.ts

@@ -1,153 +1,153 @@
 export const main: {
     'del-by-id': {
-        id: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
     };
     writer: {
-        master: import("@cero-base/core/schema").Prim;
-        writer: import("@cero-base/core/schema").Prim;
-        sig: import("@cero-base/core/schema").Prim;
-        isIndexer: import("@cero-base/core/schema").Prim;
+        master: import("@cero-base/core").Prim;
+        writer: import("@cero-base/core").Prim;
+        sig: import("@cero-base/core").Prim;
+        isIndexer: import("@cero-base/core").Prim;
     };
     counter: {
-        name: import("@cero-base/core/schema").Prim;
-        value: import("@cero-base/core/schema").Prim;
+        name: import("@cero-base/core").Prim;
+        value: import("@cero-base/core").Prim;
     };
     member: {
-        id: import("@cero-base/core/schema").Prim;
-        key: import("@cero-base/core/schema").Prim;
-        role: import("@cero-base/core/schema").Prim;
-        name: import("@cero-base/core/schema").Prim;
-        createdAt: import("@cero-base/core/schema").Prim;
-        updatedAt: import("@cero-base/core/schema").Prim;
-        sig: import("@cero-base/core/schema").Prim;
-        index: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        key: import("@cero-base/core").Prim;
+        role: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        updatedAt: import("@cero-base/core").Prim;
+        sig: import("@cero-base/core").Prim;
+        index: import("@cero-base/core").Prim;
     };
     device: {
-        id: import("@cero-base/core/schema").Prim;
-        memberId: import("@cero-base/core/schema").Prim;
-        name: import("@cero-base/core/schema").Prim;
-        isMobile: import("@cero-base/core/schema").Prim;
-        createdAt: import("@cero-base/core/schema").Prim;
-        updatedAt: import("@cero-base/core/schema").Prim;
-        index: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        memberId: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
+        isMobile: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        updatedAt: import("@cero-base/core").Prim;
+        index: import("@cero-base/core").Prim;
     };
     invite: {
-        id: import("@cero-base/core/schema").Prim;
-        invite: import("@cero-base/core/schema").Prim;
-        publicKey: import("@cero-base/core/schema").Prim;
-        data: import("@cero-base/core/schema").Prim;
-        sig: import("@cero-base/core/schema").Prim;
-        role: import("@cero-base/core/schema").Prim;
-        expires: import("@cero-base/core/schema").Prim;
-        createdAt: import("@cero-base/core/schema").Prim;
-        index: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        invite: import("@cero-base/core").Prim;
+        publicKey: import("@cero-base/core").Prim;
+        data: import("@cero-base/core").Prim;
+        sig: import("@cero-base/core").Prim;
+        role: import("@cero-base/core").Prim;
+        expires: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        index: import("@cero-base/core").Prim;
     };
     handle: {
-        id: import("@cero-base/core/schema").Prim;
-        type: import("@cero-base/core/schema").Prim;
-        key: import("@cero-base/core/schema").Prim;
-        encryptionKey: import("@cero-base/core/schema").Prim;
-        name: import("@cero-base/core/schema").Prim;
-        createdAt: import("@cero-base/core/schema").Prim;
-        updatedAt: import("@cero-base/core/schema").Prim;
-        index: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        type: import("@cero-base/core").Prim;
+        key: import("@cero-base/core").Prim;
+        encryptionKey: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        updatedAt: import("@cero-base/core").Prim;
+        index: import("@cero-base/core").Prim;
     };
     claim: {
-        identity: import("@cero-base/core/schema").Prim;
-        writer: import("@cero-base/core/schema").Prim;
-        sig: import("@cero-base/core/schema").Prim;
+        identity: import("@cero-base/core").Prim;
+        writer: import("@cero-base/core").Prim;
+        sig: import("@cero-base/core").Prim;
     };
 };
 export const local: {
     master: {
-        seed: import("@cero-base/core/schema").Prim;
+        seed: import("@cero-base/core").Prim;
     };
     keypair: {
-        publicKey: import("@cero-base/core/schema").Prim;
-        secretKey: import("@cero-base/core/schema").Prim;
+        publicKey: import("@cero-base/core").Prim;
+        secretKey: import("@cero-base/core").Prim;
     };
     'handle-keypair': {
-        id: import("@cero-base/core/schema").Prim;
-        publicKey: import("@cero-base/core/schema").Prim;
-        secretKey: import("@cero-base/core/schema").Prim;
-        encryptionKey: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        publicKey: import("@cero-base/core").Prim;
+        secretKey: import("@cero-base/core").Prim;
+        encryptionKey: import("@cero-base/core").Prim;
     };
 };
 export const rpc: {
     'req-empty': {
-        ok: import("@cero-base/core/schema").Prim;
+        ok: import("@cero-base/core").Prim;
     };
     'req-restore': {
-        phrase: import("@cero-base/core/schema").Prim;
+        phrase: import("@cero-base/core").Prim;
     };
     'req-row': {
-        handle: import("@cero-base/core/schema").Prim;
-        ref: import("@cero-base/core/schema").Prim;
-        data: import("@cero-base/core/schema").Prim;
-        local: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        ref: import("@cero-base/core").Prim;
+        data: import("@cero-base/core").Prim;
+        local: import("@cero-base/core").Prim;
     };
     'req-id': {
-        handle: import("@cero-base/core/schema").Prim;
-        ref: import("@cero-base/core/schema").Prim;
-        id: import("@cero-base/core/schema").Prim;
-        local: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        ref: import("@cero-base/core").Prim;
+        id: import("@cero-base/core").Prim;
+        local: import("@cero-base/core").Prim;
     };
     'req-query': {
-        handle: import("@cero-base/core/schema").Prim;
-        ref: import("@cero-base/core/schema").Prim;
-        query: import("@cero-base/core/schema").Prim;
-        local: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        ref: import("@cero-base/core").Prim;
+        query: import("@cero-base/core").Prim;
+        local: import("@cero-base/core").Prim;
     };
     'req-call': {
-        handle: import("@cero-base/core/schema").Prim;
-        op: import("@cero-base/core/schema").Prim;
-        data: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        op: import("@cero-base/core").Prim;
+        data: import("@cero-base/core").Prim;
     };
     'req-invite': {
-        handle: import("@cero-base/core/schema").Prim;
-        role: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        role: import("@cero-base/core").Prim;
     };
     'req-revoke': {
-        handle: import("@cero-base/core/schema").Prim;
-        invite: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
+        invite: import("@cero-base/core").Prim;
     };
     'req-join': {
-        parent: import("@cero-base/core/schema").Prim;
-        ref: import("@cero-base/core/schema").Prim;
-        invite: import("@cero-base/core/schema").Prim;
+        parent: import("@cero-base/core").Prim;
+        ref: import("@cero-base/core").Prim;
+        invite: import("@cero-base/core").Prim;
     };
     'req-open': {
-        parent: import("@cero-base/core/schema").Prim;
-        row: import("@cero-base/core/schema").Prim;
+        parent: import("@cero-base/core").Prim;
+        row: import("@cero-base/core").Prim;
     };
     'req-handle': {
-        handle: import("@cero-base/core/schema").Prim;
+        handle: import("@cero-base/core").Prim;
     };
     'res-data': {
-        data: import("@cero-base/core/schema").Prim;
+        data: import("@cero-base/core").Prim;
     };
     'res-rows': {
-        data: import("@cero-base/core/schema").Prim;
-        total: import("@cero-base/core/schema").Prim;
-        size: import("@cero-base/core/schema").Prim;
+        data: import("@cero-base/core").Prim;
+        total: import("@cero-base/core").Prim;
+        size: import("@cero-base/core").Prim;
     };
     'res-count': {
-        count: import("@cero-base/core/schema").Prim;
+        count: import("@cero-base/core").Prim;
     };
     'res-invite': {
-        invite: import("@cero-base/core/schema").Prim;
+        invite: import("@cero-base/core").Prim;
     };
     'res-handle': {
-        id: import("@cero-base/core/schema").Prim;
-        type: import("@cero-base/core/schema").Prim;
-        name: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        type: import("@cero-base/core").Prim;
+        name: import("@cero-base/core").Prim;
     };
     'res-identity': {
-        id: import("@cero-base/core/schema").Prim;
-        deviceId: import("@cero-base/core/schema").Prim;
-        phrase: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core").Prim;
+        deviceId: import("@cero-base/core").Prim;
+        phrase: import("@cero-base/core").Prim;
     };
     'res-ok': {
-        ok: import("@cero-base/core/schema").Prim;
+        ok: import("@cero-base/core").Prim;
     };
 };

package/types/extensions/handle-sync.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mirror a child handle's `profile` (name + avatar) onto its row in the parent's
+ * `handles` list — so a handle list shows names + avatars without opening each
+ * one. Adds the synced `fields` to the `handle` builtin.
+ *
+ * On create it seeds the handle's `profile.name` from the open `{ name }`, then
+ * reflects the (app-owned) `profile` onto the row. Requires your handle types to
+ * declare a `profile` single — handles without one are left untouched.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function handleSync({ fields }?: {
+    fields?: Record<string, any>;
+}): {
+    schema: {
+        handles: {
+            kind: "extend";
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+};

package/types/extensions/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./profile-sync.js";
+export * from "./handle-sync.js";

package/types/extensions/profile-sync.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Mirror your `profile` onto your `member` row in every handle you're in.
+ * Declares a `profile` single (`name`, `avatar`, plus any extra `fields`) and
+ * mirrors them onto the `member` builtin, then publishes when you open/join a
+ * handle and whenever your profile changes. An app may declare its own richer
+ * `profile` instead — the app schema wins.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function profileSync({ fields }?: {
+    fields?: Record<string, any>;
+}): {
+    schema: {
+        profile: import("@cero-base/core").TypeDef;
+        members: {
+            kind: "extend";
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+};

package/types/handle/index.d.ts

@@ -86,10 +86,44 @@ export class Handle extends ReadyResource {
     _opts: any;
     _onerror: any;
     children: Set<any>;
+    _owned: Set<any>;
     store: Database;
     pair: Pairing;
     _wantsPair: boolean;
-    _offUpdate: () => void;
+    /**
+     * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`)
+     * to this handle's lifecycle — it's destroyed automatically on close, so
+     * callers don't track cleanup. De-registers itself if destroyed earlier.
+     *
+     * @template {{ destroy?: Function, once?: Function }} T
+     * @param {T} resource
+     * @returns {T}
+     */
+    own<T extends {
+        destroy?: Function;
+        once?: Function;
+    }>(resource: T): T;
+    /**
+     * An `AbortSignal` that fires when this handle closes. Pass it as
+     * `{ signal }` to `on`/`after`/`before`/`watch` to drop a subscription on
+     * close — or use your own `AbortController` for a finer scope.
+     *
+     * @returns {AbortSignal}
+     */
+    get signal(): AbortSignal;
+    _ac: AbortController;
+    /**
+     * `EventEmitter.on` plus an optional `{ signal }` that removes the listener
+     * when the signal aborts — e.g. `me.on('handle', fn, { signal: me.signal })`.
+     *
+     * @param {string} event
+     * @param {(...args: any[]) => void} fn
+     * @param {{ signal?: AbortSignal }} [opts]
+     * @returns {this}
+     */
+    on(event: string, fn: (...args: any[]) => void, opts?: {
+        signal?: AbortSignal;
+    }): this;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */
@@ -203,7 +237,6 @@ export class Handle extends ReadyResource {
      * @returns {Promise<void>}
      */
     resume(): Promise<void>;
-    _syncMember(child: any): Promise<void>;
     /**
      * @param {Handle} child
      * @param {{ role?: string }} [opts]

package/types/index.d.ts

@@ -25,6 +25,10 @@
  * @returns {Promise<Handle>}
  */
 export function cero(dir: string, spec: any, opts?: CeroOpts): Promise<Handle>;
+export namespace cero {
+    export { internal as _internal };
+    export function use(...exts: any[]): number;
+}
 /**
  * Restore a cero instance from a mnemonic phrase. Closes the running
  * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
@@ -94,9 +98,10 @@ export type CeroOpts = {
     recoveryTimeout?: number;
 };
 import { Handle } from './handle/index.js';
+import { internal } from './lib/internal.js';
 import { Ref } from './handle/index.js';
 import { Local } from './local/index.js';
 import { Identity } from '@cero-base/core/identity';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, call, open } from "./lib/operators.js";
+export { put, set, get, del, count, watch, call, open, before, after } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/internal.d.ts

@@ -0,0 +1,3 @@
+export namespace internal {
+    let extensions: any[];
+}

package/types/lib/operators.d.ts

@@ -1,12 +1,30 @@
 export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
-export function set(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
+export function set(ref: Ref, row: Record<string, any>, opts?: {
+    upsert?: boolean;
+}): Promise<SingleResult>;
 export function del(ref: Ref, id?: string): Promise<void>;
 export function count(ref: Ref, q?: Record<string, any>): Promise<{
     data: number;
 }>;
 export function call(ref: Ref, d?: Record<string, any>): Promise<any>;
+export function before(ref: Ref, fn: (ctx: {
+    op: string;
+    name: string;
+    row: any;
+}) => any, opts?: {
+    signal?: AbortSignal;
+}): () => void;
+export function after(ref: Ref, fn: (ctx: {
+    op: string;
+    name: string;
+    row: any;
+}) => void, opts?: {
+    signal?: AbortSignal;
+}): () => void;
 export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
-export function watch(ref: Ref, q?: Record<string, any>): any;
+export function watch(ref: Ref, q?: Record<string, any>, opts?: {
+    signal?: AbortSignal;
+}): any;
 export function open(ref: Ref, arg?: string | {
     invite?: string;
     id?: string;

package/types/lib/utils.d.ts

@@ -7,6 +7,14 @@
  * @param {Record<string, RefInfo>} refs
  */
 export function attachRefs(target: any, refs: Record<string, RefInfo>): void;
+/**
+ * Run `cb` when `signal` aborts — or immediately if it already has. No-op
+ * without a signal. The listener removes itself on fire.
+ *
+ * @param {AbortSignal} [signal]
+ * @param {() => void} cb
+ */
+export function onAbort(signal?: AbortSignal, cb: () => void): void;
 /**
  * @typedef {'collection' | 'single' | 'action' | 'handle'} RefKind
  * @typedef {{ kind?: string, schema?: string }} RefInfo

package/types/rpc/client.d.ts

@@ -111,7 +111,7 @@ declare class LocalRefs {
     /** @param {Client} client */
     constructor(client: Client);
     parent: Client;
-    spec: import("@cero-base/core/rpc").Spec;
+    spec: import("@cero-base/core").Spec;
     store: this;
     _local: boolean;
     /** Underlying RPC channel borrowed from the parent. */