@cero-base/cero 1.19.0 → 2.1.0

package/types/handle/index.d.ts

@@ -74,10 +74,6 @@ export type HandleOpts = {
      * Writer keypair.
      */
     keyPair?: KeyPair;
-    /**
-     * Join discovery server-only; flip later with `setActive`.
-     */
-    passive?: boolean;
     /**
      * When `false`, skips creating a `Pairing` session.
      */
@@ -148,7 +144,6 @@ export type CeroHandle = Handle & Record<string, import('../lib/refs.js').Ref>;
  * @property {Array<{ epoch: number, entropy: Uint8Array }>} [epochs]  Rotation epochs delivered at join.
  * @property {string} [namespace]              Corestore namespace.
  * @property {KeyPair} [keyPair]               Writer keypair.
- * @property {boolean} [passive]               Join discovery server-only; flip later with `setActive`.
  * @property {boolean} [pair]                  When `false`, skips creating a `Pairing` session.
  *
  * @typedef {object} CreateChildOpts
@@ -186,10 +181,6 @@ export type CeroHandle = Handle & Record<string, import('../lib/refs.js').Ref>;
  */
 /**
  * A cero handle — a single writable database session attached to a swarm.
- * The "root" handle is the user's facade; child handles (created via
- * `_create`/`_join`/`_load`) live under it and share the same identity,
- * network and corestore. Ref properties (`profile`, `members`, ...) are
- * attached dynamically per the schema; child handles also carry a `name`.
  */
 export declare class Handle extends ReadyResource {
     identity: any;
@@ -201,8 +192,11 @@ export declare class Handle extends ReadyResource {
     _discovery: any;
     _dir: string;
     _opts: any;
+    extensions: any;
+    operators: any;
     _onerror: any;
     children: Set<any>;
+    _typeHooks: Set<any>;
     _loading: Map<any, any>;
     _joining: Map<any, any>;
     _coreKeys: Map<any, any>;
@@ -214,16 +208,47 @@ export declare class Handle extends ReadyResource {
     store: Database;
     pair: Pairing;
     _wantsPair: boolean;
-    _invitesSync: () => Promise<void>;
     _ac: AbortController;
+    _invitesSync: (touched: any) => void;
     /** @param {HandleOpts} [opts] */
     constructor(opts?: HandleOpts);
+    /**
+     * An `AbortSignal` that fires when this handle closes.
+     *
+     * @returns {AbortSignal}
+     */
+    get signal(): AbortSignal;
+    /** The top-most handle in the parent chain — itself for a root handle. */
+    get root(): this;
+    /**
+     * Lazily-built file server for this identity. Root-only — child handles
+     * reach it through `this.root.fileServer`.
+     *
+     * @returns {FileServer}
+     */
+    get fileServer(): FileServer;
+    /**
+     * Lazily-built blob store for THIS handle's writing device, at the current rotation epoch.
+     *
+     * @returns {Blobs}
+     */
+    get blobs(): Blobs;
+    /** The handle type of a child, null on the root. */
+    get type(): any;
+    /** Canonical id — identity id for the root handle, store key for children. */
+    get id(): any;
+    /** This device's id + name. `null` on child handles. */
+    get device(): {
+        id: any;
+        name: any;
+    };
+    get suspended(): boolean;
     _open(): Promise<void>;
     _close(): Promise<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.
+     * 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.
      *
      * @template {{ destroy?: Function, once?: Function }} T
      * @param {T} resource
@@ -233,14 +258,6 @@ export declare class Handle extends ReadyResource {
         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;
     /**
      * `EventEmitter.on` plus an optional `{ signal }` that removes the listener
      * when the signal aborts — e.g. `me.on('handle', fn, { signal: me.signal })`.
@@ -253,24 +270,6 @@ export declare class Handle extends ReadyResource {
     on(event: string, fn: (...args: any[]) => void, opts?: {
         signal?: AbortSignal;
     }): this;
-    /** The top-most handle in the parent chain — itself for a root handle. */
-    get root(): this;
-    /**
-     * Lazily-built file server for this identity. Root-only — child handles
-     * reach it through `this.root.fileServer`.
-     *
-     * @returns {FileServer}
-     */
-    get fileServer(): FileServer;
-    /**
-     * @param {Uint8Array} coreKey
-     * @param {object} info
-     * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
-     */
-    _resolveCore(coreKey: Uint8Array, info: object): {
-        key: Uint8Array;
-        encryptionKey: Uint8Array;
-    } | null;
     /**
      * Resolve a durable file id to an ephemeral download url via this identity's
      * file server.
@@ -279,38 +278,6 @@ export declare class Handle extends ReadyResource {
      * @returns {string}
      */
     getLink(id: string): string;
-    /**
-     * Lazily-built blob store for THIS handle's writing device, at the current
-     * rotation epoch. One core per writer per epoch that writes files: the base
-     * era uses the handle's encryptionKey, rotated epochs use a key derived
-     * from the epoch entropy — so a removed member cannot decrypt files added
-     * after the rotation. Instances carry `.stamp` so the file row records
-     * which era its core belongs to.
-     *
-     * @returns {Blobs}
-     */
-    get blobs(): Blobs;
-    _baseBlobs(): Blobs;
-    _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
-    /**
-     * Remember the blob-core key a file id points at so the file server can
-     * open the core. Lives on the Handle (not the shared operators) because the
-     * epoch-key derivation pulls native crypto — the RPC client must stay
-     * bundleable without it.
-     *
-     * @param {string} id
-     * @param {number} [stamp]
-     */
-    _registerBlobCore(id: string, stamp?: number): void;
-    _blobCoreKey(stamp: any): Uint8Array<ArrayBufferLike>;
-    /** Canonical id — identity id for the root handle, store key for children. */
-    get id(): any;
-    /** This device's id + name. `null` on child handles. */
-    get device(): {
-        id: any;
-        name: any;
-    };
-    get suspended(): boolean;
     /**
      * Initialise a fresh database: write the genesis claim, derive the writer.
      * Forwards to `Database.bootstrap`.
@@ -327,14 +294,12 @@ export declare class Handle extends ReadyResource {
      */
     claim(): Promise<void>;
     /**
-     * Flip this handle's swarm announce mode — `setActive(false)` demotes an
-     * idle/background room to server-only (still reachable, stops searching);
-     * `setActive(true)` promotes it back on focus. Cheap, safe to call often.
+     * `true` ranks this handle as just touched, `false` takes it out of the swarm until the
+     * next update lands in it.
      *
      * @param {boolean} active
-     * @returns {Promise<void>}
      */
-    setActive(active: boolean): Promise<void>;
+    setActive(active: boolean): void;
     /**
      * Mint a pairing invite for this handle.
      *
@@ -346,7 +311,6 @@ export declare class Handle extends ReadyResource {
         expiresIn?: number;
         data?: any;
     }): Promise<string>;
-    _syncInvites(): Promise<void>;
     /**
      * Revoke a previously-minted invite by its string form.
      *
@@ -363,7 +327,6 @@ export declare class Handle extends ReadyResource {
      * @returns {Promise<void>}
      */
     accept(candidate: any, { role, name }?: AcceptOpts): Promise<void>;
-    _checkGrant(role: any): Promise<void>;
     /**
      * Leave a child handle — removes it from the parent's `handles` collection
      * and closes the session. No-op on root handles.
@@ -372,9 +335,41 @@ export declare class Handle extends ReadyResource {
      */
     leave(): Promise<void>;
     /**
-     * Create a new child handle of `type`. Owner-flow — generates a fresh
-     * writer, adds it as a writer + member, and registers the child on the
-     * parent's `handles` collection.
+     * Pause networking + storage. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume a suspended root handle. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    /**
+     * @param {Uint8Array} coreKey
+     * @param {object} info
+     * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
+     */
+    _resolveCore(coreKey: Uint8Array, info: object): {
+        key: Uint8Array;
+        encryptionKey: Uint8Array;
+    } | null;
+    _baseBlobs(): Blobs;
+    _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
+    /**
+     * Remember the blob-core key a file id points at so the file server can open the core.
+     *
+     * @param {string} id
+     * @param {number} [stamp]
+     */
+    _registerBlobCore(id: string, stamp?: number): void;
+    _blobCoreKey(stamp: any): Uint8Array<ArrayBufferLike>;
+    _syncInvites(): Promise<void>;
+    _checkGrant(role: any): Promise<void>;
+    /**
+     * Create a new child handle of `type`. Owner-flow — generates a fresh writer, adds it as a
+     * writer + member, and registers the child on the parent's `handles` collection.
      *
      * @param {string} type
      * @param {CreateChildOpts} [opts]
@@ -382,9 +377,7 @@ export declare class Handle extends ReadyResource {
      */
     _create(type: string, { name, routes, role, accept }?: CreateChildOpts): Promise<Handle>;
     /**
-     * Join a child handle by invite (joiner-flow). Waits for writer
-     * capability and registers the child on the parent's `handles`
-     * collection.
+     * Join a child handle by invite (joiner-flow).
      *
      * @param {string} invite
      * @param {string} type
@@ -401,9 +394,8 @@ export declare class Handle extends ReadyResource {
      */
     _pair(invite: string, type: string, { routes, timeout }?: JoinChildOpts, target?: Uint8Array | null): Promise<Handle>;
     /**
-     * Get an open child by id, or re-open it. Concurrent calls for the same id
-     * share one in-flight load, so the child is built — and `handle` emitted —
-     * exactly once.
+     * Get an open child by id, or re-open it. Concurrent calls for the same id share one
+     * in-flight load, so the child is built — and `handle` emitted — exactly once.
      *
      * @param {string} type
      * @param {string} id
@@ -419,29 +411,10 @@ export declare class Handle extends ReadyResource {
      * @returns {Promise<Handle>}
      */
     _reopen(type: string, id: string, opts: any): Promise<Handle>;
-    /**
-     * Pause networking + storage. Idempotent; no-op on child handles.
-     *
-     * @returns {Promise<void>}
-     */
-    suspend(): Promise<void>;
     _suspend(): Promise<void>;
-    /**
-     * Resume a suspended root handle. Idempotent; no-op on child handles.
-     *
-     * @returns {Promise<void>}
-     */
-    resume(): Promise<void>;
     _resume(): Promise<void>;
-    /**
-     * Pair into an existing handle via an invite, returning a brand-new
-     * `Handle` already configured with the resolved key + encryption key.
-     *
-     * @param {string} invite
-     * @param {StaticJoinOpts} [opts]
-     * @returns {Promise<Handle>}
-     */
-    static join(invite: string, { parent, network, identity, store, spec, namespace, routes, timeout }?: StaticJoinOpts): Promise<Handle>;
+    _adopt(child: any, info: any): void;
+    _hookType(op: any, ref: any, fn: any, opts: any): () => void;
     /**
      * @param {Handle} child
      * @param {{ role?: string }} [opts]
@@ -466,4 +439,13 @@ export declare class Handle extends ReadyResource {
         publicKey: Uint8Array;
         secretKey: Uint8Array;
     } | null>;
+    /**
+     * Pair into an existing handle via an invite, returning a brand-new
+     * `Handle` already configured with the resolved key + encryption key.
+     *
+     * @param {string} invite
+     * @param {StaticJoinOpts} [opts]
+     * @returns {Promise<Handle>}
+     */
+    static join(invite: string, { parent, network, identity, store, spec, namespace, routes, timeout }?: StaticJoinOpts): Promise<Handle>;
 }

package/types/index.d.ts

@@ -1,12 +1,11 @@
 import { Identity } from '@cero-base/core/identity';
 import { Handle, Ref } from './handle/index.js';
 import { Local } from './local/index.js';
-import { put, set, get, del, count, watch, changes, call, open, rotate, before, after, bind, define } from './lib/operators.js';
+import { put, set, get, del, watch, changes, call, open, rotate, before, after } from './lib/operators.js';
 import { peek } from './lib/peek.js';
 import { t, schema } from './lib/spec.js';
-import { internal } from './lib/internal.js';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, changes, call, open, rotate, before, after, bind, define } from './lib/operators.js';
+export { put, set, get, del, watch, changes, call, open, rotate, before, after } from './lib/operators.js';
 export { peek } from './lib/peek.js';
 export { t, schema } from './lib/spec.js';
 export type CeroHandle = import('./handle/index.js').CeroHandle;
@@ -54,6 +53,14 @@ export type CeroOpts = {
      * Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
      */
     mirrors?: Array<string | Uint8Array>;
+    /**
+     * How many rooms search, how many only announce, and the idle ms before the rest leave the swarm.
+     */
+    presence?: {
+        active?: number;
+        announced?: number;
+        idle?: number;
+    };
     /**
      * Existing database key to recover into, skipping the pointer lookup.
      */
@@ -79,9 +86,13 @@ export type CeroOpts = {
      */
     storageKey?: Uint8Array;
     /**
-     * `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
+     * The extensions this instance runs, instead of the ones the spec carries. Build with the same list.
+     */
+    extensions?: import('./extensions/index.js').Extension[];
+    /**
+     * The operators to bind, instead of the ones the spec carries.
      */
-    extensions?: boolean;
+    operators?: Record<string, any>;
     /**
      * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
      */
@@ -108,19 +119,19 @@ export type CeroOpts = {
  * @property {number[]} [backoffs]                     Swarm reconnect backoff tiers in ms (testing/tuning).
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
  * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
+ * @property {{ active?: number, announced?: number, idle?: number }} [presence]  How many rooms search, how many only announce, and the idle ms before the rest leave the swarm.
  * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
  * @property {(err: any) => void} [onerror]            Background-task error handler.
  * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
- * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
+ * @property {import('./extensions/index.js').Extension[]} [extensions]  The extensions this instance runs, instead of the ones the spec carries. Build with the same list.
+ * @property {Record<string, any>} [operators]  The operators to bind, instead of the ones the spec carries.
  * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 /**
- * Open (or create) a cero handle at `dir`. Sets up storage, network and
- * identity, then returns a ready root `Handle` with all schema refs
- * attached as properties.
+ * Open (or create) a cero handle at `dir`.
  *
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
@@ -134,7 +145,6 @@ export declare namespace cero {
     export { set };
     export { get };
     export { del };
-    export { count };
     export { watch };
     export { changes };
     export { call };
@@ -145,15 +155,9 @@ export declare namespace cero {
     export { peek };
     export { restore };
     export { schema };
-    export { bind };
-    export { define };
-    export { internal as _internal };
-    export var use: (...exts: any[]) => void;
 }
 /**
- * Restore a cero instance from a mnemonic phrase. Closes the running
- * instance, wipes the on-disk `main/` tree and re-opens with the phrase, which
- * recovers so the writer slot is re-claimed.
+ * Restore a cero instance from a mnemonic phrase.
  *
  * @param {Handle} me   Existing root handle to restore.
  * @param {string} phrase   BIP-39 mnemonic phrase.

package/types/lib/bluetooth.d.ts

@@ -1,18 +1,7 @@
 import ReadyResource from 'ready-resource';
 /**
- * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
- * facade over ble-swarm. Bluetooth only changes how peers meet and carry
- * bytes; capability-gated replication still decides what syncs. Discovery is
- * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
- * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
- *
- * ```js
- * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
- * await me.bluetooth.start()
- * me.bluetooth.peers          // Map of live BLE links
- * me.bluetooth.on('update', () => {})
- * ```
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin facade over
+ * ble-swarm.
  *
  * @extends ReadyResource
  */
@@ -49,6 +38,7 @@ export declare class Bluetooth extends ReadyResource {
     /** @returns {Map<string, any>} Live BLE links, keyed by peer public key. */
     get peers(): Map<string, any>;
     _open(): Promise<void>;
+    _close(): Promise<void>;
     /**
      * Begin advertising + scanning. Idempotent; no-op when unsupported.
      *
@@ -56,34 +46,19 @@ export declare class Bluetooth extends ReadyResource {
      */
     start(): Promise<void>;
     /**
-     * Stop advertising/scanning and drop links; open invite rendezvous end with
-     * the radio. Idempotent. Local data and the rest of the network (DHT) are
-     * untouched.
+     * Stop advertising/scanning and drop links; open invite rendezvous end with the radio.
      *
      * @returns {Promise<void>}
      */
     stop(): Promise<void>;
     /**
-     * Offline join rendezvous: retune the radio to the invite-derived topic so
-     * holder and joiner find each other with zero DHT. One topic at a time —
-     * announcing a new invite replaces the previous rendezvous. Returns a stop
-     * function — closing the QR must stop the rendezvous so a photographed
-     * invite doesn't stay an ambient discovery beacon (admission itself is
-     * always gated by blind-pairing verifying the invite). The retune back to
-     * the mesh topic waits for live links to drain: the link a join just
-     * established survives and carries the joiner's initial replication.
-     * Auto-stops at the invite's expiry, on `stop()`, and on close.
-     *
-     * Only active while nearby sync is on: before `start()` (and after `stop()`)
-     * this is a no-op — the user controls the radio, and a join must not touch
-     * Bluetooth (OS permissions, GATT server) they never enabled.
+     * Offline join rendezvous: retune the radio to the invite-derived topic so holder and
+     * joiner find each other with zero DHT.
      *
      * @param {string} invite  Z32 invite string.
      * @returns {() => void}
      */
     announce(invite: string): () => void;
-    _stopAnnounce(): void;
-    _clearAnnounce(): void;
     /**
      * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
      *
@@ -96,5 +71,6 @@ export declare class Bluetooth extends ReadyResource {
      * @returns {Promise<void>}
      */
     resume(): Promise<void>;
-    _close(): Promise<void>;
+    _stopAnnounce(): void;
+    _clearAnnounce(): void;
 }

package/types/lib/constants.d.ts

@@ -3,14 +3,3 @@ export declare const COUNTERS = "counters";
 export declare const EPOCHS = "epochs";
 export declare const TIMEOUT = 30000;
 export declare const FLUSH = 500;
-export declare const DB_TYPE: {
-    string: string;
-    uint: string;
-    int: string;
-    bool: string;
-    bytes: string;
-    json: string;
-    fixed32: string;
-    fixed64: string;
-    file: string;
-};