@nodefony/realtime 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { realtimeConfigSchema, type IRealtimeSchemaConfig } from "./config.js";
 import type { IBackplane } from "../interfaces/IBackplane.js";
 /**
@@ -19,11 +19,13 @@ import type { IBackplane } from "../interfaces/IBackplane.js";
  *   faire dans un JSON Schema Studio). L'instance, si fournie, prend précédence
  *   sur `driver` côté service ; ce dernier reste source d'introspection/UI.
  *
- * **Layering d'environnement** (convention-frère avec `REDIS_*` de
- * `@nodefony/redis`) : `NF_REALTIME_DRIVER` surcharge le driver backplane
- * APRÈS le parse (schéma pur, déterministe). Indispensable en déploiement
- * (k8s/Docker : `NF_REALTIME_DRIVER=redis`) et fiable quel que soit le
- * timing du merge `module-realtime` côté app (cf chantier ordering config).
+ * **Variables d'environnement** : `NF_REALTIME_DRIVER`,
+ * `NF_REALTIME_BACKPLANE_SECRET` et `NF_REALTIME_BACKPLANE_NAMESPACE` ne se
+ * lisent PAS ici. Chacune est déclarée sur son champ dans `config.ts`
+ * (`.meta({ env })`) et posée par le Kernel AVANT la validation : le schéma
+ * les valide comme une valeur de l'application (un secret de moins de 32
+ * caractères arrête le démarrage). Un appel direct de ce builder, hors Kernel,
+ * ne les voit donc pas.
  *
  * @param config - configuration brute (sections omises = défauts sûrs).
  * @param options.backplane - instance `IBackplane` custom (override le driver à
@@ -34,6 +36,27 @@ import type { IBackplane } from "../interfaces/IBackplane.js";
 export declare function defineRealtimeConfig(config?: IRealtimeConfigInput, options?: {
     backplane?: IBackplane;
 }): IRealtimeConfig;
+/**
+ * Le builder pour une entrée NON typée — la config reçue par le module au
+ * démarrage, dont le schéma décide seul de la forme. Interne au paquet : une
+ * application passe par {@link defineRealtimeConfig}, qui type ce qu'elle écrit.
+ *
+ * @param config - configuration brute, validée par le schéma
+ * @param options.backplane - instance `IBackplane` custom
+ * @returns config gelée prête pour `RealtimeService`.
+ * @throws BootConfigurationError si invalide.
+ */
+export declare function buildRealtimeConfig(config?: unknown, options?: {
+    backplane?: IBackplane;
+}): IRealtimeConfig;
+/**
+ * Vrai si la valeur est une config produite par {@link buildRealtimeConfig}
+ * (donc validée par le schéma). Lu une fois, à l'init du service.
+ *
+ * @param value - la config lue sur le module
+ * @returns `true` si elle sort du builder
+ */
+export declare function isRealtimeConfig(value: unknown): value is IRealtimeConfig;
 /**
  * JSON Schema introspectable de la config realtime — destiné au formulaire
  * d'édition Studio (futur). N'inclut PAS `backplane.instance` (non sérialisable).

package/dist/types/nodefony/decorators/realtimeDecorators.d.ts

@@ -140,8 +140,25 @@ export declare function RealtimeChannel(channel: string, policy?: IChannelPolicy
  *   }
  */
 export declare function RealtimeInbound(method: string, policy?: IChannelPolicy): MethodDecorator;
