@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/group-mls.js

@@ -0,0 +1,164 @@
+import { HLC } from '@kubun/hlc';
+import { getKubunLogger } from '@kubun/logger';
+import { getP2PStore } from '@kubun/store-p2p';
+import { exportGroupInfo as exportEnkakuGroupInfo, readMessageEpoch } from '@kumiai/mls';
+import { fromB64 } from '@sozai/codec';
+import { anchorImmutabilityPolicy, readGroupAnchor } from './group-anchor.js';
+import { CommitOutOfOrderError, DecryptError } from './mls-receive-errors.js';
+/**
+ * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
+ * {@link GroupMLS} lifecycle port: apply received Commits to advance the epoch,
+ * export GroupInfo for a recovery responder, and expose the epoch-independent
+ * recovery seed. group-rpc owns the transport + orchestration (subscribe the
+ * non-rotating handshake topic, run these methods, resync the app lane when the
+ * epoch advances); this adapter owns the MLS state, storage, and atomicity.
+ */ export function createGroupMLS(params) {
+    const { registry, stores, hlc, groupID } = params;
+    const logger = params.logger ?? getKubunLogger('plugin-p2p:group-mls');
+    return {
+        /**
+     * Apply a received MLS handshake Commit: advance the local ratchet and write
+     * the membership delta derived by diffing the roster before and after.
+     *
+     * Runs INSIDE a single store transaction so the ratchet advance (persisted
+     * by the registry) and the resulting roster delta writes commit or roll back
+     * together. A roster-write failure after the ratchet persisted would
+     * otherwise leave a removed member's writes still applying. The registry
+     * holds the per-group lock across the whole transaction, so no concurrent
+     * same-group op can interleave.
+     *
+     * Epoch handling (advisory pre-check on the cleartext header):
+     * - `messageEpoch < handle.epoch` → already applied; no-op (`advanced:false`).
+     * - `messageEpoch > handle.epoch` → gap in the stream; throw
+     *   {@link CommitOutOfOrderError} so the hub redelivers after the gap fills.
+     * - otherwise process; `processMessage` is the authoritative crypto check.
+     */ async processCommit (commit, context) {
+            // The transport sender is auxiliary (logging), NOT the MLS committer and
+            // never an authorization boundary — the Commit authenticates its committer
+            // internally.
+            logger.debug('processCommit', {
+                groupID,
+                senderDID: context.senderDID
+            });
+            return await registry.withHandleReplacingInTransaction(groupID, stores, async (handle, tx)=>{
+                // The Commit's cleartext wire-header epoch is the sender's pre-commit
+                // epoch — the epoch a receiver must be at to process it.
+                const messageEpoch = readMessageEpoch(commit);
+                const handleEpoch = handle.epoch;
+                if (messageEpoch != null && messageEpoch < handleEpoch) {
+                    return {
+                        result: {
+                            advanced: false
+                        },
+                        updated: handle
+                    };
+                }
+                if (messageEpoch != null && messageEpoch > handleEpoch) {
+                    throw new CommitOutOfOrderError(messageEpoch, handleEpoch);
+                }
+                const before = handle.listMembers();
+                try {
+                    await handle.processMessage(commit, {
+                        commitPolicy: anchorImmutabilityPolicy
+                    });
+                } catch (error) {
+                    // A Commit that fails the authenticated MLS check at the matching
+                    // epoch is corrupt/forged — unrecoverable, so ack-and-skip rather
+                    // than redeliver. (Future-epoch ordering is handled above via
+                    // CommitOutOfOrderError, which DOES redeliver.)
+                    throw new DecryptError('Failed to process MLS commit', error);
+                }
+                const after = handle.listMembers();
+                const beforeIDs = new Set(before.map((member)=>member.id));
+                const afterIDs = new Set(after.map((member)=>member.id));
+                const removed = before.filter((member)=>!afterIDs.has(member.id)).map((member)=>member.id);
+                const added = after.filter((member)=>!beforeIDs.has(member.id)).map((member)=>member.id);
+                // All reads + writes use the transactional p2p store so they share the
+                // tx's single connection (a bare store read inside the tx would
+                // deadlock single-connection SQLite against the tx's write lock).
+                const localHLC = HLC.serialize(hlc.now());
+                const p2pStore = await getP2PStore(tx);
+                for (const memberDID of removed){
+                    await p2pStore.markMemberRemoved(groupID, memberDID, localHLC);
+                }
+                for (const memberDID of added){
+                    // Role defaults to 'member': the MLS ratchet (listMembers) carries no
+                    // kubun role, so a receiver can't recover the committer's
+                    // admin/member distinction from the Commit. The write-membership gate
+                    // keys only on `removed_at_hlc`, never role, so this divergence is not
+                    // a security issue; a role-bearing path corrects it later.
+                    await p2pStore.addGroupMember({
+                        group_id: groupID,
+                        member_did: memberDID,
+                        role: 'member',
+                        hlc: localHLC
+                    });
+                }
+                return {
+                    result: {
+                        advanced: handle.epoch > handleEpoch
+                    },
+                    updated: handle
+                };
+            }).catch((error)=>{
+                // A corrupt/forged Commit threw inside the transaction, so it rolled back
+                // (DB untouched). Ack-and-skip it: report no epoch advance so group-rpc
+                // acks and the hub stops redelivering — group-rpc re-fetches any Commit
+                // whose `processCommit` throws, so letting a corrupt frame escape here
+                // would poison-redeliver forever. CommitOutOfOrderError (future-epoch gap)
+                // and transient store faults are re-thrown so they DO redeliver and retry.
+                if (error instanceof DecryptError) {
+                    logger.warn('dropping corrupt MLS commit (ack-and-skip)', {
+                        groupID,
+                        error
+                    });
+                    return {
+                        advanced: false
+                    };
+                }
+                throw error;
+            });
+        },
+        /**
+     * Export a fresh `MLSMessage(GroupInfo)` from the current handle for a
+     * recovery responder to send a stranded peer. Read-only: takes the registry
+     * lock but does not advance or persist state.
+     */ async exportGroupInfo () {
+            return await registry.readHandle(groupID, async (handle)=>{
+                const { groupInfo } = await exportEnkakuGroupInfo({
+                    group: handle
+                });
+                return groupInfo;
+            });
+        },
+        /**
+     * Re-sync from a recovery reply (a peer stranded past the handshake
+     * backlog).
+     *
+     * DESIGN GAP — intentionally unimplemented. The only MLS path that catches a
+     * stranded member up from GroupInfo is `joinGroupExternal({ resync: true })`,
+     * which produces an external-commit `commitMessage` that EVERY other member
+     * MUST process to admit the rejoiner's replaced leaf and advance to the new
+     * epoch. The {@link GroupMLS.applyRecovery} contract returns only
+     * `{ advanced }` and group-rpc's `recover()` never fans out anything on the
+     * handshake topic — so this adapter has no channel to deliver that Commit.
+     * Applying it locally and dropping the Commit would fork the group (this peer
+     * ahead on an epoch nobody else has). Failing loudly here is strictly safer
+     * than a silent fork until the transport/orchestration question is resolved.
+     */ async applyRecovery (_groupInfo) {
+            throw new Error('GroupMLS.applyRecovery is not wired: an MLS resync produces an external Commit that ' + 'other members must process, but the recovery port has no channel to fan it out. ' + 'Resolve the recovery transport design before enabling deep recovery.');
+        },
+        /**
+     * The epoch-independent secret for the non-rotating handshake/recovery topic,
+     * sourced from the genesis anchor (immutable, authenticated by the GroupInfo
+     * signature → every member on every epoch reads the same value). Throws when
+     * the anchor is absent: a group with no anchor cannot participate in recovery.
+     */ async exportRecoverySecret () {
+            const anchor = await registry.readHandle(groupID, (handle)=>readGroupAnchor(handle));
+            if (anchor == null) {
+                throw new Error(`group ${groupID} has no genesis anchor; cannot derive recovery secret`);
+            }
+            return fromB64(anchor.recoverySecret);
+        }
+    };
+}

package/lib/groups/group-peer-manager.d.ts

@@ -0,0 +1,108 @@
+import type { StoreProvider } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import type { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { GraphStoreAPI } from '@kubun/store-graph';
+import type { HubLike } from '@kumiai/hub-tunnel';
+import { type GroupPeer } from '@kumiai/rpc';
+import type { OnServerDIDObserved } from '../hub/did-observing-transport.js';
+import type { CreateHubClient } from '../hub/http-client.js';
+import type { RejoinResult, StoreUnreadableMode } from '../types.js';
+import type { GroupBroadcastMessage } from './broadcast.js';
+import type { P2PEventEmitter } from './events.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+import { type GroupProtocols } from './group-protocols.js';
+export type GroupPeerManagerParams = {
+    /**
+     * Spawns a fresh `Client<HubProtocol>` for a hub URL. The manager wraps each
+     * URL's client in one reconnecting {@link createHubLike} (a single device
+     * receive drain), lazily on first peer creation for that hub.
+     */
+    createHubClient: CreateHubClient;
+    /** Single canonical access point for the device's MLS `GroupHandle` instances. */
+    registry: GroupHandleRegistry;
+    /**
+     * Store coordinator. Resolves the device's p2p store for the apply path,
+     * group↔hub binding reads, and server-DID pinning; also passed to
+     * `createGroupMLS` for the receive-side commit transaction.
+     */
+    stores: StoreProvider;
+    graphStore: GraphStoreAPI;
+    /**
+     * Engine graph internals — threaded into the apply path so a `sync/mutationApply`
+     * frame routes peer-authored mutations through `applyVerifiedMutation` with
+     * `origin: 'peer'`.
+     */
+    graph: GraphInternals;
+    /** Device-wide monotonic clock shared with the engine and MLS receive path. */
+    hlc: HLC;
+    /** Authenticated DID of this device (normalized). */
+    localDID: string;
+    emitter: P2PEventEmitter;
+    /** Fresh correlation ids for group-rpc; forwarded to each peer when set. */
+    getRandomID?: () => string;
+    logger?: Logger;
+    /** Receive-side storage mode. Forwarded to the apply path. Defaults to `'persist'`. */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
+    /**
+     * Fired once per freshly-spawned hub client when its first signed response
+     * arrives, with the hub URL bound. Lets callers route capture into
+     * `captureServerDID` for TOFU pinning; omitting it skips capture.
+     */
+    onServerDIDObserved?: OnServerDIDObserved;
+};
+/**
+ * Coordinates the per-(group, hub) `GroupPeer`s for one device — full multi-hub.
+ *
+ * The manager owns one reconnecting `HubLike` per hub URL (created lazily on
+ * first use, shared across every group bound to that hub via the multi-subscriber
+ * adapter) and one `GroupPeer` per (group, hub) pair. A peer exists iff the group
+ * is joined AND bound to that hub. Lifecycle mirrors the old `HubRelayManager`,
+ * but per (group, hub) instead of single-hub: the wiring phase drives `addGroup`
+ * / `removeGroup` / `addBinding` / `removeBinding` from the emitter and holds the
+ * unsubscribes. The manager does not subscribe to the emitter itself.
+ */
+export type GroupPeerManager = {
+    /** Bring up peers for each already-bound hub of each joined group. */
+    start: (groupIDs: Array<string>) => Promise<void>;
+    /** Mark a group joined and create a peer for each of its hub bindings. */
+    addGroup: (groupID: string) => Promise<void>;
+    /** Unmark a group and dispose all its peers (GC-ing now-idle hubs). */
+    removeGroup: (groupID: string) => Promise<void>;
+    /** Create the (group, hub) peer if the group is joined and none exists yet. */
+    addBinding: (groupID: string, hubURL: string) => Promise<void>;
+    /** Dispose the (group, hub) peer if present, GC-ing the hub if now idle. */
+    removeBinding: (groupID: string, hubURL: string) => Promise<void>;
+    /** Fan a broadcast message out across every hub-peer of a group. */
+    broadcast: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /** Fan a locally-produced MLS Commit out across every hub-peer of a group. */
+    sendCommit: (groupID: string, commit: Uint8Array) => Promise<void>;
+    /** Deep recovery is deferred — always reports `recovery-failed` without throwing. */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
+    /** The peer for one (group, hub), or `undefined` (used by tests). */
+    peer: (groupID: string, hubURL: string) => GroupPeer<GroupProtocols> | undefined;
+    /**
+     * The shared reconnecting `HubLike` for a hub URL, creating it on first use.
+     * Lets a caller obtain the device-wide drain to pass into a directed sync
+     * transport (provider/listener) sharing the same hub connection.
+     */
+    getHubLike: (hubURL: string) => HubLike & {
+        dispose: () => Promise<void>;
+    };
+    /** Dispose every peer and hub, then clear all maps. */
+    stop: () => Promise<void>;
+    /** Alias for {@link stop}. */
+    dispose: () => Promise<void>;
+};
+/**
+ * Send-side union → procedure mapping — the inverse of `buildGroupHandlers`.
+ *
+ * Translates a {@link GroupBroadcastMessage} into the matching group-rpc
+ * `dispatch` on a peer's control/sync protocol surface. Variants with no carried
+ * procedure (catalog control) and the legacy catch-up variants (now a `gather`,
+ * not a dispatch) are logged and no-op'd, matching the receive side.
+ */
+export declare function dispatchMessage(peer: GroupPeer<GroupProtocols>, message: GroupBroadcastMessage, logger?: Logger): Promise<void>;
+export declare function createGroupPeerManager(params: GroupPeerManagerParams): GroupPeerManager;

package/lib/groups/group-peer-manager.js

@@ -0,0 +1,344 @@
+import { getDelegationStore } from '@kubun/store-delegation';
+import { getP2PStore } from '@kubun/store-p2p';
+import { createGroupPeer } from '@kumiai/rpc';
+import { createHubLike } from '../hub/hub-like.js';
+import { readGroupAnchor } from './group-anchor.js';
+import { createGroupCrypto } from './group-crypto.js';
+import { buildGroupHandlers } from './group-handlers.js';
+import { createGroupMLS } from './group-mls.js';
+import { groupProtocols } from './group-protocols.js';
+const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
+/**
+ * Send-side union → procedure mapping — the inverse of `buildGroupHandlers`.
+ *
+ * Translates a {@link GroupBroadcastMessage} into the matching group-rpc
+ * `dispatch` on a peer's control/sync protocol surface. Variants with no carried
+ * procedure (catalog control) and the legacy catch-up variants (now a `gather`,
+ * not a dispatch) are logged and no-op'd, matching the receive side.
+ */ export async function dispatchMessage(peer, message, logger) {
+    switch(message.type){
+        case 'ledger:entry':
+            await peer.protocol('control').dispatch('control/ledgerEntry', {
+                token: message.token
+            });
+            return;
+        case 'delegation:share':
+            await peer.protocol('control').dispatch('control/delegationShare', {
+                token: message.token,
+                hlc: message.hlc
+            });
+            return;
+        case 'delegation:revoke':
+            await peer.protocol('control').dispatch('control/delegationRevoke', {
+                token: message.token,
+                hlc: message.hlc
+            });
+            return;
+        case 'group:leaveRequest':
+            await peer.protocol('control').dispatch('control/groupLeaveRequest', {
+                memberDID: message.memberDID,
+                hlc: message.hlc
+            });
+            return;
+        case 'mutation:apply':
+            await peer.protocol('sync').dispatch('sync/mutationApply', {
+                entries: message.entries
+            });
+            return;
+        case 'catalog:create':
+        case 'catalog:update':
+        case 'catalog:delete':
+            logger?.warn('dispatchMessage: no broadcast path for catalog control', {
+                type: message.type
+            });
+            return;
+        case 'ledger-catchup:request':
+        case 'ledger-catchup:reply':
+            logger?.warn('dispatchMessage: unsupported via broadcast (catch-up uses gather)', {
+                type: message.type
+            });
+            return;
+    }
+}
+export function createGroupPeerManager(params) {
+    // One reconnecting HubLike per hub URL (shared across that hub's groups).
+    const hubLikes = new Map();
+    // One peer per (group, hub), keyed `${groupID}|${hubURL}`.
+    const peers = new Map();
+    // Groups the device currently belongs to.
+    const joined = new Set();
+    // Active bindings: groupID → set of hub URLs that have a live peer.
+    const bindings = new Map();
+    // Reverse index for GC: hub URL → set of groupIDs with a peer on it.
+    const hubGroups = new Map();
+    const { logger } = params;
+    const getHubLike = (hubURL)=>{
+        const existing = hubLikes.get(hubURL);
+        if (existing != null) {
+            return existing;
+        }
+        const hub = createHubLike({
+            // Resolved per (re)connect: the pinned server DID is read fresh from the
+            // local hub row so a row update re-arms TOFU on the next reconnect.
+            createClient: async ()=>{
+                const store = await getP2PStore(params.stores);
+                const row = await store.getHubByURL(hubURL);
+                return params.createHubClient(hubURL, {
+                    ...params.onServerDIDObserved != null ? {
+                        onServerDID: (serverDID)=>params.onServerDIDObserved?.({
+                                hubURL,
+                                serverDID
+                            })
+                    } : {},
+                    ...row?.server_did != null ? {
+                        expectedServerDID: row.server_did
+                    } : {}
+                });
+            },
+            localDID: params.localDID,
+            ...logger != null ? {
+                logger
+            } : {}
+        });
+        hubLikes.set(hubURL, hub);
+        return hub;
+    };
+    const buildProcessParams = async ()=>{
+        const [p2pStore, delegationStore] = await Promise.all([
+            getP2PStore(params.stores),
+            getDelegationStore(params.stores)
+        ]);
+        return {
+            p2pStore,
+            delegationStore,
+            graphStore: params.graphStore,
+            graph: params.graph,
+            selfDID: params.localDID,
+            storeUnreadable: params.storeUnreadable,
+            defaultAccessLevel: params.defaultAccessLevel,
+            // Forwarding is dropped in this cutover — the receive path applies locally
+            // only and never re-broadcasts to other groups.
+            forwarding: undefined,
+            emitter: params.emitter,
+            hlc: params.hlc,
+            // Reads the genesis anchor baked into the MLS GroupContext so role
+            // projection on a received ledger entry runs against the authenticated
+            // epoch-0 creator. Null for a group with no anchor (e.g. external).
+            getGroupAnchor: (groupID)=>params.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle)),
+            logger
+        };
+    };
+    // Create a peer for one (group, hub) pair, idempotent on the key. The peer is
+    // eager (createGroupPeer restores the anchored MLS handle + opens the receive
+    // drain in its constructor), so it must only be called once the group's MLS
+    // state is seeded (i.e. after `groupJoined`).
+    const createPeer = async (groupID, hubURL)=>{
+        const key = peerKey(groupID, hubURL);
+        if (peers.has(key)) {
+            return;
+        }
+        const processParams = await buildProcessParams();
+        // Re-check after the await: a concurrent call may have installed this peer,
+        // or `removeGroup` may have left the group, while the store resolved. The
+        // emitter handlers (groupJoined/groupLeft/hubBound/hubUnbound) are not
+        // serialized, so installing a live peer for a no-longer-joined group here
+        // would leak a drain + apply mutations for a left group.
+        if (peers.has(key) || !joined.has(groupID)) {
+            return;
+        }
+        const peer = createGroupPeer({
+            hub: getHubLike(hubURL),
+            crypto: createGroupCrypto(params.registry, groupID),
+            mls: createGroupMLS({
+                registry: params.registry,
+                stores: params.stores,
+                hlc: params.hlc,
+                groupID,
+                ...logger != null ? {
+                    logger
+                } : {}
+            }),
+            localDID: params.localDID,
+            protocols: groupProtocols,
+            handlers: buildGroupHandlers(processParams, groupID),
+            ...params.getRandomID != null ? {
+                getRandomID: params.getRandomID
+            } : {}
+        });
+        peers.set(key, peer);
+        let groupSet = bindings.get(groupID);
+        if (groupSet == null) {
+            groupSet = new Set();
+            bindings.set(groupID, groupSet);
+        }
+        groupSet.add(hubURL);
+        let hubSet = hubGroups.get(hubURL);
+        if (hubSet == null) {
+            hubSet = new Set();
+            hubGroups.set(hubURL, hubSet);
+        }
+        hubSet.add(groupID);
+    };
+    // Dispose one (group, hub) peer, updating both indexes, and GC the hub's
+    // HubLike once its last peer is gone.
+    const disposePeer = async (groupID, hubURL)=>{
+        const key = peerKey(groupID, hubURL);
+        const peer = peers.get(key);
+        if (peer == null) {
+            return;
+        }
+        peers.delete(key);
+        const groupSet = bindings.get(groupID);
+        if (groupSet != null) {
+            groupSet.delete(hubURL);
+            if (groupSet.size === 0) {
+                bindings.delete(groupID);
+            }
+        }
+        const hubSet = hubGroups.get(hubURL);
+        if (hubSet != null) {
+            hubSet.delete(groupID);
+            if (hubSet.size === 0) {
+                hubGroups.delete(hubURL);
+            }
+        }
+        await peer.dispose();
+        // GC the HubLike when no peer references it anymore.
+        if (!hubGroups.has(hubURL)) {
+            const hub = hubLikes.get(hubURL);
+            if (hub != null) {
+                hubLikes.delete(hubURL);
+                await hub.dispose();
+            }
+        }
+    };
+    // Fan an operation across every live peer of a group. A single hub's failure
+    // is logged but does not sink the others; this rejects only when EVERY hub
+    // fails (and there was at least one peer), so an ordering-sensitive caller
+    // (`broadcastNow` before a local teardown) still observes a total failure
+    // while a partial multi-hub failure resolves and the message reaches the
+    // reachable hubs.
+    const fanOutToPeers = async (groupID, op, label)=>{
+        const groupSet = bindings.get(groupID);
+        if (groupSet == null || groupSet.size === 0) {
+            return;
+        }
+        const tasks = [];
+        for (const hubURL of groupSet){
+            const peer = peers.get(peerKey(groupID, hubURL));
+            if (peer != null) {
+                tasks.push(op(peer));
+            }
+        }
+        if (tasks.length === 0) {
+            return;
+        }
+        const results = await Promise.allSettled(tasks);
+        const rejected = results.filter((result)=>result.status === 'rejected');
+        for (const result of rejected){
+            logger?.warn(`${label} failed on a hub`, {
+                groupID,
+                error: result.reason
+            });
+        }
+        if (rejected.length === results.length) {
+            throw rejected[0]?.reason;
+        }
+    };
+    const addGroup = async (groupID)=>{
+        joined.add(groupID);
+        const store = await getP2PStore(params.stores);
+        const hubs = await store.listHubsByGroupID(groupID);
+        if (hubs.length === 0) {
+            logger?.warn('group has no hub bindings, no peer created', {
+                groupID
+            });
+            return;
+        }
+        const results = await Promise.allSettled(hubs.map((hub)=>createPeer(groupID, hub.url)));
+        results.forEach((result, index)=>{
+            if (result.status === 'rejected') {
+                logger?.error('createPeer failed', {
+                    groupID,
+                    hubURL: hubs[index]?.url,
+                    error: result.reason
+                });
+            }
+        });
+    };
+    return {
+        async start (groupIDs) {
+            const results = await Promise.allSettled(groupIDs.map((id)=>addGroup(id)));
+            results.forEach((result, index)=>{
+                if (result.status === 'rejected') {
+                    logger?.error('addGroup failed during start', {
+                        groupID: groupIDs[index],
+                        error: result.reason
+                    });
+                }
+            });
+        },
+        addGroup,
+        async removeGroup (groupID) {
+            joined.delete(groupID);
+            const groupSet = bindings.get(groupID);
+            const urls = groupSet != null ? [
+                ...groupSet
+            ] : [];
+            for (const hubURL of urls){
+                await disposePeer(groupID, hubURL);
+            }
+        },
+        async addBinding (groupID, hubURL) {
+            if (!joined.has(groupID)) {
+                logger?.debug('binding ignored: group not joined', {
+                    groupID,
+                    hubURL
+                });
+                return;
+            }
+            await createPeer(groupID, hubURL);
+        },
+        async removeBinding (groupID, hubURL) {
+            await disposePeer(groupID, hubURL);
+        },
+        async broadcast (groupID, message) {
+            await fanOutToPeers(groupID, (peer)=>dispatchMessage(peer, message, logger), 'broadcast');
+        },
+        async sendCommit (groupID, commit) {
+            await fanOutToPeers(groupID, (peer)=>peer.localCommitted(commit), 'sendCommit');
+        },
+        async rejoinGroup (_groupID) {
+            // INERT stub: deep recovery is deferred. `mls.applyRecovery` deliberately
+            // throws (a GroupInfo lacks the missed path secrets → applying it forks the
+            // group), and tier-1 replay via `processCommit` is automatic, so there is
+            // nothing to drive here. The real path is Welcome re-admission — see
+            // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+            return {
+                status: 'recovery-failed'
+            };
+        },
+        peer (groupID, hubURL) {
+            return peers.get(peerKey(groupID, hubURL));
+        },
+        getHubLike,
+        async stop () {
+            const livePeers = [
+                ...peers.values()
+            ];
+            peers.clear();
+            bindings.clear();
+            hubGroups.clear();
+            joined.clear();
+            const liveHubs = [
+                ...hubLikes.values()
+            ];
+            hubLikes.clear();
+            await Promise.all(livePeers.map((peer)=>peer.dispose()));
+            await Promise.all(liveHubs.map((hub)=>hub.dispose()));
+        },
+        async dispose () {
+            await this.stop();
+        }
+    };
+}