@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/hub/sender-scoped-hub-view.js

@@ -0,0 +1,59 @@
+/**
+ * A view over one device's hub whose drain carries one peer's frames only.
+ *
+ * A device dialing two peers at once receives both answers on the same topic —
+ * its own dialer topic for the (group, epoch) — so an unfiltered drain hands
+ * each session the other's frames. Opening one consumes an MLS ratchet
+ * generation and DESTROYS it for the session it belonged to, which starves that
+ * session to its idle timeout with nothing raised anywhere.
+ *
+ * The filtering is asked of the hub rather than done here: a sink parks a
+ * single waiter, so a view that filtered by calling
+ * `next()` on the consumer's behalf would take that slot and starve the session
+ * it was meant to protect — measurably, even when it drops nothing at all. That
+ * is why this is not {@link createPeerScopedHubView}, which a RESPONDER uses:
+ * a responder's drain is long-lived and shared across its spawns, and it owns
+ * the topic subscription for its whole life. A caller's is neither, so
+ * `subscribe` and `unsubscribe` pass straight through to the session's own
+ * lifecycle.
+ */ export function createSenderScopedHubView({ hub, peerDID, publishTimeoutMs }) {
+    const publish = async (params)=>{
+        const sent = hub.publish(params);
+        if (publishTimeoutMs == null) {
+            return await sent;
+        }
+        let timer;
+        try {
+            return await Promise.race([
+                sent,
+                new Promise((_resolve, reject)=>{
+                    timer = setTimeout(()=>{
+                        reject(new Error(`hub tunnel publish to ${peerDID} did not reach a hub within ${publishTimeoutMs}ms`));
+                    }, publishTimeoutMs);
+                })
+            ]);
+        } finally{
+            if (timer != null) {
+                clearTimeout(timer);
+            }
+        }
+    };
+    const view = {
+        publish,
+        subscribe: (subscriberDID, topicID, options)=>hub.subscribe(subscriberDID, topicID, options),
+        unsubscribe: (subscriberDID, topicID)=>hub.unsubscribe?.(subscriberDID, topicID),
+        // Returned as the hub built it: the consumer must hold the sink's waiter
+        // itself. The caller's own scope is forwarded rather than replaced — the
+        // transport asks for its `receiveTopicID`, and a session that is handed the
+        // frames of the OTHER role on the same peer destroys them just as surely as
+        // one handed another peer's.
+        receive: (subscriberDID, options)=>hub.receive(subscriberDID, {
+                ...options,
+                senderDID: peerDID
+            }),
+        ...hub.events != null ? {
+            events: hub.events
+        } : {}
+    };
+    return view;
+}

package/lib/hub/server-did.d.ts

@@ -0,0 +1,67 @@
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { P2PEventEmitter } from '../groups/events.js';
+/**
+ * What a hub advertises at `GET /info`: the DID every token addressed to it must
+ * name, and where its protocols are mounted. Same shape a device serves for its
+ * own peer surface, so one reader handles both.
+ */
+export type HubInfo = {
+    did: string;
+    protocols: Record<string, string>;
+};
+export type FetchHubInfoParams = {
+    hubURL: string;
+    fetch: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /** Caller's own signal, e.g. a connection being disposed mid-discovery. */
+    signal?: AbortSignal;
+};
+/**
+ * Read a hub's `/info`. Resolved against the origin, so it works whether the
+ * configured URL is the origin or the relay mount path under it. Throws on an
+ * unreachable hub, a non-2xx reply, or a body that is not the advertised shape.
+ */
+export declare function fetchHubInfo(params: FetchHubInfoParams): Promise<HubInfo>;
+export type HubServerDIDResolver = {
+    /**
+     * The DID to address this hub's tokens to. The recorded `server_did` when the
+     * row has one, otherwise discovered from `/info` and recorded. `undefined`
+     * when the hub cannot be discovered — the caller then dials without an
+     * audience and lets the hub refuse it. `signal` abandons an in-flight read.
+     */
+    resolve: (hubURL: string, signal?: AbortSignal) => Promise<string | undefined>;
+    /**
+     * Called after the hub refused a request with `EK02`, which conflates a stale
+     * audience with a refused caller. Re-reads `/info`: a DID that differs from
+     * the recorded one is adopted and reported, so the next dial addresses the
+     * hub's current identity; a DID that matches means the refusal was about who
+     * asked, and nothing is changed.
+     */
+    refresh: (hubURL: string) => Promise<void>;
+};
+export type CreateHubServerDIDResolverParams = {
+    stores: StoreProvider;
+    emitter: P2PEventEmitter;
+    fetch: typeof globalThis.fetch;
+    logger?: Logger;
+    /**
+     * Shortest gap between two `/info` reads for one hub URL. Bounds the discovery
+     * traffic of a device the hub keeps refusing: it retries the connection on its
+     * own backoff, but must not re-ask who the hub is on every attempt.
+     */
+    refreshIntervalMs?: number;
+    /** Per-request timeout for an `/info` read. */
+    infoTimeoutMs?: number;
+};
+/**
+ * Resolves the audience a device's hub tokens carry, treating the recorded
+ * `server_did` as a cache rather than a pin.
+ *
+ * A hub redeployed without a persisted key comes up under a new DID; that is a
+ * routine operation, not an attack, so a stale record is refreshed from `/info`
+ * and reported to the application instead of failing the connection. Replaces
+ * the earlier trust-on-first-use capture, which took the DID from a response
+ * signer and refused every later connection whose signer differed.
+ */
+export declare function createHubServerDIDResolver(params: CreateHubServerDIDResolverParams): HubServerDIDResolver;