-/** Lecture (lazy, au handshake) du registre des actions décorées. */
-export declare function getRealtimeActions(instance: object): Record<string, RpcActionHandler> | null;
+/**
+ * Méthode d'action liée à son instance, appelable avec ses arguments réels —
+ * plusieurs quand ses paramètres sont décorés (`@Body`, `@CurrentUser`…).
+ */
+export type RealtimeActionMethod = (...args: unknown[]) => unknown;
+/**
+ * Enveloppe posée sur une action décorée au handshake : reçoit la méthode liée
+ * et son nom de propriété, rend le handler JSON-RPC à enregistrer.
+ */
+export type RealtimeActionWrapper = (method: RealtimeActionMethod, propertyKey: string | symbol) => RpcActionHandler;
+/**
+ * Lecture (lazy, au handshake) du registre des actions décorées.
+ *
+ * @param instance - le contrôleur de la connexion
+ * @param wrap - enveloppe optionnelle de chaque action (résolution des
+ *   paramètres décorés) ; sans elle, l'action reçoit la charge JSON-RPC brute
+ * @returns les handlers par nom d'action, ou `null` si aucune n'est décorée
+ */
+export declare function getRealtimeActions(instance: object, wrap?: RealtimeActionWrapper): Record<string, RpcActionHandler> | null;
 /** Lecture (lazy, au handshake) du registre des canaux décorés. */
 export declare function getRealtimeChannels(instance: object): Record<string, RealtimeChannelFactory> | null;
 /** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */

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/IRealtimeController.d.ts

