@nodefony/realtime 10.0.0-beta.3 → 10.0.0-beta.5

package/dist/nodefony/testing/index.js

@@ -1,6 +1,7 @@
+import { isRecord } from "../src/guards.js";
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
 import { RequestContext } from "nodefony";
-//#region nodefony/testing/index.ts
+// nodefony/testing/index.ts
 /**
 * `@nodefony/realtime/testing` — **harnais de test d'un controller temps réel**.
 *
@@ -53,6 +54,67 @@ async function waitFor(predicate, ticks) {
 	return predicate();
 }
 /**
+* Motifs de refus du protocole, rendus exhaustifs par le compilateur : un motif
+* ajouté à `IRealtimeDenied.reason` casse la compilation ICI, au lieu de faire
+* lever le harnais sur un refus légitime.
+*/
+const DENIED_REASONS = {
+	forbidden: true,
+	limit: true,
+	unknown: true
+};
+function isDeniedReason(reason) {
+	return Object.hasOwn(DENIED_REASONS, reason);
+}
+/** Erreur JSON-RPC 2.0 (§5.1) d'une trame, ou `null` si sa forme est fausse. */
+function readRpcError(error) {
+	if (!isRecord(error) || typeof error.code !== "number" || typeof error.message !== "string") return null;
+	return Object.hasOwn(error, "data") ? {
+		code: error.code,
+		message: error.message,
+		data: error.data
+	} : {
+		code: error.code,
+		message: error.message
+	};
+}
+/**
+* Lit une trame émise par le contrôleur sous test. Une trame dont un champ a
+* la mauvaise forme LÈVE : c'est un défaut du contrôleur, que le test doit
+* voir, pas une donnée à écarter.
+*/
+function readFrame(data) {
+	const value = JSON.parse(data);
+	const fault = () => /* @__PURE__ */ new Error(`createRealtimeHarness: trame JSON-RPC malformée émise — ${data}`);
+	if (!isRecord(value)) throw fault();
+	const { jsonrpc, id, method } = value;
+	if (jsonrpc !== void 0 && typeof jsonrpc !== "string") throw fault();
+	if (id !== void 0 && typeof id !== "number" && typeof id !== "string") throw fault();
+	if (method !== void 0 && typeof method !== "string") throw fault();
+	const error = Object.hasOwn(value, "error") ? readRpcError(value.error) : void 0;
+	if (error === null) throw fault();
+	return {
+		...jsonrpc === void 0 ? {} : { jsonrpc },
+		...id === void 0 ? {} : { id },
+		...method === void 0 ? {} : { method },
+		...Object.hasOwn(value, "params") ? { params: value.params } : {},
+		...Object.hasOwn(value, "result") ? { result: value.result } : {},
+		...error === void 0 ? {} : { error }
+	};
+}
+/** Lit le `params` d'un `realtime:denied` — lève si le contrôleur l'a mal formé. */
+function readDenied(params) {
+	if (isRecord(params) && typeof params.channel === "string" && typeof params.reason === "string" && isDeniedReason(params.reason) && (params.detail === void 0 || typeof params.detail === "string")) return params.detail === void 0 ? {
+		channel: params.channel,
+		reason: params.reason
+	} : {
+		channel: params.channel,
+		reason: params.reason,
+		detail: params.detail
+	};
+	throw new Error(`createRealtimeHarness: realtime:denied malformé — ${JSON.stringify(params)}`);
+}
+/**
 * Monte un controller temps réel sur une fausse connexion et rend de quoi le
 * piloter.
 *
@@ -85,7 +147,7 @@ function createRealtimeHarness(create, options = {}) {
 	const connection = {
 		readyState: OPEN,
 		send: (data, cb) => {
-			received.push(JSON.parse(data));
+			received.push(readFrame(data));
 			cb?.();
 		},
 		close: (code, reason) => {
@@ -96,6 +158,7 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 	const controller = create({
+		type: "websocket",
 		connection,
 		once: (event, fn) => {
 			if (event === "onFinish") onFinish = fn;
@@ -147,10 +210,21 @@ function createRealtimeHarness(create, options = {}) {
 			return welcome;
 		},
 		async subscribe(channel) {
+			const from = received.length;
 			await feed(rpc({
 				method: "subscribe",
 				params: { channel }
 			}));
+			await waitFor(() => {
+				for (let i = from; i < received.length; i++) {
+					const f = received[i];
+					if ((f?.method === "realtime:subscribed" || f?.method === "realtime:denied") && isRecord(f.params) && f.params["channel"] === channel) return true;
+				}
+				return false;
+			}, 20);
+		},
+		subscriptions() {
+			return received.filter((f) => f.method === "realtime:subscribed").map((f) => isRecord(f.params) ? String(f.params["channel"]) : "");
 		},
 		async unsubscribe(channel) {
 			await feed(rpc({
@@ -187,7 +261,7 @@ function createRealtimeHarness(create, options = {}) {
 			return received.filter((f) => f.method === channel && f.id === void 0).map((f) => f.params);
 		},
 		denials() {
-			return received.filter((f) => f.method === "realtime:denied").map((f) => f.params);
+			return received.filter((f) => f.method === "realtime:denied").map((f) => readDenied(f.params));
 		},
 		close() {
 			if (closed) return;
@@ -201,5 +275,4 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 }
-//#endregion
 export { createRealtimeHarness };

package/dist/types/index.d.ts

@@ -81,6 +81,7 @@ export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, ge
 export type { RealtimeChannelFactory } from "./nodefony/decorators/realtimeDecorators.js";
 export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./nodefony/interfaces/IRealtimeController.js";
 export type { IChannelPolicy } from "./nodefony/interfaces/IChannelPolicy.js";
+export type { IRealtimeConnectionState } from "./nodefony/interfaces/IRealtimeConnectionState.js";
 export type { IClientLogsLimits } from "./nodefony/interfaces/IClientLogsLimits.js";
 export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from "./nodefony/src/server/syslogUplink.js";
 export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.js";

package/dist/types/nodefony/interfaces/IRealtimeConnectionState.d.ts

@@ -0,0 +1,40 @@
+import type { JsonRpcPeer } from "nodefony";
+import type { WsConnectionTransport } from "../src/transport/WsConnectionTransport.js";
+import type { ChannelSink } from "../src/server/RealtimeHub.js";
+import type { RealtimeInboundHandler } from "./IRealtimeController.js";
+/**
+ * État du protocole temps réel d'UNE connexion WebSocket — posé au welcome, et
+ * relu à chaque frame jusqu'à la fermeture.
+ *
+ * Il vit sur la CONNEXION (`WebsocketContext`), pas sur le contrôleur : un
+ * `forward` fait construire une instance neuve qui sert la même socket, et
+ * l'état doit lui survivre.
+ *
+ * Le pair y est rangé sous son contrat EFFACÉ, ce qu'il est d'ailleurs à sa
+ * construction. Plusieurs contrôleurs peuvent servir la même connexion, et aucun
+ * type ne relie cet état à l'un d'eux : chacun le relit sous son propre contrat
+ * (`RealtimeController.requestClient` → `JsonRpcPeer.requestAs`).
+ */
+export interface IRealtimeConnectionState {
+    /** `realtime:welcome` émis : la poignée de main ne se rejoue pas. */
+    welcomed: boolean;
+    /** Le pair JSON-RPC de la connexion, sous son contrat effacé. */
+    peer: JsonRpcPeer;
+    /** Le transport qui relie le pair à la socket (contre-pression, sonde). */
+    transport: WsConnectionTransport;
+    /** Canal → sink de CETTE connexion auprès du hub partagé, pour s'en désabonner. */
+    channels: Map<string, ChannelSink>;
+    /** Canaux full-duplex qui acceptent une entrée client ; `null` s'il n'y en a aucun. */
+    inbound: Record<string, RealtimeInboundHandler> | null;
+}
+declare module "@nodefony/http" {
+    interface IWebsocketConnectionState {
+        /**
+         * État du protocole temps réel de la connexion, posé par
+         * `@nodefony/realtime` au welcome ; `undefined` avant, et sur toute socket
+         * qu'aucun `RealtimeController` ne sert. Réservé au module : le lire,
+         * jamais l'écrire.
+         */
+        __nfRealtime?: IRealtimeConnectionState;
+    }
+}

