@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/sync/sync-manager.js

@@ -1 +1,301 @@
-import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as s}from"@kubun/store-graph";import{applySyncMutations as r}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#s;#r;#i;#n=new e;#o=new Map;#a=new Map;#l;#c;#g;#p;constructor(e){this.#e=e.deployClusters,this.#t=e.graph,this.#s=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#i=new n({runtime:e.runtime}),this.#c=e.serverResolver,this.#g=e.storeUnreadable??"persist",this.#p=e.defaultAccessLevel}get peerRegistry(){return this.#i}setIdentity(e){this.#l=e}setServerResolver(e){this.#c=e}async addPeer(e){await this.#i.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#i.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#i.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#i.listPeers(e)}async getPeer(e){return this.#i.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:a,scopes:l,delegationTokens:c=[],knownModelIDs:g,direction:p}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:a,scopes:l});let m=await this.#i.getPeer({peerDID:a,stores:e.stores});if(!m)throw Error(`Peer ${a} not found`);let d=`merkle-sync-${a}-${Date.now()}`,h={peerID:a,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#o.set(d,h),this.#m({type:"started",peerID:a,timestamp:Date.now()});try{let u=this.#l;if(!t(u))throw Error("Signing identity required for Merkle sync");let y=new o({runtime:this.#s,identity:u,logger:this.#r,serverResolver:this.#c});n=await y.connect(m.endpoint,a);let v=p??"pull";this.#r.info("Negotiating sync scopes",{scopes:l,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await y.negotiate(n,l,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#o.delete(d),{sessionID:d,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await s(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),b=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:b});let C=await y.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:b,localEntries:R,delegationTokens:c});return C.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:C.mutationJWTs.length}),h.documentsCompleted=(await r({db:e.stores,graph:this.#t,mutationJWTs:C.mutationJWTs,selfDID:this.#l.id,storeUnreadable:this.#g,defaultAccessLevel:this.#p})).applied),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:C.divergentBuckets,mutationsReceived:C.mutationJWTs.length}),{sessionID:d,divergentBuckets:C.divergentBuckets,messagesReceived:C.mutationJWTs.length,messagesSent:C.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:a,error:e}),this.#m({type:"error",peerID:a,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#o.delete(d)}}getStatus(e){let{peerDID:t}=e,s=Array.from(this.#o.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),r={};for(let[e,s]of this.#a.entries())t&&e!==t||(r[e]=s);return{activeSessions:s,lastSyncByPeer:r}}onSyncEvent(e){return this.#n.on("sync",e)}#m(e){this.#n.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#o.clear(),this.#a.clear()}}
+import { isSigningIdentity } from '@kokuin/token';
+import { getGraphStore } from '@kubun/store-graph';
+import { EventEmitter } from '@sozai/event';
+import { fromEmitter } from '@sozai/generator';
+import { applySyncMutations } from './merkle-apply.js';
+import { buildMerkleTree } from './merkle-tree.js';
+import { PeerRegistry } from './peer-registry.js';
+import { SyncClient } from './sync-client.js';
+export class SyncManager {
+    #deployClusters;
+    #graph;
+    #runtime;
+    #logger;
+    #peerRegistry;
+    #events = new EventEmitter();
+    #activeSessions = new Map();
+    #lastSyncByPeer = new Map();
+    #identity;
+    #serverResolver;
+    #storeUnreadable;
+    #defaultAccessLevel;
+    constructor(params){
+        this.#deployClusters = params.deployClusters;
+        this.#graph = params.graph;
+        this.#runtime = params.runtime;
+        this.#identity = params.identity;
+        this.#logger = params.logger;
+        this.#peerRegistry = new PeerRegistry({
+            runtime: params.runtime
+        });
+        this.#serverResolver = params.serverResolver;
+        this.#storeUnreadable = params.storeUnreadable ?? 'persist';
+        this.#defaultAccessLevel = params.defaultAccessLevel;
+    }
+    get peerRegistry() {
+        return this.#peerRegistry;
+    }
+    /**
+   * Configure the signing identity used for sync operations.
+   */ setIdentity(identity) {
+        this.#identity = identity;
+    }
+    /**
+   * Configure the resolver for the transports built locally rather than dialled:
+   * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose
+   * group id arrives as the resolver's `route`).
+   */ setServerResolver(resolver) {
+        this.#serverResolver = resolver;
+    }
+    // ---- Peer management (delegates to PeerRegistry) ----
+    async addPeer(params) {
+        await this.#peerRegistry.addPeer(params);
+        this.#logger.info('Peer added', {
+            peerDID: params.config.peerDID
+        });
+    }
+    async removePeer(params) {
+        await this.#peerRegistry.removePeer(params);
+        this.#logger.info('Peer removed', {
+            peerDID: params.peerDID
+        });
+    }
+    async updatePeerConfig(params) {
+        await this.#peerRegistry.updatePeer(params);
+        this.#logger.info('Peer updated', {
+            peerDID: params.peerDID
+        });
+    }
+    async listPeers(params) {
+        return this.#peerRegistry.listPeers(params);
+    }
+    async getPeer(params) {
+        return this.#peerRegistry.getPeer(params);
+    }
+    // ---- Sync orchestration ----
+    async merkleSyncWithPeer(params) {
+        const { peerDID, scopes, delegationTokens = [], knownModelIDs, direction: requestedDirection } = params;
+        this.#logger.info('Starting Merkle sync with peer', {
+            peerDID,
+            scopes
+        });
+        let endpoint = params.endpoint;
+        if (endpoint == null) {
+            const peer = await this.#peerRegistry.getPeer({
+                peerDID,
+                stores: params.stores
+            });
+            if (!peer) {
+                throw new Error(`Peer ${peerDID} not found`);
+            }
+            endpoint = peer.endpoint;
+        }
+        // Random, not a timestamp: two syncs to the same peer in the same
+        // millisecond collide, and the second overwrites the first's entry in
+        // `#activeSessions` — so one of them never clears.
+        const sessionID = `merkle-sync-${peerDID}-${this.#runtime.getRandomID()}`;
+        const sessionData = {
+            peerID: peerDID,
+            startTime: Date.now(),
+            documentsAttempted: 0,
+            documentsCompleted: 0
+        };
+        this.#activeSessions.set(sessionID, sessionData);
+        this.#emitEvent({
+            type: 'started',
+            peerID: peerDID,
+            timestamp: Date.now()
+        });
+        let client;
+        try {
+            const identity = this.#identity;
+            if (!isSigningIdentity(identity)) {
+                throw new Error('Signing identity required for Merkle sync');
+            }
+            const syncClient = new SyncClient({
+                runtime: this.#runtime,
+                identity,
+                logger: this.#logger,
+                serverResolver: this.#serverResolver
+            });
+            client = await syncClient.connect(endpoint, peerDID);
+            // Step 1: Negotiate scopes
+            const direction = requestedDirection ?? 'pull';
+            this.#logger.info('Negotiating sync scopes', {
+                scopes,
+                direction
+            });
+            const { acceptedScopes, excludedDocumentIDs, missingClusters, direction: agreedDirection } = await syncClient.negotiate(client, scopes, delegationTokens, knownModelIDs, direction);
+            if (acceptedScopes.length === 0) {
+                this.#logger.info('No scopes accepted by peer');
+                this.#lastSyncByPeer.set(peerDID, Date.now());
+                this.#emitEvent({
+                    type: 'completed',
+                    peerID: peerDID,
+                    timestamp: Date.now()
+                });
+                this.#activeSessions.delete(sessionID);
+                return {
+                    sessionID,
+                    divergentBuckets: 0,
+                    messagesReceived: 0,
+                    messagesSent: 0,
+                    missingClusters
+                };
+            }
+            // Step 1b: Deploy missing clusters before building merkle tree
+            if (missingClusters != null && Object.keys(missingClusters).length > 0) {
+                if (this.#deployClusters != null) {
+                    this.#logger.info('Deploying missing clusters from peer', {
+                        clusterCount: Object.keys(missingClusters).length
+                    });
+                    await this.#deployClusters(missingClusters);
+                } else {
+                    this.#logger.warn('Missing clusters received but no deployClusters callback configured', {
+                        clusterCount: Object.keys(missingClusters).length
+                    });
+                }
+            }
+            // Step 2: Build local Merkle tree for accepted scopes
+            this.#logger.info('Building local Merkle tree', {
+                acceptedScopes
+            });
+            const graphStore = await getGraphStore(params.stores);
+            const documentIDs = await graphStore.getDocumentIDsForScope(acceptedScopes, excludedDocumentIDs);
+            const localEntries = await graphStore.getMutationLogForDocuments(documentIDs);
+            const localTree = buildMerkleTree(localEntries);
+            // Step 3: Sync with peer via bidirectional channel
+            const syncDirection = agreedDirection ?? direction;
+            this.#logger.info('Requesting Merkle sync from peer', {
+                localTreeBuckets: Object.keys(localTree.buckets).length,
+                direction: syncDirection
+            });
+            const syncResult = await syncClient.merkleSync(client, {
+                scopes: acceptedScopes,
+                excludedDocumentIDs,
+                localTree,
+                direction: syncDirection,
+                localEntries,
+                // Forward the same delegation tokens used during negotiate so the
+                // merkle-sync access gate authorizes the accepted non-owned scopes. A
+                // revocation landing between negotiate and sync fails the sync; the
+                // retry renegotiates with the updated revocation state.
+                delegationTokens
+            });
+            // Step 4: Apply received mutation JWTs locally
+            if (syncResult.mutationJWTs.length > 0) {
+                this.#logger.info('Applying sync mutations', {
+                    mutations: syncResult.mutationJWTs.length
+                });
+                const applyResult = await applySyncMutations({
+                    db: params.stores,
+                    graph: this.#graph,
+                    mutationJWTs: syncResult.mutationJWTs,
+                    selfDID: this.#identity.id,
+                    storeUnreadable: this.#storeUnreadable,
+                    defaultAccessLevel: this.#defaultAccessLevel
+                });
+                // Attempted counts what arrived to be applied; completed counts what
+                // landed. Reported side by side, so leaving one at 0 makes every sync
+                // read as having applied nothing of nothing.
+                sessionData.documentsAttempted += syncResult.mutationJWTs.length;
+                sessionData.documentsCompleted = applyResult.applied;
+                if (applyResult.deferred > 0) {
+                    this.#logger.info('Deferred sync mutations for retry next round', {
+                        deferred: applyResult.deferred
+                    });
+                }
+            }
+            this.#lastSyncByPeer.set(peerDID, Date.now());
+            this.#emitEvent({
+                type: 'completed',
+                peerID: peerDID,
+                timestamp: Date.now()
+            });
+            this.#logger.info('Merkle sync completed', {
+                divergentBuckets: syncResult.divergentBuckets,
+                mutationsReceived: syncResult.mutationJWTs.length
+            });
+            return {
+                sessionID,
+                divergentBuckets: syncResult.divergentBuckets,
+                messagesReceived: syncResult.mutationJWTs.length,
+                messagesSent: syncResult.mutationsSent,
+                missingClusters
+            };
+        } catch (error) {
+            // DEBUG, and re-thrown: this layer cannot know whether the failure is a
+            // problem. An unreachable peer is `catchUpWithBestPeer`'s ORDINARY outcome
+            // (it warns once and walks past), while `syncPeer` raises to a screen.
+            // Reporting `error` here made every napping phone a red console error on
+            // the other one. Kept for the session-scoped detail no caller holds.
+            this.#logger.debug('Merkle sync failed', {
+                peerDID,
+                error
+            });
+            this.#emitEvent({
+                type: 'error',
+                peerID: peerDID,
+                timestamp: Date.now(),
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        } finally{
+            if (client != null) {
+                try {
+                    client.abort('SyncComplete');
+                    await client.dispose();
+                } catch  {
+                // Transport may already be closed
+                }
+            }
+            this.#activeSessions.delete(sessionID);
+        }
+    }
+    // ---- Status ----
+    getStatus(params) {
+        const { peerDID } = params;
+        const sessions = Array.from(this.#activeSessions.values()).filter((s)=>!peerDID || s.peerID === peerDID).map((data)=>({
+                peerID: data.peerID,
+                startTime: data.startTime,
+                documentsAttempted: data.documentsAttempted,
+                documentsCompleted: data.documentsCompleted
+            }));
+        const lastSyncByPeer = {};
+        for (const [peer, time] of this.#lastSyncByPeer.entries()){
+            if (!peerDID || peer === peerDID) {
+                lastSyncByPeer[peer] = time;
+            }
+        }
+        return {
+            activeSessions: sessions,
+            lastSyncByPeer
+        };
+    }
+    // ---- Events ----
+    onSyncEvent(callback) {
+        return this.#events.on('sync', callback);
+    }
+    /**
+   * Async-iterable view of the sync event stream, for bridging into a GraphQL
+   * subscription. An optional `filter` narrows to a single peer. Closing the
+   * generator (its `return()`, e.g. a subscriber disconnecting) unsubscribes the
+   * underlying listener, so no listener leaks past the consumer.
+   */ subscribeEvents(filter) {
+        return fromEmitter(this.#events, 'sync', {
+            filter
+        });
+    }
+    #emitEvent(event) {
+        this.#events.emit('sync', event).catch((error)=>{
+            this.#logger.error('Error in sync event listener', {
+                error
+            });
+        });
+    }
+    // ---- Lifecycle ----
+    async dispose() {
+        this.#activeSessions.clear();
+        this.#lastSyncByPeer.clear();
+    }
+}

