@muhkoo/connect 0.8.0-alpha.0 → 0.10.0-alpha.0

package/dist/connect.d.ts

@@ -1415,6 +1415,18 @@ interface ShardByteCache {
     get(hash: string): Promise<Uint8Array | null>;
     put(hash: string, bytes: Uint8Array): Promise<void>;
 }
+/**
+ * A peer block source (the p2p layer's `PeerExchange` satisfies this
+ * structurally). Consulted between the local cache and origin: a block fetched
+ * from a peer is verified by hash before use. Declared here so the storage layer
+ * doesn't import the p2p module (dependency arrow stays p2p → storage).
+ */
+interface PeerBlockSource {
+    getBlock(hash: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+}
 interface ShardClientOptions {
     /** Base URL of the accelerator (e.g. `https://muhkoo-accelerator.workers.dev`). */
     baseUrl: string;
@@ -1446,6 +1458,12 @@ interface ShardClientOptions {
      * keyed by `hash`, so only the hash needs recording.
      */
     deferUpload?: (hash: string) => Promise<void>;
+    /**
+     * Optional peer block source. When present, GETs try peers between the local
+     * cache and origin (peer blocks are verified by hash); PUTs announce the new
+     * block to peers. Best-effort — any failure falls through to origin.
+     */
+    peers?: PeerBlockSource;
 }
 /**
  * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
@@ -1458,6 +1476,7 @@ declare class ShardClient {
     private readonly fetchFn;
     private readonly cache?;
     private readonly deferUpload?;
+    private readonly peers?;
     constructor(opts: ShardClientOptions);
     /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
     urlForHash(hash: string): string;
@@ -1475,6 +1494,9 @@ declare class ShardClient {
      * `null` for 404 so callers can distinguish "missing" from "errored".
      */
     getShard(hash: string): Promise<Uint8Array | null>;
+    /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
+     *  cache is present, so RS recovery can proceed); throws otherwise. */
+    private fetchFromOrigin;
     /**
      * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
      * dedup-rewrite. The server can implement this as a HEAD or return a small
@@ -2492,6 +2514,21 @@ declare class ZkAuth {
      * to re-enable encryption/messaging without a full re-login.
      */
     restore(): Promise<AuthUser | null>;
+    /**
+     * Boot helper — call this once on app start. Restores the session AND, when a
+     * passkey is enrolled, silently unlocks the identity via WebAuthn (recovering
+     * the master seed so the ratchet keypair rehydrates and `client.kv` works).
+     * The seed is never persisted, so a passkey (or password) is the only way to
+     * unlock after a reload — this keeps that off the app's plate.
+     *
+     * Returns `{ user, unlocked }`. When `unlocked` is false (no passkey, the
+     * user cancelled, or the browser required a gesture), prompt for a password
+     * and call {@link unlock}. Apps need no key-management scaffolding beyond this.
+     */
+    resume(): Promise<{
+        user: AuthUser | null;
+        unlocked: boolean;
+    }>;
     /**
      * Re-derive identity material for an already-authenticated (restored)
      * session, so the client can decrypt storage and run the ratchet. Verifies
@@ -3704,11 +3741,29 @@ declare class SpaceKeyring implements EpochKeyProvider {
     private readonly policy;
     /** Cached member directory: memberId → imported ECDSA verify key. */
     private readonly memberEcdsa;
+    /** Coalesce concurrent roster refreshes (the parallel history/backlog decode
+     *  would otherwise fire one `roster` fetch PER message — a thundering herd). */
+    private dirInFlight;
+    private dirRefreshedAt;
+    /** Min gap between non-forced roster refreshes. A miss that persists within
+     *  this window won't re-fetch (the roster hasn't changed that fast); genuine
+     *  membership changes use `{ force: true }` (join requests / history loads). */
+    private static readonly DIR_COOLDOWN_MS;
     constructor(deps: SpaceKeyringDeps);
     /** The cached ECDSA verify key for a member, if known. */
     ecdsaKeyFor(memberId: string): CryptoKey | undefined;
-    /** Refresh the member directory (memberId → ECDSA key) from the roster. */
-    refreshDirectory(): Promise<void>;
+    /**
+     * Refresh the member directory (memberId → ECDSA key) from the roster.
+     * Coalesces concurrent callers into ONE fetch, and skips a fetch when one
+     * completed within {@link DIR_COOLDOWN_MS} (unless `force`). Without this, a
+     * page of N messages decoded in parallel — each missing the cold directory —
+     * fires N simultaneous `roster` requests that queue behind the browser's
+     * connection limit and take many seconds.
+     */
+    refreshDirectory(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    private doRefreshDirectory;
     currentEpoch(): number;
     keyForEpoch(epoch: number): Uint8Array | undefined;
     hasAnyKey(): boolean;
@@ -3729,6 +3784,13 @@ declare class SpaceKeyring implements EpochKeyProvider {
      * epoch keys obtained. Safe to call repeatedly (idempotent).
      */
     pullKeys(): Promise<number>;
+    /**
+     * Background freshness check for the cache-hit fast path: confirm we hold the
+     * current epoch (picks up a rotation / our removal) WITHOUT the full newcomer
+     * admit handshake. Cheap + idempotent; never blocks first paint. Returns the
+     * number of newly-obtained epoch keys (0 = already current).
+     */
+    reconcile(): Promise<number>;
     /**
      * Wrap our group key(s) for a newcomer and post the blobs. In a `static`
      * space the newcomer receives every epoch we hold (full history); in a
@@ -3775,6 +3837,19 @@ declare class SpaceKeyring implements EpochKeyProvider {
  */
 
 type Listener = (e: CustomEvent) => void;
+/**
+ * A P2P swarm attached to a Space (the p2p layer's `PeerNetwork` satisfies this
+ * structurally — Space never imports the p2p module). `exchange` is consulted by
+ * the Space's file `ShardClient`; `start` runs peer discovery on connect; `close`
+ * tears the mesh down.
+ */
+interface AttachedPeerNetwork {
+    readonly exchange: PeerBlockSource;
+    start(): void;
+    close(): void;
+    gossip(data: Uint8Array): void;
+    onGossip(cb: (from: string, data: Uint8Array) => void): () => void;
+}
 interface SpaceFileMetadata {
     name: string;
     type: string;
@@ -3914,6 +3989,8 @@ declare class Space {
     private readonly events;
     private rawWired;
     private catchUpUnsub;
+    /** Optional P2P swarm for this Space (block exchange among members). */
+    private peerNet;
     constructor(deps: SpaceDeps);
     /** The encoded space id (same as the transport name for fan-out spaces). */
     get id(): string;
@@ -3922,6 +3999,19 @@ declare class Space {
     /** Open the space websocket (resolves the ticket + identity lazily). */
     connect(): Promise<void>;
     disconnect(): void;
+    /** Attach a P2P swarm so this Space's file reads/writes can use peers. */
+    attachPeerNetwork(net: AttachedPeerNetwork): void;
+    /**
+     * Broadcast an app payload directly to connected Space peers over P2P,
+     * **bypassing the server** — for CRDT ops / high-frequency state (live
+     * cursors, presence, collaborative edits) you don't want to push through the
+     * relay. No-op when no P2P mesh is active (requires `client` `p2p`).
+     * Unlike {@link sendEphemeral} (server-relayed, metered, size-limited), this
+     * is peer-direct and fragments large payloads.
+     */
+    gossipToPeers(data: Uint8Array): void;
+    /** Subscribe to peer gossip ({@link gossipToPeers}). Returns an unsubscribe fn. */
+    onPeerGossip(handler: (from: string, data: Uint8Array) => void): () => void;
     /** Subscribe to a raw channel event. Buffered until `connect()` if early. */
     on(event: string, handler: Listener): void;
     off(event: string, handler: Listener): void;
@@ -3982,7 +4072,7 @@ declare class Space {
      * indicators, presence, or live cursors are built on top of this. No-op if
      * the space isn't connected (ephemeral signals aren't worth queuing).
      */
-    sendEphemeral(subject: string, data: unknown): void;
+    sendEphemeral(subject: string, data: unknown, to?: string): void;
     /** Subscribe to inbound ephemeral signals. `from` is the authenticated sender. */
     onEphemeral(handler: (e: EphemeralEvent) => void): () => void;
     /** Subscribe to inbound join requests (for a key-holder to admit). */
@@ -4160,6 +4250,53 @@ declare class MessageNamespace {
     private myId;
 }
 
+/**
+ * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
+ * keypair (the connect `KeyStore` entry keyed by the member id / username).
+ *
+ * Historically each app hand-rolled this (see the web app's old
+ * `personal/spaceLoader.ts`): generate a keypair at register, seed-wrap it, and
+ * PUT it to the personal space; on login GET + unwrap + hydrate the `KeyStore`.
+ * That scaffolding now lives here so ANY app gets a **stable** member keypair
+ * across reloads for free — without which the member re-admits to every space on
+ * every load and the group-key cache can never round-trip.
+ *
+ * Security invariant: the wrapping secret is the **master seed** (not the
+ * password), so the blob survives password changes and unlocks under a passkey.
+ * The seed is only ever held in memory (never persisted), so this vault can only
+ * provision/rehydrate while the client is unlocked.
+ */
+
+/** Opaque personal-space blob store (a `PersonalSpaceClient` or a kv-backed shim). */
+interface ChatKeyStore {
+    get(key: string): Promise<WrappedPayload | null>;
+    put(key: string, value: WrappedPayload): Promise<void>;
+}
+declare class ChatKeyVault {
+    private readonly store;
+    constructor(store: ChatKeyStore);
+    /**
+     * Register-time: ensure a keypair exists for `memberId`, seed-wrap the
+     * dehydrated form, and persist it to the personal space. Idempotent — reuses
+     * an existing in-tab keypair rather than minting a second one.
+     */
+    provision(memberId: string, seedSecret: string): Promise<void>;
+    /**
+     * Sign-in / unlock time: fetch the wrapped blob, unwrap with the seed, and
+     * hydrate the `KeyStore` — restoring the SAME keypair the member had before.
+     * Returns `true` when a keypair is now in hand (already present or hydrated),
+     * `false` when there's no blob yet (a brand-new member → caller provisions).
+     * Throws only on a genuine unwrap failure (wrong secret / tampered blob).
+     */
+    rehydrate(memberId: string, seedSecret: string): Promise<boolean>;
+    /**
+     * Ensure a stable keypair is in hand: rehydrate from the vault if a blob
+     * exists, otherwise mint one and persist it (so it's stable next session).
+     * Used at register and lazily when a space is first opened.
+     */
+    ensure(memberId: string, seedSecret: string): Promise<void>;
+}
+
 /**
  * `client.space` — the fan-out group-encryption surface.
  *
@@ -4195,6 +4332,18 @@ interface SpaceNamespaceDeps {
     cache?: SpaceKeyCache;
     /** Offline manager — enables message caching + offline send replay. */
     offline?: OfflineManager;
+    /** SDK-owned ratchet-keypair vault — gives a STABLE member keypair across
+     *  reloads (rehydrate-or-provision) instead of a fresh one each session. */
+    chatKeys?: ChatKeyVault;
+    /** P2P swarm config — enables peer block exchange among Space members. */
+    p2p?: {
+        enabled?: boolean;
+        /** `() => new Worker(new URL(...))` to run the block engine off-thread. */
+        workerFactory?: () => Worker;
+        iceServers?: RTCIceServer[];
+        maxPeers?: number;
+        debug?: boolean;
+    };
 }
 declare class SpaceNamespace {
     private readonly deps;
@@ -4661,6 +4810,20 @@ interface ClientOptions {
         /** Soft cap on durable-queue bytes before degrading to online-only. */
         maxQueueBytes?: number;
     };
+    /**
+     * Peer-to-peer block exchange (`client.space` files) among Space members,
+     * over WebRTC signaled on the Space relay. Best-effort — falls back to
+     * origin. **Opt-in** (browser only). Pass `workerFactory` to run the block
+     * engine off the main thread.
+     */
+    p2p?: {
+        enabled?: boolean;
+        workerFactory?: () => Worker;
+        iceServers?: RTCIceServer[];
+        maxPeers?: number;
+        /** Log P2P mesh + block-exchange activity to the console (staging/dev). */
+        debug?: boolean;
+    };
 }
 declare class Client {
     readonly baseUrl: string;
@@ -5158,6 +5321,386 @@ declare function writeBeatsTombstone(writeHlc: string, tombstoneHlc: string | nu
  */
 declare function deleteBeatsWrite(deleteHlc: string, writeHlc: string | null): boolean;
 
+/**
+ * `PeerExchange` — the thin façade the storage layer consults to try fetching a
+ * block from peers before falling back to origin. It satisfies the structural
+ * `PeerBlockSource` interface that {@link ../storage/transport/ShardClient}
+ * declares (so storage never imports the p2p module — the dependency arrow stays
+ * one-way, p2p → storage).
+ *
+ * It delegates to an {@link EngineHandle} — either an in-process {@link
+ * ./worker/blockEngine.BlockEngine} or the Web Worker proxy — so the same façade
+ * works whether the block engine runs on the main thread or off it.
+ */
+
+/** The subset of a block engine (in-process or worker-proxied) PeerExchange drives. */
+interface EngineHandle {
+    want(hash: string, timeoutMs: number): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+}
+interface PeerExchangeOptions {
+    /** How long to wait for a peer before giving up to origin. Default 2500ms. */
+    timeoutMs?: number;
+    /** Log peer-served vs origin-fallback per block to the console. */
+    debug?: boolean;
+}
+declare class PeerExchange implements PeerBlockSource {
+    private readonly engine;
+    private readonly timeoutMs;
+    private readonly debug;
+    constructor(engine: EngineHandle, opts?: PeerExchangeOptions);
+    getBlock(hash: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+}
+
+/**
+ * `SpaceSignaler` — WebRTC signaling carried over the Space's existing ephemeral
+ * relay. No new server channel: `Space.sendEphemeral`/`onEphemeral` already
+ * blind-relay `pub` frames stamped with the authenticated sender, so SDP
+ * offers/answers and ICE candidates ride a reserved subject (`__p2p__`) scoped
+ * to Space membership. The sender (`from`) is server-stamped and can't be
+ * spoofed; the payload is opaque to the server.
+ *
+ * Envelopes carry a `to` (a member id, or `"*"` for discovery) so the
+ * accelerator can optionally unicast peer-pair signaling instead of broadcasting
+ * (a small, backward-compatible `pub` enhancement); the client filters by `to`
+ * regardless.
+ */
+declare const P2P_SUBJECT = "__p2p__";
+type SignalKind = "hello" | "bye" | "offer" | "answer" | "ice";
+interface SignalEnvelope {
+    /** Target member id, or `"*"` to broadcast (discovery / departure). */
+    to: string;
+    kind: SignalKind;
+    data?: unknown;
+}
+/** The slice of {@link ../../spaces/Space.Space} the signaler needs. */
+interface SignalingSpace {
+    sendEphemeral(subject: string, data: unknown, to?: string): void;
+    onEphemeral(handler: (e: {
+        from: string;
+        subject: string;
+        data: unknown;
+    }) => void): () => void;
+}
+declare class SpaceSignaler {
+    private readonly space;
+    private readonly myId;
+    constructor(space: SignalingSpace, myId: string);
+    /** Send a signal to one peer (or `"*"`). */
+    send(to: string, kind: SignalKind, data?: unknown): void;
+    /** Announce/withdraw P2P availability to all Space members. */
+    broadcast(kind: SignalKind, data?: unknown): void;
+    /**
+     * Subscribe to inbound signals addressed to us (or broadcast). Skips our own
+     * echoes. Returns an unsubscribe function.
+     */
+    onSignal(cb: (from: string, kind: SignalKind, data: unknown) => void): () => void;
+}
+
+/**
+ * `PeerTransport` — the pluggable wire under the block engine. It moves opaque
+ * frames between Space peers; it knows nothing about blocks, hashes, or the
+ * protocol. {@link ./WebRtcTransport} implements it over RTCDataChannels today;
+ * a future libp2p/Helia transport can implement the same interface without the
+ * block engine or `ShardClient` changing.
+ *
+ * Implementations are responsible for fragmenting/ reassembling frames larger
+ * than the underlying channel's max message size (a 4 MiB shard won't fit in one
+ * `RTCDataChannel.send`); the engine always deals in whole frames.
+ */
+type PeerId = string;
+interface PeerTransport {
+    /** Currently connected peer ids. */
+    peers(): PeerId[];
+    /** Dial a discovered peer (optional — some transports connect implicitly). */
+    connectTo?(peer: PeerId): void;
+    /** Send a whole frame to one peer on `channel` (fragmented internally if needed). */
+    send(peer: PeerId, data: Uint8Array, channel?: number): void;
+    /** Send a whole frame to every connected peer on `channel`. */
+    broadcast(data: Uint8Array, channel?: number): void;
+    /** Subscribe to inbound (reassembled) frames. Returns an unsubscribe fn. */
+    onMessage(cb: (peer: PeerId, data: Uint8Array, channel: number) => void): () => void;
+    /** Subscribe to the connected-peer set changing. Returns an unsubscribe fn. */
+    onPeerChange(cb: (peers: PeerId[]) => void): () => void;
+    /** Tear down all connections. */
+    close(): void;
+}
+
+/**
+ * `BlockEngine` — the bitswap-lite want/have ledger. Host-agnostic: it speaks
+ * only to a {@link BlockStore} (get/put/has) and an `out` sink that ships
+ * encoded frames to a peer (or `"*"` to broadcast). The host wires `out` and
+ * `handleFrame` to a real transport — on the main thread or inside the Web
+ * Worker (see {@link ./engineClient}) — so this class is pure and unit-testable.
+ *
+ * It never sees keys: blocks are AES-GCM ciphertext, addressed by SHA-256. The
+ * one trust check is integrity — an inbound BLOCK is re-hashed and dropped on
+ * mismatch, so a malicious peer can't poison the store (the requester just
+ * falls back to origin).
+ */
+interface BlockStore {
+    get(hash: string): Promise<Uint8Array | null>;
+    put(hash: string, bytes: Uint8Array): Promise<void>;
+    has(hash: string): Promise<boolean>;
+}
+/** Ship an encoded frame to one peer, or `"*"` for every connected peer. */
+type OutSink = (target: string | "*", frame: Uint8Array) => void;
+/** Lowercase hex SHA-256 of `bytes` — injected so tests can stub it. */
+type Hasher = (bytes: Uint8Array) => Promise<string>;
+declare class BlockEngine {
+    private readonly store;
+    private readonly out;
+    private readonly hash;
+    private readonly wants;
+    constructor(store: BlockStore, out: OutSink, hash: Hasher);
+    /**
+     * Ask the swarm for a block. Resolves with the verified bytes, or `null` on
+     * timeout (caller then falls back to origin). Returns immediately if we
+     * already hold it; concurrent wants for the same hash share one request.
+     */
+    want(hash: string, timeoutMs: number): Promise<Uint8Array | null>;
+    /** Tell the swarm we now hold `hash` (so peers wanting it can pull from us). */
+    announce(hash: string): void;
+    /** Handle one inbound frame from `peer`. */
+    handleFrame(peer: string, frame: Uint8Array): Promise<void>;
+    /** Drop all pending waits (resolve null) — on teardown. */
+    close(): void;
+}
+
+/**
+ * `PeerNetwork` — the per-Space orchestrator that ties the pieces together on
+ * the main thread:
+ *
+ *   transport (WebRTC)  ⇄  engine host (Worker or in-process)  →  PeerExchange
+ *        ▲                                                            │
+ *        └────────────── signaling over the Space relay ─────────────┘
+ *
+ * It owns one {@link ./transport/WebRtcTransport} + one {@link
+ * ./worker/engineHost.EngineHost}, wires inbound frames to the engine and the
+ * engine's outbound frames back to the transport, runs peer discovery over the
+ * Space's ephemeral channel, and exposes a {@link ./PeerExchange.PeerExchange}
+ * for `ShardClient` to consult. Scope is one Space (private swarm).
+ *
+ * `engineHost` defaults to in-process; pass `workerFactory` to run the block
+ * engine off the main thread (the consumer's bundler resolves the worker URL).
+ */
+
+interface PeerNetworkOptions {
+    /** The Space (used for signaling over its ephemeral relay). */
+    space: SignalingSpace;
+    /** Our authenticated member id (the Space's `myId`). */
+    myId: string;
+    /** Blockstore for the in-process engine. Defaults to a `ShardCache`. */
+    store?: BlockStore;
+    /** Run the block engine in a Worker — `() => new Worker(new URL(...))`. */
+    workerFactory?: () => Worker;
+    iceServers?: RTCIceServer[];
+    maxPeers?: number;
+    /** Peer fetch timeout passed to PeerExchange. */
+    timeoutMs?: number;
+    /** Inject a transport (tests / a future libp2p transport). Default WebRTC. */
+    transport?: PeerTransport;
+    /** Log mesh + block-exchange activity to the console (use on staging/dev). */
+    debug?: boolean;
+}
+declare class PeerNetwork {
+    /** Pass this to a `ShardClient` as `peers`. */
+    readonly exchange: PeerExchange;
+    private readonly transport;
+    private readonly host;
+    private readonly signaler;
+    private readonly offs;
+    private readonly gossipCbs;
+    private closed;
+    constructor(opts: PeerNetworkOptions);
+    /**
+     * Begin peer discovery — broadcast a hello so existing members dial us and
+     * we learn them. Call once the signaling channel is live (the Space fires
+     * this on CONNECTED); safe to call again on reconnect.
+     */
+    start(): void;
+    /**
+     * Broadcast an app payload to all connected peers over the gossip channel —
+     * a direct, server-bypassing data path for CRDT ops / high-frequency state
+     * (cursors, presence, collaborative edits). Single-hop (no re-forwarding).
+     */
+    gossip(data: Uint8Array): void;
+    /** Subscribe to gossip from peers. Returns an unsubscribe function. */
+    onGossip(cb: (from: string, data: Uint8Array) => void): () => void;
+    /** Connected peer count (open data channels). */
+    peerCount(): number;
+    close(): void;
+}
+
+/**
+ * Whether this environment can do WebRTC peering. `RTCPeerConnection` is
+ * Window-only (absent in Node/Workers/SSR), so this gates whether a
+ * {@link ./PeerNetwork} can be built at all.
+ */
+declare function isP2pCapable(): boolean;
+
+/**
+ * `WebRtcTransport` — a {@link ./PeerTransport.PeerTransport} over RTCDataChannels,
+ * signaled by {@link ../signaling/SpaceSignaler}. Runs on the **main thread**
+ * (`RTCPeerConnection` is Window-only — not available in Workers), so the block
+ * engine lives in a Worker and this only shuttles bytes.
+ *
+ * Connection setup uses a deterministic initiator (the peer with the smaller id
+ * dials) to avoid offer/answer glare. STUN handles NAT traversal; there is no
+ * TURN — an unreachable peer simply never connects and the caller falls back to
+ * origin (P2P is best-effort).
+ *
+ * Frames (up to a 4 MiB shard) exceed an RTCDataChannel's max message size, so
+ * each frame is fragmented into `CHUNK`-sized pieces with a 12-byte header
+ * `[msgId u32][index u32][total u32]` and reassembled per peer.
+ */
+
+interface WebRtcTransportOptions {
+    iceServers?: RTCIceServer[];
+    /** Cap on simultaneous peer connections (mesh size). Default 8. */
+    maxPeers?: number;
+}
+declare class WebRtcTransport implements PeerTransport {
+    private readonly signaler;
+    private readonly myId;
+    private readonly conns;
+    private readonly msgCbs;
+    private readonly peerCbs;
+    private readonly offSignal;
+    private readonly iceServers;
+    private readonly maxPeers;
+    private nextMsgId;
+    constructor(signaler: SpaceSignaler, myId: PeerId, opts?: WebRtcTransportOptions);
+    peers(): PeerId[];
+    /** Dial a peer (no-op unless we're the deterministic initiator for the pair). */
+    connectTo(peerId: PeerId): void;
+    send(peer: PeerId, data: Uint8Array, channel?: number): void;
+    broadcast(data: Uint8Array, channel?: number): void;
+    onMessage(cb: (peer: PeerId, data: Uint8Array, channel: number) => void): () => void;
+    onPeerChange(cb: (peers: PeerId[]) => void): () => void;
+    close(): void;
+    private newPc;
+    private initiate;
+    private bindChannel;
+    private onSignal;
+    private drop;
+    private firePeerChange;
+    private sendFragmented;
+    private drain;
+    private onChunk;
+}
+
+/**
+ * `EngineHost` — the boundary {@link ../PeerNetwork} wires a transport to. It
+ * abstracts *where* the {@link ./blockEngine.BlockEngine} runs:
+ *   - {@link LocalEngineHost} runs it on the calling thread (tests, or a
+ *     fallback when the Web Worker can't be built by a consumer's bundler);
+ *   - the Worker proxy ({@link ./engineClient}) runs it off-thread.
+ *
+ * Either way the host exposes the same surface: drive `want`/`announce`, feed it
+ * inbound frames via `handleFrame`, and receive its outbound frames via
+ * `onOutbound` (which the network forwards to the transport).
+ */
+
+interface EngineHost {
+    want(hash: string, timeoutMs: number): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+    /** Feed an inbound frame received from `peer` on the transport. */
+    handleFrame(peer: string, frame: Uint8Array): void;
+    /** Receive frames the engine wants to send (`"*"` = broadcast). */
+    onOutbound(cb: (target: string, frame: Uint8Array) => void): () => void;
+    close(): void;
+}
+/** Runs the engine in-process (main thread or test). */
+declare class LocalEngineHost implements EngineHost {
+    private readonly engine;
+    private readonly cbs;
+    constructor(store: BlockStore, hasher: Hasher);
+    want(hash: string, timeoutMs: number): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+    handleFrame(peer: string, frame: Uint8Array): void;
+    onOutbound(cb: (target: string, frame: Uint8Array) => void): () => void;
+    close(): void;
+}
+
+/**
+ * `WorkerEngineHost` — the main-thread proxy to a {@link ./blockEngine.BlockEngine}
+ * running inside a dedicated Web Worker (so hashing, blockstore I/O, and the
+ * protocol codec stay off the main thread). It speaks the small message protocol
+ * in {@link ./blockEngine.worker} and satisfies {@link ./engineHost.EngineHost},
+ * so {@link ../PeerNetwork} treats it identically to the in-process host.
+ *
+ * Block bytes cross the worker boundary as **transferable** ArrayBuffers
+ * (zero-copy). Only encrypted blocks ever cross — keys never enter the worker.
+ */
+
+declare class WorkerEngineHost implements EngineHost {
+    private readonly worker;
+    private readonly wants;
+    private readonly cbs;
+    private nextId;
+    constructor(worker: Worker);
+    want(hash: string, timeoutMs: number): Promise<Uint8Array | null>;
+    announce(hash: string): void;
+    handleFrame(peer: string, frame: Uint8Array): void;
+    onOutbound(cb: (target: string, frame: Uint8Array) => void): () => void;
+    close(): void;
+}
+
+/**
+ * Bitswap-lite wire protocol for peer block exchange. Four frame types over a
+ * {@link ../transport/PeerTransport} data channel:
+ *
+ *   WANT(hash)         — "does anyone have this block?" / "send it to me"
+ *   HAVE(hash)         — "I hold this block" (announce / reply to a WANT)
+ *   BLOCK(hash, bytes) — the block itself (verified by hash on receipt)
+ *   CANCEL(hash)       — "stop, I got it elsewhere"
+ *
+ * Frames are compact binary so a 4 MiB shard isn't base64-bloated through JSON:
+ *
+ *   byte 0      : type (0 WANT | 1 HAVE | 2 BLOCK | 3 CANCEL)
+ *   bytes 1..33 : 32-byte raw SHA-256 of the block (our shard hash, hex-decoded)
+ *   bytes 33..  : payload (BLOCK only)
+ *
+ * Blocks are AES-GCM ciphertext, so a frame carries nothing readable; the hash
+ * is the capability check (the receiver re-hashes the payload and drops a
+ * mismatch). See {@link ./blockEngine}.
+ */
+declare enum FrameType {
+    WANT = 0,
+    HAVE = 1,
+    BLOCK = 2,
+    CANCEL = 3
+}
+interface DecodedFrame {
+    type: FrameType;
+    /** Lowercase hex SHA-256 (matches `shardHash`). */
+    hash: string;
+    /** Present only for {@link FrameType.BLOCK}. */
+    payload?: Uint8Array;
+}
+declare function encodeWant(hash: string): Uint8Array;
+declare function encodeHave(hash: string): Uint8Array;
+declare function encodeCancel(hash: string): Uint8Array;
+declare function encodeBlock(hash: string, payload: Uint8Array): Uint8Array;
+declare function decode(frame: Uint8Array): DecodedFrame;
+
+type protocol_DecodedFrame = DecodedFrame;
+type protocol_FrameType = FrameType;
+declare const protocol_FrameType: typeof FrameType;
+declare const protocol_decode: typeof decode;
+declare const protocol_encodeBlock: typeof encodeBlock;
+declare const protocol_encodeCancel: typeof encodeCancel;
+declare const protocol_encodeHave: typeof encodeHave;
+declare const protocol_encodeWant: typeof encodeWant;
+declare namespace protocol {
+  export { protocol_FrameType as FrameType, protocol_decode as decode, protocol_encodeBlock as encodeBlock, protocol_encodeCancel as encodeCancel, protocol_encodeHave as encodeHave, protocol_encodeWant as encodeWant };
+  export type { protocol_DecodedFrame as DecodedFrame };
+}
+
 /**
  * KeyringClient — HTTP implementation of {@link KeyringTransport} against the
  * accelerator's per-space keyring endpoints. All blobs are opaque to the
@@ -5218,5 +5761,5 @@ declare class KeyringClient implements KeyringTransport {
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
-export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, CachedSpaceMessage, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, ConnectivityOptions, ConnectivityState, DbQueryPage, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionInvokeOptions, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, HlcParts, HlcState, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvEntry, KvNamespaceDeps, LoginOptions, LwwMap, LwwRegister, MessageBody, MessageDeletedEvent, MessageEntry, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOp, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, OfflineEntry, OfflineManagerDeps, OfflineStore, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, Pkce, PublicKeyJWK, QueueEntry, RatchetState, ReceiveResult, RegisterParams, Replayer, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHandoff, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardByteCache, ShardClientOptions, SharedSpaceClientOptions, SnapshotNamespaceDeps, SnarkProof, SpaceChannelLike, SpaceCursor, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, SpaceOfflineAdapter, StorageChangeEvent, StoreName, StoredSession, Subscription, UserIdentity, VaultFactor, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AttachedPeerNetwork, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, BlockStore, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, CachedSpaceMessage, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, ConnectivityOptions, ConnectivityState, DbQueryPage, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EngineHandle, EngineHost, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionInvokeOptions, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, Hasher, HlcParts, HlcState, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvEntry, KvNamespaceDeps, LoginOptions, LwwMap, LwwRegister, MessageBody, MessageDeletedEvent, MessageEntry, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOp, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, OfflineEntry, OfflineManagerDeps, OfflineStore, OutSink, PacketCipher, PacketHeaders, PacketOptions, Participant, PeerBlockSource, PeerExchangeOptions, PeerId, PeerNetworkOptions, PeerTransport, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, Pkce, PublicKeyJWK, QueueEntry, RatchetState, ReceiveResult, RegisterParams, Replayer, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHandoff, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardByteCache, ShardClientOptions, SharedSpaceClientOptions, SignalEnvelope, SignalKind, SignalingSpace, SnapshotNamespaceDeps, SnarkProof, SpaceChannelLike, SpaceCursor, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, SpaceOfflineAdapter, StorageChangeEvent, StoreName, StoredSession, Subscription, UserIdentity, VaultFactor, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WebRtcTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };