@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/sync/handlers.js

@@ -1,6 +1,7 @@
-import { createRevocationChecker } from '@kokuin/capability';
-import { createRevocationBackend, getDelegationStore } from '@kubun/store-delegation';
+import { createDelegationRevocationChecker, getDelegationStore } from '@kubun/store-delegation';
 import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { wrapHandlers } from '../util/handler-error.js';
 import { authorizeScope, checkSyncDelegation } from './authorize.js';
 import { resolveCatalogSyncScopes } from './catalog-scope.js';
 import { SyncAccessDeniedError } from './errors.js';
@@ -17,11 +18,33 @@ export { checkSyncDelegation };
     async function getRevocationChecker() {
         if (cachedRevocationChecker == null) {
             const delegationStore = await getDelegationStore(db);
-            cachedRevocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+            cachedRevocationChecker = createDelegationRevocationChecker(delegationStore);
         }
         return cachedRevocationChecker;
     }
-    return {
+    // Circle-granted read resolution, shared by negotiate and merkle-sync so the
+    // two gates authorize identical scopes. Reads run against this device's own
+    // projected state (the owner's tier-2 default + the requester's membership).
+    let cachedCircleReadGrant = null;
+    async function getCircleReadGrant() {
+        if (cachedCircleReadGrant == null) {
+            const [graphStore, p2pStore] = await Promise.all([
+                getGraphStore(db),
+                getP2PStore(db)
+            ]);
+            cachedCircleReadGrant = {
+                getUserModelReadDefault: (ownerDID, modelID)=>graphStore.getUserModelAccessDefault(ownerDID, modelID, 'read'),
+                // `listAccessibleCircles` excludes tombstoned circles, so a removed
+                // circle is simply absent and the gate fails closed on it.
+                listAccessibleCircles: (viewerDID, circleIDs)=>p2pStore.listAccessibleCircles(viewerDID, circleIDs),
+                listMemberGroupIDs: (viewerDID, groupIDs)=>p2pStore.listMemberGroupIDs(viewerDID, groupIDs)
+            };
+        }
+        return cachedCircleReadGrant;
+    }
+    // Wrapped so a refusal carrying a registered KubunErrorCode reaches the
+    // calling device with its code and reason instead of enkaku's generic EK01.
+    return wrapHandlers({
         'sync/negotiate': async (ctx)=>{
             const { scopes, delegationTokens, catalogIDs, knownModelIDs, direction } = ctx.param;
             const payload = ctx.message.payload;
@@ -43,7 +66,7 @@ export { checkSyncDelegation };
             const graphStore = await getGraphStore(db);
             // Catalog-based scope resolution
             if (catalogIDs != null && catalogIDs.length > 0) {
-                const catalogScope = await resolveCatalogSyncScopes(db, catalogIDs, knownModelIDs);
+                const catalogScope = await resolveCatalogSyncScopes(db, catalogIDs);
                 // Generate scopes from resolved catalog criteria
                 if (catalogScope.modelIDs.length > 0) {
                     if (catalogScope.owners != null) {
@@ -53,8 +76,10 @@ export { checkSyncDelegation };
                                 const accepted = await authorizeScope({
                                     viewerDID,
                                     ownerDID,
+                                    modelID,
                                     delegationTokens,
-                                    revocationChecker: await getRevocationChecker()
+                                    revocationChecker: await getRevocationChecker(),
+                                    circleReadGrant: await getCircleReadGrant()
                                 });
                                 if (accepted) {
                                     acceptedScopes.push({
@@ -72,8 +97,10 @@ export { checkSyncDelegation };
                                 const accepted = await authorizeScope({
                                     viewerDID,
                                     ownerDID,
+                                    modelID,
                                     delegationTokens,
-                                    revocationChecker: await getRevocationChecker()
+                                    revocationChecker: await getRevocationChecker(),
+                                    circleReadGrant: await getCircleReadGrant()
                                 });
                                 if (accepted) {
                                     acceptedScopes.push({
@@ -85,10 +112,6 @@ export { checkSyncDelegation };
                         }
                     }
                 }
-                // Fetch missing cluster definitions
-                if (catalogScope.missingClusterIDs.length > 0) {
-                    missingClusters = await graphStore.getClusters(catalogScope.missingClusterIDs);
-                }
             }
             // Explicit scopes (existing behavior)
             if (scopes != null) {
@@ -96,8 +119,10 @@ export { checkSyncDelegation };
                     const accepted = await authorizeScope({
                         viewerDID,
                         ownerDID: scope.ownerDID,
+                        modelID: scope.modelID,
                         delegationTokens,
-                        revocationChecker: await getRevocationChecker()
+                        revocationChecker: await getRevocationChecker(),
+                        circleReadGrant: await getCircleReadGrant()
                     });
                     if (accepted) {
                         acceptedScopes.push(scope);
@@ -117,6 +142,20 @@ export { checkSyncDelegation };
                 seen.add(key);
                 return true;
             });
+            // A model the requester does not have is one it cannot store documents
+            // for, so ship the cluster it was deployed in. Computed over the ACCEPTED
+            // scopes rather than over a catalog: production negotiates with explicit
+            // scopes and sends no `catalogIDs`, so a catalog-only computation is
+            // unreachable there — and an unauthorized scope must not leak a model
+            // definition either way.
+            const knownSet = new Set(knownModelIDs ?? []);
+            // Concurrently: one read per unknown model, none depending on another, on
+            // the negotiate that a peer waits out before any document moves.
+            const resolved = await Promise.all(uniqueScopes.filter((scope)=>!knownSet.has(scope.modelID)).map((scope)=>graphStore.getClusterForModel(scope.modelID)));
+            const missingClusterIDs = new Set(resolved.filter((id)=>id != null));
+            if (missingClusterIDs.size > 0) {
+                missingClusters = await graphStore.getClusters(Array.from(missingClusterIDs));
+            }
             logger.info('sync/negotiate completed', {
                 requested: (scopes?.length ?? 0) + (catalogIDs?.length ?? 0),
                 accepted: uniqueScopes.length,
@@ -154,7 +193,8 @@ export { checkSyncDelegation };
             selfDID: params.selfDID,
             storeUnreadable,
             defaultAccessLevel: params.defaultAccessLevel,
-            getRevocationChecker
+            getRevocationChecker,
+            getCircleReadGrant
         })
-    };
+    });
 }

package/lib/sync/hub-tunnel-sync-listener.d.ts

@@ -1,26 +1,36 @@
 import { type ProcedureHandlers } from '@enkaku/server';
 import type { OwnIdentity } from '@kokuin/token';
-import { type HubLike, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
+import type { Logger } from '@kubun/logger';
+import { type MailboxHub, type ObservabilityEventListener } 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 HubTunnelSyncListenerParams = {
     /**
-     * Shared multi-subscriber device hub (from `createHubLike`). Each spawned
-     * server transport attaches its own sink to this device-wide drain and filters
-     * to its `receiveTopicID`; lifecycle events ride `hub.events`.
+     * Shared multi-subscriber device hub (from `createHubLike`). Every listener on
+     * a device receives on the SAME topic (this device's inbox for the epoch), so
+     * the hub is not handed to the transport directly — it is fronted by a
+     * per-peer view that drops other peers' frames before they reach the cipher.
+     * Lifecycle events ride `hub.events`.
      */
-    hub: HubLike;
+    hub: MailboxHub;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;
     peerDID: string;
     identity: OwnIdentity;
     syncHandlers: ProcedureHandlers<SyncProtocol>;
-    getRandomID?: () => string;
+    /**
+     * Threaded through to every spawned session's server rather than defaulted
+     * here, so a device whose platform primitives differ from the Node defaults
+     * keeps one generator across the whole plugin.
+     */
+    runtime: Runtime;
     idleTimeoutMs?: number;
     reconnectTimeoutMs?: number;
     inboxCapacity?: number;
     onEvent?: ObservabilityEventListener;
+    logger?: Logger;
 };
 export declare class HubTunnelSyncListener {
     #private;

package/lib/sync/hub-tunnel-sync-listener.js

@@ -1,8 +1,11 @@
 import { Server } from '@enkaku/server';
 import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
-import { inboxTopic } from '@kumiai/rpc';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
 import { createGroupCrypto } from '../groups/group-crypto.js';
 import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createPeerScopedHubView } from '../hub/peer-scoped-hub-view.js';
+import { createTunnelEventLogger } from './tunnel-observability.js';
+import { tunnelTopic } from './tunnel-topics.js';
 export class HubTunnelSyncListener {
     #hub;
     #registry;
@@ -11,23 +14,25 @@ export class HubTunnelSyncListener {
     #peerDID;
     #identity;
     #syncHandlers;
-    #getRandomID;
+    #runtime;
     #idleTimeoutMs;
     #reconnectTimeoutMs;
     #inboxCapacity;
     #onEvent;
+    #logger;
     #started = false;
     #stopped = false;
+    /** Consecutive failed spawns, for the re-arm backoff. Reset by a success. */ #respawnAttempt = 0;
+    #respawnTimer;
     #current;
     // Single MLSEncryptor reused across spawns. Ordering across overlapping
     // spawns (old transport's last decrypt vs. new spawn's first encrypt) is
     // covered by the GroupHandleRegistry's per-group mutex.
     #encryptor;
-    // This device's inbox topic for the live epoch, cached from the first spawn.
-    // Within an epoch it is stable (same secret + localDID), so it lets the
-    // disposed handler re-subscribe synchronously and close the gap left by the
-    // departing transport's teardown-unsubscribe before the async respawn lands.
-    #receiveTopicID;
+    // Per-peer view over the device hub, built once and shared by every spawn: it
+    // holds the inbox subscription for the listener's whole life, so respawns
+    // neither re-arm nor release a topic other listeners are draining.
+    #peerHub;
     constructor(params){
         this.#hub = params.hub;
         this.#registry = params.registry;
@@ -36,11 +41,12 @@ export class HubTunnelSyncListener {
         this.#peerDID = params.peerDID;
         this.#identity = params.identity;
         this.#syncHandlers = params.syncHandlers;
-        this.#getRandomID = params.getRandomID;
+        this.#runtime = params.runtime;
         this.#idleTimeoutMs = params.idleTimeoutMs;
         this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
         this.#inboxCapacity = params.inboxCapacity;
         this.#onEvent = params.onEvent;
+        this.#logger = params.logger;
     }
     start() {
         if (this.#started || this.#stopped) return;
@@ -49,11 +55,55 @@ export class HubTunnelSyncListener {
             registry: this.#registry,
             groupID: this.#groupID
         });
-        void this.#spawn();
+        this.#peerHub = createPeerScopedHubView({
+            hub: this.#hub,
+            peerDID: this.#peerDID
+        });
+        this.#spawnGuarded();
+    }
+    /**
+   * Spawn, and survive a spawn that throws.
+   *
+   * `#spawn` can reject — `exportSecret(APP_TOPIC_LABEL)` throws whenever the
+   * group handle is unavailable (mid-epoch-change, group left, registry lock
+   * contention). Left bare, that was an unhandled rejection AND a listener that
+   * stopped answering forever: the only other respawn trigger is the
+   * transport's `disposed` event, which cannot fire for a session that was
+   * never built. From the dialer's side that is exactly the silence this
+   * listener exists to eliminate.
+   */ #spawnGuarded() {
+        void this.#spawn().then(()=>{
+            this.#respawnAttempt = 0;
+        }).catch((error)=>{
+            this.#logger?.warn('hub tunnel listener spawn failed', {
+                groupID: this.#groupID,
+                peerDID: this.#peerDID,
+                attempt: this.#respawnAttempt,
+                error
+            });
+            this.#scheduleRespawn();
+        });
+    }
+    #scheduleRespawn() {
+        if (this.#stopped || this.#respawnTimer != null) return;
+        // Bounded: a handle that is unavailable because the group was left never
+        // becomes available, and this must not spin on it.
+        const delay = Math.min(30_000, 250 * 2 ** Math.min(this.#respawnAttempt++, 7));
+        const timer = setTimeout(()=>{
+            this.#respawnTimer = undefined;
+            if (this.#stopped) return;
+            this.#spawnGuarded();
+        }, delay);
+        timer.unref?.();
+        this.#respawnTimer = timer;
     }
     async stop() {
         if (this.#stopped) return;
         this.#stopped = true;
+        if (this.#respawnTimer != null) {
+            clearTimeout(this.#respawnTimer);
+            this.#respawnTimer = undefined;
+        }
         const current = this.#current;
         this.#current = undefined;
         if (current != null) {
@@ -69,30 +119,53 @@ export class HubTunnelSyncListener {
             }
         }
         this.#encryptor = undefined;
+        this.#peerHub = undefined;
     }
     async #spawn() {
         if (this.#stopped) return;
         const encryptor = this.#encryptor;
-        if (encryptor == null) {
-            throw new Error('HubTunnelSyncListener: encryptor not initialized; call start() first');
+        const peerHub = this.#peerHub;
+        if (encryptor == null || peerHub == null) {
+            throw new Error('HubTunnelSyncListener: not initialized; call start() first');
         }
-        // Derive the epoch-bound inbox topics for this spawn. The server accepts
-        // inbound frames on its own inbox (`receiveTopicID`) and replies to the
-        // peer's inbox (`sendTopicID`). Topics rotate with the MLS epoch, so each
+        // Derive the epoch-bound, role-scoped topics for this spawn. The server
+        // accepts inbound frames on this device's RESPONDER topic and replies to the
+        // peer's DIALER topic — the mirror of what the dialing side derives, and
+        // disjoint from it, so this device's own dial to the same peer never lands
+        // here. Topics rotate with the MLS epoch, so each
         // spawn re-derives them against the live handle. MLS decrypt inside the
         // registry lock remains the authoritative membership/forward-secrecy gate;
         // stale-after-remove ciphertext surfaces as DecryptError.
-        const crypto = createGroupCrypto(this.#registry, this.#groupID);
-        const secret = await crypto.exportSecret();
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
         const epoch = crypto.epoch();
-        const sendTopicID = inboxTopic(secret, epoch, this.#peerDID);
-        const receiveTopicID = inboxTopic(secret, epoch, this.#localDID);
-        this.#receiveTopicID = receiveTopicID;
+        const sendTopicID = tunnelTopic(secret, epoch, 'dialer', this.#peerDID);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'responder', this.#localDID);
         // A stop() that landed while we awaited the handle must abort the spawn.
         if (this.#stopped) return;
+        // No sessionID: a responder locks to whatever session dials it, so the id
+        // is not known until the first frame. Everything else is, and `role` is what
+        // separates this listener's lines from the dialer's on the same device. The
+        // two now read disjoint topics, so `receiveTopicID` says the same thing —
+        // but it says it in a hash, and only the role says it at a glance.
+        const sessionLogger = this.#logger?.with({
+            role: 'listener',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            epoch,
+            receiveTopicID
+        });
         let transportRef;
         const transport = createEncryptedHubTunnelTransport({
-            hub: this.#hub,
+            hub: peerHub,
             encryptor,
             groupID: this.#groupID,
             sessionID: {
@@ -104,7 +177,7 @@ export class HubTunnelSyncListener {
             idleTimeoutMs: this.#idleTimeoutMs,
             reconnectTimeoutMs: this.#reconnectTimeoutMs,
             inboxCapacity: this.#inboxCapacity,
-            onEvent: this.#onEvent,
+            onEvent: sessionLogger == null ? this.#onEvent : createTunnelEventLogger(sessionLogger, this.#onEvent),
             onSessionEnd: ()=>{
                 // Peer signaled end-of-session. Dispose the transport deterministically
                 // so the `disposed` event fires and the spawn loop re-arms for the
@@ -120,7 +193,7 @@ export class HubTunnelSyncListener {
         // servers. Per-scope authorization is handled uniformly by the merkle-sync
         // scope-gate, not here.
         const server = new Server({
-            getRandomID: this.#getRandomID,
+            runtime: this.#runtime,
             handlers: this.#syncHandlers,
             identity: this.#identity,
             accessRules: {
@@ -137,9 +210,31 @@ export class HubTunnelSyncListener {
             server
         };
         this.#current = session;
+        // Defence in depth, and today only that: there is no `await` between the
+        // `#stopped` check above and this assignment, so a `stop()` cannot
+        // currently interleave into that window. The moment one is introduced —
+        // anything awaited while building the transport or the server — a `stop()`
+        // landing there would find `#current === undefined`, dispose nothing and
+        // return, while this spawn stood up a subscribed, draining transport that
+        // nothing holds a reference to. Re-checking after the assignment is what
+        // makes that a non-event: whichever side runs second does the teardown.
+        if (this.#stopped) {
+            this.#current = undefined;
+            try {
+                await transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            return;
+        }
         // `disposed` may fire more than once for a single session (disposing the
         // server can re-enter the transport's dispose). Collapse to exactly one
-        // teardown + respawn so the inbox is re-armed once, not N times.
+        // teardown + respawn so one session leaves exactly one successor.
         let handled = false;
         transport.events.on('disposed', ()=>{
             if (handled) return;
@@ -152,21 +247,15 @@ export class HubTunnelSyncListener {
             void server.dispose().catch(()=>{
             // ignore
             });
-            // The departing transport's teardown unsubscribes this device's inbox
-            // topic. Re-subscribe it eagerly (idempotent server-side) so a peer that
-            // reconnects immediately — before the async respawn re-derives and
-            // re-subscribes — does not lose its first frame to a momentarily empty
-            // topic. Within an epoch the topic is stable, so this targets the same
-            // inbox the next spawn will use.
-            const receiveTopicID = this.#receiveTopicID;
-            if (receiveTopicID != null) {
-                void Promise.resolve(this.#hub.subscribe(this.#localDID, receiveTopicID)).catch(()=>{
-                // best-effort; the respawn re-subscribes authoritatively
-                });
-            }
+            // Nothing re-arms the inbox here. This fires even after stop(), so a
+            // departing listener would be re-subscribing a topic it no longer uses on
+            // behalf of listeners it knows nothing about. The gap it was covering is
+            // closed at the source instead: the per-peer view never releases the
+            // topic, so the departing transport's teardown cannot empty it.
+            //
             // Respawn for the next session. The next spawn re-derives the topics
-            // against the (possibly advanced) epoch and re-subscribes.
-            void this.#spawn();
+            // against the (possibly advanced) epoch, and survives failing to.
+            this.#spawnGuarded();
         });
     }
 }

package/lib/sync/hub-tunnel-sync-provider.d.ts

@@ -1,23 +1,42 @@
 import type { ClientTransportOf } from '@enkaku/protocol';
-import { type HubLike, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
+import type { Logger } from '@kubun/logger';
+import { type ObservabilityEventListener } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { DeviceHub } from '../hub/hub-like.js';
 import type { SyncProtocol } from '../protocol.js';
 import type { SyncTransportProvider } from './sync-client.js';
 export type HubTunnelSyncProviderParams = {
     /**
-     * Shared multi-subscriber device hub (from `createHubLike`). The transport's
-     * `receive()` attaches its own sink to this device-wide drain and filters to
-     * `receiveTopicID`; lifecycle events ride `hub.events`.
+     * Shared multi-subscriber device hub (from `createHubLike`). Each session
+     * attaches its own sink to this device-wide drain, narrowed to the peer it
+     * dialled, and filters to `receiveTopicID`; lifecycle events ride
+     * `hub.events`.
      */
-    hub: HubLike;
+    hub: DeviceHub;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;
     peerDID: string;
+    /**
+     * Supplies the platform primitives, including the per-session id generator.
+     * Threaded in from the caller rather than defaulted here: this package runs on
+     * React Native and in the browser as well as on node, so the one runtime the
+     * host built has to reach every seam that mints an id.
+     */
+    runtime: Runtime;
     idleTimeoutMs?: number;
     reconnectTimeoutMs?: number;
     inboxCapacity?: number;
     onEvent?: ObservabilityEventListener;
+    /**
+     * Where this session's frame-level events and its open/close are recorded. A
+     * session that is handed nothing raises nothing until its idle timeout fires
+     * — half a minute later, from inside the dependency, naming neither the group
+     * nor the peer — so without this the only account of a starved dial is a
+     * stack trace with no message.
+     */
+    logger?: Logger;
 };
 export declare class HubTunnelSyncProvider implements SyncTransportProvider {
     #private;
@@ -25,12 +44,13 @@ export declare class HubTunnelSyncProvider implements SyncTransportProvider {
     /**
      * Build a fresh client transport for one tunnel sync session.
      *
-     * The tunnel rides group-scoped inbox topics derived from the group's current
-     * MLS epoch secret: outbound frames publish to the peer's inbox
-     * (`inboxTopic(secret, epoch, peerDID)`) and the transport subscribes to this
-     * device's own inbox (`inboxTopic(secret, epoch, localDID)`). Topics rotate
-     * with the epoch, so a transport built in epoch N stops matching once a commit
-     * advances the group — callers create a new transport per session.
+     * The tunnel rides group-scoped, ROLE-scoped topics derived from the group's
+     * current MLS epoch secret: outbound frames publish to the peer's responder
+     * topic, and the transport subscribes to this device's own dialer topic —
+     * which the peer's listener writes its answers to and nothing else does.
+     * Topics rotate with the epoch, so a transport built in epoch N stops matching
+     * once a commit advances the group — callers create a new transport per
+     * session.
      */
     createSyncTransport(signal?: AbortSignal): Promise<ClientTransportOf<SyncProtocol>>;
 }

package/lib/sync/hub-tunnel-sync-provider.js

@@ -1,50 +1,94 @@
 import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
-import { inboxTopic } from '@kumiai/rpc';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
 import { createGroupCrypto } from '../groups/group-crypto.js';
 import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createSenderScopedHubView } from '../hub/sender-scoped-hub-view.js';
+import { createTunnelEventLogger } from './tunnel-observability.js';
+import { tunnelTopic } from './tunnel-topics.js';
 export class HubTunnelSyncProvider {
     #hub;
     #registry;
     #groupID;
     #localDID;
     #peerDID;
+    #runtime;
     #idleTimeoutMs;
     #reconnectTimeoutMs;
     #inboxCapacity;
     #onEvent;
+    #logger;
     constructor(params){
         this.#hub = params.hub;
         this.#registry = params.registry;
         this.#groupID = params.groupID;
         this.#localDID = params.localDID;
         this.#peerDID = params.peerDID;
+        this.#runtime = params.runtime;
         this.#idleTimeoutMs = params.idleTimeoutMs;
         this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
         this.#inboxCapacity = params.inboxCapacity;
         this.#onEvent = params.onEvent;
+        this.#logger = params.logger;
     }
     /**
    * Build a fresh client transport for one tunnel sync session.
    *
-   * The tunnel rides group-scoped inbox topics derived from the group's current
-   * MLS epoch secret: outbound frames publish to the peer's inbox
-   * (`inboxTopic(secret, epoch, peerDID)`) and the transport subscribes to this
-   * device's own inbox (`inboxTopic(secret, epoch, localDID)`). Topics rotate
-   * with the epoch, so a transport built in epoch N stops matching once a commit
-   * advances the group — callers create a new transport per session.
+   * The tunnel rides group-scoped, ROLE-scoped topics derived from the group's
+   * current MLS epoch secret: outbound frames publish to the peer's responder
+   * topic, and the transport subscribes to this device's own dialer topic —
+   * which the peer's listener writes its answers to and nothing else does.
+   * Topics rotate with the epoch, so a transport built in epoch N stops matching
+   * once a commit advances the group — callers create a new transport per
+   * session.
    */ async createSyncTransport(signal) {
-        const sessionID = generateSessionID();
+        const sessionID = this.#runtime.getRandomID();
         const encryptor = new MLSEncryptor({
             registry: this.#registry,
             groupID: this.#groupID
         });
-        const crypto1 = createGroupCrypto(this.#registry, this.#groupID);
-        const secret = await crypto1.exportSecret();
-        const epoch = crypto1.epoch();
-        const sendTopicID = inboxTopic(secret, epoch, this.#peerDID);
-        const receiveTopicID = inboxTopic(secret, epoch, this.#localDID);
-        return createEncryptedHubTunnelTransport({
-            hub: this.#hub,
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        const sendTopicID = tunnelTopic(secret, epoch, 'responder', this.#peerDID);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'dialer', this.#localDID);
+        // Bound once and carried by every line this session logs, including the
+        // frame drops below. The transport's own idle timeout names none of this —
+        // it raises a bare `TimeoutInterruption` from inside the dependency — so
+        // attributing a starved session to a group, a peer and an epoch is only
+        // possible from here.
+        const sessionLogger = this.#logger?.with({
+            role: 'dialer',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            sessionID,
+            epoch,
+            receiveTopicID
+        });
+        sessionLogger?.debug('tunnel session opening');
+        const transport = createEncryptedHubTunnelTransport({
+            // The peer-scoped VIEW, never the device hub: two sessions open at once
+            // receive on this same inbox topic, and a frame one of them opens is
+            // destroyed for the other — MLS consumes a ratchet generation per open.
+            // The loser starves to its idle timeout with nothing raised.
+            // The idle timeout is reused as the publish bound on purpose: "a session
+            // that gets nothing for N gives up" and "a session that cannot even send
+            // for N gives up" are one promise to whoever is waiting, and a second knob
+            // would only let the two drift apart.
+            hub: createSenderScopedHubView({
+                hub: this.#hub,
+                peerDID: this.#peerDID,
+                ...this.#idleTimeoutMs == null ? {} : {
+                    publishTimeoutMs: this.#idleTimeoutMs
+                }
+            }),
             encryptor,
             groupID: this.#groupID,
             sessionID,
@@ -55,10 +99,15 @@ export class HubTunnelSyncProvider {
             idleTimeoutMs: this.#idleTimeoutMs,
             reconnectTimeoutMs: this.#reconnectTimeoutMs,
             inboxCapacity: this.#inboxCapacity,
-            onEvent: this.#onEvent
+            onEvent: sessionLogger == null ? this.#onEvent : createTunnelEventLogger(sessionLogger, this.#onEvent)
         });
+        // The close is as load-bearing as the open: a session that ends without
+        // having received anything is what an unreachable peer looks like, and the
+        // pair of lines is what says whether it ran for milliseconds or waited out
+        // the full idle window.
+        transport.events.on('disposed', ()=>{
+            sessionLogger?.debug('tunnel session closed');
+        });
+        return transport;
     }
 }
-function generateSessionID() {
-    return crypto.randomUUID();
-}