js-bao-wss-client 2.2.0-alpha.3 → 2.2.0-alpha.4

package/dist/JsBaoClient.d.ts

@@ -93,7 +93,7 @@ export type { DocumentDebugSnapshot, DocumentPermission, LocalDocumentEntry, Loc
 export type { LogLevel } from "./internal/logger";
 export type { RequestOptions } from "./internal/httpClient";
 export type { LocksAPI } from "./api/locksApi";
-export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionStartOptions, FunctionStartResult, FunctionRunRef, } from "./api/functionsApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, } from "./api/functionsApi";
 export type { LockHandle, LockContention, AcquireResponse, AcquireOptions, BlockingAcquireOptions, ReleaseResult, RenewResult, LockStatus, LockListEntry, LockListResult, } from "./api/locksApi";
 export type { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 export type { ResourceMetadataReadResult, ResourceMetadataWriteResult, ResourceMetadataBatchRequestItem, ResourceMetadataBatchParams, ResourceMetadataBatchCategoryResult, ResourceMetadataBatchResourceResult, ResourceMetadataBatchResult, ResourceMetadataListEntry, ResourceMetadataListResult, ResourceMetadataDeleteResult, ResourceMetadataResolveParams, ResourceMetadataResolveResult, } from "./api/resourceMetadataApi";
@@ -884,6 +884,62 @@ export interface DirectMessageEvent {
     /** When the platform sent it, ISO 8601. */
     sentAt: string;
 }
+/**
+ * A message a server function published to a channel this client has joined.
+ *
+ * Emitted over the `channelMessage` event channel
+ * (`client.on("channelMessage", ...)`) for every channel this client holds a
+ * live membership in — the `channel` field says which. `payload` is the
+ * function's own value, passed through unread by the platform.
+ *
+ * Like {@link DirectMessageEvent} it is a LIVE frame with no durable record
+ * behind it, and `functionKey` is its only attribution: a function publishing
+ * from a database-change trigger runs as the app and acts for no user.
+ */
+export interface ChannelMessageEvent {
+    type: "channel.message";
+    channel: string;
+    payload: unknown;
+    functionKey: string;
+    /** When the platform sent it, ISO 8601. */
+    sentAt: string;
+}
+/**
+ * A live channel membership, returned by
+ * {@link JsBaoClient.subscribeToChannel}.
+ *
+ * `expiresAt` is epoch milliseconds and is the membership's whole lifetime:
+ * expiry is the only revocation a channel grant has, so past it the server
+ * stops delivering even though this socket stays open. Renewing means asking
+ * the authorizing function for another grant and subscribing again — which
+ * replaces this membership rather than adding one.
+ */
+export interface ChannelSubscription {
+    channel: string;
+    expiresAt: number;
+    /** Leave the channel. Idempotent. */
+    unsubscribe: () => void;
+}
+/**
+ * A channel subscription the server refused when nothing was waiting on it.
+ *
+ * Emitted over the `channelSubscribeFailed` event channel
+ * (`client.on("channelSubscribeFailed", ...)`). The case this exists for is
+ * RECONNECT: after the socket comes back the client presents each held grant
+ * again, and a grant that expired while the connection was down is refused with
+ * no pending call to reject. The registration for that channel — and only that
+ * channel — is dropped, and this is how an app hears about it, so it can ask
+ * its authorizing function for a fresh grant and subscribe again.
+ *
+ * A refusal that answers a {@link JsBaoClient.subscribeToChannel} call is
+ * reported by rejecting that promise instead, so a failure is never announced
+ * twice. `message` is the server's uniform refusal: an expired, tampered,
+ * cross-app or cross-user grant are deliberately indistinguishable.
+ */
+export interface ChannelSubscribeFailedEvent {
+    channel: string;
+    message: string;
+}
 /**
  * Payload of the `workflowStatus` event (`client.on("workflowStatus", ...)`).
  * Delivered in real time when a workflow run started by this user reaches a
@@ -1562,6 +1618,8 @@ export interface JsBaoEvents {
     meUpdateFailed: MeUpdateFailedEvent;
     notification: NotificationEvent;
     directMessage: DirectMessageEvent;
+    channelMessage: ChannelMessageEvent;
+    channelSubscribeFailed: ChannelSubscribeFailedEvent;
     workflowStatus: WorkflowStatusEvent;
     workflowStarted: WorkflowStartedEvent;
     syncPerf: {
@@ -1919,6 +1977,50 @@ export declare class JsBaoClient extends Observable<any> {
     /** Registry of active database subscriptions — routes inbound `db.change`
      *  frames to the right callback and drives reconnect re-subscribe. */
     private dbSubscriptions;
+    /**
+     * Channel memberships this client is holding, `channel → grant` (#3184).
+     *
+     * The GRANT is stored, not just the channel, because a membership is keyed
+     * by a connection: after a reconnect the server has no record of it, and the
+     * only thing that re-establishes one is presenting the credential again. A
+     * grant that has expired in the meantime is refused, and the refusal drops
+     * exactly that channel's registration.
+     */
+    private channelGrants;
+    /**
+     * Subscribes waiting for their own channel's ack (D3184-007).
+     *
+     * `sent` records whether the frame this call is waiting on ever reached the
+     * wire — R3184-002. A subscribe made before the socket opened registers its
+     * grant and nudges the connection, but sends nothing; the open handler has
+     * to send THAT attempt rather than queue a second one behind it, or the
+     * caller waits out the full 20 s timeout on a connection that came up
+     * immediately.
+     */
+    private pendingChannelSubscribes;
+    /**
+     * How many times this channel has been left — R3184-005.
+     *
+     * A subscribe queued behind an in-flight one is a continuation that has not
+     * run yet, and `unsubscribeFromChannel` cannot cancel a `.then`. Without a
+     * generation, leaving a channel while a renewal was queued would run that
+     * renewal afterwards: the registration would come back, a subscribe would go
+     * out, and the client would be delivered to on a channel it had explicitly
+     * left. Each attempt captures the count it was created under and does
+     * nothing if it has moved.
+     */
+    private channelEpochs;
+    /**
+     * One subscribe at a time per channel — CR3184-004.
+     *
+     * The server answers a subscribe with a frame that names the CHANNEL and
+     * nothing finer, which is what lets subscriptions to DIFFERENT channels be
+     * told apart. Two requests for the SAME channel cannot be: the first answer
+     * would settle both, so an expired grant racing a renewal would reject the
+     * renewal too and drop a registration the server had accepted. Chaining them
+     * keeps every answer attributable to the request that asked for it.
+     */
+    private channelSubscribeChain;
     /** Sub-API for managing documents (list, create, get, delete, share).
      * @group Sub-APIs */
     documents: DocumentsAPI;
@@ -3072,6 +3174,94 @@ export declare class JsBaoClient extends Observable<any> {
     /** Check if an offline grant is stored locally.
      * @group Offline & Sync */
     hasOfflineGrantStored(): Promise<boolean>;
+    /**
+     * Join a channel a server function authorized.
+     *
+     * `grant` is the token `ctx.channels.authorize` handed back: a signed,
+     * short-lived credential naming this app, this channel and this user. The
+     * promise resolves on the server's ack FOR THIS CHANNEL, so concurrent
+     * subscribes cannot resolve each other, and rejects on the server's uniform
+     * refusal — an expired, tampered, cross-app or cross-user grant are
+     * deliberately indistinguishable, so the rejection says only that the grant
+     * was not accepted.
+     *
+     * Calling it again with a fresh grant RENEWS the membership: expiry is the
+     * only revocation a channel has, so an app that wants a long-lived channel
+     * re-invokes its authorizing function before `expiresAt` and subscribes
+     * again. Frames arrive as `client.on("channelMessage", …)`.
+     *
+     * Two calls for the SAME channel run one after the other, so a renewal
+     * issued while an earlier subscribe is still in flight is answered on its own
+     * merits rather than by whichever frame arrives first.
+     *
+     * @group Realtime
+     */
+    subscribeToChannel(channel: string, grant: string): Promise<ChannelSubscription>;
+    /** The generation `unsubscribeFromChannel` bumps — R3184-005. */
+    private channelEpoch;
+    /**
+     * Re-present a stored grant after a reconnect — through the SAME chain an
+     * explicit subscribe uses (SO3184-006).
+     *
+     * The reconnect pass used to write straight to the socket, which put an
+     * attempt on the wire that the per-channel bookkeeping knew nothing about.
+     * The server's answer names the channel and nothing finer, so a refusal of
+     * the re-issued (possibly expired) grant would settle a RENEWAL the app made
+     * in the meantime: the fresh subscribe would reject and its registration
+     * would be deleted, while the server had accepted it and was delivering to
+     * it. Chaining keeps every answer attributable to the request that asked for
+     * it, exactly as `subscribeToChannel` does.
+     *
+     * Nobody is waiting on this one, so its refusal is announced as
+     * `channelSubscribeFailed` (CR3184-005) rather than rejecting a promise.
+     */
+    private reissueChannelSubscribe;
+    /**
+     * Give up on every subscribe waiting for an answer, because the socket that
+     * would have carried it is gone (SO3184-006).
+     *
+     * The GRANTS stay: the socket failed, not the credential, and the reconnect
+     * pass presents each one again. What must not stay is a pending attempt —
+     * its answer can never arrive, and leaving it in the per-channel chain would
+     * hold the re-issue behind it for the full 20 s timeout.
+     */
+    private abortPendingChannelSubscribes;
+    private startChannelSubscribe;
+    /**
+     * Put the subscribes that never reached the wire onto it — R3184-002.
+     *
+     * A call made while the socket was down registered its grant, created its
+     * promise and sent nothing. On open its frame is sent for the attempt that
+     * is already waiting, so the ack settles the original call. Channels with
+     * nothing pending go the other way, through the ordinary re-issue.
+     *
+     * Returns the channels it sent for, so the reconnect pass does not queue a
+     * second attempt for them.
+     */
+    private flushUnsentChannelSubscribes;
+    /**
+     * Leave a channel. Idempotent, and safe on a closed socket: the
+     * registration goes either way, so a reconnect does not bring it back.
+     *
+     * A subscribe still in flight, or queued behind one, is cancelled with it:
+     * leaving means leaving, so a queued renewal cannot put the membership back
+     * afterwards, and a `subscribeToChannel` promise still waiting for its ack
+     * rejects rather than resolving with a subscription to a channel this client
+     * has already left.
+     *
+     * @group Realtime
+     */
+    unsubscribeFromChannel(channel: string): void;
+    private sendChannelSubscribe;
+    /**
+     * Settle every call waiting on one channel — with the ack, or with the
+     * refusal. Only that channel's waiters and only that channel's
+     * registration: a client with several subscriptions must not lose the ones
+     * that worked (D3184-007).
+     */
+    private settleChannelSubscribe;
+    private handleChannelSubscribed;
+    private handleChannelMessage;
     /**
      * Internal entry point for DatabasesAPI.subscribe(). Ensures the WS is
      * connected, registers the callback with the registry, sends the

package/dist/JsBaoClient.js

@@ -547,6 +547,50 @@ export class JsBaoClient extends Observable {
         this.serviceWorkerBridgeLastToken = null;
         this.pendingSelfRemovalDocs = new Set();
         this.pendingSelfRemovalTimers = new Map();
+        /**
+         * Channel memberships this client is holding, `channel → grant` (#3184).
+         *
+         * The GRANT is stored, not just the channel, because a membership is keyed
+         * by a connection: after a reconnect the server has no record of it, and the
+         * only thing that re-establishes one is presenting the credential again. A
+         * grant that has expired in the meantime is refused, and the refusal drops
+         * exactly that channel's registration.
+         */
+        this.channelGrants = new Map();
+        /**
+         * Subscribes waiting for their own channel's ack (D3184-007).
+         *
+         * `sent` records whether the frame this call is waiting on ever reached the
+         * wire — R3184-002. A subscribe made before the socket opened registers its
+         * grant and nudges the connection, but sends nothing; the open handler has
+         * to send THAT attempt rather than queue a second one behind it, or the
+         * caller waits out the full 20 s timeout on a connection that came up
+         * immediately.
+         */
+        this.pendingChannelSubscribes = new Map();
+        /**
+         * How many times this channel has been left — R3184-005.
+         *
+         * A subscribe queued behind an in-flight one is a continuation that has not
+         * run yet, and `unsubscribeFromChannel` cannot cancel a `.then`. Without a
+         * generation, leaving a channel while a renewal was queued would run that
+         * renewal afterwards: the registration would come back, a subscribe would go
+         * out, and the client would be delivered to on a channel it had explicitly
+         * left. Each attempt captures the count it was created under and does
+         * nothing if it has moved.
+         */
+        this.channelEpochs = new Map();
+        /**
+         * One subscribe at a time per channel — CR3184-004.
+         *
+         * The server answers a subscribe with a frame that names the CHANNEL and
+         * nothing finer, which is what lets subscriptions to DIFFERENT channels be
+         * told apart. Two requests for the SAME channel cannot be: the first answer
+         * would settle both, so an expired grant racing a renewal would reject the
+         * renewal too and drop a registration the server had accepted. Chaining them
+         * keeps every answer attributable to the request that asked for it.
+         */
+        this.channelSubscribeChain = new Map();
         this.workflowApplyHandlers = new Map();
         this.applyingTokenFromController = false;
         this.controllerPreviousToken = null;
@@ -5402,6 +5446,33 @@ export class JsBaoClient extends Observable {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
+        // #3184 — the same reconnect problem, one credential heavier. A channel
+        // membership is a `ConnectionMapping` row keyed by the connection that is
+        // now gone, so every held grant has to be presented again. A grant that
+        // expired while the socket was down is refused, the refusal drops only that
+        // channel's registration, and — since nothing is waiting on a re-issue —
+        // it is announced as `channelSubscribeFailed` (CR3184-005).
+        try {
+            if (this.isWebSocketOpen()) {
+                // R3184-002 first: a subscribe made while the socket was down is
+                // already waiting for an ack and has sent nothing. Its frame goes now,
+                // and the re-issue pass below skips it — a second attempt would have
+                // to queue behind the first, which can then only end in its timeout.
+                const flushed = this.flushUnsentChannelSubscribes();
+                // A SNAPSHOT: the re-issues below register their own grants as they go.
+                for (const [channel, held] of [...this.channelGrants]) {
+                    if (flushed.has(channel))
+                        continue;
+                    this.reissueChannelSubscribe(channel, held.grant);
+                    logger.debug("[channel] re-subscribed on reconnect", { channel });
+                }
+            }
+        }
+        catch (err) {
+            logger.debug("[channel] reconnect re-subscribe pass failed", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
         logger.log(`[CONNECT] Evaluating sync for ${this.docManager.getOpenDocCount()} open documents`);
         this.docManager.forEachOpenDoc((documentId, _doc) => {
             const startMode = this.docManager.getStartNetworkMode(documentId) || "afterIndexedDb";
@@ -6561,7 +6632,18 @@ export class JsBaoClient extends Observable {
         try {
             const data = JSON.parse(messageData);
             logger.log(`🔄 Processing type: ${data.type}`);
-            if (data.type === "error") {
+            if (data.type === "error" && data.context === "channel.subscribe") {
+                // #3184 — a refused subscribe is a scoped answer to one request, not a
+                // fault on the connection, so it settles that channel's pending call
+                // instead of being emitted as a connection error. The frame echoes the
+                // channel precisely so this can find the right one.
+                const channel = typeof data.channel === "string" ? data.channel : "";
+                logger.warn("Channel subscribe refused", { channel });
+                if (channel) {
+                    this.settleChannelSubscribe(channel, new Error(`subscribeToChannel: ${data.message || "the grant was not accepted"}`));
+                }
+            }
+            else if (data.type === "error") {
                 logger.error("Server error:", data.message, {
                     documentId: data.documentId,
                     messageType: data.messageType,
@@ -6889,6 +6971,17 @@ export class JsBaoClient extends Observable {
             else if (data.type === "direct.message") {
                 this.handleDirectMessage(data);
             }
+            else if (data.type === "channel.subscribed") {
+                this.handleChannelSubscribed(data);
+            }
+            else if (data.type === "channel.unsubscribed") {
+                // Nothing to settle: `unsubscribeFromChannel` has already dropped the
+                // registration, and the ack exists so a client CAN wait for it.
+                logger.debug("[channel] unsubscribed", { channel: data?.channel });
+            }
+            else if (data.type === "channel.message") {
+                this.handleChannelMessage(data);
+            }
             else if (data.type === "workflowStatus") {
                 this.handleWorkflowStatusMessage(data);
             }
@@ -6972,6 +7065,10 @@ export class JsBaoClient extends Observable {
         }
         catch { }
         this.clearAllSyncWatchdogs("ws-close");
+        // #3184 / SO3184-006 — the answers these were waiting for cannot arrive on
+        // a socket that is gone. The held grants survive; the reconnect pass
+        // presents them again.
+        this.abortPendingChannelSubscribes("the connection closed");
         this.docManager.clearPendingSyncOperations();
         this.docManager.forEachOpenDoc((documentId, _doc) => this._updateSynced(documentId, false));
         for (const documentId of this.docManager.listAwarenessDocIds()) {
@@ -7311,6 +7408,23 @@ export class JsBaoClient extends Observable {
         catch { }
         try {
             this.dbSubscriptions?.clear();
+            this.channelGrants.clear();
+            this.channelSubscribeChain.clear();
+            // R3184-005 — every queued continuation belongs to a generation that is
+            // over, so none of them re-registers a channel on the way down.
+            for (const channel of [
+                ...this.channelEpochs.keys(),
+                ...this.pendingChannelSubscribes.keys(),
+            ]) {
+                this.channelEpochs.set(channel, this.channelEpoch(channel) + 1);
+            }
+            for (const [channel, waiting] of this.pendingChannelSubscribes) {
+                for (const entry of waiting) {
+                    clearTimeout(entry.timer);
+                    entry.reject(new Error(`subscribeToChannel: client destroyed while joining '${channel}'`));
+                }
+            }
+            this.pendingChannelSubscribes.clear();
         }
         catch { }
         super.destroy();
@@ -8256,6 +8370,315 @@ export class JsBaoClient extends Observable {
     async hasOfflineGrantStored() {
         return this.auth.hasOfflineGrantStored();
     }
+    /**
+     * Join a channel a server function authorized.
+     *
+     * `grant` is the token `ctx.channels.authorize` handed back: a signed,
+     * short-lived credential naming this app, this channel and this user. The
+     * promise resolves on the server's ack FOR THIS CHANNEL, so concurrent
+     * subscribes cannot resolve each other, and rejects on the server's uniform
+     * refusal — an expired, tampered, cross-app or cross-user grant are
+     * deliberately indistinguishable, so the rejection says only that the grant
+     * was not accepted.
+     *
+     * Calling it again with a fresh grant RENEWS the membership: expiry is the
+     * only revocation a channel has, so an app that wants a long-lived channel
+     * re-invokes its authorizing function before `expiresAt` and subscribes
+     * again. Frames arrive as `client.on("channelMessage", …)`.
+     *
+     * Two calls for the SAME channel run one after the other, so a renewal
+     * issued while an earlier subscribe is still in flight is answered on its own
+     * merits rather than by whichever frame arrives first.
+     *
+     * @group Realtime
+     */
+    subscribeToChannel(channel, grant) {
+        if (!channel || typeof channel !== "string") {
+            return Promise.reject(new Error("subscribeToChannel: channel is required"));
+        }
+        if (!grant || typeof grant !== "string") {
+            return Promise.reject(new Error("subscribeToChannel: a channel grant is required"));
+        }
+        // CR3184-004 — queued behind whatever this channel is already waiting on,
+        // however that one ends. The previous call's outcome is its caller's;
+        // this one only needs the wire to itself.
+        //
+        // R3184-005 — and only while the app still wants this channel. An
+        // `unsubscribeFromChannel` between queueing and running means this
+        // continuation must not resurrect the membership it just left.
+        const epoch = this.channelEpoch(channel);
+        const previous = this.channelSubscribeChain.get(channel);
+        const attempt = (previous ? previous.catch(() => { }) : Promise.resolve())
+            .then(() => {
+            if (this.channelEpoch(channel) !== epoch) {
+                throw new Error(`subscribeToChannel: '${channel}' was left before this subscribe ran`);
+            }
+            return this.startChannelSubscribe(channel, grant);
+        });
+        this.channelSubscribeChain.set(channel, attempt.catch(() => { }));
+        return attempt;
+    }
+    /** The generation `unsubscribeFromChannel` bumps — R3184-005. */
+    channelEpoch(channel) {
+        return this.channelEpochs.get(channel) ?? 0;
+    }
+    /**
+     * Re-present a stored grant after a reconnect — through the SAME chain an
+     * explicit subscribe uses (SO3184-006).
+     *
+     * The reconnect pass used to write straight to the socket, which put an
+     * attempt on the wire that the per-channel bookkeeping knew nothing about.
+     * The server's answer names the channel and nothing finer, so a refusal of
+     * the re-issued (possibly expired) grant would settle a RENEWAL the app made
+     * in the meantime: the fresh subscribe would reject and its registration
+     * would be deleted, while the server had accepted it and was delivering to
+     * it. Chaining keeps every answer attributable to the request that asked for
+     * it, exactly as `subscribeToChannel` does.
+     *
+     * Nobody is waiting on this one, so its refusal is announced as
+     * `channelSubscribeFailed` (CR3184-005) rather than rejecting a promise.
+     */
+    reissueChannelSubscribe(channel, grant) {
+        const epoch = this.channelEpoch(channel);
+        const previous = this.channelSubscribeChain.get(channel);
+        const attempt = (previous ? previous.catch(() => { }) : Promise.resolve())
+            .then(() => {
+            if (this.channelEpoch(channel) !== epoch) {
+                throw new Error(`subscribeToChannel: '${channel}' was left before this subscribe ran`);
+            }
+            return this.startChannelSubscribe(channel, grant);
+        });
+        this.channelSubscribeChain.set(channel, attempt.catch(() => { }));
+        attempt.catch((error) => {
+            // A re-issue the app cancelled is not a failure to announce.
+            if (this.channelEpoch(channel) !== epoch)
+                return;
+            // A re-issue the socket carried away is not a refusal: keep the
+            // registration so the next reconnect presents the grant again, and say
+            // nothing. Only the SERVER's answer removes a membership.
+            if (!this.isWebSocketOpen()) {
+                if (!this.channelGrants.has(channel)) {
+                    this.channelGrants.set(channel, { grant, expiresAt: 0 });
+                }
+                return;
+            }
+            try {
+                this.emit("channelSubscribeFailed", [
+                    {
+                        channel,
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                ]);
+            }
+            catch (err) {
+                logger.debug("[channel] subscribe-failed emit failed", {
+                    channel,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        });
+    }
+    /**
+     * Give up on every subscribe waiting for an answer, because the socket that
+     * would have carried it is gone (SO3184-006).
+     *
+     * The GRANTS stay: the socket failed, not the credential, and the reconnect
+     * pass presents each one again. What must not stay is a pending attempt —
+     * its answer can never arrive, and leaving it in the per-channel chain would
+     * hold the re-issue behind it for the full 20 s timeout.
+     */
+    abortPendingChannelSubscribes(reason) {
+        const pending = [...this.pendingChannelSubscribes];
+        this.pendingChannelSubscribes.clear();
+        this.channelSubscribeChain.clear();
+        for (const [channel, waiting] of pending) {
+            for (const entry of waiting) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error(`subscribeToChannel: ${reason} while joining '${channel}'`));
+            }
+        }
+    }
+    startChannelSubscribe(channel, grant) {
+        // Registered BEFORE the send, so a socket that drops between the two
+        // re-issues this subscribe on reconnect rather than losing it.
+        this.channelGrants.set(channel, { grant, expiresAt: 0 });
+        return new Promise((resolve, reject) => {
+            const waiting = this.pendingChannelSubscribes.get(channel) ?? [];
+            const entry = {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.settleChannelSubscribe(channel, new Error(`subscribeToChannel: no answer for '${channel}' within 20s`));
+                }, 20000),
+                grant,
+                sent: false,
+            };
+            waiting.push(entry);
+            this.pendingChannelSubscribes.set(channel, waiting);
+            if (this.isWebSocketOpen()) {
+                entry.sent = true;
+                this.sendChannelSubscribe(channel, grant);
+            }
+            else {
+                // Nothing went out. `flushUnsentChannelSubscribes` sends it the moment
+                // the socket opens (R3184-002) — queueing a re-issue behind it instead
+                // would leave this call waiting for its own 20 s timeout, because the
+                // re-issue cannot start until this attempt settles.
+                try {
+                    this.wsManager.connect();
+                }
+                catch { }
+            }
+        });
+    }
+    /**
+     * Put the subscribes that never reached the wire onto it — R3184-002.
+     *
+     * A call made while the socket was down registered its grant, created its
+     * promise and sent nothing. On open its frame is sent for the attempt that
+     * is already waiting, so the ack settles the original call. Channels with
+     * nothing pending go the other way, through the ordinary re-issue.
+     *
+     * Returns the channels it sent for, so the reconnect pass does not queue a
+     * second attempt for them.
+     */
+    flushUnsentChannelSubscribes() {
+        const flushed = new Set();
+        for (const [channel, waiting] of this.pendingChannelSubscribes) {
+            const unsent = waiting.filter((entry) => !entry.sent);
+            if (unsent.length === 0)
+                continue;
+            // The newest attempt's grant: it is the one the caller most recently
+            // asked for, and `channelGrants` already holds it for the reconnect pass.
+            const grant = unsent[unsent.length - 1].grant;
+            for (const entry of unsent)
+                entry.sent = true;
+            flushed.add(channel);
+            this.sendChannelSubscribe(channel, grant);
+            logger.debug("[channel] sent a subscribe held back by a closed socket", {
+                channel,
+            });
+        }
+        return flushed;
+    }
+    /**
+     * Leave a channel. Idempotent, and safe on a closed socket: the
+     * registration goes either way, so a reconnect does not bring it back.
+     *
+     * A subscribe still in flight, or queued behind one, is cancelled with it:
+     * leaving means leaving, so a queued renewal cannot put the membership back
+     * afterwards, and a `subscribeToChannel` promise still waiting for its ack
+     * rejects rather than resolving with a subscription to a channel this client
+     * has already left.
+     *
+     * @group Realtime
+     */
+    unsubscribeFromChannel(channel) {
+        this.channelGrants.delete(channel);
+        this.channelSubscribeChain.delete(channel);
+        // Bumped BEFORE the pending calls are settled: a rejection handler that
+        // subscribes again should be starting a new generation, not racing this one.
+        this.channelEpochs.set(channel, this.channelEpoch(channel) + 1);
+        const waiting = this.pendingChannelSubscribes.get(channel);
+        if (waiting && waiting.length > 0) {
+            this.pendingChannelSubscribes.delete(channel);
+            for (const entry of waiting) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error(`subscribeToChannel: '${channel}' was left while joining`));
+            }
+        }
+        else {
+            // Nothing was waiting, so there is nothing to reject and no
+            // `channelSubscribeFailed` to announce: leaving is what the app asked for.
+            this.pendingChannelSubscribes.delete(channel);
+        }
+        try {
+            if (this.isWebSocketOpen()) {
+                this.ws?.send(JSON.stringify({ type: "channel.unsubscribe", channel }));
+            }
+        }
+        catch (err) {
+            logger.debug("[channel] unsubscribe send failed", {
+                channel,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    sendChannelSubscribe(channel, grant) {
+        try {
+            this.ws?.send(JSON.stringify({ type: "channel.subscribe", channel, grant }));
+        }
+        catch (err) {
+            logger.debug("[channel] subscribe send failed", {
+                channel,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Settle every call waiting on one channel — with the ack, or with the
+     * refusal. Only that channel's waiters and only that channel's
+     * registration: a client with several subscriptions must not lose the ones
+     * that worked (D3184-007).
+     */
+    settleChannelSubscribe(channel, outcome) {
+        const waiting = this.pendingChannelSubscribes.get(channel);
+        this.pendingChannelSubscribes.delete(channel);
+        if (outcome instanceof Error) {
+            this.channelGrants.delete(channel);
+            if (!waiting || waiting.length === 0) {
+                // CR3184-005 — nobody asked for this one, so a rejected promise cannot
+                // report it. That is the reconnect re-issue: the client presented a
+                // stored grant on its own initiative and the server refused it, and
+                // silently dropping the registration would leave the app believing it
+                // was still in a channel it had just been removed from.
+                try {
+                    this.emit("channelSubscribeFailed", [
+                        { channel, message: outcome.message },
+                    ]);
+                }
+                catch (err) {
+                    logger.debug("[channel] subscribe-failed emit failed", {
+                        channel,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+        for (const entry of waiting ?? []) {
+            clearTimeout(entry.timer);
+            if (outcome instanceof Error) {
+                entry.reject(outcome);
+            }
+            else {
+                entry.resolve({
+                    channel,
+                    expiresAt: outcome.expiresAt,
+                    unsubscribe: () => this.unsubscribeFromChannel(channel),
+                });
+            }
+        }
+    }
+    handleChannelSubscribed(data) {
+        const channel = typeof data?.channel === "string" ? data.channel : "";
+        if (!channel)
+            return;
+        const expiresAt = Number(data?.expiresAt) || 0;
+        const stored = this.channelGrants.get(channel);
+        if (stored)
+            this.channelGrants.set(channel, { ...stored, expiresAt });
+        this.settleChannelSubscribe(channel, { expiresAt });
+    }
+    handleChannelMessage(data) {
+        try {
+            this.emit("channelMessage", [data]);
+        }
+        catch (err) {
+            // A frame nobody is listening for is not an error, exactly as for
+            // `directMessage`: an unknown-to-this-app channel must be inert.
+            logger.debug("[channel] client emit failed", { error: err });
+        }
+    }
     /**
      * Internal entry point for DatabasesAPI.subscribe(). Ensures the WS is
      * connected, registers the callback with the registry, sends the

package/dist/api/functionsApi.d.ts

@@ -8,6 +8,19 @@ import type { JsBaoClient, ClaimApplyResult, ConfirmApplyResult, ReleaseApplyRes
  */
 /** How a synchronous invocation settled. */
 export type FunctionInvokeStatus = "completed" | "failed" | "timeout";
+/**
+ * The resolved platform ceilings an invocation ran under.
+ *
+ * `[function.limits]` clamped element-wise to the platform's own values, so a
+ * function may lower a ceiling and never raise one. Reported because the
+ * declared value and the enforced value are not always the same number: the
+ * platform enforces `cpuMs` with a minimum of its own.
+ */
+export interface FunctionInvokeLimits {
+    cpuMs: number;
+    subRequests: number;
+    ratePerMinute: number;
+}
 /**
  * The invoke envelope.
  *
@@ -24,6 +37,14 @@ export interface FunctionInvokeResult<TOutput = unknown> {
     /** Present when `status` is `"failed"`. */
     error?: string;
     errorCode?: string;
+    /**
+     * The ceilings the sandbox ran under.
+     *
+     * Present on every outcome the sandbox produced; absent from a refusal that
+     * never reached it, which has no run to describe — and those refusals are
+     * HTTP errors, so a caller holding this envelope has one.
+     */
+    limits?: FunctionInvokeLimits;
 }
 /**
  * What to send with an invocation. Every field is optional — a function that

package/dist/browser.umd.js

@@ -16419,6 +16419,50 @@
             this.serviceWorkerBridgeLastToken = null;
             this.pendingSelfRemovalDocs = new Set();
             this.pendingSelfRemovalTimers = new Map();
+            /**
+             * Channel memberships this client is holding, `channel → grant` (#3184).
+             *
+             * The GRANT is stored, not just the channel, because a membership is keyed
+             * by a connection: after a reconnect the server has no record of it, and the
+             * only thing that re-establishes one is presenting the credential again. A
+             * grant that has expired in the meantime is refused, and the refusal drops
+             * exactly that channel's registration.
+             */
+            this.channelGrants = new Map();
+            /**
+             * Subscribes waiting for their own channel's ack (D3184-007).
+             *
+             * `sent` records whether the frame this call is waiting on ever reached the
+             * wire — R3184-002. A subscribe made before the socket opened registers its
+             * grant and nudges the connection, but sends nothing; the open handler has
+             * to send THAT attempt rather than queue a second one behind it, or the
+             * caller waits out the full 20 s timeout on a connection that came up
+             * immediately.
+             */
+            this.pendingChannelSubscribes = new Map();
+            /**
+             * How many times this channel has been left — R3184-005.
+             *
+             * A subscribe queued behind an in-flight one is a continuation that has not
+             * run yet, and `unsubscribeFromChannel` cannot cancel a `.then`. Without a
+             * generation, leaving a channel while a renewal was queued would run that
+             * renewal afterwards: the registration would come back, a subscribe would go
+             * out, and the client would be delivered to on a channel it had explicitly
+             * left. Each attempt captures the count it was created under and does
+             * nothing if it has moved.
+             */
+            this.channelEpochs = new Map();
+            /**
+             * One subscribe at a time per channel — CR3184-004.
+             *
+             * The server answers a subscribe with a frame that names the CHANNEL and
+             * nothing finer, which is what lets subscriptions to DIFFERENT channels be
+             * told apart. Two requests for the SAME channel cannot be: the first answer
+             * would settle both, so an expired grant racing a renewal would reject the
+             * renewal too and drop a registration the server had accepted. Chaining them
+             * keeps every answer attributable to the request that asked for it.
+             */
+            this.channelSubscribeChain = new Map();
             this.workflowApplyHandlers = new Map();
             this.applyingTokenFromController = false;
             this.controllerPreviousToken = null;
@@ -21274,6 +21318,33 @@
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
+            // #3184 — the same reconnect problem, one credential heavier. A channel
+            // membership is a `ConnectionMapping` row keyed by the connection that is
+            // now gone, so every held grant has to be presented again. A grant that
+            // expired while the socket was down is refused, the refusal drops only that
+            // channel's registration, and — since nothing is waiting on a re-issue —
+            // it is announced as `channelSubscribeFailed` (CR3184-005).
+            try {
+                if (this.isWebSocketOpen()) {
+                    // R3184-002 first: a subscribe made while the socket was down is
+                    // already waiting for an ack and has sent nothing. Its frame goes now,
+                    // and the re-issue pass below skips it — a second attempt would have
+                    // to queue behind the first, which can then only end in its timeout.
+                    const flushed = this.flushUnsentChannelSubscribes();
+                    // A SNAPSHOT: the re-issues below register their own grants as they go.
+                    for (const [channel, held] of [...this.channelGrants]) {
+                        if (flushed.has(channel))
+                            continue;
+                        this.reissueChannelSubscribe(channel, held.grant);
+                        logger.debug("[channel] re-subscribed on reconnect", { channel });
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug("[channel] reconnect re-subscribe pass failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
             logger.log(`[CONNECT] Evaluating sync for ${this.docManager.getOpenDocCount()} open documents`);
             this.docManager.forEachOpenDoc((documentId, _doc) => {
                 const startMode = this.docManager.getStartNetworkMode(documentId) || "afterIndexedDb";
@@ -22433,7 +22504,18 @@
             try {
                 const data = JSON.parse(messageData);
                 logger.log(`🔄 Processing type: ${data.type}`);
-                if (data.type === "error") {
+                if (data.type === "error" && data.context === "channel.subscribe") {
+                    // #3184 — a refused subscribe is a scoped answer to one request, not a
+                    // fault on the connection, so it settles that channel's pending call
+                    // instead of being emitted as a connection error. The frame echoes the
+                    // channel precisely so this can find the right one.
+                    const channel = typeof data.channel === "string" ? data.channel : "";
+                    logger.warn("Channel subscribe refused", { channel });
+                    if (channel) {
+                        this.settleChannelSubscribe(channel, new Error(`subscribeToChannel: ${data.message || "the grant was not accepted"}`));
+                    }
+                }
+                else if (data.type === "error") {
                     logger.error("Server error:", data.message, {
                         documentId: data.documentId,
                         messageType: data.messageType,
@@ -22761,6 +22843,17 @@
                 else if (data.type === "direct.message") {
                     this.handleDirectMessage(data);
                 }
+                else if (data.type === "channel.subscribed") {
+                    this.handleChannelSubscribed(data);
+                }
+                else if (data.type === "channel.unsubscribed") {
+                    // Nothing to settle: `unsubscribeFromChannel` has already dropped the
+                    // registration, and the ack exists so a client CAN wait for it.
+                    logger.debug("[channel] unsubscribed", { channel: data?.channel });
+                }
+                else if (data.type === "channel.message") {
+                    this.handleChannelMessage(data);
+                }
                 else if (data.type === "workflowStatus") {
                     this.handleWorkflowStatusMessage(data);
                 }
@@ -22844,6 +22937,10 @@
             }
             catch { }
             this.clearAllSyncWatchdogs("ws-close");
+            // #3184 / SO3184-006 — the answers these were waiting for cannot arrive on
+            // a socket that is gone. The held grants survive; the reconnect pass
+            // presents them again.
+            this.abortPendingChannelSubscribes("the connection closed");
             this.docManager.clearPendingSyncOperations();
             this.docManager.forEachOpenDoc((documentId, _doc) => this._updateSynced(documentId, false));
             for (const documentId of this.docManager.listAwarenessDocIds()) {
@@ -23180,6 +23277,23 @@
             catch { }
             try {
                 this.dbSubscriptions?.clear();
+                this.channelGrants.clear();
+                this.channelSubscribeChain.clear();
+                // R3184-005 — every queued continuation belongs to a generation that is
+                // over, so none of them re-registers a channel on the way down.
+                for (const channel of [
+                    ...this.channelEpochs.keys(),
+                    ...this.pendingChannelSubscribes.keys(),
+                ]) {
+                    this.channelEpochs.set(channel, this.channelEpoch(channel) + 1);
+                }
+                for (const [channel, waiting] of this.pendingChannelSubscribes) {
+                    for (const entry of waiting) {
+                        clearTimeout(entry.timer);
+                        entry.reject(new Error(`subscribeToChannel: client destroyed while joining '${channel}'`));
+                    }
+                }
+                this.pendingChannelSubscribes.clear();
             }
             catch { }
             super.destroy();
@@ -24125,6 +24239,315 @@
         async hasOfflineGrantStored() {
             return this.auth.hasOfflineGrantStored();
         }
+        /**
+         * Join a channel a server function authorized.
+         *
+         * `grant` is the token `ctx.channels.authorize` handed back: a signed,
+         * short-lived credential naming this app, this channel and this user. The
+         * promise resolves on the server's ack FOR THIS CHANNEL, so concurrent
+         * subscribes cannot resolve each other, and rejects on the server's uniform
+         * refusal — an expired, tampered, cross-app or cross-user grant are
+         * deliberately indistinguishable, so the rejection says only that the grant
+         * was not accepted.
+         *
+         * Calling it again with a fresh grant RENEWS the membership: expiry is the
+         * only revocation a channel has, so an app that wants a long-lived channel
+         * re-invokes its authorizing function before `expiresAt` and subscribes
+         * again. Frames arrive as `client.on("channelMessage", …)`.
+         *
+         * Two calls for the SAME channel run one after the other, so a renewal
+         * issued while an earlier subscribe is still in flight is answered on its own
+         * merits rather than by whichever frame arrives first.
+         *
+         * @group Realtime
+         */
+        subscribeToChannel(channel, grant) {
+            if (!channel || typeof channel !== "string") {
+                return Promise.reject(new Error("subscribeToChannel: channel is required"));
+            }
+            if (!grant || typeof grant !== "string") {
+                return Promise.reject(new Error("subscribeToChannel: a channel grant is required"));
+            }
+            // CR3184-004 — queued behind whatever this channel is already waiting on,
+            // however that one ends. The previous call's outcome is its caller's;
+            // this one only needs the wire to itself.
+            //
+            // R3184-005 — and only while the app still wants this channel. An
+            // `unsubscribeFromChannel` between queueing and running means this
+            // continuation must not resurrect the membership it just left.
+            const epoch = this.channelEpoch(channel);
+            const previous = this.channelSubscribeChain.get(channel);
+            const attempt = (previous ? previous.catch(() => { }) : Promise.resolve())
+                .then(() => {
+                if (this.channelEpoch(channel) !== epoch) {
+                    throw new Error(`subscribeToChannel: '${channel}' was left before this subscribe ran`);
+                }
+                return this.startChannelSubscribe(channel, grant);
+            });
+            this.channelSubscribeChain.set(channel, attempt.catch(() => { }));
+            return attempt;
+        }
+        /** The generation `unsubscribeFromChannel` bumps — R3184-005. */
+        channelEpoch(channel) {
+            return this.channelEpochs.get(channel) ?? 0;
+        }
+        /**
+         * Re-present a stored grant after a reconnect — through the SAME chain an
+         * explicit subscribe uses (SO3184-006).
+         *
+         * The reconnect pass used to write straight to the socket, which put an
+         * attempt on the wire that the per-channel bookkeeping knew nothing about.
+         * The server's answer names the channel and nothing finer, so a refusal of
+         * the re-issued (possibly expired) grant would settle a RENEWAL the app made
+         * in the meantime: the fresh subscribe would reject and its registration
+         * would be deleted, while the server had accepted it and was delivering to
+         * it. Chaining keeps every answer attributable to the request that asked for
+         * it, exactly as `subscribeToChannel` does.
+         *
+         * Nobody is waiting on this one, so its refusal is announced as
+         * `channelSubscribeFailed` (CR3184-005) rather than rejecting a promise.
+         */
+        reissueChannelSubscribe(channel, grant) {
+            const epoch = this.channelEpoch(channel);
+            const previous = this.channelSubscribeChain.get(channel);
+            const attempt = (previous ? previous.catch(() => { }) : Promise.resolve())
+                .then(() => {
+                if (this.channelEpoch(channel) !== epoch) {
+                    throw new Error(`subscribeToChannel: '${channel}' was left before this subscribe ran`);
+                }
+                return this.startChannelSubscribe(channel, grant);
+            });
+            this.channelSubscribeChain.set(channel, attempt.catch(() => { }));
+            attempt.catch((error) => {
+                // A re-issue the app cancelled is not a failure to announce.
+                if (this.channelEpoch(channel) !== epoch)
+                    return;
+                // A re-issue the socket carried away is not a refusal: keep the
+                // registration so the next reconnect presents the grant again, and say
+                // nothing. Only the SERVER's answer removes a membership.
+                if (!this.isWebSocketOpen()) {
+                    if (!this.channelGrants.has(channel)) {
+                        this.channelGrants.set(channel, { grant, expiresAt: 0 });
+                    }
+                    return;
+                }
+                try {
+                    this.emit("channelSubscribeFailed", [
+                        {
+                            channel,
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    ]);
+                }
+                catch (err) {
+                    logger.debug("[channel] subscribe-failed emit failed", {
+                        channel,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            });
+        }
+        /**
+         * Give up on every subscribe waiting for an answer, because the socket that
+         * would have carried it is gone (SO3184-006).
+         *
+         * The GRANTS stay: the socket failed, not the credential, and the reconnect
+         * pass presents each one again. What must not stay is a pending attempt —
+         * its answer can never arrive, and leaving it in the per-channel chain would
+         * hold the re-issue behind it for the full 20 s timeout.
+         */
+        abortPendingChannelSubscribes(reason) {
+            const pending = [...this.pendingChannelSubscribes];
+            this.pendingChannelSubscribes.clear();
+            this.channelSubscribeChain.clear();
+            for (const [channel, waiting] of pending) {
+                for (const entry of waiting) {
+                    clearTimeout(entry.timer);
+                    entry.reject(new Error(`subscribeToChannel: ${reason} while joining '${channel}'`));
+                }
+            }
+        }
+        startChannelSubscribe(channel, grant) {
+            // Registered BEFORE the send, so a socket that drops between the two
+            // re-issues this subscribe on reconnect rather than losing it.
+            this.channelGrants.set(channel, { grant, expiresAt: 0 });
+            return new Promise((resolve, reject) => {
+                const waiting = this.pendingChannelSubscribes.get(channel) ?? [];
+                const entry = {
+                    resolve,
+                    reject,
+                    timer: setTimeout(() => {
+                        this.settleChannelSubscribe(channel, new Error(`subscribeToChannel: no answer for '${channel}' within 20s`));
+                    }, 20000),
+                    grant,
+                    sent: false,
+                };
+                waiting.push(entry);
+                this.pendingChannelSubscribes.set(channel, waiting);
+                if (this.isWebSocketOpen()) {
+                    entry.sent = true;
+                    this.sendChannelSubscribe(channel, grant);
+                }
+                else {
+                    // Nothing went out. `flushUnsentChannelSubscribes` sends it the moment
+                    // the socket opens (R3184-002) — queueing a re-issue behind it instead
+                    // would leave this call waiting for its own 20 s timeout, because the
+                    // re-issue cannot start until this attempt settles.
+                    try {
+                        this.wsManager.connect();
+                    }
+                    catch { }
+                }
+            });
+        }
+        /**
+         * Put the subscribes that never reached the wire onto it — R3184-002.
+         *
+         * A call made while the socket was down registered its grant, created its
+         * promise and sent nothing. On open its frame is sent for the attempt that
+         * is already waiting, so the ack settles the original call. Channels with
+         * nothing pending go the other way, through the ordinary re-issue.
+         *
+         * Returns the channels it sent for, so the reconnect pass does not queue a
+         * second attempt for them.
+         */
+        flushUnsentChannelSubscribes() {
+            const flushed = new Set();
+            for (const [channel, waiting] of this.pendingChannelSubscribes) {
+                const unsent = waiting.filter((entry) => !entry.sent);
+                if (unsent.length === 0)
+                    continue;
+                // The newest attempt's grant: it is the one the caller most recently
+                // asked for, and `channelGrants` already holds it for the reconnect pass.
+                const grant = unsent[unsent.length - 1].grant;
+                for (const entry of unsent)
+                    entry.sent = true;
+                flushed.add(channel);
+                this.sendChannelSubscribe(channel, grant);
+                logger.debug("[channel] sent a subscribe held back by a closed socket", {
+                    channel,
+                });
+            }
+            return flushed;
+        }
+        /**
+         * Leave a channel. Idempotent, and safe on a closed socket: the
+         * registration goes either way, so a reconnect does not bring it back.
+         *
+         * A subscribe still in flight, or queued behind one, is cancelled with it:
+         * leaving means leaving, so a queued renewal cannot put the membership back
+         * afterwards, and a `subscribeToChannel` promise still waiting for its ack
+         * rejects rather than resolving with a subscription to a channel this client
+         * has already left.
+         *
+         * @group Realtime
+         */
+        unsubscribeFromChannel(channel) {
+            this.channelGrants.delete(channel);
+            this.channelSubscribeChain.delete(channel);
+            // Bumped BEFORE the pending calls are settled: a rejection handler that
+            // subscribes again should be starting a new generation, not racing this one.
+            this.channelEpochs.set(channel, this.channelEpoch(channel) + 1);
+            const waiting = this.pendingChannelSubscribes.get(channel);
+            if (waiting && waiting.length > 0) {
+                this.pendingChannelSubscribes.delete(channel);
+                for (const entry of waiting) {
+                    clearTimeout(entry.timer);
+                    entry.reject(new Error(`subscribeToChannel: '${channel}' was left while joining`));
+                }
+            }
+            else {
+                // Nothing was waiting, so there is nothing to reject and no
+                // `channelSubscribeFailed` to announce: leaving is what the app asked for.
+                this.pendingChannelSubscribes.delete(channel);
+            }
+            try {
+                if (this.isWebSocketOpen()) {
+                    this.ws?.send(JSON.stringify({ type: "channel.unsubscribe", channel }));
+                }
+            }
+            catch (err) {
+                logger.debug("[channel] unsubscribe send failed", {
+                    channel,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        sendChannelSubscribe(channel, grant) {
+            try {
+                this.ws?.send(JSON.stringify({ type: "channel.subscribe", channel, grant }));
+            }
+            catch (err) {
+                logger.debug("[channel] subscribe send failed", {
+                    channel,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        /**
+         * Settle every call waiting on one channel — with the ack, or with the
+         * refusal. Only that channel's waiters and only that channel's
+         * registration: a client with several subscriptions must not lose the ones
+         * that worked (D3184-007).
+         */
+        settleChannelSubscribe(channel, outcome) {
+            const waiting = this.pendingChannelSubscribes.get(channel);
+            this.pendingChannelSubscribes.delete(channel);
+            if (outcome instanceof Error) {
+                this.channelGrants.delete(channel);
+                if (!waiting || waiting.length === 0) {
+                    // CR3184-005 — nobody asked for this one, so a rejected promise cannot
+                    // report it. That is the reconnect re-issue: the client presented a
+                    // stored grant on its own initiative and the server refused it, and
+                    // silently dropping the registration would leave the app believing it
+                    // was still in a channel it had just been removed from.
+                    try {
+                        this.emit("channelSubscribeFailed", [
+                            { channel, message: outcome.message },
+                        ]);
+                    }
+                    catch (err) {
+                        logger.debug("[channel] subscribe-failed emit failed", {
+                            channel,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+            }
+            for (const entry of waiting ?? []) {
+                clearTimeout(entry.timer);
+                if (outcome instanceof Error) {
+                    entry.reject(outcome);
+                }
+                else {
+                    entry.resolve({
+                        channel,
+                        expiresAt: outcome.expiresAt,
+                        unsubscribe: () => this.unsubscribeFromChannel(channel),
+                    });
+                }
+            }
+        }
+        handleChannelSubscribed(data) {
+            const channel = typeof data?.channel === "string" ? data.channel : "";
+            if (!channel)
+                return;
+            const expiresAt = Number(data?.expiresAt) || 0;
+            const stored = this.channelGrants.get(channel);
+            if (stored)
+                this.channelGrants.set(channel, { ...stored, expiresAt });
+            this.settleChannelSubscribe(channel, { expiresAt });
+        }
+        handleChannelMessage(data) {
+            try {
+                this.emit("channelMessage", [data]);
+            }
+            catch (err) {
+                // A frame nobody is listening for is not an error, exactly as for
+                // `directMessage`: an unknown-to-this-app channel must be inert.
+                logger.debug("[channel] client emit failed", { error: err });
+            }
+        }
         /**
          * Internal entry point for DatabasesAPI.subscribe(). Ensures the WS is
          * connected, registers the callback with the registry, sends the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-bao-wss-client",
-  "version": "2.2.0-alpha.3",
+  "version": "2.2.0-alpha.4",
   "description": "Client library for js-bao-wss Yjs WebSocket service",
   "author": "Primitive LLC",
   "license": "UNLICENSED",
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "lib0": "^0.2.0",
     "yjs": "^13.6.0",
-    "js-bao": ">=0.6.0",
+    "js-bao": ">=0.6.1",
     "better-sqlite3": "^11.0.0",
     "y-sqlite3": "^0.1.0",
     "react": ">=17.0.0",