package/lib/hub/server-did.js

@@ -0,0 +1,131 @@
+import { getP2PStore } from '@kubun/store-p2p';
+function isHubInfo(value) {
+    if (value == null || typeof value !== 'object') return false;
+    const candidate = value;
+    return typeof candidate.did === 'string' && candidate.did.length > 0 && typeof candidate.protocols === 'object';
+}
+/** Only an HTTP(S) hub has an `/info` to read; an in-process one is dialled directly. */ function isDiscoverable(hubURL) {
+    try {
+        const protocol = new URL(hubURL).protocol;
+        return protocol === 'http:' || protocol === 'https:';
+    } catch  {
+        return false;
+    }
+}
+const DEFAULT_INFO_TIMEOUT_MS = 5000;
+/**
+ * Read a hub's `/info`. Resolved against the origin, so it works whether the
+ * configured URL is the origin or the relay mount path under it. Throws on an
+ * unreachable hub, a non-2xx reply, or a body that is not the advertised shape.
+ */ export async function fetchHubInfo(params) {
+    const infoURL = new URL('/info', params.hubURL).toString();
+    const timeout = AbortSignal.timeout(params.timeoutMs ?? DEFAULT_INFO_TIMEOUT_MS);
+    const response = await params.fetch(infoURL, {
+        signal: params.signal == null ? timeout : AbortSignal.any([
+            timeout,
+            params.signal
+        ])
+    });
+    if (!response.ok) {
+        throw new Error(`hub /info at ${infoURL} responded with status ${response.status}`);
+    }
+    const body = await response.json();
+    if (!isHubInfo(body)) {
+        throw new Error(`hub /info at ${infoURL} returned an unexpected shape`);
+    }
+    return body;
+}
+const DEFAULT_REFRESH_INTERVAL_MS = 60_000;
+/**
+ * Resolves the audience a device's hub tokens carry, treating the recorded
+ * `server_did` as a cache rather than a pin.
+ *
+ * A hub redeployed without a persisted key comes up under a new DID; that is a
+ * routine operation, not an attack, so a stale record is refreshed from `/info`
+ * and reported to the application instead of failing the connection. Replaces
+ * the earlier trust-on-first-use capture, which took the DID from a response
+ * signer and refused every later connection whose signer differed.
+ */ export function createHubServerDIDResolver(params) {
+    const refreshIntervalMs = params.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS;
+    // hub URL → when `/info` was last read for it.
+    const lastReadAt = new Map();
+    const readInfo = async (hubURL, signal)=>{
+        lastReadAt.set(hubURL, Date.now());
+        try {
+            return await fetchHubInfo({
+                hubURL,
+                fetch: params.fetch,
+                ...params.infoTimeoutMs == null ? {} : {
+                    timeoutMs: params.infoTimeoutMs
+                },
+                ...signal == null ? {} : {
+                    signal
+                }
+            });
+        } catch (error) {
+            params.logger?.warn('hub /info read failed', {
+                hubURL,
+                error
+            });
+            return undefined;
+        }
+    };
+    return {
+        resolve: async (hubURL, signal)=>{
+            const store = await getP2PStore(params.stores);
+            const row = await store.getHubByURL(hubURL);
+            if (row?.server_did != null) {
+                return row.server_did;
+            }
+            if (!isDiscoverable(hubURL)) {
+                return undefined;
+            }
+            const info = await readInfo(hubURL, signal);
+            if (info == null) {
+                return undefined;
+            }
+            if (row != null) {
+                await store.updateHub(row.id, {
+                    server_did: info.did
+                });
+            }
+            return info.did;
+        },
+        refresh: async (hubURL)=>{
+            if (!isDiscoverable(hubURL)) {
+                return;
+            }
+            const lastRead = lastReadAt.get(hubURL);
+            if (lastRead != null && Date.now() - lastRead < refreshIntervalMs) {
+                return;
+            }
+            const store = await getP2PStore(params.stores);
+            const row = await store.getHubByURL(hubURL);
+            const recorded = row?.server_did ?? null;
+            const info = await readInfo(hubURL);
+            if (info == null || info.did === recorded) {
+                return;
+            }
+            if (row != null) {
+                await store.updateHub(row.id, {
+                    server_did: info.did
+                });
+            }
+            if (recorded == null) {
+                // Nothing was recorded, so nothing changed from the application's view:
+                // this is the first identity it learns for the hub.
+                return;
+            }
+            await params.emitter.emit('hubServerDIDChanged', {
+                hubURL,
+                previousServerDID: recorded,
+                serverDID: info.did
+            }).catch((error)=>{
+                params.logger?.error('hubServerDIDChanged emit failed', {
+                    hubURL,
+                    error
+                });
+            });
+        }
+    };
+}

