@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/hub/hub-like.js

@@ -1,28 +1,97 @@
+import { RequestError } from '@enkaku/client';
+import { ErrorCodes } from '@enkaku/protocol';
+import { hubErrorFromCode, RetentionExceededError } from '@kumiai/hub-protocol';
 import { fromB64, toB64 } from '@sozai/codec';
 import { EventEmitter } from '@sozai/event';
 import { AckBatch, abortableSleep, computeBackoff } from './ack-backoff.js';
 const DEFAULT_ACK_FLUSH_MS = 500;
 const DEFAULT_ACK_FLUSH_MAX = 10;
 const DEFAULT_BACKOFF_BASE_MS = 1000;
-const DEFAULT_BACKOFF_MAX_MS = 60000;
+// Half a minute, not a minute. This is the longest a device sits doing nothing
+// after a hub comes back — and on a phone the person is usually watching, so a
+// ceiling they can wait out beats one that saves a few dials. `retryNow` exists
+// for when even this is too long.
+const DEFAULT_BACKOFF_MAX_MS = 30000;
 const DEFAULT_BACKOFF_JITTER = 0.25;
 const DISPOSED_SENTINEL = Symbol('disposed');
+/**
+ * Rebuild a named hub error from the wire code its reply carried, so callers
+ * branch on the class: a lost compare-and-set is rebased and retried, a retention
+ * refusal never is. A transport failure carries no hub code and passes through
+ * untouched — that distinction is the point.
+ */ function asHubError(error) {
+    if (error instanceof RequestError) {
+        return hubErrorFromCode(error.code, error.message) ?? error;
+    }
+    return error;
+}
+function rethrowHubError(error) {
+    throw asHubError(error);
+}
+/**
+ * The hub answered — with a result or with a refusal. Either way it is reachable,
+ * which is the only thing this predicate is asked about. A transport failure
+ * carries no reply and answers `false`.
+ */ function hubAnswered(result) {
+    return result.status === 'fulfilled' || result.reason instanceof RequestError;
+}
+/**
+ * Permanent means the hub ANSWERED, not that the call failed: a retention above the
+ * operator's cap is a settled fact about the request, and no reconnect changes it.
+ * Anything else — a dropped socket, a hub mid-restart — is transient, because the
+ * cost of retrying a settled refusal is a busy loop while the cost of not retrying a
+ * transient one is a peer that never comes back.
+ *
+ * Mirrors `isPermanentSubscribeFailure` in `@kumiai/rpc`'s hub mux, which is internal
+ * to that package. Name as well as instance, for the same reason it gives: a host
+ * bundling two copies of hub-protocol would break `instanceof` alone and silently turn
+ * a permanent refusal back into a retry loop.
+ */ function isPermanentSubscribeFailure(error) {
+    return error instanceof RetentionExceededError || error instanceof Error && error.name === 'RetentionExceededError';
+}
+/**
+ * The hub answered "no" on authorization. Keyed on the code, never the message:
+ * a misaddressed token and a caller outside the allowlist arrive under the same
+ * code with different text, and the text is not part of the wire contract.
+ */ function isAccessDenied(error) {
+    return error instanceof RequestError && error.code === ErrorCodes.ACCESS_DENIED;
+}
 /**
  * One independent receive subscriber. The underlying single hub/receive drain
  * fans every decoded message to every active sink; each sink buffers in its own
  * queue and parks a single waiter when drained. Sinks are long-lived across
  * reconnects — only the draining channel is swapped, never the sinks.
  *
- * A sink does NOT filter by topic: topic demux is the mux's job. A message for a
- * topic the sink's mux has no listener for is simply never pulled/acked here.
+ * A sink filters by sender and by topic, and both have to happen here rather
+ * than in a wrapper around the iterator. A sink parks exactly one waiter, so a
+ * layer that filters by calling `next()` on its behalf takes that slot from the
+ * consumer — which is why an iterator-wrapping view starves a directed session
+ * even when it drops nothing.
+ *
+ * A subscriber that asks for neither still gets everything: the group-peer mux
+ * calls `receive(localDID)` unscoped and demuxes topics itself, after the frames
+ * it holds have been decrypted for it. A directed tunnel cannot, which is what
+ * both filters exist for.
  */ class ReceiveSink {
     #queue = [];
     #waiter = null;
     #stopped = false;
+    #senderDID;
+    #topicID;
+    constructor(options){
+        this.#senderDID = options?.senderDID;
+        this.#topicID = options?.topicID;
+    }
     push(message) {
         if (this.#stopped) {
             return;
         }
+        if (this.#senderDID != null && message.senderDID !== this.#senderDID) {
+            return;
+        }
+        if (this.#topicID != null && message.topicID !== this.#topicID) {
+            return;
+        }
         const waiter = this.#waiter;
         if (waiter != null) {
             this.#waiter = null;
@@ -93,6 +162,7 @@ const DISPOSED_SENTINEL = Symbol('disposed');
  */ class HubLikeAdapter {
     #createClient;
     #localDID;
+    #onAccessDenied;
     #logger;
     #ackFlushMs;
     #ackFlushMax;
@@ -101,18 +171,39 @@ const DISPOSED_SENTINEL = Symbol('disposed');
     #backoffJitter;
     #client = null;
     #channel = null;
+    // Why the current `hub/receive` call ended, when it ended by being refused.
+    #channelFailure = null;
     #ackBatch = null;
     #receiveTask = null;
     #controller = new AbortController();
-    #activeTopics = new Set();
+    // Refcounted, not a set: one device drain is shared by the group peer's mux
+    // and by every tunnel session, and several of them hold the same topic at
+    // once. Dropping the topic on the first unsubscribe deafens every other
+    // holder, and the hub has no way to tell them.
+    #activeTopics = new Map();
     #reconnectAttempt = 0;
     // Non-null while a reconnect is in flight. publish/subscribe/unsubscribe wait
     // on it so they bind to the fresh client rather than racing the swap.
     #reconnectGate = null;
+    // True for the duration of one #openInner, on either the first-connect or the
+    // reconnect path — the mutual exclusion #scheduleReconnect enforces.
+    #opening = false;
+    // A reconnect asked for while one was already in flight, replayed once it ends.
+    #reconnectPending = false;
+    // Cuts the current backoff sleep short. Non-null only while the loop is
+    // sleeping, which is also the only time cutting it short means anything.
+    #wakeReconnect = null;
+    // Callers of `retryNow` waiting to hear how the next attempt went.
+    #attemptWaiters = [];
     #opened = false;
+    // Whether the CURRENT connection has evidence behind it: something the hub
+    // answered, or a frame it delivered. Building a client and creating a channel
+    // prove nothing — an HTTP client does no I/O until it writes — so an open with
+    // no evidence must not reset the backoff, or an unreachable hub is redialled at
+    // the base delay for as long as the app runs.
+    #proven = false;
     #openPromise = null;
     #disposed = false;
-    #events = new EventEmitter();
     // Fan-out receive: one underlying hub/receive drain feeds N independent
     // subscriber sinks (group-peer muxes + sync transports share one device DID
     // drain). Each sink owns its queue + waiter; sinks survive reconnects, only
@@ -127,6 +218,7 @@ const DISPOSED_SENTINEL = Symbol('disposed');
     constructor(params){
         this.#createClient = params.createClient;
         this.#localDID = params.localDID;
+        this.#onAccessDenied = params.onAccessDenied;
         this.#logger = params.logger;
         this.#ackFlushMs = params.ackFlushMs ?? DEFAULT_ACK_FLUSH_MS;
         this.#ackFlushMax = params.ackFlushMax ?? DEFAULT_ACK_FLUSH_MAX;
@@ -135,17 +227,16 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         this.#backoffJitter = params.backoffJitter ?? DEFAULT_BACKOFF_JITTER;
     }
     // --- lifecycle events ---
-    events = {
-        subscribe: (listener)=>{
-            return this.#events.on('lifecycle', listener);
-        }
-    };
+    #events = new EventEmitter();
+    get events() {
+        return this.#events;
+    }
     // Subscriber rejections must never break the state machine: emit awaits all
     // listeners and swallows (logs) any that throw, mirroring the older
     // hub-connection lifecycle dispatch.
     async #emit(event) {
         try {
-            await this.#events.emit('lifecycle', event);
+            await this.#events.emit('status', event);
         } catch (error) {
             this.#logger?.warn('hub-like lifecycle subscriber threw', {
                 type: event.type,
@@ -166,19 +257,46 @@ const DISPOSED_SENTINEL = Symbol('disposed');
             await this.#emit({
                 type: 'connected'
             });
+            // The channel this open built ended while it was still being built, so
+            // the connection now reported is already dead. Nothing else retries it:
+            // its drain asked while the open held the exclusion.
+            this.#replayPendingReconnect();
         }).catch((error)=>{
             // Allow a later call to retry the first connect.
             this.#openPromise = null;
+            // And retry it without one. The reconnect loop otherwise only ever
+            // starts from the receive loop's tail, which requires a channel to have
+            // existed — so a device whose FIRST connect fails has no drain and
+            // nothing retrying. A passive co-member booted during a hub outage is
+            // that device: it never publishes, so nothing re-attempts the open on
+            // its behalf, and the bug hides behind any device that also writes.
+            this.#scheduleReconnect();
             throw error;
         });
         this.#openPromise = promise;
         return promise;
     }
     async #openInner() {