package/lib/sync/tunnel-listeners.d.ts

@@ -0,0 +1,52 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { SyncProtocol } from '../protocol.js';
+export type TunnelListenersParams = {
+    stores: StoreProvider;
+    registry: GroupHandleRegistry;
+    identity: OwnIdentity;
+    localDID: string;
+    runtime: Runtime;
+    syncHandlers: ProcedureHandlers<SyncProtocol>;
+    /** The group's device-wide drain, or `undefined` when no hub is bound. */
+    tunnelHub: (groupID: string) => MailboxHub | undefined;
+    logger?: Logger;
+    idleTimeoutMs?: number;
+};
+export type TunnelListeners = {
+    /**
+     * Bring one group's listener set in line with its roster. Safe to call on any
+     * signal and at any frequency — repeated calls for an unchanged group do
+     * nothing.
+     */
+    reconcile: (groupID: string) => Promise<void>;
+    /** Reconcile every group this device has joined. */
+    reconcileAll: (groupIDs: Array<string>) => Promise<void>;
+    /** Stop and forget one group's listeners. */
+    removeGroup: (groupID: string) => Promise<void>;
+    dispose: () => Promise<void>;
+};
+/**
+ * The answering half of the tunnel: one listener per co-member per group, so a
+ * device that dials `tunnel://<groupID>/<ourDID>` finds something draining the
+ * mailbox.
+ *
+ * Without this a route resolves, opens, publishes its first frame and idles out:
+ * "nobody is home" and "nobody is listening" are the same silence to the dialer.
+ *
+ * ONE PER PEER, not one per group: every listener on a device receives on the
+ * same inbox topic, and two sharing a raw drain destroy each other's frames.
+ * `HubTunnelSyncListener` fronts the hub with a per-peer view for exactly this,
+ * so peers are separated here rather than multiplexed inside a session.
+ *
+ * Gated on this device having declared a profile — the same invariant presence
+ * runs on. A device that never opted in is in nobody's projection, so nothing
+ * can dial it and a listener would hold a subscription open for a session that
+ * cannot arrive.
+ */
+export declare function createTunnelListeners(params: TunnelListenersParams): TunnelListeners;

