@cero-base/core 0.0.5 → 0.2.0

package/README.md

@@ -34,6 +34,99 @@ export const schema = t.schema(
 | `private` (default) | Across paired devices |
 | `shared`            | Between room members  |
 
+## Built-in collections
+
+cero provides built-in collections that always exist on every database — you don't declare them in `t.schema()` to use them:
+
+| Name       | Scope     | Shape                                                |
+| ---------- | --------- | ---------------------------------------------------- |
+| `profile`  | `private` | Single-row identity profile (`name`, `avatar`, etc.) |
+| `devices`  | `private` | All devices paired to this identity                  |
+| `rooms`    | `private` | Rooms saved to this identity (id, key, name, …)      |
+| `invites`  | `private` | Pending invites this identity has created            |
+| `mirrors`  | `private` | Replicated-room hints (autobase mirror keys)         |
+| `settings` | `private` | Key/value app settings (replicated across devices)   |
+| `members`  | `shared`  | Members of the current room                          |
+
+They're accessed via the same `Collection` API:
+
+```js
+const profile = (await db.collection('profile').get())[0]
+await db.collection('profile').put({ name: 'Alice' })
+
+const devices = await db.collection('devices').get()
+const rooms = await db.collection('rooms').get() // saved rooms
+
+const room = await db.rooms.open() // open one
+const members = await room.collection('members').get()
+```
+
+`db.collection('rooms')` returns the identity-replicated saved-room list. Use `db.rooms.create/open/pair/close` for room _lifecycle_ (those aren't Collection ops).
+
+### Local-scope built-ins via `db.local.collection(name)`
+
+cero also maintains device-local tables that don't replicate (rooms cache with rich indexes, file metadata, etc.). Reach them via `db.local.collection(name)`:
+
+| Name       | Key                           | Purpose                                                                             |
+| ---------- | ----------------------------- | ----------------------------------------------------------------------------------- |
+| `identity` | `[]`                          | Single-row identity record (key, keyPair, …)                                        |
+| `rooms`    | `['key']`                     | Local rooms cache with `by-name`/`by-updatedAt`/`by-discoveryKey` indexes           |
+| `files`    | `['key', 'blob.blockOffset']` | Local file metadata                                                                 |
+| `settings` | `['key']`                     | Local key/value settings (distinct from the identity-replicated `settings` builtin) |
+| `counters` | `['name']`                    | Local counter table                                                                 |
+
+```js
+const localRooms = await db.local.collection('rooms').get()
+const cachedFiles = await db.local.collection('files').get()
+```
+
+`db.local.collection(name)` also resolves user-declared local collections (those declared with `scope: 'local'` in `t.schema()`), so `db.local.collection('drafts')` and `db.collection('drafts')` are equivalent for a user-local `drafts`.
+
+### Indexes and handlers
+
+`indexes` and `handlers` work on any collection — user-defined or built-in:
+
+```js
+import { t } from '@cero-base/core/schema'
+
+export const schema = t.schema(
+  {
+    // User-defined collection
+    tasks: {
+      fields: { id: t.string, title: t.string, dept: t.string, done: t.bool },
+      key: ['id'],
+      scope: 'shared',
+      indexes: { 'by-dept': ['dept'] },
+      handlers: {
+        'archive-task': async (op, ctx) => {
+          const path = '@chat/tasks'
+          const m = await ctx.view.get(path, { id: op.id })
+          if (m) await ctx.view.insert(path, { ...m, done: true })
+        }
+      }
+    },
+
+    // Built-in extension — same shape, no key/scope/timestamps (those are fixed)
+    members: {
+      fields: { department: t.string, level: t.uint },
+      indexes: { 'by-department': ['department'] },
+      handlers: {
+        'promote-member': async (op, ctx) => {
+          const path = '@chat/members'
+          const m = await ctx.view.get(path, { id: op.id })
+          if (m) await ctx.view.insert(path, { ...m, role: 'admin' })
+        }
+      }
+    }
+  },
+  { namespace: 'chat' }
+)
+```
+
+Custom dispatch payloads are encoded as `input-${type}` (all fields optional), so partial payloads like `{ id }` work without re-supplying every field.
+
+Built-ins are **opt-out**, not opt-in: omit them from `t.schema()` and they still work with cero's default fields. List them only when you need to customize. `key`, `scope`, and `timestamps` are fixed for built-ins — passing them throws.
+
 ## Usage
 
 ```js
@@ -54,6 +147,9 @@ const room = await db.rooms.open()
 const messages = room.collection('messages')
 await messages.put({ text: 'Hello!', memberId: db.id })
 
+// Custom dispatches declared via the built-in's handlers
+await room.collection('members').dispatch('promote-member', { id: someId })
+
 // Batch writes
 const batch = db.batch()
 batch.put('settings', { key: 'a', value: '1' })
@@ -73,15 +169,14 @@ For RPC support, use `@cero-base/rpc`'s build which includes RPC types automatic
 
 ## Exports
 
-| Export       | Path                      | Description                                     |
-| ------------ | ------------------------- | ----------------------------------------------- |
-| `CeroBase`   | `@cero-base/core`         | Main database class                             |
-| `Room`       | `@cero-base/core`         | Room wrapper with collections, members, invites |
-| `Collection` | `@cero-base/core`         | Collection with put/get/del/sub                 |
-| `Batch`      | `@cero-base/core`         | Buffered multi-collection writes                |
-| `Schema`     | `@cero-base/core`         | Schema class                                    |
-| `t`          | `@cero-base/core/schema`  | Type helpers for defining schemas               |
-| `build`      | `@cero-base/core/builder` | Build spec from schema                          |
+| Export       | Path                      | Description                                                                                                       |
+| ------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `CeroBase`   | `@cero-base/core`         | Main database class — `.collection(name)`, `.local.collection(name)`, `.invite(opts?)`, `.join(input)`, `.seed()` |
+| `Room`       | `@cero-base/core`         | Room wrapper with `.collection(name)` + `.invite(opts?)`                                                          |
+| `Collection` | `@cero-base/core`         | Collection with put/get/del/sub/dispatch                                                                          |
+| `Batch`      | `@cero-base/core`         | Buffered multi-collection writes                                                                                  |
+| `t`          | `@cero-base/core/schema`  | Type helpers (`t.string`, `t.optional`, `t.array`, …)                                                             |
+| `build`      | `@cero-base/core/builder` | Build spec from schema                                                                                            |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "0.0.5",
+  "version": "0.2.0",
   "description": "P2P database with collection-based CRUD and RPC",
   "files": [
     "src",
@@ -23,7 +23,7 @@
     "test": "brittle test/*.js"
   },
   "dependencies": {
-    "@lekinox/cero": "^1.0.10",
+    "@lekinox/cero": "^1.3.1",
     "compact-encoding": "^2.19.1",
     "ready-resource": "^1.0.2",
     "safety-catch": "^1.0.2"

package/src/lib/base.js

@@ -28,9 +28,16 @@ export class CeroBase extends Cero {
 
     this.schema = schema
     this._baseUpdateHandler = null
+
+    // Expose cero's local-scope tables (rooms cache, files, settings, …) and
+    // user-declared `scope: 'local'` collections via the unified Collection API.
+    // db.local already has cero's find/insert/delete; we just add .collection.
+    if (this.local) {
+      this.local.collection = (name) => new Collection(this, name, { local: true })
+    }
+
     this.once('ready', () => {
       this._bindIdentityBase()
-      this._initFacades()
     })
   }
 
@@ -59,32 +66,11 @@ export class CeroBase extends Cero {
     return this.pair(input, opts)
   }
 
-  _initFacades() {
-    const p = this.identity?.profile
-    if (p) {
-      this._profile = {
-        get: () => p.get(),
-        set: (data) => p.set(data),
-        sub: () => p.subscribe()
-      }
-    }
-
-    const d = this.identity?.devices
-    if (d) {
-      this._devices = {
-        get: (query) => d.list(query),
-        sub: (id) => d.subscribe(id),
-        invite: () => this.invites.create().then(({ invite }) => invite)
-      }
-    }
-  }
-
-  get profile() {
-    return this._profile || null
-  }
-
-  get devices() {
-    return this._devices || null
+  /** Create a device-pairing invite string for this identity. */
+  async invite(opts = {}) {
+    if (!this.opened) await this.ready()
+    const { invite } = await this.invites.create(opts)
+    return invite
   }
 
   collection(name) {

package/src/lib/batch.js

@@ -24,7 +24,10 @@ export class Batch {
       data.createdAt = data.createdAt ?? Date.now()
     }
 
-    this.operations.push({ action: 'add', name, data, scope })
+    // If cero doesn't have add-${type}, fall back to set-${type} which is
+    // itself an upsert.
+    const action = this.schema.hasAdd(name) ? 'add' : 'set'
+    this.operations.push({ action, name, data, scope })
     return data
   }
 
@@ -35,7 +38,7 @@ export class Batch {
     const [existing] = await col.get(query)
     if (!existing) return false
 
-    const keys = this.schema.collections[name]?.key || ['id']
+    const keys = this.schema.keysOf(name)
     const keyData = keys.reduce((acc, k) => ((acc[k] = existing[k]), acc), {})
 
     this.operations.push({ action: 'del', name, data: keyData, scope })

package/src/lib/collection.js

@@ -1,6 +1,7 @@
 import { Readable } from 'streamx'
 import { randomId } from './crypto.js'
 import { debounce, isLocal, isPrivate } from './utils.js'
+import { SCOPE_LOCAL } from './constants.js'
 
 /** Route a write operation based on scope */
 function writeOp(owner, scope, path, ns, op, data, isDel) {
@@ -25,28 +26,62 @@ function writeOp(owner, scope, path, ns, op, data, isDel) {
  * tasks.sub().on('data', cb)
  */
 export class Collection {
-  constructor(owner, name) {
+  constructor(owner, name, opts = {}) {
     this.owner = owner
     this.schema = owner.schema
+    this.name = name
+
+    if (opts.local) {
+      // Forced local resolution — used by db.local.collection(name) to reach
+      // cero's local-scope built-ins (rooms cache, files, etc.) and user-
+      // declared `scope: 'local'` collections via the same accessor.
+      const type = this.schema.localTypeOf(name)
+      if (!type) throw new Error(`'${name}' is not a local collection`)
+      this.scope = SCOPE_LOCAL
+      this.type = type
+      this.keys = this.schema.localKeysOf(name)
+      this.path = `@local/${name}`
+      this.ns = '@local'
+      this.hasAdd = true // local merges via direct insert; no dispatch involved
+      this.timestamps = false
+      this.counter = false
+      this.indexes = null
+      return
+    }
 
     const def = this.schema.collections[name]
     this.scope = this.schema.getScope(name)
-    this.name = name
     this.type = this.schema.types.get(name)
     this.path = this.schema.getPath(name)
     this.ns = this.path.split('/')[0]
-    this.keys = def.key || ['id']
+    this.keys = this.schema.keysOf(name)
+    this.hasAdd = this.schema.hasAdd(name)
     this.timestamps = this.schema.hasTimestamps(name)
     this.counter = !isLocal(this.scope) // all non-local collections have counter
-    this.indexes = def.indexes || null
-    this.db = isLocal(this.scope) ? null : isPrivate(this.scope) ? owner.identity.db : owner.room.db
+    this.indexes = def?.indexes || null
+  }
+
+  get db() {
+    if (isLocal(this.scope)) return null
+    return isPrivate(this.scope) ? this.owner.identity.db : this.owner.room.db
   }
 
   /** Upsert — insert if new, update if exists */
   async put(doc) {
-    const data = doc.id ? doc : { ...doc, id: randomId() }
-    const keyQuery = this.keys.reduce((acc, k) => ((acc[k] = data[k]), acc), {})
-    const existing = data.id ? await this._getOne(keyQuery) : null
+    const isNew = !doc.id
+    const data = isNew ? { ...doc, id: randomId() } : doc
+
+    // If cero doesn't have add-${type} for this built-in (profile, settings),
+    // there's no auto-incrementing index — set-${type} is the only path and
+    // is itself an idempotent upsert.
+    if (!this.hasAdd) {
+      return this._write(`set-${this.type}`, data)
+    }
+
+    // Freshly randomized id can't possibly exist — skip the lookup.
+    const existing = isNew
+      ? null
+      : await this._getOne(this.keys.reduce((acc, k) => ((acc[k] = data[k]), acc), {}))
 
     if (existing) {
       const updated = { ...existing, ...data }
@@ -118,6 +153,15 @@ export class Collection {
     return true
   }
 
+  /** Dispatch a custom op (registered via the schema's handlers) on this collection */
+  async dispatch(op, data) {
+    if (isLocal(this.scope)) {
+      throw new Error(`Cannot dispatch on local collection '${this.name}'`)
+    }
+    const target = isPrivate(this.scope) ? this.owner.identity : this.owner.room
+    return target.dispatch(`${this.ns}/${op}`, data)
+  }
+
   /** Subscribe — returns Readable stream of query results */
   sub(query = {}, opts = {}) {
     const stream = new Readable()

package/src/lib/room.js

@@ -64,10 +64,6 @@ export class Room extends ReadyResource {
       this.room = await this.db.rooms.open(this._arg)
     }
 
-    this.profile = withSub(this.room.profile)
-    this.members = withSub(this.room.members)
-    this.invites = withSub(this.room.invites)
-
     this.room.on('update', () => this.emit('update'))
   }
 
@@ -96,9 +92,9 @@ export class Room extends ReadyResource {
   }
 
   /** Shorthand — create invite and return the string */
-  async invite() {
+  async invite(opts = {}) {
     if (!this.opened) await this.ready()
-    const { invite } = await this.room.invites.create()
+    const { invite } = await this.room.invites.create(opts)
     return invite
   }
 
@@ -147,10 +143,3 @@ function detectType(input) {
 
   return 'invite'
 }
-
-function withSub(obj) {
-  if (!obj) return obj
-  const wrapped = { ...obj, sub: obj.subscribe.bind(obj) }
-  if (obj.list) wrapped.get = obj.list.bind(obj)
-  return wrapped
-}

package/src/lib/schema.js

@@ -1,6 +1,86 @@
+import Hyperschema from 'hyperschema'
+import { extendIdentitySchema, extendIdentityDispatch } from '@lekinox/cero/src/identity/schema.js'
+import { extendRoomSchema, extendRoomDispatch } from '@lekinox/cero/src/room/schema.js'
 import { singular, toFields, scopeNs, isLocal, isPrivate, isShared } from './utils.js'
 import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
 
+// Built-in collections inherited from cero. Names map to:
+//   - scope: private = identity-replicated, shared = room-replicated
+//   - type:  singular type name in cero's schema (e.g. 'member' for 'members')
+//   - key:   primary key fields (empty array = single-row collection, e.g. profile)
+//
+// Whether each built-in supports add/set/del is DERIVED from cero's dispatch
+// table at schema-build time (see ceroDispatches), not hardcoded here.
+const BUILTINS = {
+  members: { scope: SCOPE_SHARED, type: 'member', key: ['id'] },
+  profile: { scope: SCOPE_PRIVATE, type: 'profile', key: [] },
+  devices: { scope: SCOPE_PRIVATE, type: 'device', key: ['id'] },
+  rooms: { scope: SCOPE_PRIVATE, type: 'room', key: ['id'] },
+  invites: { scope: SCOPE_PRIVATE, type: 'invite', key: ['id'] },
+  mirrors: { scope: SCOPE_PRIVATE, type: 'mirror', key: ['key'] },
+  settings: { scope: SCOPE_PRIVATE, type: 'setting', key: ['key'] }
+}
+
+// Local-scope built-ins cero registers in @local/* — exposed to apps via
+// db.local.collection(name). Distinct from BUILTINS (which are private/shared).
+const LOCAL_BUILTINS = {
+  identity: { type: 'identity', key: [] },
+  rooms: { type: 'room', key: ['key'] },
+  files: { type: 'file', key: ['key', 'blob.blockOffset'] },
+  settings: { type: 'setting', key: ['key'] },
+  counters: { type: 'counter', key: ['name'] }
+}
+
+// One in-memory Hyperschema per (scope, ns) — built once by running cero's
+// extender and reused for every type lookup. The extender registers all
+// built-in types in the namespace; baseFieldsOf just reads them back.
+const schemaCache = new Map()
+function builtinSchema(scope, nsName) {
+  const key = `${scope}:${nsName}`
+  let schema = schemaCache.get(key)
+  if (schema) return schema
+
+  schema = new Hyperschema()
+  const ns = schema.namespace(nsName)
+  if (scope === SCOPE_SHARED) {
+    extendRoomSchema(schema, ns)
+  } else {
+    extendIdentitySchema(schema, ns)
+  }
+  schemaCache.set(key, schema)
+  return schema
+}
+
+function baseFieldsOf(scope, nsName, typeName) {
+  const type = builtinSchema(scope, nsName).types.get(`@${nsName}/${typeName}`)
+  if (!type) throw new Error(`Built-in type '${typeName}' not found in cero schema`)
+  return type.toJSON().fields
+}
+
+// Cache of dispatch names cero registers per scope. Runs cero's extender
+// against a stub namespace that just captures register() calls.
+const dispatchCache = new Map()
+function ceroDispatches(scope) {
+  if (dispatchCache.has(scope)) return dispatchCache.get(scope)
+  const captured = new Set()
+  const stubNs = {
+    name: scope === SCOPE_SHARED ? 'room' : 'identity',
+    register: (desc) => captured.add(desc.name)
+  }
+  if (scope === SCOPE_SHARED) {
+    extendRoomDispatch(null, stubNs)
+  } else {
+    extendIdentityDispatch(null, stubNs)
+  }
+  dispatchCache.set(scope, captured)
+  return captured
+}
+
+// Does cero have an `add-${type}` dispatch for this built-in?
+function ceroHasAdd(scope, typeName) {
+  return ceroDispatches(scope).has(`add-${typeName}`)
+}
+
 /**
  * Type helpers for defining schema fields
  * Usage: { name: t.string, count: t.int, active: t.bool }
@@ -45,9 +125,32 @@ t.schema = defineSchema
 
 export function defineSchema(collections, opts = {}) {
   const entries = Object.entries(collections)
-  const types = new Map(entries.map(([name]) => [name, singular(name)]))
 
-  const getScope = ([, def]) => def.scope || SCOPE_PRIVATE
+  // Validate built-in entries: user can't override fixed metadata (key, scope, timestamps).
+  for (const [name, def] of entries) {
+    if (!BUILTINS[name]) continue
+    if (def.key !== undefined) {
+      throw new Error(`'${name}' is a built-in; key is fixed and cannot be set`)
+    }
+    if (def.scope !== undefined && def.scope !== BUILTINS[name].scope) {
+      throw new Error(
+        `'${name}' is a built-in with scope '${BUILTINS[name].scope}'; cannot override`
+      )
+    }
+    if (def.timestamps !== undefined) {
+      throw new Error(`'${name}' is a built-in; timestamps is fixed and cannot be set`)
+    }
+  }
+
+  // Type name resolution: built-ins use cero's singular type name, user collections use singular(plural).
+  const types = new Map([
+    // Pre-populate with built-ins so they resolve even when user didn't declare them.
+    ...Object.entries(BUILTINS).map(([name, info]) => [name, info.type]),
+    ...entries.map(([name]) => [name, BUILTINS[name]?.type || singular(name)])
+  ])
+
+  const getScope = ([name, def]) =>
+    BUILTINS[name] ? BUILTINS[name].scope : def.scope || SCOPE_PRIVATE
   const localEntries = entries.filter((e) => getScope(e) === SCOPE_LOCAL)
   const privateEntries = entries.filter((e) => getScope(e) === SCOPE_PRIVATE)
   const sharedEntries = entries.filter((e) => getScope(e) === SCOPE_SHARED)
@@ -60,10 +163,76 @@ export function defineSchema(collections, opts = {}) {
     types,
 
     getScope(collection) {
+      if (BUILTINS[collection]) return BUILTINS[collection].scope
       const def = collections[collection]
       return def ? def.scope || SCOPE_PRIVATE : null
     },
 
+    isBuiltin(collection) {
+      return !!BUILTINS[collection]
+    },
+
+    /**
+     * Does Collection.put follow the add/set merge path for this collection?
+     *
+     * - User-defined: always yes. Non-local user collections get auto-generated
+     *   `add-${type}` dispatches; local collections take the merge path even
+     *   without dispatches (they write straight to the local store).
+     * - Built-ins: derived from cero's actual dispatch table — `false` for
+     *   collections cero exposes only via `set-${type}` (e.g. profile, settings).
+     */
+    hasAdd(collection) {
+      const builtin = BUILTINS[collection]
+      if (builtin) return ceroHasAdd(builtin.scope, builtin.type)
+      return !!collections[collection]
+    },
+
+    keysOf(collection) {
+      if (BUILTINS[collection]) return BUILTINS[collection].key
+      return collections[collection]?.key || ['id']
+    },
+
+    isLocalBuiltin(collection) {
+      return !!LOCAL_BUILTINS[collection]
+    },
+
+    /**
+     * Resolve a name to its local-scope type. Returns null if the name doesn't
+     * map to a local collection (cero built-in or user-declared `scope: 'local'`).
+     */
+    localTypeOf(collection) {
+      if (LOCAL_BUILTINS[collection]) return LOCAL_BUILTINS[collection].type
+      const def = collections[collection]
+      if (def?.scope === SCOPE_LOCAL) return singular(collection)
+      return null
+    },
+
+    localKeysOf(collection) {
+      if (LOCAL_BUILTINS[collection]) return LOCAL_BUILTINS[collection].key
+      const def = collections[collection]
+      if (def?.scope === SCOPE_LOCAL) return def.key || ['id']
+      return null
+    },
+
+    /**
+     * Resolve a local collection name to its hyperdb spec + path. Returns null
+     * if `name` isn't a local collection. Local built-ins don't have input-X
+     * types, so the prefix is ignored for them.
+     */
+    localResolve(collection, prefix) {
+      const ns = scopeNs(SCOPE_LOCAL)
+      if (LOCAL_BUILTINS[collection]) {
+        return { spec: ns, path: `@${ns}/${LOCAL_BUILTINS[collection].type}` }
+      }
+      const def = collections[collection]
+      if (def?.scope === SCOPE_LOCAL) {
+        const type = singular(collection)
+        const name = prefix ? `${prefix}-${type}` : type
+        return { spec: ns, path: `@${ns}/${name}` }
+      }
+      return null
+    },
+
     isLocal(collection) {
       return isLocal(this.getScope(collection))
     },
@@ -131,6 +300,51 @@ export function defineSchema(collections, opts = {}) {
       const local = scope === SCOPE_LOCAL
       const ns = nsName || scopeNs(scope)
       for (const [name, def] of items) {
+        if (BUILTINS[name]) {
+          // Built-in extension: re-register the type with extra fields appended.
+          // cero's later registration is idempotent and skips when the type already exists.
+          const typeName = BUILTINS[name].type
+          const baseFields = baseFieldsOf(scope, ns, typeName)
+          const userFields = toFields(def.fields || {}).map((f) => ({ ...f, required: false }))
+
+          const baseNames = new Set(baseFields.map((f) => f.name))
+          for (const uf of userFields) {
+            if (baseNames.has(uf.name)) {
+              throw new Error(
+                `'${uf.name}' is a base field of '${typeName}' and cannot be redeclared`
+              )
+            }
+          }
+
+          const allFields = [...baseFields, ...userFields]
+          register.type({ name: typeName, compact: false, fields: allFields })
+          register.type({
+            name: `input-${typeName}`,
+            compact: false,
+            fields: allFields.map((f) => ({ ...f, required: false }))
+          })
+
+          if (def.indexes) {
+            for (const [idx, idxFields] of Object.entries(def.indexes)) {
+              register.index({
+                name: `${name}-${idx}`,
+                collection: `@${ns}/${name}`,
+                key: idxFields
+              })
+            }
+          }
+
+          // Register custom dispatches for user-supplied handlers.
+          // Use input-${type} (all-optional fields) so callers can pass partial
+          // payloads like { id } without re-supplying every base field.
+          if (def.handlers) {
+            for (const op of Object.keys(def.handlers)) {
+              register.dispatch({ name: op, requestType: `@${ns}/input-${typeName}` })
+            }
+          }
+          continue
+        }
+
         const type = types.get(name)
         const fields = schemaFields(def)
         const typePath = `@${ns}/${type}`
@@ -157,6 +371,29 @@ export function defineSchema(collections, opts = {}) {
           register.dispatch({ name: `set-${type}`, requestType: typePath })
           register.dispatch({ name: `del-${type}`, requestType: `@${ns}/del-${type}` })
         }
+
+        // Register custom dispatches for user-supplied handlers.
+        // Use input-${type} so callers can pass partial payloads.
+        if (!local && def.handlers) {
+          for (const op of Object.keys(def.handlers)) {
+            register.dispatch({ name: op, requestType: `@${ns}/input-${type}` })
+          }
+        }
+      }
+
+      // Register input-${type} for implicit built-ins (not in user schema)
+      // so the RPC bridge can encode partial payloads for Collection writes.
+      if (!local) {
+        for (const [name, info] of Object.entries(BUILTINS)) {
+          if (info.scope !== scope) continue
+          if (collections[name]) continue // already handled by built-in branch above
+          const baseFields = baseFieldsOf(info.scope, ns, info.type)
+          register.type({
+            name: `input-${info.type}`,
+            compact: false,
+            fields: baseFields.map((f) => ({ ...f, required: false }))
+          })
+        }
       }
     },
 
@@ -165,6 +402,16 @@ export function defineSchema(collections, opts = {}) {
       const handlers = {}
       const p = (name) => `@${nsFor(scope)}/${name}`
       for (const [name, def] of items) {
+        if (BUILTINS[name]) {
+          // Built-in extension: cero already owns add/set/del — only register custom handlers.
+          if (def.handlers) {
+            for (const [op, handler] of Object.entries(def.handlers)) {
+              handlers[p(op)] = handler
+            }
+          }
+          continue
+        }
+
         const type = types.get(name)
         const path = p(name)
         const keys = def.key || ['id']