package/lib/hub/wiring.d.ts

@@ -1,19 +1,21 @@
-import type { OwnIdentity } from '@enkaku/token';
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { OwnIdentity } from '@kokuin/token';
 import type { KubunDB } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { LaneResult, PendingCommit } from '@kumiai/rpc';
+import type { Runtime } from '@sozai/runtime';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
-import { type BroadcastEvent } from '../groups/broadcast-service.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
-import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { BuildLedgerRedrive } from '../groups/group-peer-manager.js';
+import type { PeerPresence } from '../groups/peer-presence.js';
+import type { SyncProtocol } from '../protocol.js';
 import type { ForwardingConfig } from '../sync/forwarder.js';
-import type { RejoinResult, StoreUnreadableMode } from '../types.js';
-import type { OnServerDIDObserved } from './connection-pool.js';
-import type { GroupChannel, GroupChannelParams } from './group-channel.js';
-import type { HubConnection, HubConnectionParams } from './hub-connection.js';
-import { type CreateHubClient } from './relay-manager.js';
+import type { SyncTransportProvider } from '../sync/sync-client.js';
+import type { LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult, StoreUnreadableMode } from '../types.js';
+import type { CreateHubClient } from './http-client.js';
 export type HubWiring = {
     ready: Promise<void>;
     scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void;
@@ -25,79 +27,103 @@ export type HubWiring = {
      */
     broadcastNow: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
     /**
-     * Fire-and-forget fan-out of a pre-produced MLS handshake Commit to a
-     * group's existing members. Wired to `HubRelayManager.sendCommit`.
+     * Drive a commit through the group's canonical commit hub and await its
+     * outcome. Wired to
+     * `GroupPeerManager.commit`. The lane builds against the live handle,
+     * publishes to the commit log, and adopts the advance only on acceptance. A
+     * group with no hub bound commits against its in-process loopback log, so this
+     * rejects only when the group has no lane at all.
      */
-    scheduleSendCommit: (groupID: string, commitBytes: Uint8Array) => void;
+    commitToGroup: (groupID: string, build: () => Promise<PendingCommit>) => Promise<LaneResult>;
     /**
      * Run stale-device MLS epoch recovery for an active group. Wired to
-     * `HubRelayManager.rejoinGroup`; a no-op `recovery-failed` under
-     * `DISABLED_HUB` (no relay, nothing to rejoin).
+     * `GroupPeerManager.rejoinGroup`, which recovers through the rendezvous when a
+     * live member answers — reporting `recovered` on success, or `recovery-failed`
+     * (without throwing) when no responder is reachable.
      */
     rejoinGroup: (groupID: string) => Promise<RejoinResult>;
+    /**
+     * Gather the group's control ledger from its current members and fold missing
+     * entries locally. Wired to `GroupPeerManager.requestLedgerCatchup`; a no-op
+     * all-zero summary for a group with no live hub peer to gather from.
+     */
+    requestLedgerCatchup: (groupID: string, options?: LedgerCatchupOptions) => Promise<LedgerCatchupSummary>;
+    /**
+     * This device's peer-lane presence, resolved through the same late-bound
+     * `ready` every other lane operation waits on. The manager owns it because the
+     * internal triggers fire from there.
+     */
+    presence: () => Promise<PeerPresence>;
+    /** See {@link GroupPeerManager.retryHubs}. */
+    retryHubs: () => Promise<boolean>;
+    /**
+     * Build the transport for one directed sync session to a co-member, relayed by
+     * the group's hub. `undefined` when the group has no hub bound — there is no
+     * tunnel to offer, and the caller falls back to a registered URL.
+     *
+     * A route and nothing more: it grants the peer no access, and the session it
+     * carries is authorized per document at the far end exactly as an HTTP one is.
+     */
+    syncTransportTo: (groupID: string, peerDID: string) => Promise<SyncTransportProvider | undefined>;
     dispose: () => Promise<void>;
 };
 export type SetupHubRelayParams = {
     identity: OwnIdentity;
-    /** Fresh correlation ids for the rejoin flow. */
-    getRandomID: () => string;
+    /** Host runtime, forwarded to each peer for fresh group-rpc correlation ids. */
+    runtime: Runtime;
     db: KubunDB;
     /**
-     * Engine graph internals — threaded through to `BroadcastService` so the
-     * `mutation:apply` broadcast variant can route peer-authored mutations
-     * through the engine with `origin: 'peer'`.
+     * Engine graph internals — threaded through to the per-group peer apply path
+     * so a `sync/mutationApply` frame routes peer-authored mutations through the
+     * engine with `origin: 'peer'`.
      */
     graph: GraphInternals;
     emitter: P2PEventEmitter;
     createHubClient: CreateHubClient;
-    onRemoteBroadcast: (event: BroadcastEvent) => void;
-    /**
-     * Single canonical access point for MLS `GroupHandle` instances. Threaded
-     * into `BroadcastService` so encrypt/decrypt go through the per-group
-     * mutex once Phase 3 lands. Currently stored but unused.
-     */
+    /** Single canonical access point for MLS `GroupHandle` instances. */
     registry: GroupHandleRegistry;
-    /** Shared health monitor; receive outcomes drive epoch-stale detection. */
-    monitor?: GroupHealthMonitor;
-    logger: Logger;
     /**
-     * Optional testing seam forwarded to `HubRelayManager`. Production code
-     * leaves this unset so the manager uses its default `GroupChannel`
-     * constructor.
+     * Rebuilds a lost `ledger` commit's surviving tokens into a fresh commit for
+     * the seam to re-drive once. Sourced from the group manager's ledger write
+     * path — see {@link BuildLedgerRedrive}.
      */
-    createGroupChannel?: (params: GroupChannelParams) => GroupChannel;
-    /**
-     * Optional testing seam forwarded to `HubRelayManager`. Production code
-     * leaves this unset so the manager uses its default `HubConnection`
-     * constructor.
-     */
-    createHubConnection?: (params: HubConnectionParams) => HubConnection;
+    buildLedgerRedrive: BuildLedgerRedrive;
+    logger: Logger;
     /**
-     * Receive-side storage mode. Forwarded to `BroadcastService` →
-     * `processBroadcast`. Defaults to `'persist'` when omitted.
+     * Receive-side storage mode. Forwarded to the apply path. Defaults to
+     * `'persist'` when omitted.
      */
     storeUnreadable?: StoreUnreadableMode;
     /** Server default access level — required when `storeUnreadable === 'drop'`. */
     defaultAccessLevel?: DefaultAccessLevel;
     /**
-     * Forwarding config. Threaded through to `BroadcastService` →
-     * `processBroadcast` along with the hub's own `scheduleBroadcast` hook.
-     * Default `false` disables the receive-time forwarding pipeline.
+     * Per-peer N+1 re-broadcast config, forwarded to the apply path together with
+     * the `scheduleBroadcast` hook it needs — the receive path gates on both, so
+     * one without the other is a silent no-op. Omitted or `false` disables it.
      */
     forwarding?: ForwardingConfig;
     /**
-     * Forwarded to `HubRelayManager` → `HubConnectionPool`. Fired with the
-     * observed `serverDID` after the first signed response from a freshly-spawned
-     * client. Lets callers route capture into `captureServerDID` for TOFU
-     * pinning; omitting it skips capture entirely.
-     */
-    onServerDIDObserved?: OnServerDIDObserved;
-    /**
-     * Device-wide monotonic clock forwarded to `BroadcastService` for stamping
+     * Device-wide monotonic clock forwarded to the apply path for stamping
      * `removed_at_hlc` on roster reconciliation. Required: production passes the
      * engine's single instance so roster writes share the device's one clock.
      */
     hlc: HLC;
+    /**
+     * Reconnect-backoff overrides forwarded to every hub adapter. Test-only; when
+     * omitted the adapter runs on its production defaults.
+     */
+    hubReconnectBackoff?: {
+        baseMs?: number;
+        maxMs?: number;
+        jitter?: number;
+    };
+    /** @see DEFAULT_TUNNEL_IDLE_TIMEOUT_MS */
+    tunnelIdleTimeoutMs?: number;
+    /**
+     * Sync procedures served over an inbound hub tunnel. The same handlers the
+     * direct and HTTP transports serve; omitted, this device dials tunnels but
+     * answers none.
+     */
+    syncHandlers?: ProcedureHandlers<SyncProtocol>;
 };
 export declare function setupHubRelay(params: SetupHubRelayParams): HubWiring;
-export declare const DISABLED_HUB: HubWiring;

package/lib/hub/wiring.js

@@ -1 +1,189 @@
-import{BroadcastService as e}from"../groups/broadcast-service.js";import{HubRelayManager as r}from"./relay-manager.js";export function setupHubRelay(a){let o,{identity:t,getRandomID:d,db:i,graph:s,emitter:n,createHubClient:c,onRemoteBroadcast:u,registry:p,monitor:l,logger:h,createGroupChannel:m,createHubConnection:g,storeUnreadable:f,defaultAccessLevel:y,forwarding:w,onServerDIDObserved:b,hlc:v}=a,D=[],B=(e,r)=>{o.then(a=>a.broadcast(e,r).catch(r=>{h.error("broadcast failed",{groupID:e,error:r})}),()=>{})},G=async(e,r)=>{let a=await o;await a.broadcast(e,r)},I=async e=>{let r=await o;return await r.rejoinGroup(e)};return(o=(async()=>{let[a,o]=await Promise.all([i.getStore("p2p"),i.getStore("graph")]),G=new e({p2pStore:a,graphStore:o,graph:s,selfDID:t.id,registry:p,hlc:v,storeUnreadable:f,defaultAccessLevel:y,forwarding:w,scheduleBroadcast:B,emitter:n,logger:h}),I=new r({p2pStore:a,broadcastService:G,deviceID:t.id,createHubClient:c,monitor:l,identity:t,getRandomID:d,logger:h,createGroupChannel:m,createHubConnection:g,onServerDIDObserved:b});D.push(G.on("broadcast",u)),D.push(n.on("groupJoined",e=>I.addGroup(e.id).catch(r=>{h.error("addGroup failed",{groupID:e.id,error:r})}))),D.push(n.on("groupLeft",e=>I.removeGroup(e.groupID).catch(r=>{h.error("removeGroup failed",{groupID:e.groupID,error:r})}))),D.push(n.on("hubBound",({groupID:e,hubURL:r})=>I.addBinding(e,r).catch(a=>{h.error("addBinding failed",{groupID:e,hubURL:r,error:a})}))),D.push(n.on("hubUnbound",({groupID:e,hubURL:r})=>I.removeBinding(e,r).catch(a=>{h.error("removeBinding failed",{groupID:e,hubURL:r,error:a})})));let S=await a.listGroups();return await I.start(S.map(e=>e.id)),I})()).catch(e=>{h.error("hub relay setup failed",{error:e})}),{ready:o.then(()=>void 0),scheduleBroadcast:B,broadcastNow:G,scheduleSendCommit:(e,r)=>{o.then(a=>a.sendCommit(e,r).catch(r=>{h.error("sendCommit failed",{groupID:e,error:r})}),()=>{})},rejoinGroup:I,dispose:async()=>{for(let e of D)try{e()}catch{}D.length=0;try{let e=await o;await e.stop()}catch{}}}}export const DISABLED_HUB={ready:Promise.resolve(),scheduleBroadcast:()=>{},broadcastNow:async()=>{},scheduleSendCommit:()=>{},rejoinGroup:async()=>({status:"recovery-failed"}),dispose:async()=>{}};
+import { createGroupPeerManager } from '../groups/group-peer-manager.js';
+import { HubTunnelSyncProvider } from '../sync/hub-tunnel-sync-provider.js';
+/**
+ * How long a directed tunnel session waits with nothing arriving before it
+ * gives up. Idle, not total: any frame resets it, so a long sync that is
+ * progressing never trips it and only a peer that never answers does.
+ *
+ * The cost this buys is paid by automatic catch-up, which tries the next
+ * candidate after each one — so a group whose devices are all off spends this
+ * once per candidate before reporting `no-route`.
+ */ const DEFAULT_TUNNEL_IDLE_TIMEOUT_MS = 30_000;
+export function setupHubRelay(params) {
+    const { identity, runtime, db, graph, emitter, createHubClient, registry, buildLedgerRedrive, logger, storeUnreadable, defaultAccessLevel, forwarding, hlc, hubReconnectBackoff, tunnelIdleTimeoutMs } = params;
+    const unsubscribes = [];
+    // Late-bound `ready` resolving to the live manager. The fire-and-forget
+    // schedulers chain off it so a caller can enqueue work before boot completes;
+    // the awaitable variants simply await it.
+    let ready;
+    const scheduleBroadcast = (groupID, message)=>{
+        void ready.then((manager)=>manager.broadcast(groupID, message).catch((error)=>{
+                logger.error('broadcast failed', {
+                    groupID,
+                    error
+                });
+            }), ()=>{
+        // ready rejected; setup failure already logged below
+        });
+    };
+    const broadcastNow = async (groupID, message)=>{
+        const manager = await ready;
+        await manager.broadcast(groupID, message);
+    };
+    const commitToGroup = async (groupID, build)=>{
+        const manager = await ready;
+        return await manager.commit(groupID, build);
+    };
+    const rejoinGroup = async (groupID)=>{
+        const manager = await ready;
+        return await manager.rejoinGroup(groupID);
+    };
+    const requestLedgerCatchup = async (groupID, options)=>{
+        const manager = await ready;
+        return await manager.requestLedgerCatchup(groupID, options);
+    };
+    const presence = async ()=>(await ready).presence;
+    const retryHubs = async ()=>await (await ready).retryHubs();
+    const syncTransportTo = async (groupID, peerDID)=>{
+        const hub = (await ready).tunnelHub(groupID);
+        if (hub == null) {
+            return undefined;
+        }
+        return new HubTunnelSyncProvider({
+            hub,
+            registry,
+            groupID,
+            localDID: identity.id,
+            peerDID,
+            runtime,
+            // A tunnel session against a device that is off publishes its first frame
+            // and then waits on a mailbox nobody is draining. Unbounded, that is a
+            // catch-up that never returns and a peer screen that never settles — so
+            // the deadline is the transport's, not the caller's, and it is what makes
+            // "unreachable" an outcome instead of a hang.
+            idleTimeoutMs: tunnelIdleTimeoutMs ?? DEFAULT_TUNNEL_IDLE_TIMEOUT_MS,
+            // Without this the session's frame drops reach a listener nobody set, and
+            // a dial that is handed nothing reports only the dependency's bare
+            // `TimeoutInterruption` half a minute later.
+            logger: logger.getChild('tunnel-session')
+        });
+    };
+    ready = (async ()=>{
+        const [p2pStore, graphStore] = await Promise.all([
+            db.getStore('p2p'),
+            db.getStore('graph')
+        ]);
+        const manager = createGroupPeerManager({
+            createHubClient,
+            registry,
+            buildLedgerRedrive,
+            stores: db,
+            graphStore,
+            graph,
+            hlc,
+            localDID: identity.id,
+            identity,
+            emitter,
+            runtime,
+            logger,
+            storeUnreadable,
+            defaultAccessLevel,
+            forwarding,
+            // The manager's own fan-out, reached through the same late-bound `ready`
+            // every other scheduler chains off — a forward is one more broadcast, so
+            // it takes the path a locally-authored one already takes.
+            scheduleBroadcast,
+            ...hubReconnectBackoff != null ? {
+                hubReconnectBackoff
+            } : {},
+            // The answering half of the tunnel. Without handlers the manager stands up
+            // no listeners, and a dialled route reaches a mailbox nobody drains.
+            ...params.syncHandlers != null ? {
+                syncHandlers: params.syncHandlers
+            } : {},
+            tunnelIdleTimeoutMs: tunnelIdleTimeoutMs ?? DEFAULT_TUNNEL_IDLE_TIMEOUT_MS
+        });
+        unsubscribes.push(emitter.on('groupJoined', (group)=>manager.addGroup(group.id).catch((error)=>{
+                logger.error('addGroup failed', {
+                    groupID: group.id,
+                    error
+                });
+            })));
+        // The roster IS the listener set, so the projection that records it is the
+        // honest trigger. The epoch-change trigger stays for the topics it moves;
+        // it fires too early to be relied on for membership.
+        for (const event of [
+            'groupMemberJoined',
+            'groupMemberLeft'
+        ]){
+            unsubscribes.push(emitter.on(event, ({ groupID })=>manager.reconcileTunnelListeners(groupID).catch((error)=>{
+                    logger.error('tunnel listener reconcile failed', {
+                        groupID,
+                        error
+                    });
+                })));
+        }
+        unsubscribes.push(emitter.on('groupLeft', (group)=>manager.removeGroup(group.groupID).catch((error)=>{
+                logger.error('removeGroup failed', {
+                    groupID: group.groupID,
+                    error
+                });
+            })));
+        unsubscribes.push(emitter.on('hubBound', ({ groupID, hubURL })=>manager.addBinding(groupID, hubURL).catch((error)=>{
+                logger.error('addBinding failed', {
+                    groupID,
+                    hubURL,
+                    error
+                });
+            })));
+        unsubscribes.push(emitter.on('hubUnbound', ({ groupID, hubURL })=>manager.removeBinding(groupID, hubURL).catch((error)=>{
+                logger.error('removeBinding failed', {
+                    groupID,
+                    hubURL,
+                    error
+                });
+            })));
+        const groups = await p2pStore.listGroups();
+        await manager.start(groups.map((g)=>g.id));
+        return manager;
+    })();
+    // Prevent an unhandled rejection if nobody awaits `ready` directly.
+    ready.catch((error)=>{
+        logger.error('hub relay setup failed', {
+            error
+        });
+    });
+    return {
+        // Handle rejection here too: the base `.catch` covers the root `ready`, not
+        // this derived chain, and callers of `.ready` don't always await it.
+        ready: ready.then(()=>undefined, (error)=>{
+            logger.error('hub relay setup failed', {
+                error
+            });
+        }),
+        scheduleBroadcast,
+        broadcastNow,
+        commitToGroup,
+        rejoinGroup,
+        requestLedgerCatchup,
+        presence,
+        retryHubs,
+        syncTransportTo,
+        dispose: async ()=>{
+            for (const off of unsubscribes){
+                try {
+                    off();
+                } catch  {
+                // ignore
+                }
+            }
+            unsubscribes.length = 0;
+            try {
+                const manager = await ready;
+                await manager.stop();
+            } catch  {
+            // setup failed; nothing to stop
+            }
+        }
+    };
+}