@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/hub/hub-like.js

@@ -0,0 +1,1022 @@
+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;
+// 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 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;
+            waiter({
+                value: message,
+                done: false
+            });
+            return;
+        }
+        this.#queue.push(message);
+    }
+    next() {
+        if (this.#queue.length > 0) {
+            const value = this.#queue.shift();
+            return Promise.resolve({
+                value,
+                done: false
+            });
+        }
+        if (this.#stopped) {
+            return Promise.resolve({
+                value: undefined,
+                done: true
+            });
+        }
+        return new Promise((resolve)=>{
+            this.#waiter = resolve;
+        });
+    }
+    // Ends this sink only. Resolves a parked waiter as done and drops any buffer;
+    // the shared drain + connection keep running for the remaining sinks.
+    stop() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#queue = [];
+        const waiter = this.#waiter;
+        if (waiter != null) {
+            this.#waiter = null;
+            waiter({
+                value: undefined,
+                done: true
+            });
+        }
+    }
+}
+/**
+ * A single reconnecting `HubLike` over one `Client<HubProtocol>`, one per
+ * (deviceDID, hubURL). It does NOT demultiplex topics or hold per-group
+ * mutexes — group-rpc's `createHubMux` already fans the single `hub.receive`
+ * drain across topics and refcounts subscribe/unsubscribe on top of this view.
+ *
+ * Connection is established lazily on the first `publish` / `subscribe` /
+ * `receive`. A mux calls `receive(localDID)` once at construction and
+ * `subscribe(localDID, topicID)` as topics are retained, so the first of those
+ * brings the client + `hub/receive` channel up.
+ *
+ * `receive()` may be called more than once: one device runs one GroupPeer per
+ * group plus directed sync transports, and the hub delivers each message to a
+ * DID exactly once, so there must be exactly one underlying `hub/receive` drain
+ * per device DID, demultiplexed client-side by topic. Each `receive()` returns
+ * its own independent subscription (sink); the single drain fans every decoded
+ * message to every active sink. Sinks are long-lived across reconnects while
+ * only the underlying channel is swapped, so every iterable keeps yielding
+ * through transport drops. Acks are deduped so the hub is acked at most once per
+ * sequenceID regardless of how many sinks ack it.
+ */ class HubLikeAdapter {
+    #createClient;
+    #localDID;
+    #onAccessDenied;
+    #logger;
+    #ackFlushMs;
+    #ackFlushMax;
+    #backoffBaseMs;
+    #backoffMaxMs;
+    #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();
+    // 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;
+    // 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
+    // the draining channel is replaced.
+    #sinks = new Set();
+    // Ack dedupe: ack the hub at most once per sequenceID across all sinks. Holds
+    // sequenceIDs fed to the current AckBatch but not yet flushed; pruned when the
+    // batch flushes (see the send wrapper in #openInner) and cleared whenever the
+    // AckBatch is reset on reconnect/dispose so redelivered messages can re-ack.
+    // Bounded by the in-flight (unflushed) ack count.
+    #ackedPending = new Set();
+    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;
+        this.#backoffBaseMs = params.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+        this.#backoffMaxMs = params.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS;
+        this.#backoffJitter = params.backoffJitter ?? DEFAULT_BACKOFF_JITTER;
+    }
+    // --- lifecycle events ---
+    #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('status', event);
+        } catch (error) {
+            this.#logger?.warn('hub-like lifecycle subscriber threw', {
+                type: event.type,
+                error
+            });
+        }
+    }
+    // --- connection setup ---
+    #ensureOpen() {
+        if (this.#opened) {
+            return Promise.resolve();
+        }
+        if (this.#openPromise != null) {
+            return this.#openPromise;
+        }
+        const promise = this.#openInner().then(async ()=>{
+            this.#opened = true;
+            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();
+            } catch (error) {
+                this.#logger?.debug('hub-like previous client dispose failed', {
+                    error
+                });
+            }
+        }
+        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/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 — 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.
+        this.#ackedPending.clear();
+        this.#ackBatch = new AckBatch({
+            flushMs: this.#ackFlushMs,
+            flushMax: this.#ackFlushMax,
+            send: async (ids)=>{
+                try {
+                    await channel.send({
+                        ack: ids
+                    });
+                } finally{
+                    // Forget flushed sequenceIDs so the dedupe set stays bounded; a future
+                    // redelivery (after reconnect) is then free to ack again.
+                    for (const id of ids){
+                        this.#ackedPending.delete(id);
+                    }
+                }
+            },
+            logger: this.#logger
+        });
+        this.#receiveTask = this.#runReceiveLoop(client, channel).catch((error)=>{
+            this.#logger?.debug('hub-like receive task tail error', {
+                error
+            });
+        });
+        // 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.keys()
+        ];
+        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];
+                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) {
+        const reader = channel.readable.getReader();
+        let caughtError = null;
+        try {
+            while(!this.#controller.signal.aborted){
+                const readPromise = reader.read();
+                const disposedPromise = client.disposed.then(()=>DISPOSED_SENTINEL);
+                const raceResult = await Promise.race([
+                    readPromise,
+                    disposedPromise
+                ]);
+                if (typeof raceResult === 'symbol') {
+                    break;
+                }
+                const { done, value } = raceResult;
+                if (done) {
+                    break;
+                }
+                this.#pushMessage({
+                    sequenceID: value.sequenceID,
+                    senderDID: value.senderDID,
+                    topicID: value.topicID,
+                    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) {
+            caughtError = error;
+            this.#logger?.warn('hub-like receive loop error', {
+                error
+            });
+        } finally{
+            try {
+                reader.releaseLock();
+            } catch  {
+            // ignore
+            }
+        }
+        // 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
+            // sleep, so there is no observable interleaving.
+            await this.#emit({
+                type: 'disconnected'
+            });
+            this.#scheduleReconnect();
+        }
+    }
+    #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)=>{
+            resolveGate = resolve;
+        });
+        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 Promise.race([
+                        abortableSleep(delay, this.#controller.signal),
+                        wake
+                    ]);
+                } catch  {
+                    this.#settleAttempt(false);
+                    return;
+                } finally{
+                    this.#wakeReconnect = null;
+                }
+                if (this.#disposed) {
+                    return;
+                }
+                await this.#emit({
+                    type: 'reconnecting'
+                });
+                try {
+                    this.#ackBatch?.dispose();
+                    this.#ackBatch = null;
+                    this.#channel = null;
+                    await this.#openInner();
+                    // 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({
+                        type: 'connected'
+                    });
+                    return;
+                } catch (error) {
+                    // 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);
+    }
+    /**
+   * 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 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;
+        }
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        const client = this.#client;
+        if (client == null) {
+            throw new Error('hub-like adapter not connected');
+        }
+        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, 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
+            // identity, so surface it as a warning rather than a hard failure.
+            this.#logger?.warn('hub-like publish senderDID does not match localDID', {
+                senderDID,
+                localDID: this.#localDID
+            });
+        }
+        const client = await this.#ready();
+        // 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),
+                retain,
+                expectedHead,
+                publishID
+            }
+        }).catch(rethrowHubError);
+        return {
+            sequenceID: result.sequenceID
+        };
+    };
+    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();
+        const result = await client.request('hub/v1/topic/fetch', {
+            param: {
+                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/v1/unsubscribe', {
+            param: {
+                topicID
+            }
+        }).catch(rethrowHubError);
+    };
+    #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(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
+        // sink before this resolves, so no in-flight message is lost to it. Failures
+        // surface through lifecycle events + retry.
+        void this.#ensureOpen().catch((error)=>{
+            this.#logger?.warn('hub-like open on receive failed', {
+                error
+            });
+        });
+        // Removing one sink ends only that subscription; the shared drain,
+        // connection and AckBatch persist while any other sink remains. Full
+        // teardown happens only via the adapter's dispose().
+        const removeSink = ()=>{
+            if (this.#sinks.delete(sink)) {
+                sink.stop();
+            }
+        };
+        const iterator = {
+            next: ()=>sink.next(),
+            return: ()=>{
+                removeSink();
+                return Promise.resolve({
+                    value: undefined,
+                    done: true
+                });
+            }
+        };
+        return {
+            [Symbol.asyncIterator]: ()=>iterator,
+            return: ()=>{
+                removeSink();
+            },
+            ack: (sequenceID)=>{
+                // Dedupe across all sinks: the first ack for a sequenceID feeds the
+                // shared AckBatch; repeats (same or another sink) are no-ops until the
+                // batch flushes and prunes it. If no batch is live (mid-reconnect), skip
+                // recording so a post-reconnect re-ack still reaches the hub.
+                if (this.#ackedPending.has(sequenceID)) {
+                    return;
+                }
+                const ackBatch = this.#ackBatch;
+                if (ackBatch == null) {
+                    return;
+                }
+                this.#ackedPending.add(sequenceID);
+                ackBatch.add(sequenceID);
+            }
+        };
+    };
+    // Fan the decoded message out to every active sink. Sinks whose mux has no
+    // listener for the topic simply never pull/ack it; that is expected and the
+    // hub redelivers such messages on reconnect.
+    #pushMessage(message) {
+        if (this.#disposed) {
+            return;
+        }
+        for (const sink of this.#sinks){
+            sink.push(message);
+        }
+    }
+    // --- disposal ---
+    dispose = async ()=>{
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#controller.abort();
+        // End every subscription: stop each sink (resolving parked waiters as done)
+        // and drop them. New receive() calls are rejected once disposed.
+        for (const sink of this.#sinks){
+            sink.stop();
+        }
+        this.#sinks.clear();
+        const ackBatch = this.#ackBatch;
+        this.#ackBatch = null;
+        if (ackBatch != null) {
+            try {
+                await ackBatch.flush();
+            } catch (error) {
+                this.#logger?.debug('hub-like ack flush during dispose failed', {
+                    error
+                });
+            }
+            ackBatch.dispose();
+        }
+        // Close the channel before awaiting the receive task so the reader unblocks.
+        try {
+            this.#channel?.close();
+        } 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) {
+            try {
+                await client.dispose();
+            } catch (error) {
+                this.#logger?.debug('hub-like client dispose failed', {
+                    error
+                });
+            }
+        }
+        try {
+            await this.#receiveTask;
+        } catch  {
+        // ignore
+        }
+        this.#channel = null;
+        this.#receiveTask = null;
+        this.#activeTopics.clear();
+        this.#ackedPending.clear();
+    };
+}
+export function createHubLike(params) {
+    return new HubLikeAdapter(params);
+}