+        this.#opening = true;
+        // Any reconnect asked for before this attempt is answered BY this attempt;
+        // only a request raised from here on outlives it.
+        this.#reconnectPending = false;
+        try {
+            await this.#openConnection();
+        } finally{
+            this.#opening = false;
+        }
+    }
+    async #openConnection() {
         // On the reconnect path dispose the prior client so its transport is freed
         // before a fresh one is acquired. dispose is idempotent.
         const previous = this.#client;
         this.#client = null;
+        this.#proven = false;
+        // Detach BEFORE the dispose: disposing a live client ends its drain, and a
+        // drain that still reads as current schedules a reconnect against the
+        // connection replacing it.
+        this.#channel = null;
         if (previous != null) {
             try {
                 await previous.dispose();
@@ -188,16 +306,29 @@ const DISPOSED_SENTINEL = Symbol('disposed');
                 });
             }
         }
-        const client = await this.#createClient();
+        const client = await this.#createClient(this.#controller.signal);
+        if (this.#disposed) {
+            // Disposed while the factory ran: adopting this client would hand the
+            // adapter a live connection nothing will ever close.
+            await client.dispose().catch(()=>{});
+            throw new Error('hub-like adapter disposed');
+        }
         this.#client = client;
-        const channel = client.createChannel('hub/receive', {
+        const channel = client.createChannel('hub/v1/receive', {
             param: {},
             signal: this.#controller.signal
         });
         this.#channel = channel;
         // The channel call is a promise; swallow its rejection so an aborted /
-        // dropped channel never surfaces as an unhandled rejection.
-        void channel.catch(()=>{});
+        // dropped channel never surfaces as an unhandled rejection — and keep the
+        // reason, because a refusal is visible ONLY here: an error reply rejects the
+        // call and closes the readable, so the drain below sees a clean end. The
+        // rejection is queued before that close, so it is recorded by the time the
+        // drain exits.
+        this.#channelFailure = null;
+        void channel.catch((error)=>{
+            this.#channelFailure = error;
+        });
         // A fresh AckBatch means the prior batch's pending acks (if any) were
         // dropped without flushing; clear the dedupe set so the hub's redelivered
         // messages can be acked again on this connection.
@@ -228,24 +359,108 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         // Re-issue hub/subscribe for every active topic. Empty on the first open;
         // on reconnect it re-registers the device's topics with the fresh client.
         const topics = [
-            ...this.#activeTopics
+            ...this.#activeTopics.keys()
         ];
-        if (topics.length > 0) {
-            const results = await Promise.allSettled(topics.map((topicID)=>client.request('hub/subscribe', {
+        if (topics.length === 0) {
+            return;
+        }
+        const results = await Promise.allSettled(topics.map((topicID)=>client.request('hub/v1/subscribe', {
+                param: {
+                    topicID
+                }
+            })));
+        // Not one of them reached the hub, so this connection is a socket to nowhere.
+        // Reporting it open is what used to make an unreachable hub cost a full
+        // connect cycle per base delay: every listener acts on `connected`, every
+        // publish that follows fails, and the drain dies a moment later asking for the
+        // next one. A refusal is NOT this case — the hub answered, which is all the
+        // open needs to know.
+        if (!results.some(hubAnswered)) {
+            const [first] = results;
+            // One line, at debug: this is the hub being away, which the reconnect below
+            // reports once. Warning per topic here is how an unreachable hub used to
+            // cost a warning per topic per attempt.
+            this.#logger?.debug('hub-like open reached no hub', {
+                topics: topics.length
+            });
+            throw first.reason ?? new Error('hub did not answer any subscribe');
+        }
+        this.#proven = true;
+        const failed = [];
+        for(let i = 0; i < results.length; i++){
+            const result = results[i];
+            if (result.status !== 'rejected') {
+                continue;
+            }
+            const topicID = topics[i];
+            const error = asHubError(result.reason);
+            this.#logger?.warn('hub-like re-subscribe failed', {
+                topicID,
+                // An abort carries its reason on the signal, and React Native's
+                // AbortController polyfill has no `reason` — so a torn-down client
+                // rejects with `undefined` and the log says only that it was torn down.
+                error: error ?? 'aborted (no reason)'
+            });
+            if (isPermanentSubscribeFailure(error)) {
+                // Same rule `subscribe` applies: a settled refusal must stop being asked,
+                // or every reconnect for the device's life re-issues it.
+                this.#activeTopics.delete(topicID);
+            } else {
+                failed.push(topicID);
+            }
+        }
+        if (failed.length > 0) {
+            // Nothing re-issues these until the next drop, and a connection can stay up
+            // for hours — so leaving it here is a device that reports itself connected
+            // and receives nothing on those topics. Retried on the live connection
+            // rather than by cycling it: publish and subscribe wait on the reconnect
+            // gate, so a device whose subscribes the hub keeps refusing would go from
+            // deaf to wedged.
+            void this.#retryTopics(client, failed);
+        }
+    }
+    /**
+   * Re-issue subscribes the open could not land, on the connection that failed
+   * them, until they land or that connection is gone. Bounded by the client: a
+   * drop ends this lane, and the reconnect's own re-subscribe takes over.
+   */ async #retryTopics(client, topics) {
+        let pending = topics;
+        let attempt = 0;
+        while(pending.length > 0 && this.#client === client && !this.#disposed){
+            try {
+                await abortableSleep(computeBackoff(attempt++, this.#backoffBaseMs, this.#backoffMaxMs, this.#backoffJitter), this.#controller.signal);
+            } catch  {
+                return;
+            }
+            if (this.#client !== client || this.#disposed) {
+                return;
+            }
+            const results = await Promise.allSettled(pending.map((topicID)=>client.request('hub/v1/subscribe', {
                     param: {
                         topicID
                     }
                 })));
+            const stillFailing = [];
             for(let i = 0; i < results.length; i++){
                 const result = results[i];
-                if (result.status === 'rejected') {
-                    // Keep the topic registered: the next reconnect retries it.
-                    this.#logger?.warn('hub-like re-subscribe failed', {
-                        topicID: topics[i],
-                        error: result.reason
-                    });
+                const topicID = pending[i];
+                if (result.status !== 'rejected') {
+                    continue;
+                }
+                if (isPermanentSubscribeFailure(asHubError(result.reason))) {
+                    this.#activeTopics.delete(topicID);
+                } else if (this.#activeTopics.has(topicID)) {
+                    stillFailing.push(topicID);
                 }
+            // A topic no longer registered was unsubscribed while this lane ran; it
+            // is dropped by falling through both branches.
             }
+            pending = stillFailing;
+        }
+        if (pending.length === 0) {
+            this.#logger?.debug('hub-like re-subscribe recovered', {
+                topics: topics.length
+            });
         }
     }
     async #runReceiveLoop(client, channel) {
