@cero-base/cero 1.18.2 → 2.0.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.18.2",
+  "version": "2.0.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",
@@ -18,8 +18,7 @@
     "src",
     "types",
     "README.md",
-    "LICENSE",
-    "!**/CLAUDE.md"
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
@@ -82,31 +81,36 @@
     "events": {
       "bare": "bare-events",
       "default": "events"
+    },
+    "process": {
+      "bare": "bare-process",
+      "default": "process"
     }
   },
   "scripts": {
-    "build:test": "rm -rf test/fixture/spec && node test/fixture/build.js",
+    "build:test": "rm -rf test/fixtures/spec && node test/fixtures/build.js",
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
     "test": "npm run test:bare",
     "pretest:bare": "npm run build:test",
-    "test:bare": "ls test/*.test.js | xargs -P1 -n1 brittle-bare test/bare.js",
-    "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
+    "test:bare": "find test -name '*.test.js' | sort | xargs -P1 -n1 brittle-bare",
+    "test:node": "find test -name '*.test.js' | sort | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.18.2",
+    "@cero-base/core": "^2.0.0",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.8.1",
     "bare-path": "^3.1.2",
     "ble-swarm": "^2.3.0",
-    "compact-encoding": "^3.3.2",
-    "corestore": "^7.12.2",
+    "compact-encoding": "^3.4.0",
+    "corestore": "^7.12.3",
     "hrpc": "^4.3.1",
-    "hypercore": "^11.35.2",
+    "hypercore": "^11.35.4",
     "hypercore-crypto": "^3.7.0",
+    "hypercore-id-encoding": "^1.3.0",
     "hypercore-storage": "^3.2.1",
     "hyperdb": "^6.9.0",
     "hyperdispatch": "^1.6.0",
@@ -124,7 +128,7 @@
     "bare-process": "^4.5.1",
     "bare-url": "^2.5.4",
     "brittle": "^4.1.1",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "license": "Apache-2.0"
 }

package/src/build/index.js

@@ -9,18 +9,8 @@ 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,
-  builtinTypes,
-  builtinCollections,
-  builtinDispatches,
-  rotateDispatch,
-  rpcTypes,
-  rpcCommands,
-  getHyperdbType
-} from './builtins.js'
+import { registry } from '../extensions/index.js'
+import * as internal from './internal.js'
 
 /**
  * @typedef {import('@cero-base/core/schema').Schema} Schema
@@ -34,29 +24,22 @@ import {
 /**
  * Compile a cero schema into wire-level artifacts and write them to disk.
  *
- * Emits a `main/` tree (schema + hyperdb + dispatch + rpc), a `local/` tree
- * for per-device data, one `handles/<name>/` tree per child handle type, and
- * an `index.js` that re-exports a ready-to-use `spec` object.
- *
  * @param {string} specDir          Output directory.
  * @param {SchemaInput} schema      Either a `schema(...)` wrapper or its raw defs object.
  * @param {BuildOpts} [opts]
  * @returns {Promise<void>}
  */
-export { getHyperdbType } from './builtins.js'
-
 export async function build(specDir, schema, { ns = NS, extensions = true } = {}) {
   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) → builtin type