package/dist/types/nodefony/interfaces/IRealtimeToken.d.ts

@@ -45,4 +45,17 @@ export interface IRealtimeToken {
      * (publish/subscribe), payé seulement sur `api.request`.
      */
     isValid?(nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce
+     * bien le même ? `false` si le compte a disparu, a été désactivé ou
+     * verrouillé, ou si un AUTRE compte a repris son identifiant (suppression
+     * hors framework puis recréation). Optionnel — absent = considéré confirmé.
+     *
+     * Distinct d'{@link isValid} parce que son coût l'est : il relit l'annuaire
+     * des comptes (une lecture, comme une requête HTTP en zone), là où
+     * `isValid` ne lit qu'un store de jetons ou de sessions. Appelé par le pont
+     * `api.request` SEULEMENT, jamais par la re-validation périodique du hub —
+     * qui le paierait pour chaque socket ouverte, à chaque tour.
+     */
+    confirmAccount?(): Promise<boolean>;
 }

package/dist/types/nodefony/interfaces/index.d.ts

@@ -11,6 +11,7 @@
 export type { IBackplane, IBackplaneMessage, BackplaneHandler, } from "./IBackplane.js";
 export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./IRealtimeController.js";
 export type { IChannelPolicy } from "./IChannelPolicy.js";
+export type { IRealtimeConnectionState } from "./IRealtimeConnectionState.js";
 export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./IRealtimeProbe.js";
 export type { IRealtimeToken } from "./IRealtimeToken.js";
 export type { IRealtimeHandshake } from "./IRealtimeHandshake.js";

package/dist/types/nodefony/src/server/RealtimeController.d.ts

@@ -26,6 +26,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
  */
 export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController {
+    #private;
     /**
      * Une instance PAR CONNEXION, par construction — le défaut `singleton` des
      * contrôleurs ne s'applique pas ici. Le pair JSON-RPC de la connexion capture
@@ -90,7 +91,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     protected realtimeInbound(): Record<string, RealtimeInboundHandler>;
     /**
-     * Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+     * Opt-in du **pont API** (une action, deux transports) : `true` → la
      * connexion expose la méthode RPC `api.request {path}` qui re-route le path
      * porté par le message vers l'action controller correspondante — la MÊME
      * action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
@@ -120,6 +121,39 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
      */
     protected handleRealtime(message: string | Buffer | null): void;
+    /**
+     * Lit les trames BINAIRES de cette connexion — le point d'extension d'un
+     * protocole binaire écrit par l'application, à côté du JSON-RPC ; pendant
+     * serveur de `NodefonySocket.onBinary`.
+     *
+     * Le protocole temps réel est du JSON-RPC texte : il ne sait pas à quel canal
+     * une trame binaire appartient. Sans cette méthode, une trame binaire est
+     * écartée, comptée (`binaryDiscarded` de la sonde de connexion) et journalisée
+     * une fois par connexion. La surcharger la reçoit telle quelle, octets exacts,
+     * en `Uint8Array` — le type que livre aussi `NodefonySocket.onBinary` dans le
+     * navigateur : un décodeur s'écrit une fois pour les deux côtés. À l'exécution
+     * c'est un `Buffer` de `ws`, qui en est un.
+     *
+     * ⚠️ Hors du verrou de trame, et pour toute la série 10 : la trame brute ne
+     * passe ni par l'autorisation `beforeDispatch` ni par les gardes d'action et de
+     * canal du JSON-RPC. La connexion, elle, a déjà franchi Origin, l'authentificateur
+     * et le pare-feu. L'identité se lit par `RequestContext.getAuthenticatedUser()`,
+     * et toute décision d'accès sur une trame binaire appartient à l'application.
+     *
+     * ⚠️ Un `DataView` se construit sur `data.buffer` AVEC `data.byteOffset` et
+     * `data.byteLength` : un `Buffer` issu du pool de Node ne commence pas à 0.
+     *
+     * @param data - les octets reçus.
+     */
+    protected onRealtimeBinary?(data: Uint8Array): void;
+    /**
+     * Faute de câblage : `handleRealtime` reçu par une instance qui ne sert pas
+     * une connexion WebSocket — route sans `methods: ["WEBSOCKET"]`, ou faux
+     * contexte de test sans `type`. Levée plutôt que passée sous silence : le
+     * client attendrait un welcome qui ne vient jamais. Chemin froid.
+     */
+    private outsideWebsocketError;
+    private receiveBinary;
     /**
      * **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
      * connexion (sur une action qu'il a exposée via `client.register(...)`) et attend
@@ -143,6 +177,22 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * handshake n'est pas terminé.
      */
     protected notifyClient<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void;
+    /**
+     * Émet une trame BINAIRE vers CETTE connexion, sans la sérialiser — pendant
+     * sortant de {@link onRealtimeBinary}, et de `NodefonySocket.sendBinary` côté
+     * client. Même contre-pression que les frames JSON-RPC.
+     *
+     * @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
+     * @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
+     *   la trame jetée par la contre-pression.
+     */
+    protected sendBinaryToClient(data: Uint8Array): boolean;
+    /**
+     * État realtime de CETTE connexion, `undefined` avant le welcome — pour les
+     * chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
+     * gardent leur lecture en ligne : ils sont sur le chemin de chaque frame.
+     */
+    private coldConnState;
     /**
      * Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
      * réseau) PUIS crée peer+transport, enregistre les actions, welcome + cleanup.
@@ -164,6 +214,14 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * canaux FULL-DUPLEX déclarés (entrée client → handler `realtimeInbound`).
      */
     private onRealtimeNotification;
+    /**
+     * Acquitte un abonnement ACCEPTÉ (`realtime:subscribed`) — le seul signal
+     * qui dise au client à partir de quand le flux du canal lui est livré.
+     *
+     * Un refus n'y passe jamais : il a `realtime:denied`. Cold path (1×/canal et
+     * par connexion).
+     */
+    private acknowledgeSubscription;
     /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
     private startChannel;
     /**
@@ -187,7 +245,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     private actionParamsWrapper;
     /**
-     * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+     * Handler de la méthode RPC `api.request {path}` — le **pont socket**
      * (POC Ph.3) : résout le path porté par le message via le Router
      * (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
      * exécute l'action SANS la rendre (`executeAction`) : la valeur nue est

package/dist/types/nodefony/src/server/ServerRealtimeSocket.d.ts

@@ -16,8 +16,9 @@ import { type IRealtimeSocket, type IRealtimeChannel, type IChannelStats, type R
  *    l'état créé est passif, et c'est la fabrique du controller qui tranchera quand
  *    une connexion cliente le demandera. Un service n'invente donc jamais un canal
  *    pour les autres.
- *  - `request` : **non supporté** — un handle au-dessus du hub n'a PAS de pair unique
- *    (le hub est multi-clients). Pour un RPC serveur→client 1-1, utiliser
+ *  - `request` : **non supporté, et déprécié** — un handle au-dessus du hub n'a PAS de
+ *    pair unique (le hub est multi-clients), et le contrat commun `IRealtimeSocket` ne
+ *    le promet plus. Pour un RPC serveur→client 1-1, utiliser
  *    `RealtimeController.requestClient` (par connexion, L1).
  *
  * Lazy : aucune structure allouée tant que le service n'`on`/`subscribe`/`publish` pas.
@@ -25,7 +26,7 @@ import { type IRealtimeSocket, type IRealtimeChannel, type IChannelStats, type R
  * @typeParam Emit   — canaux pub/sub SORTANTS (`publish`) = ServerToClient.
  * @typeParam Listen — canaux pub/sub RÉCEPTIONNÉS (`subscribe`/`on`) = ClientToServer.
  */
-export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen, Actions> {
+export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen> {
     #private;
     private readonly hub;
     constructor(hub?: import("./RealtimeHub.js").RealtimeHub);
@@ -39,14 +40,23 @@ export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEvents
     subscribe(channel: EventNames<Listen> | (string & {})): void;
     /** Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur. */
     unsubscribe(channel: EventNames<Listen> | (string & {})): void;
-    /** Branche un handler de réception sur un canal. Renvoie un `dispose`. */
+    /**
+     * Branche un handler de réception sur un canal. Renvoie un `dispose`.
+     *
+     * Le handler typé par `Listen` se range sans conversion sous
+     * `RealtimeHandler`, qui porte la frontière du contrat typé : il reçoit ce
+     * que le hub publie, dont `Listen` décrit la forme sans la valider.
+     */
     on<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void;
-    /** Retire un handler d'un canal. */
+    /** Retire un handler d'un canal — même frontière que {@link on}. */
     off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void;
     /**
-     * **Non supporté.** Un handle au-dessus du hub n'a pas de pair unique
-     * (multi-clients). Pour un RPC serveur→client 1-1, utiliser
-     * `RealtimeController.requestClient` (par connexion, L1).
+     * **Non supporté** : rejette toujours. Un handle au-dessus du hub n'a pas de pair
+     * unique (multi-clients), et le contrat commun `IRealtimeSocket` ne promet plus
+     * `request`. Comportement inchangé pour toute la série 10.
+     *
+     * @deprecated Retrait en 11.0. Pour un RPC serveur→client 1-1, utiliser
+     *   `RealtimeController.requestClient` (par connexion, L1).
      */
     request<K extends string, T = unknown>(_method: K, _params?: ContractParams<Actions, K>, _timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
     /** Vue par-canal ({@link IRealtimeChannel}) — fine liaison sur les primitives. */

package/dist/types/nodefony/src/server/subscribedAck.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Trame d'acquittement d'abonnement — `realtime:subscribed`, écrite d'un bloc.
+ *
+ * Tout ce qui précède le nom du canal ne dépend que du protocole : il est
+ * calculé une fois au chargement du module. Seul le canal se sérialise par
+ * trame. On évite ainsi l'enveloppe allouée et le `JSON.stringify` générique
+ * de `JsonRpcPeer.notify` — mesuré à ~0,5 µs par acquittement, soit l'essentiel
+ * du surcoût d'un `subscribe` acquitté.
+ *
+ * ⚠️ C'est une SECONDE écriture du format de notification : son égalité avec
+ * `JsonRpcPeer.buildNotification` est verrouillée par `subscribedAck.test.ts`,
+ * sur des noms de canal hostiles (guillemets, barres obliques inverses,
+ * caractères de contrôle, Unicode).
+ *
+ * @internal
+ */
+/**
+ * Sérialise la notification `realtime:subscribed { channel }`.
+ *
+ * @param channel - le canal acquitté (entrée réseau : échappé par `JSON.stringify`).
+ * @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
+ */
+export declare function subscribedAckFrame(channel: string): string;

package/dist/types/nodefony/src/transport/WsConnectionTransport.d.ts

@@ -6,7 +6,7 @@ import type { IRealtimeConnProbe } from "../../interfaces/IRealtimeProbe.js";
  * `ctx.connection` (WebsocketContext) la fournit.
  */
 export interface RawWsConnection {
-    send(data: string, cb?: (err?: Error) => void): void;
+    send(data: string | ArrayBuffer | ArrayBufferView, cb?: (err?: Error) => void): void;
     close(code?: number, reason?: string): void;
     readonly readyState: number;
     /**
@@ -46,6 +46,8 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
     private _bytesSent;
     private _messagesSent;
     private _dropped;
+    private _binaryDiscarded;
+    private _malformedDiscarded;
     private readonly _max;
     private readonly _policy;
     private readonly _closeAfterDrops;
@@ -56,6 +58,29 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
     });
     connect(): void;
     send(raw: string): void;
+    /**
+     * Émet des octets tels quels — trame binaire RFC 6455, hors JSON-RPC (#617).
+     * Même contre-pression (`decideSend`, la règle unique) et mêmes compteurs que
+     * {@link send}. Écrite à part, et non en factorisant `send` : `send` est le
+     * chemin de CHAQUE frame JSON-RPC, et n'y paie pas un appel de plus.
+     *
+     * @param data - les octets à émettre.
+     * @returns `true` si la trame est partie, `false` si la connexion était
+     *   fermée ou la contre-pression l'a jetée.
+     */
+    sendBinary(data: Uint8Array): boolean;
+    /**
+     * Compte une trame ENTRANTE écartée et rend le cumul de sa nature — `1` dit
+     * « première », le seul instant où l'appelant journalise.
+     *
+     * @param kind - `binary` (sans lecteur) ou `malformed` (texte non JSON).
+     * @returns le cumul de cette nature, après incrément.
+     */
+    discard(kind: "binary" | "malformed"): number;
+    /** Cumul de trames BINAIRES reçues et écartées faute de lecteur — monotone. */
+    get binaryDiscarded(): number;
+    /** Cumul de trames TEXTE reçues et écartées parce que non JSON — monotone. */
+    get malformedDiscarded(): number;
     close(code?: number, reason?: string): void;
     get readyState(): number;
     /** Octets en file d'envoi non drainés (`ws.bufferedAmount`) — risque #1. `0` si mock. */

package/dist/types/nodefony/testing/index.d.ts

@@ -88,9 +88,11 @@ export interface IRealtimeHarnessOptions {
     /**
      * Verrou de frame (seam #1). Neutre par construction : `@nodefony/realtime`
      * ne connaît pas `@nodefony/security`. Une application qui charge la sécurité
-     * passe ici son `buildFrameAuthorizer(...)` pour éprouver une politique de
-     * canal ou une action gardée par rôle — sans lui, une `policy` déclarée n'est
-     * appliquée par personne, exactement comme au runtime.
+     * passe ici `createTestFrameAuthorizer(getRealtimeHub())` de
+     * `@nodefony/security/testing` — le verrou du pare-feu, jamais une copie —
+     * pour éprouver une politique de canal ou une action gardée par rôle. Sans
+     * lui, une `policy` déclarée n'est appliquée par personne, exactement comme
+     * au runtime.
      */
     readonly frameAuthorizer?: FrameAuthorizer;
     /**
@@ -130,7 +132,10 @@ export interface IRealtimeHarness<C extends RealtimeController> {
      *   échec) : lire `closes` pour en connaître la cause.
      */
     connect(): Promise<IRealtimeFrame>;
-    /** Demande un canal, comme le ferait un client. */
+    /**
+     * Demande un canal, comme le ferait un client, et attend la réponse du
+     * serveur (acquittement `realtime:subscribed` ou refus `realtime:denied`).
+     */
     subscribe(channel: string): Promise<void>;
     /** Rend un canal — le provider est disposé au dernier abonné. */
     unsubscribe(channel: string): Promise<void>;
@@ -149,6 +154,8 @@ export interface IRealtimeHarness<C extends RealtimeController> {
     messages(channel: string): readonly unknown[];
     /** Les refus d'abonnement notifiés (`realtime:denied`). */
     denials(): readonly IHarnessDenied[];
+    /** Les canaux dont l'abonnement a été acquitté (`realtime:subscribed`), dans l'ordre. */
+    subscriptions(): readonly string[];
     /** Ferme la socket côté client : la base dispose alors tous ses providers. */
     close(): void;
     /** `close()` puis remise à zéro du hub. À appeler en fin de cas. */