@@ -270,9 +485,16 @@ const DISPOSED_SENTINEL = Symbol('disposed');
                     sequenceID: value.sequenceID,
                     senderDID: value.senderDID,
                     topicID: value.topicID,
-                    payload: fromB64(value.payload)
+                    payload: fromB64(value.payload),
+                    // Spread, never assigned: `logPosition: undefined` is a present key, and a
+                    // consumer told the frame HAS a position reads a falsy one and moves its
+                    // durable cursor there — past every log frame below it.
+                    ...value.logPosition != null ? {
+                        logPosition: value.logPosition
+                    } : {}
                 });
                 // A successful read indicates a healthy connection.
+                this.#proven = true;
                 this.#reconnectAttempt = 0;
             }
         } catch (error) {
@@ -287,11 +509,32 @@ const DISPOSED_SENTINEL = Symbol('disposed');
             // ignore
             }
         }
-        if (!this.#controller.signal.aborted && !this.#disposed) {
-            const reason = caughtError instanceof Error && caughtError.message ? caughtError.message : 'receive loop ended';
+        // A superseded drain is not a disconnect: its channel was replaced by a live
+        // one, and reporting it would emit `disconnected` over a healthy connection
+        // and ask for a reconnect that tears that connection down — whose own drain
+        // would then ask again. Unreachable while `#scheduleReconnect`'s exclusion
+        // holds (only a dispose replaces a live client, and that skips this branch);
+        // kept because the failure it prevents is an endless reconnect, not a bug
+        // report.
+        const superseded = this.#channel !== channel;
+        if (!this.#controller.signal.aborted && !this.#disposed && !superseded) {
+            const refusal = caughtError ?? this.#channelFailure;
+            const reason = refusal instanceof Error && refusal.message ? refusal.message : 'receive loop ended';
             this.#logger?.debug('hub-like receive loop ended, scheduling reconnect', {
                 reason
             });