package/lib/sync/tunnel-listeners.js

@@ -0,0 +1,175 @@
+import { normalizeDID } from '@kokuin/token';
+import { getP2PStore } from '@kubun/store-p2p';
+import { HubTunnelSyncListener } from './hub-tunnel-sync-listener.js';
+/**
+ * The answering half of the tunnel: one listener per co-member per group, so a
+ * device that dials `tunnel://<groupID>/<ourDID>` finds something draining the
+ * mailbox.
+ *
+ * Without this a route resolves, opens, publishes its first frame and idles out:
+ * "nobody is home" and "nobody is listening" are the same silence to the dialer.
+ *
+ * ONE PER PEER, not one per group: every listener on a device receives on the
+ * same inbox topic, and two sharing a raw drain destroy each other's frames.
+ * `HubTunnelSyncListener` fronts the hub with a per-peer view for exactly this,
+ * so peers are separated here rather than multiplexed inside a session.
+ *
+ * Gated on this device having declared a profile — the same invariant presence
+ * runs on. A device that never opted in is in nobody's projection, so nothing
+ * can dial it and a listener would hold a subscription open for a session that
+ * cannot arrive.
+ */ export function createTunnelListeners(params) {
+    const selfDID = normalizeDID(params.localDID);
+    const { logger } = params;
+    // groupID → peerDID → its listener.
+    const listeners = new Map();
+    // Which drain each group's listeners were built on. A listener holds its hub
+    // for life, so a group that switches hubs needs new ones — and the peer set
+    // alone cannot show that, since the same members are still wanted.
+    const attachedHubs = new Map();
+    // And which epoch they derived their topics at. A live listener's subscription
+    // is pinned to the epoch its spawn ran at, and only a disposed transport
+    // re-derives — so a group whose epoch moved keeps draining a topic nobody
+    // publishes to any more, while every dialer idles out against the silence. The
+    // peer set cannot show this either: the same members are still wanted.
+    const attachedEpochs = new Map();
+    // Reconciles of one group run in sequence: an epoch burst fires several, and
+    // two interleaved passes over the same map would each start a listener the
+    // other has not recorded yet.
+    const queues = new Map();
+    let disposed = false;
+    const stopGroup = async (groupID)=>{
+        attachedHubs.delete(groupID);
+        attachedEpochs.delete(groupID);
+        const group = listeners.get(groupID);
+        if (group == null) {
+            return;
+        }
+        listeners.delete(groupID);
+        await Promise.allSettled([
+            ...group.values()
+        ].map((listener)=>listener.stop()));
+    };
+    const runReconcile = async (groupID)=>{
+        if (disposed) {
+            return;
+        }
+        const store = await getP2PStore(params.stores);
+        const profile = await store.getLocalPeerProfile(selfDID);
+        if (profile == null) {
+            await stopGroup(groupID);
+            return;
+        }
+        const hub = params.tunnelHub(groupID);
+        if (hub == null) {
+            // No hub bound: there is no mailbox to drain. A binding arriving later
+            // reconciles again.
+            await stopGroup(groupID);
+            return;
+        }
+        const epoch = params.registry.groupEpoch(groupID);
+        if (attachedHubs.get(groupID) !== hub || attachedEpochs.get(groupID) !== epoch) {
+            await stopGroup(groupID);
+        }
+        attachedHubs.set(groupID, hub);
+        attachedEpochs.set(groupID, epoch);
+        const members = await store.listGroupMembers(groupID);
+        const wanted = new Set(members.map((member)=>normalizeDID(member.member_did)).filter((did)=>did !== selfDID));
+        let group = listeners.get(groupID);
+        if (group == null) {
+            group = new Map();
+            listeners.set(groupID, group);
+        }
+        for (const [peerDID, listener] of group){
+            if (!wanted.has(peerDID)) {
+                group.delete(peerDID);
+                try {
+                    await listener.stop();
+                } catch (error) {
+                    logger?.warn('tunnel listener stop failed', {
+                        groupID,
+                        peerDID,
+                        error
+                    });
+                }
+            }
+        }
+        // Every await above is a point where the group could have been left or the
+        // whole thing disposed. A pass that continued past one would repopulate
+        // `listeners` with fresh, STARTED listeners for a group this device is no
+        // longer in, and they would drain that group's inbox topic indefinitely —
+        // nothing later removes what `removeGroup` already walked past.
+        if (disposed || listeners.get(groupID) !== group) {
+            return;
+        }
+        for (const peerDID of wanted){
+            if (group.has(peerDID)) {
+                continue;
+            }
+            const listener = new HubTunnelSyncListener({
+                hub,
+                registry: params.registry,
+                groupID,
+                localDID: selfDID,
+                peerDID,
+                identity: params.identity,
+                syncHandlers: params.syncHandlers,
+                runtime: params.runtime,
+                ...params.idleTimeoutMs != null ? {
+                    idleTimeoutMs: params.idleTimeoutMs
+                } : {},
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+            group.set(peerDID, listener);
+            listener.start();
+        }
+    };
+    const reconcile = (groupID)=>{
+        const queued = (queues.get(groupID) ?? Promise.resolve()).then(()=>runReconcile(groupID), ()=>runReconcile(groupID));
+        // Never let one group's failure reject a caller that only asked for a
+        // reconcile — the next signal retries, and a throw here would surface on
+        // whichever unrelated lane happened to trigger it.
+        const settled = queued.catch((error)=>{
+            logger?.warn('tunnel listener reconcile failed', {
+                groupID,
+                error
+            });
+        });
+        queues.set(groupID, settled);
+        return settled;
+    };
+    return {
+        reconcile,
+        reconcileAll: async (groupIDs)=>{
+            await Promise.all(groupIDs.map((groupID)=>reconcile(groupID)));
+        },
+        removeGroup: async (groupID)=>{
+            // Await the in-flight reconcile BEFORE tearing down. Dropping the queue
+            // entry does not stop the pass already running: it would finish after the
+            // stop and leave started listeners behind for a group the device has
+            // left. `runReconcile` also re-checks, so this is the pair.
+            const queued = queues.get(groupID);
+            queues.delete(groupID);
+            if (queued != null) {
+                await queued.catch(()=>{
+                // A failed reconcile is already logged; the teardown proceeds.
+                });
+            }
+            await stopGroup(groupID);
+        },
+        dispose: async ()=>{
+            disposed = true;
+            const inFlight = [
+                ...queues.values()
+            ];
+            queues.clear();
+            await Promise.allSettled(inFlight);
+            const groupIDs = [
+                ...listeners.keys()
+            ];
+            await Promise.allSettled(groupIDs.map((groupID)=>stopGroup(groupID)));
+        }
+    };
+}

package/lib/sync/tunnel-observability.d.ts

@@ -0,0 +1,25 @@
+import type { Logger } from '@kubun/logger';
+import type { ObservabilityEventListener } from '@kumiai/hub-tunnel';
+/**
+ * Which side of a tunnel session a transport is. Carried on every line a
+ * session logs, because the two are indistinguishable otherwise: both receive
+ * on this device's inbox topic for the epoch, and a drop only means something
+ * once you know whether the reader was answering a peer or dialling one.
+ */
+export type TunnelSessionRole = 'dialer' | 'listener';
+/**
+ * Turn a tunnel transport's observability events into log lines, and pass them
+ * on to a listener the caller supplied.
+ *
+ * Until this existed the transports' `onEvent` port had no producer anywhere in
+ * the repo — declared, forwarded to the transport, and set by nobody. Every
+ * destroyed frame was therefore silent, in tests and on devices alike: a
+ * starved session showed up as an idle timeout half a minute later with nothing
+ * saying why. That is the entire reason a two-device sync failure had to be
+ * diagnosed by reading code rather than by reading a log.
+ *
+ * `logger` is expected to carry the session's context already (`groupID`,
+ * `peerDID`, `role`, `epoch`, topics), so a line needs no arguments beyond what
+ * the event itself adds.
+ */
+export declare function createTunnelEventLogger(logger: Logger, delegate?: ObservabilityEventListener): ObservabilityEventListener;

package/lib/sync/tunnel-observability.js

@@ -0,0 +1,63 @@
+/**
+ * Drops a healthy lane never produces, so each one is a frame that reached this
+ * device and was thrown away.
+ *
+ * - `decrypt` — the ciphertext did not open. On a lane whose key is right, that
+ *   means something else opened it first: MLS consumes a ratchet generation per
+ *   open, so a second reader of the same frame is handed a key that is gone.
+ * - `session-mismatch` — it opened, and belonged to a session this reader is not
+ *   serving. The frame is destroyed for the session it WAS for, which is now
+ *   waiting out its idle timeout with nothing raised.
+ * - `group-mismatch` — a frame for another group arrived on this topic, which
+ *   the envelope catches before the cipher. Same-key misroute, never routine.
+ *
+ * Everything else is routine: `dedup` is the hub redelivering, `topic-mismatch`
+ * is the shared device drain doing its job, `envelope-decode` is a foreign
+ * publisher on the topic.
+ */ const UNEXPECTED_REASONS = new Set([
+    'decrypt',
+    'session-mismatch',
+    'group-mismatch'
+]);
+/**
+ * Turn a tunnel transport's observability events into log lines, and pass them
+ * on to a listener the caller supplied.
+ *
+ * Until this existed the transports' `onEvent` port had no producer anywhere in
+ * the repo — declared, forwarded to the transport, and set by nobody. Every
+ * destroyed frame was therefore silent, in tests and on devices alike: a
+ * starved session showed up as an idle timeout half a minute later with nothing
+ * saying why. That is the entire reason a two-device sync failure had to be
+ * diagnosed by reading code rather than by reading a log.
+ *
+ * `logger` is expected to carry the session's context already (`groupID`,
+ * `peerDID`, `role`, `epoch`, topics), so a line needs no arguments beyond what
+ * the event itself adds.
+ */ export function createTunnelEventLogger(logger, delegate) {
+    return (event)=>{
+        switch(event.type){
+            case 'decrypt-failed':
+                logger.warn('tunnel frame failed to decrypt', {
+                    error: event.error
+                });
+                break;
+            case 'envelope-decode-failed':
+                logger.debug('tunnel envelope failed to decode', {
+                    error: event.error
+                });
+                break;
+            case 'frame-dropped':
+                if (UNEXPECTED_REASONS.has(event.reason)) {
+                    logger.warn('tunnel frame dropped', {
+                        reason: event.reason
+                    });
+                } else {
+                    logger.debug('tunnel frame dropped', {
+                        reason: event.reason
+                    });
+                }
+                break;
+        }
+        delegate?.(event);
+    };
+}

package/lib/sync/tunnel-topics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which side of a directed session a topic belongs to. A `dialer` topic carries
+ * the responses flowing back to whoever opened the session; a `responder` topic
+ * carries the requests arriving at whoever answers.
+ */
+export type TunnelRole = 'dialer' | 'responder';
+/**
+ * The topic on which `ownerDID` receives the frames addressed to it in `role`.
+ *
+ * Both sides derive both topics from the same (secret, epoch), so a dialer knows
+ * where to write and a responder knows where to answer without negotiating
+ * anything. Topics rotate with the MLS epoch exactly as the inbox ones did.
+ *
+ * Scoped by role and owner but NOT by session: a device holds one drain per
+ * (role, peer) and separates concurrent sessions to different peers by sender.
+ * Two sessions in the same role to the SAME peer at once would still contend —
+ * nothing in the sync client opens those, and a session id in the scope would
+ * cost a round trip to agree on before either side could subscribe.
+ */
+export declare function tunnelTopic(secret: Uint8Array, epoch: number, role: TunnelRole, ownerDID: string): string;

package/lib/sync/tunnel-topics.js

@@ -0,0 +1,28 @@
+import { protocolTopic } from '@kumiai/rpc';
+/**
+ * The lane every directed sync tunnel rides, owned by this package.
+ *
+ * Deliberately not `inboxTopic`: that derives ONE topic per member, so a device
+ * dialing a peer and answering that same peer both read and both write the two
+ * members' inboxes. The two roles then share a topic, and sender scope cannot
+ * separate them — a peer's reply and that peer's own dial request are equally
+ * "from the peer". Whichever of the two opens a frame first consumes its MLS
+ * ratchet generation and DESTROYS it for the other, which waits out its idle
+ * timeout instead. `inboxTopic` is also `@kumiai/rpc`'s reserved lane, and a
+ * host protocol has no business publishing into it.
+ */ const SYNC_TUNNEL_PROTOCOL = 'kubun/sync-tunnel/v1';
+/**
+ * The topic on which `ownerDID` receives the frames addressed to it in `role`.
+ *
+ * Both sides derive both topics from the same (secret, epoch), so a dialer knows
+ * where to write and a responder knows where to answer without negotiating
+ * anything. Topics rotate with the MLS epoch exactly as the inbox ones did.
+ *
+ * Scoped by role and owner but NOT by session: a device holds one drain per
+ * (role, peer) and separates concurrent sessions to different peers by sender.
+ * Two sessions in the same role to the SAME peer at once would still contend —
+ * nothing in the sync client opens those, and a session id in the scope would
+ * cost a round trip to agree on before either side could subscribe.
+ */ export function tunnelTopic(secret, epoch, role, ownerDID) {
+    return protocolTopic(secret, epoch, SYNC_TUNNEL_PROTOCOL, `${role}:${ownerDID}`);
+}