-  // name, merged across scopes. App schema first, then each `cero.use()` extension.
+  // t.extend entries by internal type: app schema first, then each extension
   const extend = {}
   const defs = {}
   const collect = (entries, fromExt = false) => {
     for (const [k, v] of Object.entries(entries)) {
       if (v && v.kind === 'extend') {
-        const type = refs.main[k]?.type
+        const type = internal.defs.main[k]?.type
         if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
         // app schema wins on field conflicts, extensions only add new fields
         extend[type] = fromExt ? { ...v.fields, ...extend[type] } : { ...extend[type], ...v.fields }
@@ -66,7 +49,7 @@ export async function build(specDir, schema, { ns = NS, extensions = true } = {}
     }
   }
   collect(raw)
-  for (const ext of internal.extensions) {
+  for (const ext of registry) {
     if (ext.bundled && extensions === false) continue
     if (ext.schema) collect(ext.schema, true)
   }
@@ -93,7 +76,7 @@ export async function build(specDir, schema, { ns = NS, extensions = true } = {}
     )
   }
 
-  // Hang a `type: <name>` marker on each handle ref in main so the runtime knows which type to open.
+  // the type marker tells the runtime which handle type to open
   for (const [name] of Object.entries(handles)) {
     if (meta.refs[name]) meta.refs[name] = { kind: 'handle', type: name, schema: `@${ns}/handle` }
   }
@@ -138,7 +121,7 @@ function compile(root, ns, scope = 'main') {
     scope
   }
 
-  Object.assign(ctx.meta.refs, builtinRefs(ns, scope))
+  Object.assign(ctx.meta.refs, internal.refs(ns, scope))
 
   for (const [name, node] of Object.entries(root)) {
     if (node.kind === 'handle') {
@@ -166,13 +149,13 @@ function fileFieldNames(fields) {
 function register(name, node, ctx) {
   const fqn = `@${ctx.ns}/${name}`
   if (node.kind === 'action') {
-    ctx.types.push({ name, compact: false, fields: fieldsFor(node.fields) })
+    ctx.types.push({ name, compact: false, fields: internal.fields(node.fields) })
     ctx.dispatches.push({ name, requestType: fqn })
     ctx.meta.refs[name] = { kind: 'action', path: [name], schema: fqn }
     return
   }
   if (node.kind === 'single') {
-    ctx.types.push({ name, compact: false, fields: fieldsFor(node.fields) })
+    ctx.types.push({ name, compact: false, fields: internal.fields(node.fields) })
     ctx.collections.push({ name, schema: fqn, key: [] })
     ctx.dispatches.push({ name: `set-${name}`, requestType: fqn })
     ctx.dispatches.push({ name: `del-${name}`, requestType: `@${ctx.ns}/del-by-id` })
@@ -192,7 +175,7 @@ function register(name, node, ctx) {
         { name: 'index', type: 'uint', required: false },
         { name: 'createdAt', type: 'int', required: false },
         { name: 'updatedAt', type: 'int', required: false },
-        ...fieldsFor(node.fields)
+        ...internal.fields(node.fields)
       ]
     })
     ctx.collections.push({ name, schema: fqn, key: ['id'] })
@@ -215,10 +198,7 @@ function register(name, node, ctx) {
       }
       ctx.meta.refs[name].indexes = node.indexes
     }
-    // implicit secondary index on the auto-increment `index` — lets reads push
-    // reverse/limit down to hyperdb instead of scanning the whole collection.
-    // main scope only: local (Storage) rows never get `index` stamped, and an
-    // undefined index key crashes the encoder on insert.
+    // implicit index on the auto-increment `index`, so reverse and limit push down; main scope only
     if (ctx.scope === 'main' && !node.indexes?.index) {
       ctx.indexes.push({ name: `${name}-index`, collection: fqn, key: ['index'] })
       refEntry.orderIndex = true
@@ -226,17 +206,7 @@ function register(name, node, ctx) {
   }
 }
 
-function fieldsFor(fields) {
-  return Object.entries(fields).map(([name, marker]) => ({
-    name,
-    type: getHyperdbType(marker.prim),
-    required: marker.required === true
-  }))
-}
-
-// The contract version is the highest of the three auto-bumped artifact
-// versions — any schema/db/dispatch change advances it, so a peer can tell
-// whether an op predates or postdates its own build.
+// the contract version is the highest of the schema, db and dispatch versions
 async function contractVersion(mainDir) {
   const read = async (rel) => {
     const j = JSON.parse(await fs.readFile(join(mainDir, rel), 'utf-8'))
@@ -258,29 +228,30 @@ function emitMain(dir, ns, { types, collections, dispatches, indexes = [] }, { r
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of builtinTypes('main', extend)) sns.register(desc)
+  for (const desc of internal.types('main', extend)) sns.register(desc)
   for (const desc of types) sns.register(desc)
-  if (rpc) for (const desc of rpcTypes()) sns.register(desc)
+  if (rpc) for (const desc of internal.types('rpc')) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of builtinCollections(ns, 'main')) dns.collections.register(desc)
+  for (const desc of internal.collections(ns, 'main')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   for (const desc of indexes) dns.indexes.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })
 
   const d = Hyperdispatch.from(schemaDir, dispatchDir)
   const xns = d.namespace(ns)
-  for (const desc of builtinDispatches(ns)) xns.register(desc)
+  for (const desc of internal.dispatches(ns)) xns.register(desc)
   for (const desc of dispatches) xns.register(desc)
-  xns.register(rotateDispatch(ns))
+  // after the app's dispatches: hyperdispatch numbers routes positionally and persists them
+  xns.register({ name: 'rotate-key', requestType: `@${ns}/epoch` })
   Hyperdispatch.toDisk(d, dispatchDir, { esm: true })
 
   if (rpc) {
     const r = HRPCBuilder.from(schemaDir, rpcDir)
     const rns = r.namespace(ns)
-    for (const desc of rpcCommands(ns)) rns.register(desc)
+    for (const desc of internal.commands(ns)) rns.register(desc)
     HRPCBuilder.toDisk(r, rpcDir, { esm: true })
   }
 }
@@ -291,13 +262,13 @@ function emitLocal(dir, ns, { types, collections, indexes = [] }) {
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of builtinTypes('local')) sns.register(desc)
+  for (const desc of internal.types('local')) sns.register(desc)
   for (const desc of types) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of builtinCollections(ns, 'local')) dns.collections.register(desc)
+  for (const desc of internal.collections(ns, 'local')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   for (const desc of indexes) dns.indexes.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })

package/src/build/internal.js

@@ -0,0 +1,121 @@
+import { CeroError } from '@cero-base/core/errors'
+import { COUNTERS, EPOCHS } from '../lib/constants.js'
+import * as schemas from './schemas.js'
+
+// internal refs by scope; kind defaults to collection
+export const defs = {
+  main: {
+    members: { type: 'member' },
+    devices: { type: 'device' },
+    invites: { type: 'invite' },
+    handles: { type: 'handle' },
+    files: { type: 'file' }
+  },
+  local: {
+    master: { type: 'master', kind: 'single' },
+    keypair: { type: 'keypair', kind: 'single' },
+    'handle-keypairs': { type: 'handle-keypair' },
+    environment: { type: 'environment', kind: 'single' }
+  }
+}
+
+// a DSL primitive is its hyperdb column type, except bytes (a buffer) and file (an id string)
+const COLUMN = { bytes: 'buffer', file: 'string' }
+
+export function fields(map) {
+  return Object.entries(map).map(([name, m]) => ({
+    name,
+    type: COLUMN[m.prim] || m.prim,
+    required: m.required === true
+  }))
+}
+
+// a base field cannot be redeclared
+function merge(type, base, extra) {
+  if (!extra) return base
+  const dup = Object.keys(extra).find((k) => k in base)
+  if (dup) throw CeroError.INVALID(`'${dup}' is a base field of '${type}' and cannot be redeclared`)
+  return { ...base, ...extra }
+}
+
+export function types(scope, extend = {}) {
+  return Object.entries(schemas[scope]).map(([name, base]) => ({
+    name,
+    compact: false,
+    fields: fields(merge(name, base, extend[name]))
+  }))
+}
+
+export function refs(ns, scope) {
+  return Object.fromEntries(
+    Object.entries(defs[scope]).map(([name, def]) => [
+      name,
+      {
+        kind: def.kind || 'collection',
+        path: [name],
+        internal: true,
+        ...(scope === 'main' && { verb: def.type }),
+        schema: `@${ns}/${def.type}`
+      }
+    ])
+  )
+}
+
+export function collections(ns, scope) {
+  const out = Object.entries(defs[scope]).map(([name, def]) => ({
+    name,
+    schema: `@${ns}/${def.type}`,
+    key: def.kind === 'single' ? [] : ['id']
+  }))
+  if (scope === 'main') {
+    out.push({ name: COUNTERS, schema: `@${ns}/counter`, key: ['name'] })
+    out.push({ name: EPOCHS, schema: `@${ns}/epoch`, key: ['epoch'] })
+  }
+  return out
+}
+
+export function dispatches(ns) {
+  return [
+    { name: 'add-writer', requestType: `@${ns}/writer` },
+    { name: 'del-writer', requestType: `@${ns}/writer` },
+    { name: 'claim-writer', requestType: `@${ns}/claim` },
+    ...Object.values(defs.main).flatMap(({ type }) => [
+      { name: `add-${type}`, requestType: `@${ns}/${type}` },
+      { name: `set-${type}`, requestType: `@${ns}/${type}` },
+      { name: `del-${type}`, requestType: `@${ns}/del-by-id` }
+    ])
+  ]
+}
+
+// hrpc commands: name, request type, response type, streaming response
+const COMMANDS = [
+  ['init', 'req-empty', 'res-identity'],
+  ['restore', 'req-restore', 'res-identity'],
+  ['seed', 'req-empty', 'res-seed'],
+  ['add-row', 'req-row', 'res-data'],
+  ['add-file', 'req-add-file', 'res-data'],
+  ['add-handle', 'req-row', 'res-handle'],
+  ['set', 'req-row', 'res-data'],
+  ['get', 'req-query', 'res-rows'],
+  ['get-one', 'req-id', 'res-data'],
+  ['del', 'req-id', 'res-ok'],
+  ['count', 'req-query', 'res-count'],
+  ['watch', 'req-query', 'res-rows', true],
+  ['call', 'req-call', 'res-data'],
+  ['invite', 'req-invite', 'res-invite'],
+  ['revoke', 'req-revoke', 'res-ok'],
+  ['join', 'req-join', 'res-handle'],
+  ['open-handle', 'req-open', 'res-handle'],
+  ['close-handle', 'req-handle', 'res-ok'],
+  ['leave', 'req-handle', 'res-ok'],
+  ['changes', 'req-query', 'res-changes', true],
+  ['rotate', 'req-handle', 'res-epoch']
+]
+
+export function commands(ns) {
+  return COMMANDS.map(([name, req, res, stream]) => ({
+    name,
+    request: { name: `@${ns}/${req}` },
+    response: { name: `@${ns}/${res}`, ...(stream && { stream }) }
+  }))
+}

package/src/build/schemas.js

@@ -1,6 +1,4 @@
-// Builtin type schemas grouped by scope, in the schema DSL — kept separate from
-// the build wiring (builtins.js) so apps can extend them with `t.extend`.
-// Field order is the wire order; do not reorder.
+// field order is the wire format: append only, never reorder
 import { t } from '../lib/spec.js'
 
 const { string, bytes, int, uint, bool, required } = t
@@ -15,11 +13,7 @@ export const main = {
     sig: required(bytes),
     isIndexer: bool,
     ts: int,
-    // Who this writer belongs to. The paired add-member decides the rank in
-    // the same transaction, and a refused grant discards this admission with
-    // it — so `role` is unread since 77e5ed0 and stays only for older peers.
-    // Absent on a device you add for yourself (recovery), where the device
-    // binds to the master identity.
+    // the paired add-member decides the rank in the same transaction; `role` here is unread
     memberId: string,
     role: string
   },

package/src/extensions/handle-sync.js

@@ -2,13 +2,8 @@ import { t } from '../lib/spec.js'
 import { get, 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.
+ * 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.
  *
  * @param {{ fields?: Record<string, any> }} [opts]
  */
@@ -19,9 +14,7 @@ export function handleSync({ fields = { avatar: t.string } } = {}) {
     schema: { handles: t.extend(fields) },
     setup(me) {
       const keys = ['name', ...Object.keys(fields)]
-      // skip the write when the row already mirrors the profile — every open
-      // re-emits the watch snapshot, and an unconditional set is a new op in
-      // the replicated log forever
+      // an unconditional set on every open is a new op in the log forever
       const reflect = async (child, data) => {
         child.name = data.name
         const { data: row } = await get(me.handles, child.id)

package/src/extensions/index.js

@@ -1,2 +1,8 @@
+import { profileSync } from './profile-sync.js'
+import { handleSync } from './handle-sync.js'
+
 export * from './profile-sync.js'
 export * from './handle-sync.js'
+
+// process-wide: build() folds in each schema, cero() runs each setup
+export const registry = [profileSync(), handleSync()]

package/src/extensions/profile-sync.js

@@ -3,10 +3,6 @@ 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]
  */
@@ -23,7 +19,6 @@ export function profileSync({ fields = { avatar: t.string } } = {}) {
       const publish = (child, profile) =>
         set(child.members, { id: me.identity.id, ...profile }, { upsert: false }).catch(me._onerror)
 
-      // skip the broadcast when the member row already mirrors the profile —
       // an unconditional set on every open is a room-wide op forever
       const onHandle = async (child) => {
         const { data: profile } = await get(me.profile)