+            // Every connection opens this drain, so a refusal always reaches here.
+            // Awaited before the reconnect is scheduled: the handler may correct the
+            // audience the next dial signs with.
+            if (this.#onAccessDenied != null && isAccessDenied(refusal)) {
+                try {
+                    await this.#onAccessDenied();
+                } catch (error) {
+                    this.#logger?.warn('hub-like access-denied handler failed', {
+                        error
+                    });
+                }
+            }
             // Order is load-bearing: subscribers observe `disconnected` before the
             // reconnect loop's first `reconnecting`. `#emit` awaits subscribers, then
             // `#scheduleReconnect` runs the loop whose first action is a backoff
@@ -303,12 +546,31 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         }
     }
     #scheduleReconnect() {
+        if (this.#disposed || this.#controller.signal.aborted) {
+            return;
+        }
+        // One open at a time. Two overlapping ones each dispose the client the other
+        // just built, which aborts that client's in-flight `hub/v1/subscribe` calls —
+        // and every disposed client's drain asks for another reconnect, so the overlap
+        // sustains itself instead of settling. Recorded rather than dropped: the asking
+        // drain may be the one belonging to the connection being built right now, and
+        // dropping that leaves the adapter reporting a connection whose channel is gone.
+        if (this.#reconnectGate != null || this.#opening) {
+            this.#reconnectPending = true;
+            return;
+        }
         this.#receiveTask = this.#reconnectLoop().catch((error)=>{
             this.#logger?.debug('hub-like reconnect task tail error', {
                 error
             });
         });
     }
