@kubun/plugin-p2p 0.11.0 → 0.12.1

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,13 +1,20 @@
+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 { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
-import type { RejoinResult, StoreUnreadableMode } from '../types.js';
-import type { OnServerDIDObserved } from './did-observing-transport.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 { 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>;
@@ -20,22 +27,50 @@ 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 `GroupPeerManager.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
-     * `GroupPeerManager.rejoinGroup`; deep recovery is deferred so this currently
-     * reports `recovery-failed`.
+     * `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 group-rpc. */
-    getRandomID: () => string;
+    /** Host runtime, forwarded to each peer for fresh group-rpc correlation ids. */
+    runtime: Runtime;
     db: KubunDB;
     /**
      * Engine graph internals — threaded through to the per-group peer apply path
@@ -47,6 +82,12 @@ export type SetupHubRelayParams = {
     createHubClient: CreateHubClient;
     /** Single canonical access point for MLS `GroupHandle` instances. */
     registry: GroupHandleRegistry;
+    /**
+     * 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}.
+     */
+    buildLedgerRedrive: BuildLedgerRedrive;
     logger: Logger;
     /**
      * Receive-side storage mode. Forwarded to the apply path. Defaults to
@@ -56,17 +97,33 @@ export type SetupHubRelayParams = {
     /** Server default access level — required when `storeUnreadable === 'drop'`. */
     defaultAccessLevel?: DefaultAccessLevel;
     /**
-     * Fired with the observed `serverDID` after the first signed response from a
-     * freshly-spawned client, hub URL bound. Lets callers route capture into
-     * `captureServerDID` for TOFU pinning; omitting it skips capture.
+     * 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.
      */
-    onServerDIDObserved?: OnServerDIDObserved;
+    forwarding?: ForwardingConfig;
     /**
      * 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,6 +1,16 @@
 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, getRandomID, db, graph, emitter, createHubClient, registry, logger, storeUnreadable, defaultAccessLevel, onServerDIDObserved, hlc } = 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;
@@ -20,20 +30,44 @@ export function setupHubRelay(params) {
         const manager = await ready;
         await manager.broadcast(groupID, message);
     };
-    const scheduleSendCommit = (groupID, commitBytes)=>{
-        void ready.then((manager)=>manager.sendCommit(groupID, commitBytes).catch((error)=>{
-                logger.error('sendCommit failed', {
-                    groupID,
-                    error
-                });
-            }), ()=>{
-        // ready rejected; setup failure already logged below
-        });
+    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'),
@@ -42,17 +76,32 @@ export function setupHubRelay(params) {
         const manager = createGroupPeerManager({
             createHubClient,
             registry,
+            buildLedgerRedrive,
             stores: db,
             graphStore,
             graph,
             hlc,
             localDID: identity.id,
+            identity,
             emitter,
-            getRandomID,
+            runtime,
             logger,
             storeUnreadable,
             defaultAccessLevel,
-            onServerDIDObserved
+            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', {
@@ -60,6 +109,20 @@ export function setupHubRelay(params) {
                     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,
@@ -100,8 +163,12 @@ export function setupHubRelay(params) {
         }),
         scheduleBroadcast,
         broadcastNow,
-        scheduleSendCommit,
+        commitToGroup,
         rejoinGroup,
+        requestLedgerCatchup,
+        presence,
+        retryHubs,
+        syncTransportTo,
         dispose: async ()=>{
             for (const off of unsubscribes){
                 try {
@@ -120,13 +187,3 @@ export function setupHubRelay(params) {
         }
     };
 }
-export const DISABLED_HUB = {
-    ready: Promise.resolve(),
-    scheduleBroadcast: ()=>{},
-    broadcastNow: async ()=>{},
-    scheduleSendCommit: ()=>{},
-    rejoinGroup: async ()=>({
-            status: 'recovery-failed'
-        }),
-    dispose: async ()=>{}
-};

package/lib/index.d.ts

@@ -4,22 +4,32 @@ import { type BroadcastBatchConfig } from './sync/broadcast-queue.js';
 import { type PushSyncConfig } from './sync/broadcast-sender.js';
 import type { ForwardingConfig } from './sync/forwarder.js';
 import type { StoreUnreadableMode } from './types.js';
-export type { ContextDeps, PendingJoinRequest } from './context/types.js';
-export { ADMIN_ROLE_ENTRY_TYPE, ADMIN_ROSTER_PROJECTION, type AdminRoleValue, type AdminRosterState, adminRosterReducer, applyAdminEntryIncremental, foldAdminRoster, type ProjectAdminRosterParams, projectAdminRoster, projectAdminRosterFromStore, reprojectAdminRoster, } from './groups/admin-roster.js';
+export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, type RequireGroupAdminParams, requireGroupAdmin, } from './context/require-admin.js';
+export type { ContextDeps } from './context/types.js';
+export { ADMIN_ROLE_ENTRY_TYPE, type AdminRoleValue, type AdminRosterState, foldAdminRoster, } from './groups/admin-roster.js';
 export { type AffectedRow, type GroupBroadcastMessage, type MutationApplyEntry, type ProcessBroadcastParams, type ProcessBroadcastResult, processBroadcast, } from './groups/broadcast.js';
 export { deserializeBroadcast, serializeBroadcast } from './groups/broadcast-codec.js';
 export { createFilteredGenerator, createP2PEventEmitter, type P2PEventEmitter, type P2PEventMap, } from './groups/events.js';
-export { type GroupAnchor, groupAnchorCapabilities, readGroupAnchor, } from './groups/group-anchor.js';
+export { buildKubunGroupAnchorExtension, type GroupAnchorApp, readRecoverySecret, } from './groups/group-anchor.js';
 export { GroupHandleRegistry, type GroupHandleRegistryParams, type SeedParams, } from './groups/group-handle-registry.js';
+export type { PeerAvailability } from './groups/group-protocols.js';
 export { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeFullJoinRequest, encodeInvitePayload, encodeJoinRequest, type FullJoinRequestPayload, type InvitePayload, type JoinRequestPayload, type SuggestedHub, } from './groups/invite-payload.js';
-export { type LedgerEntry, ledgerEntryDigest, signLedgerEntry, type VerifiedLedgerEntry, verifyLedgerEntry, } from './groups/ledger-entry.js';
-export { type FoldInput, foldLedger, type LedgerReducer, } from './groups/ledger-fold.js';
-export { type CreateGroupParams, type CreateGroupResult, GroupManager, type GroupManagerParams, type InviteToGroupParams, type InviteToGroupResult, type JoinGroupParams, type JoinGroupResult, type LeaveGroupParams, type LeaveGroupResult, type RemoveGroupMemberParams, type RemoveGroupMemberResult, type RemoveMemberParams, type RemoveMemberResult, } from './groups/manager.js';
+export { resolveJoinRequestDID } from './groups/join-request-identity.js';
+export { entryOrd, type FoldInput, foldLedgerEntries, type LedgerEntry, type LedgerReducer, ledgerEntryDigest, type PositionedFoldInput, signLedgerEntry, type VerifiedLedgerEntry, verifyLedgerEntry, } from './groups/ledger.js';
+export type { CreateGroupParams, CreateGroupResult, GroupManagerParams, InviteToGroupParams, InviteToGroupResult, JoinGroupParams, JoinGroupResult, LeaveGroupParams, LeaveGroupResult, } from './groups/manager.js';
 export { MLSEncryptor, type MLSEncryptorParams } from './groups/mls-encryptor.js';
 export { type MLSGroupHandle, restoreMLSGroupHandle } from './groups/mls-group-handle.js';
 export { replacer as mlsJSONReplacer, reviver as mlsJSONReviver } from './groups/mls-json.js';
 export { deserializeMLSGroupState, type MLSGroupState, type SerializedMLSGroupState, serializeMLSGroupState, } from './groups/mls-state.js';
-export type { SyncClientMessage, SyncProtocol, SyncServerMessage } from './protocol.js';
+export { MERKLE_SYNC_PROTOCOL } from './groups/peer-selection.js';
+export { type CreateHTTPHubClientParams, type CreateHubClient, type CreateHubClientOptions, createHTTPHubClient, } from './hub/http-client.js';
+export { type BindHubToGroupParams, bindHubToGroup, type CreateHubParams, createHub, type DeleteHubParams, type DeleteHubResult, deleteHub, type GetHubParams, getHub, type Hub, type ListGroupsByHubParams, type ListHubsByGroupParams, type ListHubsParams, listGroupsByHub, listHubs, listHubsByGroup, type UnbindHubFromGroupParams, type UpdateHubParams, type UpsertHubParams, unbindHubFromGroup, updateHub, upsertHub, } from './hub/manager.js';
+export { type CreateHubServerDIDResolverParams, createHubServerDIDResolver, type FetchHubInfoParams, fetchHubInfo, type HubInfo, type HubServerDIDResolver, } from './hub/server-did.js';
+export { type HubWiring, type SetupHubRelayParams, setupHubRelay, } from './hub/wiring.js';
+export { type PeerConnection, PeerConnectionRegistry, } from './peer/connection-registry.js';
+export { type CreatePeerHandlersParams, createPeerHandlers } from './peer/handlers.js';
+export type { PeerClientMessage, PeerGroupsResult, PeerProtocol, PeerServerMessage, SyncClientMessage, SyncProtocol, SyncServerMessage, } from './protocol.js';
+export { peerProtocol } from './protocol.js';
 export { createP2PSchemaExtension } from './schema.js';
 export { type BroadcastBatchConfig, type BroadcastQueue, type BroadcastQueueParams, createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG, } from './sync/broadcast-queue.js';
 export { type BroadcastSenderParams, DEFAULT_PUSH_SYNC_CONFIG, type PushSyncConfig, wireBroadcastSender, } from './sync/broadcast-sender.js';
@@ -30,13 +40,9 @@ export { checkSyncDelegation } from './sync/handlers.js';
 export { HubTunnelSyncListener, type HubTunnelSyncListenerParams, } from './sync/hub-tunnel-sync-listener.js';
 export { HubTunnelSyncProvider, type HubTunnelSyncProviderParams, } from './sync/hub-tunnel-sync-provider.js';
 export { negotiateDirection, type PeerConfig, type PeerConfigWithID, PeerRegistry, } from './sync/peer-registry.js';
-export { SyncClient, type SyncClientParams, type SyncScope, type SyncTransportProvider, } from './sync/sync-client.js';
+export { SyncClient, type SyncClientParams, type SyncRoute, type SyncScope, type SyncServerResolver, type SyncTransportProvider, } from './sync/sync-client.js';
 export { type SyncEvent, SyncManager, type SyncManagerParams, type SyncSessionInfo, type SyncStatus, } from './sync/sync-manager.js';
-export { DIDObservingTransport, type DIDObservingTransportParams, type OnServerDIDObserved, type ServerDIDObserver, } from './hub/did-observing-transport.js';
-export { type CreateHTTPHubClientParams, type CreateHubClient, type CreateHubClientOptions, createHTTPHubClient, } from './hub/http-client.js';
-export { type BindHubToGroupParams, bindHubToGroup, type CaptureServerDIDParams, type CreateHubParams, captureServerDID, createHub, type DeleteHubParams, type DeleteHubResult, deleteHub, type GetHubParams, getHub, type Hub, HubServerDIDConflictError, type ListGroupsByHubParams, type ListHubsByGroupParams, type ListHubsParams, listGroupsByHub, listHubs, listHubsByGroup, type UnbindHubFromGroupParams, type UpdateHubParams, type UpsertHubParams, unbindHubFromGroup, updateHub, upsertHub, } from './hub/manager.js';
-export { DISABLED_HUB, type HubWiring, type SetupHubRelayParams, setupHubRelay, } from './hub/wiring.js';
-export type { CatalogData, CircleData, CircleMemberData, DeleteCatalogData, DeleteCircleData, GroupData, GroupMemberData, GroupRequestContext, InviteToGroupData, JoinGroupData, LeaveGroupData, P2PContext, P2PJoinRequestContext, RemoveCircleMemberData, RemoveGroupMemberData, StoreUnreadableMode, SyncPluginAPI, SyncRequestContext, SyncSessionResult, UpdateCircleInput, UpdateGroupInput, } from './types.js';
+export type { AddCircleMemberInput, CatalogData, CircleData, CircleMemberData, CreateCircleInput, DeleteCatalogData, DeleteCircleInput, GatheredPeer, GroupData, GroupMemberData, GroupRequestContext, HubServerDIDChangedData, InviteToGroupData, InviteToGroupInput, JoinGroupData, LeaveGroupData, LocalPeerAnnouncement, P2PContext, P2PJoinRequestContext, PeerCatchUpData, PeerGatherOptions, PresenceReason, RemoveCircleMemberInput, RemoveGroupMemberInput, StoreUnreadableMode, SyncPluginAPI, SyncRequestContext, SyncSessionResult, UpdateCircleInput, UpdateGroupInput, } from './types.js';
 export type ReceiveConfig = {
     /**
      * Receiver storage mode for incoming peer mutations.
@@ -56,6 +62,15 @@ export type ReceiveConfig = {
 export declare const DEFAULT_RECEIVE_CONFIG: ReceiveConfig;
 export type P2PPluginOptions = {
     autoAcceptPeers?: Array<string>;
+    /**
+     * How long `requestInviteToGroup` waits for its own Add commit to settle
+     * before returning the truthful pending shape (`invitePayload: null`,
+     * `request.status: PENDING`) instead of blocking further — the parked case,
+     * inviter offline. Test-only escape hatch — production omits it and runs on
+     * the 30s default; lets a headless test drive the park-then-pending path
+     * without waiting out the full production timeout.
+     */
+    inviteCommitTimeoutMs?: number;
     /**
      * Expose the sync protocol over the HTTP plugin transport.
      * - `true` / `{}` — enable at the default protocol path `'sync'`. CORS
@@ -84,6 +99,17 @@ export type P2PPluginOptions = {
      */
     hub?: boolean | {
         createHubClient?: CreateHubClient;
+        /**
+         * Reconnect-backoff overrides for every hub adapter this device spawns.
+         * Test-only escape hatch — production omits it and runs on the adapter's
+         * defaults. Lets a headless multi-device test drive an offline/reconnect
+         * cycle without waiting out the ~1 s production base delay.
+         */
+        reconnectBackoff?: {
+            baseMs?: number;
+            maxMs?: number;
+            jitter?: number;
+        };
     };
     /**
      * Batch broadcast queue config. Sender-side mutation:apply broadcasts are
@@ -133,5 +159,14 @@ export type P2PPluginOptions = {
      * regardless of whether locally-authored mutations are broadcast.
      */
     forwarding?: ForwardingConfig;
+    /**
+     * How long a directed tunnel sync session waits with nothing arriving before
+     * giving up — how fast an unreachable peer is reported as one. Idle, not
+     * total: a session that keeps receiving frames never trips it.
+     *
+     * Test-only escape hatch; production omits it and runs on the 30s default,
+     * which a headless test would otherwise have to wait out per offline peer.
+     */
+    tunnelIdleTimeoutMs?: number;
 };
 export declare function createP2PPlugin(options?: P2PPluginOptions): (params: PluginFactoryParams) => KubunPlugin;