@cero-base/core 0.0.1

package/README.md

@@ -0,0 +1,88 @@
+# @cero-base/core
+
+Collection-based CRUD layer on top of [cero](https://github.com/lekinox/cero). Define your schema, get `put/get/del/sub` across three scopes with built-in pagination.
+
+## Install
+
+```bash
+npm install @cero-base/core
+```
+
+## Schema
+
+```js
+import { t } from '@cero-base/core/schema'
+
+export const schema = t.schema(
+  {
+    drafts: { fields: { id: t.string, content: t.string }, key: ['id'], scope: 'local' },
+    settings: { fields: { key: t.string, value: t.json }, key: ['key'] },
+    messages: {
+      fields: { id: t.string, text: t.string, memberId: t.string },
+      key: ['id'],
+      scope: 'shared',
+      timestamps: true
+    }
+  },
+  { namespace: 'chat' }
+)
+```
+
+| Scope               | Replication           |
+| ------------------- | --------------------- |
+| `local`             | Device-only           |
+| `private` (default) | Across paired devices |
+| `shared`            | Between room members  |
+
+## Usage
+
+```js
+import { CeroBase } from '@cero-base/core'
+
+const db = new CeroBase('./data', schema, spec)
+await db.ready()
+
+// Local/private collections
+const drafts = db.collection('drafts')
+await drafts.put({ content: 'WIP' })
+await drafts.get()
+await drafts.del({ id: 'abc' })
+drafts.sub().on('data', console.log)
+
+// Rooms (shared collections)
+const room = await db.rooms.open()
+const messages = room.collection('messages')
+await messages.put({ text: 'Hello!', memberId: db.id })
+
+// Batch writes
+const batch = db.batch()
+batch.put('settings', { key: 'a', value: '1' })
+batch.put('settings', { key: 'b', value: '2' })
+await batch.flush()
+```
+
+## Build
+
+```js
+import { build } from '@cero-base/core/builder'
+
+await build('./spec', schema)
+```
+
+For RPC support, use `@cero-base/rpc`'s build which includes RPC types automatically.
+
+## 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                          |
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cero-base/core",
+  "version": "0.0.1",
+  "description": "P2P database with collection-based CRUD and RPC",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schema": "./src/lib/schema.js",
+    "./builder": "./src/lib/builder.js",
+    "./constants": "./src/lib/constants.js"
+  },
+  "scripts": {
+    "build:test": "rm -rf test/fixture/spec && node test/fixture/build.js",
+    "pretest": "npm run build:test",
+    "test": "brittle test/*.js"
+  },
+  "dependencies": {
+    "@lekinox/cero": "^1.0.10",
+    "compact-encoding": "^2.19.1",
+    "ready-resource": "^1.0.2",
+    "safety-catch": "^1.0.2"
+  },
+  "devDependencies": {
+    "@hyperswarm/testnet": "^3.1.4",
+    "autobase-test-helpers": "^3.1.0",
+    "brittle": "^3.7.0",
+    "corestore": "^7.9.1",
+    "duplex-through": "^1.0.2",
+    "hrpc": "^4.3.0",
+    "hyperdb": "^6.3.0",
+    "hyperdispatch": "^1.5.1",
+    "hyperschema": "^1.20.1"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/core"
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export * from './lib/index.js'

package/src/lib/base.js

@@ -0,0 +1,98 @@
+import { Cero } from '@lekinox/cero'
+import { SCOPE_PRIVATE, SCOPE_SHARED } from '../lib/constants.js'
+import { Collection } from '../lib/collection.js'
+import { Batch } from '../lib/batch.js'
+
+const SEED_WORD_COUNT = 12
+
+export class CeroBase extends Cero {
+  constructor(dir, schema, spec, opts = {}) {
+    super(
+      dir,
+      {
+        ...spec,
+        identity: {
+          ...spec.identity,
+          routes: schema.routes(SCOPE_PRIVATE),
+          counters: schema.counterNames(SCOPE_PRIVATE)
+        },
+        room: {
+          ...spec.room,
+          ns: schema.namespace || undefined,
+          routes: schema.routes(SCOPE_SHARED),
+          counters: schema.counterNames(SCOPE_SHARED)
+        }
+      },
+      opts
+    )
+
+    this.schema = schema
+    this._baseUpdateHandler = null
+    this.once('ready', () => {
+      this._bindIdentityBase()
+      this._initFacades()
+    })
+  }
+
+  _bindIdentityBase() {
+    if (this._baseUpdateHandler && this._prevBase) {
+      this._prevBase.removeListener('update', this._baseUpdateHandler)
+    }
+    this._baseUpdateHandler = () => this.emit('update')
+    this._prevBase = this.identity?.base
+    if (this._prevBase) this._prevBase.on('update', this._baseUpdateHandler)
+  }
+
+  async _swapIdentity(handler, opts) {
+    const result = await super._swapIdentity(handler, opts)
+    this._bindIdentityBase()
+    return result
+  }
+
+  seed() {
+    return this.identity?.seed?.get() || null
+  }
+
+  async join(input, opts = {}) {
+    const isSeed = typeof input === 'string' && input.trim().split(/\s+/).length >= SEED_WORD_COUNT
+    if (isSeed) return this.recover(input, opts)
+    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
+  }
+
+  collection(name) {
+    this.schema.require(name, 'db')
+    return new Collection(this, name)
+  }
+
+  batch() {
+    return new Batch(this)
+  }
+}

package/src/lib/batch.js

@@ -0,0 +1,95 @@
+import { randomId } from './crypto.js'
+import { isLocal, isPrivate, isShared } from './utils.js'
+
+/**
+ * Batch — buffer multiple put/del operations and flush as single dispatch
+ *
+ * @example
+ * const batch = db.batch()
+ * batch.put('settings', { key: 'a', value: '1' })
+ * await batch.flush()
+ */
+export class Batch {
+  constructor(owner) {
+    this.owner = owner
+    this.schema = owner.schema
+    this.operations = []
+  }
+
+  put(name, doc) {
+    const scope = this._validate(name)
+
+    const data = doc.id ? doc : { ...doc, id: randomId() }
+    if (this.schema.hasTimestamps(name)) {
+      data.createdAt = data.createdAt ?? Date.now()
+    }
+
+    this.operations.push({ action: 'add', name, data, scope })
+    return data
+  }
+
+  async del(name, query) {
+    const scope = this._validate(name)
+
+    const col = this.owner.collection(name)
+    const [existing] = await col.get(query)
+    if (!existing) return false
+
+    const keys = this.schema.collections[name]?.key || ['id']
+    const keyData = keys.reduce((acc, k) => ((acc[k] = existing[k]), acc), {})
+
+    this.operations.push({ action: 'del', name, data: keyData, scope })
+    return true
+  }
+
+  async flush() {
+    if (this.operations.length === 0) return
+
+    const localOps = this.operations.filter((op) => isLocal(op.scope))
+    const privateOps = this.operations.filter((op) => isPrivate(op.scope))
+    const sharedOps = this.operations.filter((op) => isShared(op.scope))
+
+    for (const op of localOps) {
+      const path = this.schema.getPath(op.name)
+      if (op.action === 'del') {
+        await this.owner.local.delete(path, op.data)
+      } else {
+        await this.owner.local.insert(path, op.data)
+      }
+    }
+
+    if (privateOps.length > 0) {
+      const identity = this.owner.identity
+      const ns = identity.ns
+      await identity.dispatch(`@${ns}/batch`, {
+        operations: privateOps.map((op) => {
+          const route = `@${ns}/${op.action}-${this.schema.types.get(op.name)}`
+          return identity.spec.dispatch.encode(route, op.data)
+        })
+      })
+    }
+
+    if (sharedOps.length > 0) {
+      const room = this.owner.room
+      const ns = room.ns
+      await room.dispatch(`@${ns}/batch`, {
+        operations: sharedOps.map((op) => {
+          const route = `@${ns}/${op.action}-${this.schema.types.get(op.name)}`
+          return room.spec.dispatch.encode(route, op.data)
+        })
+      })
+    }
+
+    this.operations = []
+
+    if (localOps.length > 0) {
+      this.owner.emit('update')
+    }
+  }
+
+  _validate(name) {
+    const scope = this.schema.getScope(name)
+    if (!scope) throw new Error(`Unknown collection: '${name}'`)
+    return scope
+  }
+}

package/src/lib/builder.js

@@ -0,0 +1,24 @@
+import { build as ceroBuild } from '@lekinox/cero'
+
+/**
+ * Build all specs in one output directory.
+ *
+ * @param {string} dir - Output directory
+ * @param {object} [schema] - Schema from t.schema()
+ * @param {object} [opts] - Options
+ * @param {function} [opts.rpc] - RPC builder function ({ register, ns }) => void
+ */
+export async function build(dir, schema, opts = {}) {
+  const ns = schema?.namespace || null
+  const builders = {
+    local: ({ register, ns }) => schema?.build('local', register, ns),
+    identity: ({ register, ns }) => schema?.build('private', register, ns),
+    room: ({ register, ns }) => schema?.build('shared', register, ns),
+    ...(opts.rpc ? { rpc: opts.rpc } : {})
+  }
+  if (ns) {
+    await ceroBuild(dir, ns, builders)
+  } else {
+    await ceroBuild(dir, builders)
+  }
+}

package/src/lib/collection.js

@@ -0,0 +1,208 @@
+import { Readable } from 'streamx'
+import { randomId } from './crypto.js'
+import { debounce, isLocal, isPrivate } from './utils.js'
+
+/** Route a write operation based on scope */
+function writeOp(owner, scope, path, ns, op, data, isDel) {
+  if (isLocal(scope)) {
+    const method = isDel ? 'delete' : 'insert'
+    return owner.local[method](path, data).then(() => owner.emit('update'))
+  }
+  const target = isPrivate(scope) ? owner.identity : owner.room
+  return target.dispatch(`${ns}/${op}`, data)
+}
+
+/**
+ * Collection — 4 verbs: put, get, del, sub
+ *
+ * @example
+ * const tasks = room.collection('tasks')
+ *
+ * await tasks.put({ text: 'Buy milk', done: false })
+ * await tasks.get()                       // all docs
+ * await tasks.get({ done: false })        // filtered
+ * await tasks.del({ id: 'abc' })
+ * tasks.sub().on('data', cb)
+ */
+export class Collection {
+  constructor(owner, name) {
+    this.owner = owner
+    this.schema = owner.schema
+
+    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.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
+  }
+
+  /** 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
+
+    if (existing) {
+      const updated = { ...existing, ...data }
+      if (this.timestamps) updated.updatedAt = Date.now()
+      return this._write(`set-${this.type}`, updated)
+    }
+
+    if (this.timestamps) data.createdAt = data.createdAt ?? Date.now()
+    return this._write(`add-${this.type}`, data)
+  }
+
+  /** Get docs — no query returns all, query filters, supports range queries on index */
+  async get(query = {}, opts = {}) {
+    if (isLocal(this.scope)) {
+      const all = await this.owner.local.find(this.path, opts)
+      return filter(all, query)
+    }
+
+    if (
+      this.counter &&
+      (typeof query.gte === 'number' ||
+        typeof query.lte === 'number' ||
+        typeof query.gt === 'number' ||
+        typeof query.lt === 'number')
+    ) {
+      return this._rangeByIndex(query, opts)
+    }
+
+    return findDocs(this.db, this.path, this.indexes, this.name, query, opts)
+  }
+
+  /** Get count */
+  async count() {
+    if (!this.counter) return (await this.get()).length
+
+    const counterPath = `${this.ns}/counters`
+    const snapshot = this.db.snapshot()
+    try {
+      const counter = await snapshot.get(counterPath, { name: this.name })
+      return counter?.value || 0
+    } finally {
+      await snapshot.close()
+    }
+  }
+
+  /** @private Range query on index field via the by-index index */
+  async _rangeByIndex(query, opts = {}) {
+    const indexPath = `${this.path}-by-index`
+    const snapshot = this.db.snapshot()
+    try {
+      const rangeQuery = {}
+      if (query.gte !== undefined) rangeQuery.gte = { index: query.gte }
+      if (query.lte !== undefined) rangeQuery.lte = { index: query.lte }
+      if (query.gt !== undefined) rangeQuery.gt = { index: query.gt }
+      if (query.lt !== undefined) rangeQuery.lt = { index: query.lt }
+      return snapshot.find(indexPath, { ...rangeQuery, ...opts }).toArray()
+    } finally {
+      await snapshot.close()
+    }
+  }
+
+  /** Delete a document by query */
+  async del(query) {
+    const [existing] = await this.get(query)
+    if (!existing) return false
+
+    const keyData = this.keys.reduce((acc, k) => ((acc[k] = existing[k]), acc), {})
+    await this._write(`del-${this.type}`, keyData, true)
+    return true
+  }
+
+  /** Subscribe — returns Readable stream of query results */
+  sub(query = {}, opts = {}) {
+    const stream = new Readable()
+    const emitter = this.owner
+
+    const refresh = debounce(async () => {
+      try {
+        const results = await this.get(query, opts)
+        stream.push(results)
+      } catch (err) {
+        stream.destroy(err)
+      }
+    })
+
+    refresh()
+    emitter.on('update', refresh)
+
+    const destroy = stream.destroy.bind(stream)
+    stream.destroy = (err) => {
+      emitter.off('update', refresh)
+      return destroy(err)
+    }
+
+    return stream
+  }
+
+  /** @private Single-doc lookup by key (used internally by put/del) */
+  async _getOne(query) {
+    if (isLocal(this.scope)) {
+      return this.owner.local.get(this.path, query)
+    }
+    const snapshot = this.db.snapshot()
+    try {
+      return await snapshot.get(this.path, query)
+    } finally {
+      await snapshot.close()
+    }
+  }
+
+  /** @private Route write to local/identity/room */
+  async _write(op, data, isDel = false) {
+    await writeOp(this.owner, this.scope, this.path, this.ns, op, data, isDel)
+    return isDel ? true : data
+  }
+}
+
+// ==================== Private Helpers ====================
+
+function filter(all, query) {
+  const entries = Object.entries(query)
+  if (entries.length === 0) return all
+  return all.filter((doc) => entries.every(([k, v]) => doc[k] === v))
+}
+
+async function findDocs(db, path, indexes, name, query, opts) {
+  const snapshot = db.snapshot()
+
+  try {
+    const rangeKey = query.gte || query.gt || query.lte || query.lt
+    if (rangeKey) {
+      const index = matchIndex(path, indexes, rangeKey)
+      if (!index) throw new Error(`No index found for range query on ${name}`)
+      return snapshot.find(index, { ...query, ...opts }).toArray()
+    }
+
+    const index = matchIndex(path, indexes, query)
+    if (index) {
+      return snapshot.find(index, { gte: query, lte: query, ...opts }).toArray()
+    }
+
+    const all = await snapshot.find(path, opts).toArray()
+    return filter(all, query)
+  } finally {
+    await snapshot.close()
+  }
+}
+
+function matchIndex(path, indexes, query) {
+  if (!indexes) return null
+
+  const firstField = Object.keys(query)[0]
+  if (!firstField) return null
+
+  for (const [name, fields] of Object.entries(indexes)) {
+    if (fields[0] === firstField) return `${path}-${name}`
+  }
+  return null
+}

package/src/lib/constants.js

@@ -0,0 +1,4 @@
+// User-facing scope names for cero-base schemas
+export const SCOPE_LOCAL = 'local'
+export const SCOPE_PRIVATE = 'private'
+export const SCOPE_SHARED = 'shared'

package/src/lib/crypto.js

@@ -0,0 +1,6 @@
+import crypto from 'hypercore-crypto'
+import z32 from 'z32'
+
+export function randomId() {
+  return z32.encode(crypto.randomBytes(16))
+}

package/src/lib/index.js

@@ -0,0 +1,6 @@
+export * from './base.js'
+export * from './room.js'
+export * from './batch.js'
+export * from './collection.js'
+export * from './schema.js'
+export * from './constants.js'

package/src/lib/room.js

@@ -0,0 +1,156 @@
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import HypercoreId from 'hypercore-id-encoding'
+
+import { Collection } from './collection.js'
+import { Batch } from './batch.js'
+
+/**
+ * Room - Constructable ReadyResource for shared collections
+ *
+ * @example
+ * const room = new Room(db)               // create new
+ * const room = new Room(db, roomId)       // open existing
+ * const room = new Room(db, invite)       // join via invite
+ * await room.ready()
+ *
+ * const tasks = room.collection('tasks')
+ * await tasks.insert({ text: 'Hello', done: false })
+ *
+ * @extends ReadyResource
+ */
+export class Room extends ReadyResource {
+  /**
+   * @param {Cero} db - Cero instance
+   * @param {string} [arg] - Room ID or invite string (omit to create new)
+   * @param {object} [opts] - Options
+   * @param {AbortSignal} [opts.signal] - AbortSignal for cancellation
+   */
+  constructor(db, arg, opts = {}) {
+    super()
+
+    this.db = db
+    this.schema = db.schema
+
+    this._arg = arg
+    this._opts = opts
+
+    /** @type {import('cero').Room|null} - The underlying cero room */
+    this.room = null
+
+    this.ready().catch(safetyCatch)
+  }
+
+  /** Room ID (z32) */
+  get id() {
+    return this.room?.id
+  }
+
+  /** Room public key */
+  get publicKey() {
+    return this.room?.key
+  }
+
+  async _open() {
+    if (!this.db.opened) await this.db.ready()
+
+    const type = detectType(this._arg)
+
+    if (type === 'create') {
+      this.room = await this.db.rooms.create(this._opts)
+    } else if (type === 'invite') {
+      this.room = await this.db.rooms.pair(this._arg, this._opts)
+    } else {
+      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'))
+  }
+
+  async _close() {
+    if (!this.room) return
+    this.db.rooms.release(this.room)
+    this.room = null
+  }
+
+  /**
+   * Get a collection handle for shared data
+   * @param {string} name - Collection name
+   * @returns {Collection}
+   */
+  collection(name) {
+    this.schema.require(name, 'room')
+    return new Collection(this, name)
+  }
+
+  /**
+   * Create a batch for multiple operations
+   * @returns {Batch}
+   */
+  batch() {
+    return new Batch(this)
+  }
+
+  /** Shorthand — create invite and return the string */
+  async invite() {
+    if (!this.opened) await this.ready()
+    const { invite } = await this.room.invites.create()
+    return invite
+  }
+
+  /**
+   * Dispatch an operation to the room
+   * @param {string} op - Operation path
+   * @param {object} data - Operation data
+   */
+  async dispatch(op, data) {
+    if (!this.opened) await this.ready()
+    return this.room.dispatch(op, data)
+  }
+
+  /**
+   * Async factory — creates room + awaits ready
+   * @param {Cero} db - Cero instance
+   * @param {string} [arg] - Room ID, invite, or null to create
+   * @param {object} [opts] - Options
+   * @returns {Promise<Room>}
+   */
+  static async from(db, arg, opts) {
+    const room = new this(db, arg, opts)
+    await room.ready()
+    return room
+  }
+}
+
+// ==================== Private Helpers ====================
+
+/**
+ * Detect input type: nothing (create), id, or invite
+ * @private
+ */
+function detectType(input) {
+  if (!input) return 'create'
+
+  // z32 is ~52 chars, hex is 64 chars
+  if (input.length <= 64) {
+    try {
+      HypercoreId.decode(input)
+      return 'id'
+    } catch {
+      // Not a valid ID, assume invite
+    }
+  }
+
+  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

@@ -0,0 +1,203 @@
+import { singular, toFields, scopeNs, isLocal, isPrivate, isShared } from './utils.js'
+import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
+
+/**
+ * Type helpers for defining schema fields
+ * Usage: { name: t.string, count: t.int, active: t.bool }
+ */
+export const t = {
+  string: { type: 'string', required: true },
+  int: { type: 'int', required: true },
+  uint: { type: 'uint', required: true },
+  float: { type: 'float', required: true },
+  bool: { type: 'bool', required: true },
+  buffer: { type: 'buffer', required: true },
+  fixed32: { type: 'fixed32', required: true },
+  json: { type: 'json', required: true },
+
+  optional: (field) => ({ ...field, required: false }),
+  array: (field) => ({ ...field, array: true }),
+  ref: (collection) => ({ type: 'string', required: true, ref: collection })
+}
+
+function schemaFields(def) {
+  const fields = toFields(def.fields)
+  // every type gets index for range queries / pagination (assigned by cero's Base)
+  fields.push({ name: 'index', type: 'uint', required: false })
+  if (def.timestamps) {
+    fields.push({ name: 'createdAt', type: 'uint', required: true })
+    fields.push({ name: 'updatedAt', type: 'uint', required: false })
+  }
+  return fields
+}
+
+function inputFields(def) {
+  return toFields(def.fields).map((f) => ({ ...f, required: false }))
+}
+
+function delFields(def) {
+  const keys = {}
+  for (const k of def.key || ['id']) keys[k] = def.fields[k]
+  return toFields(keys)
+}
+
+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
+  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)
+
+  const nsFor = (scope) => (scope === SCOPE_SHARED && opts.namespace) || scopeNs(scope)
+
+  return {
+    namespace: opts.namespace || null,
+    collections,
+    types,
+
+    getScope(collection) {
+      const def = collections[collection]
+      return def ? def.scope || SCOPE_PRIVATE : null
+    },
+
+    isLocal(collection) {
+      return isLocal(this.getScope(collection))
+    },
+    isPrivate(collection) {
+      return isPrivate(this.getScope(collection))
+    },
+    isShared(collection) {
+      return isShared(this.getScope(collection))
+    },
+
+    hasTimestamps(collection) {
+      return collections[collection]?.timestamps === true
+    },
+
+    hasCounter(collection) {
+      return collections[collection]?.counter === true
+    },
+
+    counterNames(scope) {
+      const items =
+        scope === SCOPE_SHARED
+          ? sharedEntries
+          : scope === SCOPE_LOCAL
+            ? localEntries
+            : privateEntries
+      // map: type name (singular) → collection name (plural)
+      const map = {}
+      for (const [name, def] of items) {
+        if (def.counter) map[types.get(name)] = name
+      }
+      return map
+    },
+
+    resolve(collection, prefix) {
+      const scope = this.getScope(collection)
+      const type = types.get(collection)
+      const name = prefix ? `${prefix}-${type}` : type
+      return { spec: scopeNs(scope), path: `@${nsFor(scope)}/${name}` }
+    },
+
+    require(collection, context) {
+      const scope = this.getScope(collection)
+      if (!scope) throw new Error(`Unknown collection: '${collection}'`)
+      if (context === 'db' && scope === SCOPE_SHARED) {
+        throw new Error(`'${collection}' is shared — use room.collection('${collection}')`)
+      }
+      if (context === 'room' && scope !== SCOPE_SHARED) {
+        throw new Error(`'${collection}' is ${scope} — use db.collection('${collection}')`)
+      }
+      return scope
+    },
+
+    getPath(collection) {
+      const scope = this.getScope(collection)
+      return `@${nsFor(scope)}/${collection}`
+    },
+
+    build(scope, register, nsName) {
+      const items =
+        scope === SCOPE_SHARED
+          ? sharedEntries
+          : scope === SCOPE_LOCAL
+            ? localEntries
+            : privateEntries
+      const local = scope === SCOPE_LOCAL
+      const ns = nsName || scopeNs(scope)
+      for (const [name, def] of items) {
+        const type = types.get(name)
+        const fields = schemaFields(def)
+        const typePath = `@${ns}/${type}`
+
+        register.type({ name: type, compact: false, fields })
+        register.type({ name: `input-${type}`, compact: false, fields: inputFields(def) })
+        if (!local) register.type({ name: `del-${type}`, compact: false, fields: delFields(def) })
+
+        register.collection({
+          name,
+          schema: typePath,
+          key: def.key || ['id'],
+          counter: !!def.counter
+        })
+
+        if (def.indexes) {
+          for (const [idx, idxFields] of Object.entries(def.indexes)) {
+            register.index({ name: `${name}-${idx}`, collection: `@${ns}/${name}`, key: idxFields })
+          }
+        }
+
+        if (!local) {
+          register.dispatch({ name: `add-${type}`, requestType: typePath })
+          register.dispatch({ name: `set-${type}`, requestType: typePath })
+          register.dispatch({ name: `del-${type}`, requestType: `@${ns}/del-${type}` })
+        }
+      }
+    },
+
+    routes(scope) {
+      const items = scope === SCOPE_PRIVATE ? privateEntries : sharedEntries
+      const handlers = {}
+      const p = (name) => `@${nsFor(scope)}/${name}`
+      for (const [name, def] of items) {
+        const type = types.get(name)
+        const path = p(name)
+        const keys = def.key || ['id']
+
+        handlers[p(`add-${type}`)] = async (op, ctx) => {
+          const counterPath = p('counters')
+          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
+          op.index = counter.value
+          counter.value++
+          await ctx.view.insert(counterPath, counter)
+          await ctx.view.insert(path, op)
+        }
+
+        handlers[p(`set-${type}`)] = (op, ctx) => ctx.view.insert(path, op)
+        handlers[p(`del-${type}`)] = async (op, ctx) => {
+          await ctx.view.delete(
+            path,
+            keys.reduce((acc, k) => ((acc[k] = op[k]), acc), {})
+          )
+          const counterPath = p('counters')
+          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
+          counter.value = Math.max(0, counter.value - 1)
+          await ctx.view.insert(counterPath, counter)
+        }
+
+        if (def.handlers) {
+          for (const [op, handler] of Object.entries(def.handlers)) {
+            handlers[p(op)] = handler
+          }
+        }
+      }
+
+      return handlers
+    }
+  }
+}

package/src/lib/utils.js

@@ -0,0 +1,60 @@
+import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
+
+/** Map user-facing scope to cero namespace */
+const SCOPE_NS = {
+  [SCOPE_LOCAL]: 'local',
+  [SCOPE_PRIVATE]: 'identity',
+  [SCOPE_SHARED]: 'room'
+}
+
+/**
+ * Convert plural collection name to singular type name
+ * tasks -> task, categories -> category
+ */
+export function singular(name) {
+  if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
+  if (name.endsWith('s')) return name.slice(0, -1)
+  return name
+}
+
+/** Get cero namespace for a scope */
+export function scopeNs(scope) {
+  return SCOPE_NS[scope]
+}
+
+/** Get dispatch/collection path: @ns/name */
+export function scopePath(scope, name) {
+  return `@${SCOPE_NS[scope]}/${name}`
+}
+
+export function isLocal(scope) {
+  return scope === SCOPE_LOCAL
+}
+
+export function isPrivate(scope) {
+  return scope === SCOPE_PRIVATE
+}
+
+export function isShared(scope) {
+  return scope === SCOPE_SHARED
+}
+
+export function debounce(fn, ms = 0) {
+  let timer
+  return (...args) => {
+    clearTimeout(timer)
+    timer = setTimeout(() => fn(...args), ms)
+  }
+}
+
+/**
+ * Convert field definitions to hyperschema field array
+ */
+export function toFields(fields) {
+  return Object.entries(fields).map(([name, def]) => ({
+    name,
+    type: def.type,
+    required: def.required ?? true,
+    array: def.array ?? false
+  }))
+}