+    /** Settle everyone waiting on the outcome of the attempt that just finished. */ #settleAttempt(connected) {
+        const waiters = this.#attemptWaiters.splice(0);
+        for (const waiter of waiters){
+            waiter(connected);
+        }
+    }
     async #reconnectLoop() {
         let resolveGate = ()=>{};
         this.#reconnectGate = new Promise((resolve)=>{
@@ -317,10 +579,22 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         try {
             while(!this.#controller.signal.aborted && !this.#disposed){
                 const delay = computeBackoff(this.#reconnectAttempt++, this.#backoffBaseMs, this.#backoffMaxMs, this.#backoffJitter);
+                // Raced against a wake rather than simply slept: a person who has just
+                // started their hub should not wait out a backoff that has grown to
+                // half a minute, and `retryNow` is how they say so.
+                const wake = new Promise((resolve)=>{
+                    this.#wakeReconnect = resolve;
+                });
                 try {
-                    await abortableSleep(delay, this.#controller.signal);
+                    await Promise.race([
+                        abortableSleep(delay, this.#controller.signal),
+                        wake
+                    ]);
                 } catch  {
+                    this.#settleAttempt(false);
                     return;
+                } finally{
+                    this.#wakeReconnect = null;
                 }
                 if (this.#disposed) {
                     return;
@@ -333,7 +607,17 @@ const DISPOSED_SENTINEL = Symbol('disposed');
                     this.#ackBatch = null;
                     this.#channel = null;
                     await this.#openInner();
-                    this.#reconnectAttempt = 0;
+                    // A reconnect that follows a failed FIRST connect is the open: without
+                    // this the adapter still reads as never-opened, and the next
+                    // `#ensureOpen` would tear this live connection down to build another.
+                    this.#opened = true;
+                    // Only a connection the hub answered starts the next outage's backoff
+                    // from scratch. An open with nothing behind it (a device holding no
+                    // topics yet) leaves the counter climbing, so the redials keep spacing
+                    // out even though each one "succeeds".
+                    if (this.#proven) {
+                        this.#reconnectAttempt = 0;
+                    }
                     // Emit before resolving the gate so awaiters observe `connected`
                     // before their queued publish/subscribe resumes.
                     await this.#emit({
@@ -341,24 +625,84 @@ const DISPOSED_SENTINEL = Symbol('disposed');
                     });
                     return;
                 } catch (error) {
-                    this.#logger?.warn('hub-like reconnect attempt failed', {
+                    // The first failure of an outage is news; the rest are the backoff
+                    // working, and a hub left off overnight would otherwise fill the log
+                    // with the same line. Reported again the moment it reconnects.
+                    const context = {
                         attempt: this.#reconnectAttempt,
                         error
-                    });
+                    };
+                    if (this.#reconnectAttempt === 1) {
+                        this.#logger?.warn('hub-like reconnect attempt failed', context);
+                    } else {
+                        this.#logger?.debug('hub-like reconnect attempt failed', context);
+                    }
+                    this.#settleAttempt(false);
                 }
             }
         } finally{
             this.#reconnectGate = null;
             resolveGate();
+            // Settled here rather than at the moment the open succeeded: a caller told
+            // "connected" while the gate is still up would have its very next publish
+            // refused as "a reconnect is in progress". Also catches waiters parked past
+            // the end of the loop, whose promise no attempt would otherwise settle.
+            this.#settleAttempt(this.#opened && this.#client != null);
+            this.#replayPendingReconnect();
+        }
+    }
+    /**
+   * Answer a reconnect asked for while an open held the exclusion — typically by
+   * the drain of the connection that open was building, which ended before it
+   * finished. Deferred a turn rather than started here: `publish`/`subscribe` park
+   * on the gate this loop just resolved, and starting the next loop synchronously
+   * would take a fresh gate before any of them resumed.
+   */ #replayPendingReconnect() {
+        if (!this.#reconnectPending || this.#disposed || this.#controller.signal.aborted) {
+            return;
         }