@@ -22,7 +22,7 @@ export type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown)
  * (Les hooks `realtimeActions()` / `realtimeChannels()` sont `protected` sur la base
  * — détail d'implémentation surchargeable, hors contrat public.)
  *
- * Côté client, le pendant n'est PAS un controller mais `RealtimeClient` — tous deux
+ * Côté client, le pendant n'est PAS un controller mais `NodefonySocket` — tous deux
  * composent le même peer ; cf vision « la socket Nodefony ».
  */
 export interface IRealtimeController {

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

@@ -12,7 +12,7 @@
  * @see IRealtimeAuthenticator
  */
 export interface IRealtimeHandshake {
-    /** En-têtes de la requête upgrade (clés en lowercase RFC 7230 §3.2). */
+    /** En-têtes de la requête upgrade (clés en lowercase RFC 9110 §5.1). */
     readonly headers: Readonly<Record<string, string | string[] | undefined>>;
     /** Cookies parsés depuis `Cookie:` (vide si en-tête absent ou mal formé). */
     readonly cookies: ReadonlyMap<string, string>;

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/backplane/RedisBackplane.d.ts

@@ -83,6 +83,13 @@ export interface IRedisSubscriber {
  * Le listener Redis est conservé pour un `unsubscribe(channel, listener)` ciblé
  * (n'arrache pas d'éventuels autres abonnés du même client).
  */
+/**
+ * Vrai si la valeur expose la surface d'un client Redis publisher — vérifié au
+ * démarrage, sur le client que rend le service `redis`.
+ */
+export declare function isRedisPublisher(value: unknown): value is IRedisPublisher;
+/** Vrai si la valeur expose la surface d'un client Redis subscriber dédié. */
+export declare function isRedisSubscriber(value: unknown): value is IRedisSubscriber;
 export declare function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber): IRedisBackplaneTransport;
 /**
  * Réglages optionnels du driver — regroupés en objet pour ne pas allonger une

package/dist/types/nodefony/src/backplane/bootNotices.d.ts

@@ -0,0 +1,25 @@
+import type { IBootNotice } from "nodefony";
+/**
+ * Le temps réel ne dépasse pas ce processus : aucun backplane actif (driver
+ * `loopback`, `cluster` hors d'un worker, ou fabrique inactive ici).
+ *
+ * Simple information en développement mono-processus — c'est le cas normal —
+ * mais à savoir avant de déployer plusieurs exemplaires : un message publié
+ * sur l'un n'atteindrait pas les clients connectés aux autres.
+ *
+ * @param driver - le driver déclaré.
+ * @returns le point à déclarer.
+ */
+export declare function realtimeLocalOnlyNotice(driver: string): IBootNotice;
+/**
+ * Le backplane déclaré n'a pas pu démarrer — le hub est retombé en local.
+ *
+ * Distinct de {@link realtimeLocalOnlyNotice} : ici, l'application a DEMANDÉ
+ * un fan-out entre exemplaires et ne l'a pas. Deux pods servent alors deux
+ * mondes temps réel disjoints, sans erreur visible.
+ *
+ * @param driver - le driver déclaré.
+ * @param reason - la cause (message de l'échec).
+ * @returns le point à déclarer.
+ */
+export declare function realtimeBackplaneDownNotice(driver: string, reason: string): IBootNotice;

package/dist/types/nodefony/src/guards.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Gardes de type internes au paquet — elles remplacent une conversion (`as`)
+ * par une vérification faite à l'exécution, pour qu'une valeur d'une autre
+ * forme soit écartée au lieu de traverser le code sous un type qui ment.
+ *
+ * Non exportées par le paquet : ce sont des détails d'implémentation.
+ */
+/**
+ * Vrai si la valeur est un objet non nul : ses propriétés se lisent alors,
+ * typées `unknown`, et chacune se vérifie avant usage.
+ *
+ * @param value - valeur venue du réseau, d'une métadonnée ou du conteneur
+ * @returns `true` pour tout objet (tableau compris), `false` pour `null` et les primitives
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Vrai si la valeur est une fonction. Toute fonction JavaScript s'appelle avec
+ * n'importe quels arguments et rend une valeur inconnue : la signature annoncée
+ * ne promet rien de plus que ce que `typeof` a vérifié.
+ *
+ * @param value - valeur lue par son nom (métadonnée, propriété dynamique)
+ * @returns `true` si la valeur est appelable
+ */
+export declare function isCallable(value: unknown): value is (...args: unknown[]) => unknown;
+/**
+ * Vrai si la valeur se comporte comme une promesse (transport asynchrone) —
+ * un client Redis rend une promesse, un faux transport de test rend `void`.
+ *
+ * @param value - retour d'un transport
+ * @returns `true` si la valeur porte une méthode `then`
+ */
+export declare function isThenable(value: unknown): value is Promise<unknown>;

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

@@ -1,3 +1,16 @@
 import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
+ * `IRealtimeAuthenticatorMatcher` ne capture le handshake.
+ *
+ * Singleton gelé (`Object.freeze`) — 0 alloc par connexion non authentifiée.
+ * Aligné sur le pattern `AnonymousToken` de `@nodefony/security` S1 (même
+ * surface logique, type `"anonymous"`, `roles = ["ROLE_ANONYMOUS"]`).
+ *
+ * Stocké par le hub sur la map `peer → token` au handshake si aucun
+ * authenticator ne capture la connexion. Les voters P6 (futur) verront un
+ * token avec `isAuthenticated() === false` et appliqueront leur politique
+ * (Zero Trust : zone protégée → frame refusée par `beforeDispatch`).
+ */
 export declare const ANONYMOUS_REALTIME_TOKEN: IRealtimeToken;
 export default ANONYMOUS_REALTIME_TOKEN;

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

@@ -11,7 +11,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * — écrit UNE fois, partagé par tous les modules. Un contrôleur concret ne déclare que
  * son métier : {@link createRealtimeChannel} (providers de canaux) + {@link realtimeActions}.
  *
- * Chaque connexion compose un `JsonRpcPeer` (le MÊME que `RealtimeClient` côté navigateur
+ * Chaque connexion compose un `JsonRpcPeer` (le MÊME que `NodefonySocket` côté navigateur
  * — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
  *
  * Usage : le sous-classe garde sa route WS et délègue —
@@ -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
@@ -111,15 +112,48 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * est structurel, pas un choix : c'est au client d'attendre `realtime:welcome`
      * avant de pousser.
      *
-     * ⚠️ Cette phrase a longtemps ajouté « ce que `RealtimeClient` fait nativement ».
+     * ⚠️ Cette phrase a longtemps ajouté « ce que le client fait nativement ».
      * C'était FAUX : le client rejouait ses abonnements dès l'ouverture de la socket,
      * si bien qu'un `subscribe` posé avant le démarrage et TOUS ceux d'après une
      * reconnexion étaient perdus ici même, sans un mot des deux côtés. Un contrat écrit
      * d'un seul côté du fil n'est pas tenu ; il l'est désormais par
-     * `RealtimeClient.replaySubscriptions` et les deux cas « la fenêtre où le serveur
-     * écoute (welcome) » de `RealtimeClientCoverage.test.ts`.
+     * `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+     * é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,8 +214,36 @@ 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;
+    /**
+     * Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
+     * (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
+     * résolus par la fonction du framework et non par une copie.
+     *
+     * L'identité ne change PAS : un message est déjà traité dans la bulle
+     * `RequestContext` du handshake (`WebsocketContext` lie son écouteur par
+     * `AsyncResource.bind`), où le pare-feu a posé `user` et `token`. La bulle
+     * ouverte ici HÉRITE de ce store et n'y ajoute que la charge (`body`, que
+     * `@Body` lit dans l'ALS comme pour `api.request`) — une écriture
+     * `RequestContext.set()` dans l'action reste ainsi propre à l'appel.
+     *
+     * Une action sans paramètre décoré est rendue telle quelle : rien ne change
+     * pour elle, ni comportement ni coût. Les métadonnées se lisent ICI, une fois
+     * par connexion.
+     *
+     * @param ctx - le contexte de la connexion
+     * @returns l'enveloppe passée à {@link getRealtimeActions}
+     */
+    private actionParamsWrapper;
     /**
      * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
      * (POC Ph.3) : résout le path porté par le message via le Router

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

@@ -71,16 +71,13 @@ export declare const RESERVED_SYSTEM_PREFIXES: readonly ["nodefony:"];
  */
 export declare const isReservedSystemChannel: typeof isPlatformChannel;
 /**
- * Période de re-validation des identités RÉVOCABLES — F4 (revue 0.6).
- * Le verrou de frame est SYNC par doctrine (identité figée au handshake, cf
- * {@link FrameAuthorizer}) → il ne peut pas re-lire la session par frame. Un socket
- * survivrait donc à sa session (`subscribe` garderait ses flux après un logout HTTP),
- * là où `api.request` re-valide déjà par requête (`isValid()`). Ce tick ferme
- * l'écart : toutes les `REVOCATION_REVALIDATE_MS`, les tokens révocables sont
- * re-validés et la connexion fermée si l'identité n'est plus valide (≤ 1 fenêtre de
- * délai). Ordre de grandeur aligné sur le heartbeat WS (`keepaliveInterval` 20 s).
+ * Période de re-validation des identités RÉVOCABLES — F4 (revue 0.6). Le verrou
+ * de frame est SYNC (identité figée au handshake) : ce tick ferme l'écart avec
+ * `api.request`, qui re-valide par requête. Définie par le cœur, qui porte le
+ * registre partagé avec les flux SSE ; ré-exportée ici pour les consommateurs
+ * du hub.
  */
-export declare const REVOCATION_REVALIDATE_MS = 30000;
+export { REVOCATION_REVALIDATE_MS } from "nodefony";
 /**
  * Le MOTIF de famille d'un canal — son dernier segment remplacé par `*`.
  *
@@ -156,7 +153,7 @@ export type ChannelFactory = (channel: string, publish: RealtimePublish) => (()
  * multiplexe des canaux ; le hub aiguille entre les sockets. La façade *consommateur*
  * côté serveur EXISTE — {@link ServerRealtimeSocket} (`subscribe/on/publish`), exportée
  * par le barrel du module : c'est elle qu'un service back tient, jamais ce hub
- * directement. Même rôle que `RealtimeClient` côté navigateur.
+ * directement. Même rôle que `NodefonySocket` côté navigateur.
  */
 export declare class RealtimeHub {
     #private;
@@ -288,14 +285,23 @@ export declare class RealtimeHub {
      */
     unregisterRevocable(entry: IRevocableConnection): void;
     /**
-     * Tick de re-validation (F4) : re-lit l'identité de chaque connexion révocable
-     * (`token.isValid()`) et FERME la socket (`4001`) si l'identité est morte : session
-     * détruite ou passée à un autre compte, jeton expiré ou révoqué.
-     * Fail-closed : une re-validation qui throw ferme aussi (parité `invokeApiRequest`).
-     * Snapshot du registre AVANT les `await` (le `close` mute le registre via le cleanup
-     * `onFinish`). Exposé (public) pour un test déterministe sans fake timers.
+     * Re-valide toutes les connexions révocables et ferme (`4001`) celles dont
+     * l'identité est morte : session détruite ou passée à un autre compte, jeton
+     * expiré ou révoqué. Fail-closed : une re-validation qui lève ferme aussi. Le
+     * registre est celui des flux SSE ({@link RevocationWatch}) — une garde, deux
+     * transports. Exposé (public) pour un test déterministe sans faux minuteur.
      */
     revalidateRevocable(): Promise<void>;
+    /**
+     * Ferme tout de suite les connexions qui ont figé cette identité — ses droits
+     * ont changé (`IDENTITY_CHANGED_EVENT`). Code {@link IDENTITY_REFRESH_CLOSE_CODE},
+     * reconnectable : le client revient avec ses rôles frais. Le registre est
+     * celui des flux SSE — une règle, deux transports.
+     *
+     * @param identifier - identifiant de connexion de l'identité changée.
+     * @returns le nombre de connexions fermées.
+     */
+    refreshIdentity(identifier: string): number;
     /**
      * Compte une frame entrante full-duplex (canaux gated SIP/bridge). Appelé par le
      * contrôleur quand un handler `realtimeInbound` traite un message client.

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/service/RealtimeService.d.ts

@@ -2,7 +2,7 @@ import { Service, Module, type JsonRpcPeer } from "nodefony";
 import { type RealtimeHub, type ChannelFactory, type ChannelSink, type FrameAuthorizer } from "../server/RealtimeHub.js";
 import type { IBackplane } from "../../interfaces/IBackplane.js";
 import type { IRealtimeProbe } from "../../interfaces/IRealtimeProbe.js";
-import type { IRealtimeConfig } from "../../config/defineModuleConfig.js";
+import { type IRealtimeConfig } from "../../config/defineModuleConfig.js";
 import type { IRealtimeAuthenticator } from "../../interfaces/IRealtimeAuthenticator.js";
 import type { IRealtimeAuthenticatorMatcher } from "../../interfaces/IRealtimeAuthenticatorMatcher.js";
 import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";

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

@@ -12,7 +12,7 @@
  *
  * Le harnais pilote le **côté serveur** : il injecte des frames JSON-RPC 2.0
  * telles qu'un client les enverrait, et lit celles qui sortent. Il n'embarque
- * PAS `RealtimeClient` — le client est un artefact navigateur du cœur, et le
+ * PAS `NodefonySocket` — le client est un artefact navigateur du cœur, et le
  * tirer ici le ferait entrer dans le paquet serveur publié. Ce qu'on veut
  * prouver d'un controller (ses canaux, ses actions, son plein-duplex, son
  * nettoyage) s'observe entièrement aux frames.
@@ -29,7 +29,7 @@
  *
  * @packageDocumentation
  */
-import type { IRealtimeDenied } from "nodefony";
+import { type IRealtimeDenied } from "nodefony";
 import type { ContextType } from "@nodefony/http";
 import type { RealtimeController } from "../src/server/RealtimeController.js";
 import { type RealtimeHub, type FrameAuthorizer } from "../src/server/RealtimeHub.js";
@@ -130,7 +130,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 +152,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. */