+        setTimeout(()=>{
+            this.#scheduleReconnect();
+        }, 0);
     }
-    async #ready() {
+    /**
+   * The live client, or an error — never a connection this call opened while a
+   * reconnect was already in flight.
+   *
+   * That loop owns the dialling and paces it on a backoff. An operation that
+   * opens on its own account is paced by nothing, so a device whose hub is not
+   * answering re-dials once per publish and logs each one, which is the entire
+   * cost the backoff exists to bound.
+   *
+   * What a caller gets while the loop is running depends on whether this adapter
+   * has ever been connected, and the two cases are genuinely different:
+   *
+   * - **Connected before.** A live setup is being repaired, so the operation
+   *   WAITS. That is what makes a commit made while the hub is away park and land
+   *   when it returns — the invite lane is built on it.
+   * - **Never connected.** There is no setup to repair and no reason to believe
+   *   the next attempt is the one that works. Waiting here hangs whoever is
+   *   bringing a lane up — a device starting while its hub is off — for as long
+   *   as the hub stays away, so the answer is "not now" and the loop keeps trying.
+   */ async #ready() {
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        if (this.#reconnectGate != null && !this.#opened) {
+            throw new Error('hub not connected: a reconnect is in progress');
+        }
+        while(this.#reconnectGate != null){
+            await this.#reconnectGate;
+        }
         if (this.#disposed) {
             throw new Error('hub-like adapter disposed');
         }
+        // Only now, with nothing else retrying: this is the caller that starts the
+        // first dial after a connection is lost, and the loop it schedules is what
+        // paces every caller behind it.
         await this.#ensureOpen();
-        // Wait out any in-flight reconnect so the operation binds to the fresh
-        // client. A new reconnect may begin after this resolves; loop until clear.
+        // Wait out a reconnect that began while the open ran, so the operation binds
+        // to the fresh client rather than to one being torn down.
         while(this.#reconnectGate != null){
             await this.#reconnectGate;
         }
@@ -371,8 +715,37 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         }
         return client;
     }
+    /**
+   * Try the hub now instead of when the backoff says so, and answer with whether
+   * that attempt connected.
+   *
+   * For the person who just started the hub the app has been failing to reach:
+   * the backoff has grown to tens of seconds by then, and waiting it out looks
+   * exactly like the app being broken. The attempt counter resets too, so a
+   * manual retry that fails leaves the automatic ones starting small again
+   * rather than resuming at the ceiling.
+   */ retryNow = async ()=>{
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        if (this.#reconnectGate == null && this.#opened && this.#client != null) {
+            return true;
+        }
+        const attempt = new Promise((resolve)=>{
+            this.#attemptWaiters.push(resolve);
+        });
+        this.#reconnectAttempt = 0;
+        if (this.#reconnectGate == null) {
+            // Nothing is retrying — a first connect that failed and left no loop, or a
+            // device that has never dialled. Start one; its first sleep is the base
+            // delay, which the wake below cuts short.
+            this.#scheduleReconnect();
+        }
+        this.#wakeReconnect?.();
+        return await attempt;
+    };
     // --- HubLike surface ---
-    publish = async ({ senderDID, topicID, payload })=>{
+    publish = async ({ senderDID, topicID, payload, retain, expectedHead, publishID })=>{
         if (senderDID !== this.#localDID) {
             // The hub derives the sender from the signed `iss`; a mismatch here means
             // a caller stamped the wrong DID. The publish still uses this device's
@@ -383,39 +756,149 @@ const DISPOSED_SENTINEL = Symbol('disposed');
             });
         }
         const client = await this.#ready();
-        const result = await client.request('hub/publish', {
+        // The log-class fields (`retain`, `expectedHead`, `publishID`) ride through to
+        // the wire so a caller can drive the CAS commit lane; a mailbox publish simply
+        // leaves them undefined.
+        const result = await client.request('hub/v1/publish', {
             param: {
                 topicID,
-                payload: toB64(payload)
+                payload: toB64(payload),
+                retain,
+                expectedHead,
+                publishID
             }
-        });
+        }).catch(rethrowHubError);
         return {
             sequenceID: result.sequenceID
         };
     };
-    subscribe = async (_subscriberDID, topicID)=>{
+    fetchTopic = async ({ topicID, after, limit })=>{
+        // The hub gates the read on subscription and derives the caller from the
+        // signed `iss`, so `subscriberDID` is never a wire field.
         const client = await this.#ready();
-        this.#activeTopics.add(topicID);
-        await client.request('hub/subscribe', {
+        const result = await client.request('hub/v1/topic/fetch', {
             param: {
-                topicID
+                topicID,
+                after,
+                limit
             }
-        });
+        }).catch(rethrowHubError);
+        return {
+            messages: result.messages.map((message)=>({
+                    sequenceID: message.sequenceID,
+                    senderDID: message.senderDID,
+                    topicID: message.topicID,
+                    payload: fromB64(message.payload),
+                    // Derived, not carried: the fetch reply has no such field and needs none. A
+                    // topic's log holds log-class frames and nothing else, and the position this
+                    // reply serves a frame at IS the sequenceID it serves it under — the value
+                    // `after`, `head` and `oldest` are compared against.
+                    logPosition: message.sequenceID
+                })),
+            head: result.head,
+            oldest: result.oldest
+        };
+    };
+    subscribe = async (_subscriberDID, topicID, options)=>{
+        // A subscription is a DECLARATION, not an operation: the adapter re-issues
+        // every registered topic on the next connection, so registering it is the
+        // whole of what a caller needs. Parking here instead — as a publish does,
+        // because a publish has to actually reach the hub — would hang the caller
+        // standing a group's lane up for as long as the hub stays away, and that
+        // caller is usually a device starting while its hub is off.
+        if (this.#reconnectGate != null) {
+            this.#retainTopic(topicID);
+            return;
+        }
+        const client = await this.#ready();
+        try {
+            await client.request('hub/v1/subscribe', {
+                param: {
+                    topicID,
+                    retention: options?.retention
+                }
+            });
+        } catch (error) {
+            // Registration follows ACCEPTANCE, with one exception. The reconnect path
+            // re-issues every registered topic, so a transient failure has to stay
+            // registered or the reconnect that would heal it never asks again. A permanent
+            // refusal must not: it would be re-issued on every reconnect for the peer's
+            // whole life, each time answered the same way and logged as a warning nobody
+            // reads. Classified on the REBUILT error, since the refusal crosses the wire as
+            // a code and the classifier matches the class.
+            const hubError = asHubError(error);
+            // The hub never answered, so there is nothing for the caller to learn and
+            // nothing for it to do: the reconnect re-issues every registered topic, and
+            // this one is now registered. Throwing here reaches a mux that floats the
+            // rejection, and one dropped transport turns into one unhandled rejection
+            // per topic the device holds.
+            if (!(error instanceof RequestError)) {
+                this.#armTopic(topicID);
+                this.#logger?.debug('hub-like subscribe deferred to the next connection', {
+                    topicID,
+                    error
+                });
+                return;
+            }
+            if (!isPermanentSubscribeFailure(hubError)) {
+                // Registered at zero holders, NOT retained: this caller is being told the
+                // subscribe failed, so it holds nothing and will not unsubscribe. Counting
+                // it as a holder here and again when it retries leaves a count no
+                // unsubscribe can drain, and "only the last holder tells the hub" then
+                // means the hub is never told at all.
+                this.#armTopic(topicID);
+            }
+            throw hubError;
+        }
+        this.#retainTopic(topicID);
     };
     unsubscribe = async (_subscriberDID, topicID)=>{
+        // Released locally while disconnected, for the same reason: the hub holds no
+        // subscription to forget — the reconnect re-issues only what is registered
+        // when it lands, and this topic will not be.
+        if (this.#reconnectGate != null) {
+            const held = (this.#activeTopics.get(topicID) ?? 0) - 1;
+            if (held > 0) {
+                this.#activeTopics.set(topicID, held);
+            } else {
+                this.#activeTopics.delete(topicID);
+            }
+            return;
+        }
         const client = await this.#ready();
+        // Only the last holder tells the hub. An untracked topic is released rather
+        // than ignored: a caller unsubscribing something this adapter never armed is
+        // asking the hub to forget a subscription it may still hold from a previous
+        // process, and swallowing that would leave the device drained by nobody.
+        const remaining = (this.#activeTopics.get(topicID) ?? 0) - 1;
+        if (remaining > 0) {
+            this.#activeTopics.set(topicID, remaining);
+            return;
+        }
         this.#activeTopics.delete(topicID);
-        await client.request('hub/unsubscribe', {
+        await client.request('hub/v1/unsubscribe', {
             param: {
                 topicID
             }
-        });
+        }).catch(rethrowHubError);
     };
-    receive = (_subscriberDID)=>{
+    #retainTopic(topicID) {
+        this.#activeTopics.set(topicID, (this.#activeTopics.get(topicID) ?? 0) + 1);
+    }
+    /**
+   * Register a topic for re-issue on the next connection without counting a
+   * holder for it. A zero-count entry is re-subscribed like any other — the
+   * reconnect reads the keys — and is released by the first `unsubscribe`.
+   */ #armTopic(topicID) {
+        if (!this.#activeTopics.has(topicID)) {
+            this.#activeTopics.set(topicID, 0);
+        }
+    }
+    receive = (_subscriberDID, options)=>{
         if (this.#disposed) {
             throw new Error('hub-like adapter disposed');
         }
-        const sink = new ReceiveSink();
+        const sink = new ReceiveSink(options);
         this.#sinks.add(sink);
         // The first receive() brings the connection up so the drain has a channel to
         // read from; later calls are idempotent. A late subscriber registers its
@@ -508,11 +991,10 @@ const DISPOSED_SENTINEL = Symbol('disposed');
         } catch  {
         // ignore
         }
-        try {
-            await this.#receiveTask;
-        } catch  {
-        // ignore
-        }
+        // And drop the client BEFORE that await, not after. The task may be the
+        // reconnect loop rather than a drain, and a loop parked inside an open is
+        // waiting on requests that settle only when their client is disposed — so
+        // awaiting the task first is a dispose that waits on itself.
         const client = this.#client;
         this.#client = null;
         if (client != null) {
@@ -524,6 +1006,11 @@ const DISPOSED_SENTINEL = Symbol('disposed');
                 });
             }
         }
+        try {
+            await this.#receiveTask;
+        } catch  {
+        // ignore
+        }
         this.#channel = null;
         this.#receiveTask = null;
         this.#activeTopics.clear();