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

package/docs/architecture.md

@@ -124,9 +124,9 @@ Nodefony étiquette avec **JSON-RPC 2.0**, une norme publique plutôt qu'un form
 | **notification** | non          | non                             | pousser un événement, s'abonner, se désabonner |
 
 Le point remarquable : le **même** moteur de protocole tourne des deux côtés du fil. La
-classe `JsonRpcPeer` (`JsonRpcPeer.ts:271`) est du code isomorphe du cœur — le navigateur
-l'exécute dans `RealtimeClient`, le serveur l'instancie une fois par connexion dans
-`RealtimeController.onHandshake()` (`RealtimeController.ts:374`). Le serveur peut donc
+classe `JsonRpcPeer` (`JsonRpcPeer.ts:311`) est du code isomorphe du cœur — le navigateur
+l'exécute dans `NodefonySocket`, le serveur l'instancie une fois par connexion dans
+`RealtimeController.onHandshake()` (`RealtimeController.ts:450`). Le serveur peut donc
 appeler le client, pas seulement l'inverse : c'est du vrai duplex, pas un aller-retour
 déguisé.
 
@@ -137,15 +137,15 @@ Trois partis pris distinguent cette pile d'un simple « serveur WebSocket ».
 **Un seul contrat de socket, des deux côtés.** Un service back qui pousse des événements
 écrit le même code qu'une page front : `publish` / `subscribe` / `on`. Côté serveur c'est
 `ServerRealtimeSocket` (`ServerRealtimeSocket.ts:43`), obtenu par `serverSocket()`
-(`ServerRealtimeSocket.ts:223`) ; côté navigateur, `RealtimeClient`. Une exception, assumée
-et explicite : `ServerRealtimeSocket.request()` (`ServerRealtimeSocket.ts:131`) **rejette
+(`ServerRealtimeSocket.ts:243`) ; côté navigateur, `NodefonySocket`. Une exception, assumée
+et explicite : `ServerRealtimeSocket.request()` (`ServerRealtimeSocket.ts:150`) **rejette
 toujours** — un handle posé sur le hub n'a pas d'interlocuteur unique, puisque le hub est
 multi-clients. Pour un appel serveur→client ciblé, on passe par la connexion :
-`RealtimeController.requestClient()` (`RealtimeController.ts:329`).
+`RealtimeController.requestClient()` (`RealtimeController.ts:395`).
 
 **Un provider par canal, pas un par client.** Si mille onglets s'abonnent au même canal de
 santé, le calcul ne doit tourner qu'une fois. Le hub crée le producteur au **premier**
-abonné et le détruit au **dernier** (`RealtimeHub.subscribe()`, `RealtimeHub.ts:462`) : le
+abonné et le détruit au **dernier** (`RealtimeHub.subscribe()`, `RealtimeHub.ts:464`) : le
 coût suit le nombre de canaux, pas le nombre de clients.
 
 **Le cluster est un détail de configuration.** Ni ton contrôleur ni ton client ne savent
@@ -154,7 +154,7 @@ chaîne de caractères. Passer de mono-process à multi-pods ne touche aucune li
 
 **Le compromis, dit franchement** : un canal **ne franchit PAS** la frontière du process
 tant que tu ne l'as pas déclaré. Le défaut est l'isolement (`RealtimeHub.publish()`,
-`RealtimeHub.ts:604`) — un choix de sûreté détaillé plus bas.
+`RealtimeHub.ts:610`) — un choix de sûreté détaillé plus bas.
 
 ## 🚀 Démarrage rapide
 
@@ -260,7 +260,7 @@ export default ChatController;
 
 ```ts
 // frontend/src/chat.ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 interface ChatMessage {
   from: string;
@@ -271,7 +271,7 @@ interface ChatMessage {
 const scheme = location.protocol === "https:" ? "wss" : "ws";
 // `shared` = une seule socket par URL pour toute la page, même si dix
 // composants la demandent (les options ne comptent qu'à la création).
-const socket = RealtimeClient.shared({
+const socket = NodefonySocket.shared({
   url: `${scheme}://${location.host}/chat/realtime`,
 });
 
@@ -291,7 +291,7 @@ export async function start(): Promise<void> {
 ### Ce qu'on observe
 
 Au démarrage du serveur, le module annonce son fond de panier — une ligne, toujours la
-même forme, quel que soit le driver (`src/packages/@nodefony/realtime/index.ts:303`) :
+même forme, quel que soit le driver (`src/packages/@nodefony/realtime/index.ts:316`) :
 
 ```
 realtime backplane  driver=loopback kind=local cross-pod=no (hub local)
@@ -322,9 +322,9 @@ La pile se lit de haut en bas ; chaque étage ne connaît que son voisin du dess
 | Étage      | Qui                                                     | Sa seule responsabilité                 | Ce qu'il ignore               |
 | ---------- | ------------------------------------------------------- | --------------------------------------- | ----------------------------- |
 | Applicatif | ton contrôleur, tes services                            | le métier : quoi publier, quoi accepter | tout le reste                 |
-| Protocole  | `JsonRpcPeer` (`JsonRpcPeer.ts:271`)                    | étiqueter, corréler, refuser une frame  | par où passent les octets     |
+| Protocole  | `JsonRpcPeer` (`JsonRpcPeer.ts:311`)                    | étiqueter, corréler, refuser une frame  | par où passent les octets     |
 | Transport  | `WsConnectionTransport` (`WsConnectionTransport.ts:46`) | déplacer des octets, mesurer la file    | ce que veut dire un message   |
-| Hub        | `RealtimeHub` (`RealtimeHub.ts:213`)                    | table des abonnés locaux + fan-out      | qu'il existe d'autres process |
+| Hub        | `RealtimeHub` (`RealtimeHub.ts:214`)                    | table des abonnés locaux + fan-out      | qu'il existe d'autres process |
 | Backplane  | `IBackplane` (`IBackplane.ts:107`)                      | porter un message aux autres process    | ce qu'est un abonné           |
 
 > [!NOTE]
@@ -338,11 +338,11 @@ La pile se lit de haut en bas ; chaque étage ne connaît que son voisin du dess
 dispatch des notifications, gestion des erreurs, `dispose()` propre. Deux points
 d'interception y sont posés :
 
-- `beforeDispatch` (`JsonRpcPeer.ts:192`) — un verrou **synchrone** appelé avant tout
+- `beforeDispatch` (`JsonRpcPeer.ts:219`) — un verrou **synchrone** appelé avant tout
   traitement de frame. Il rend `true`/`false`. Un refus sur une requête produit
   `-32001 unauthorized` ; sur une notification, la frame est jetée
-  (`JsonRpcPeer.ts:413`).
-- `onFrameAudit` (`JsonRpcPeer.ts:210`) — la trace des événements protocolaires notables
+  (`JsonRpcPeer.ts:449`).
+- `onFrameAudit` (`JsonRpcPeer.ts:236`) — la trace des événements protocolaires notables
   (frame invalide, refusée, méthode inconnue, erreur interne).
 
 La contrainte de synchronisme n'est pas un oubli : un `await` par frame coûterait une
@@ -362,21 +362,23 @@ même façon, par le hook `onFinish` du contexte, qui déclenche `fireClose()`
 Ce transport porte aussi la **back-pressure**. Elle n'est pas câblée en dur : les trois
 leviers sont des clés de configuration du serveur WebSocket, lues par le transport
 (`WsConnectionTransport.ts:63-75`) et documentées dans `@nodefony/http`
-(`http/nodefony/config/config.ts:1044`).
+(`http/nodefony/config/config.ts:1226`).
 
-| File non drainée (`bufferedAmount`)     | Décision                                            | Réglage (défaut)                                                                      |
-| --------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| sous le seuil                           | envoi normal                                        | —                                                                                     |
-| au-dessus du seuil                      | politique appliquée : frame **jetée**, ou fermeture | `websocket.maxBackpressure` (**4 MiB**) · `websocket.backpressurePolicy` (**`drop`**) |
-| drops **consécutifs** au-delà du compte | fermeture `1013` (_Try Again Later_)                | `websocket.backpressureCloseAfterDrops` (**1000**)                                    |
+| File non drainée (`bufferedAmount`) | Décision                                            | Réglage (défaut)                                                                      |
+| ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| sous le seuil                       | envoi normal                                        | —                                                                                     |
+| au-dessus du seuil                  | politique appliquée : frame **jetée**, ou fermeture | `websocket.maxBackpressure` (**4 MiB**) · `websocket.backpressurePolicy` (**`drop`**) |
+| **solde** de refus atteint          | fermeture `1013` (_Try Again Later_)                | `websocket.backpressureCloseAfterDrops` (**1000**)                                    |
 
 Deux points que la formulation « deux seuils d'octets » faisait manquer : la fermeture ne
-se déclenche pas sur un volume mais sur une **suite de frames jetées** — une seule frame
-qui repart remet le compteur à zéro — et `drop` est un choix, `close` fermant dès le
-premier dépassement. Jeter est acceptable parce que les canaux d'état sont « le dernier
-gagne » : le prochain instantané remplace celui qu'on a sauté.
-
-À ne pas confondre avec `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:63`, 1 MiB) : ce seuil-là
+se déclenche pas sur un volume mais sur un **solde de frames jetées** — +1 par refus, −1 par
+envoi, si bien qu'un pic passager redescend et qu'un client qui n'absorbe plus finit coupé — et
+`drop` est un choix, `close` fermant dès le premier dépassement. Jeter est sans conséquence sur
+un canal d'état, où le prochain instantané remplace celui qu'on a sauté ; mais le rejet ne trie
+rien, et une réponse RPC ou un événement jetés sont perdus. Détail et courbes :
+[Cadence et contre-pression](./cadence-et-contre-pression.md).
+
+À ne pas confondre avec `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:64`, 1 MiB) : ce seuil-là
 ne jette rien, il **compte** — c'est celui à partir duquel la sonde marque une connexion
 `slowConsumer`.
 
@@ -388,7 +390,7 @@ Le schéma ci-dessous rend ces étages vivants : active le temps réel et il res
 
 ## 🔌 Le cycle de vie d'une connexion
 
-Tout se joue dans `RealtimeController.onHandshake()` (`RealtimeController.ts:374`), appelé
+Tout se joue dans `RealtimeController.onHandshake()` (`RealtimeController.ts:450`), appelé
 une seule fois par connexion, en chemin froid.
 
 ```mermaid
@@ -419,19 +421,19 @@ sequenceDiagram
 
 Les étapes, dans l'ordre exact du code :
 
-1. **Contrôle de l'origine** — `RealtimeHub.checkOrigin()` (`RealtimeHub.ts:986`). Refus →
+1. **Contrôle de l'origine** — `RealtimeHub.checkOrigin()` (`RealtimeHub.ts:967`). Refus →
    fermeture `4003`. La politique vient de la configuration ; sans politique, tout passe.
 2. **Résolution de l'identité** — `RealtimeHub.resolveAuthenticator()`
-   (`RealtimeHub.ts:961`) parcourt les authentificateurs enregistrés : **le premier motif
+   (`RealtimeHub.ts:943`) parcourt les authentificateurs enregistrés : **le premier motif
    qui correspond capture**. Aucun ne correspond ? Le jeton anonyme gelé est posé
    (`ANONYMOUS_REALTIME_TOKEN`) — la lecture d'identité ne rend donc jamais `null`. Un
    échec d'authentification ferme en `4001`.
 3. **Création du peer et du transport**, puis association `peer → jeton`
-   (`RealtimeHub.setTokenForPeer()`, `RealtimeHub.ts:1018`), stockée dans une `WeakMap` : le
+   (`RealtimeHub.setTokenForPeer()`, `RealtimeHub.ts:999`), stockée dans une `WeakMap` : le
    jeton disparaît avec le peer, sans fuite.
 4. **Enregistrement des actions** — celles des décorateurs `@RealtimeAction`, puis celles
    de la surcharge `realtimeActions()`, qui gagne en cas de conflit. Le pont API
-   `api.request` n'est ajouté que si `realtimeApiRequest()` (`RealtimeController.ts:276`)
+   `api.request` n'est ajouté que si `realtimeApiRequest()` (`RealtimeController.ts:321`)
    rend `true`.
 5. **Inscription aux registres** : sonde de connexion, révocation périodique si le jeton
    est révocable, préfixes de canaux broadcast, canaux entrants.
@@ -439,7 +441,7 @@ Les étapes, dans l'ordre exact du code :
    l'identité résolue (type, authentifié ou non, rôles, portées). Le client sait **qui il
    est** sans appeler la moindre route.
 
-À la fermeture, un unique `onFinish` (`RealtimeController.ts:715`) fait le ménage complet :
+À la fermeture, un unique `onFinish` (`RealtimeController.ts:771`) fait le ménage complet :
 désabonnement de chaque canal tenu, retrait des deux registres, `fireClose()` du transport,
 `dispose()` du peer. C'est ce qui garantit qu'aucun minuteur ni écouteur ne survit à une
 déconnexion.
@@ -447,41 +449,41 @@ déconnexion.
 > [!IMPORTANT]
 > Les frames reçues **pendant** l'authentification sont jetées silencieusement : le
 > transport n'est pas encore branché. C'est au client d'attendre `realtime:welcome` avant
-> de pousser — ce que `RealtimeClient` fait nativement.
+> de pousser — ce que `NodefonySocket` fait nativement.
 
 ### Deux gardes qui ferment la connexion
 
 | Garde                 | Déclencheur                                                            | Effet                                               | Ancrage                     |
 | --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- | --------------------------- |
-| Plafond de canaux     | une connexion dépasse son quota d'abonnements (256 par défaut)         | abonnement refusé + `realtime:denied` motif `limit` | `RealtimeController.ts:618` |
-| Révocation d'identité | tick périodique ; `token.isValid()` rend `false` ou lève une exception | fermeture `4001` « session revoked »                | `RealtimeHub.ts:48`         |
+| Plafond de canaux     | une connexion dépasse son quota d'abonnements (256 par défaut)         | abonnement refusé + `realtime:denied` motif `limit` | `RealtimeController.ts:852` |
+| Révocation d'identité | tick périodique ; `token.isValid()` rend `false` ou lève une exception | fermeture `4001` « session revoked »                | `RealtimeHub.ts:49`         |
 
 La seconde mérite une explication. Le verrou de frame est synchrone et lit une identité
 figée au handshake : il ne peut donc pas voir une session qui meurt en cours de route (une
 déconnexion HTTP, par exemple). Un minuteur — démarré au premier inscrit, arrêté dès que le
-registre se vide (`RealtimeHub.registerRevocable()`, `RealtimeHub.ts:794`) — relit
+registre se vide (`RealtimeHub.registerRevocable()`, `RealtimeHub.ts:796`) — relit
 périodiquement ces identités et coupe les sockets orphelines. Seules les identités
 **révocables** y entrent : un visiteur anonyme ne coûte rien.
 
 ## Le hub — canaux partagés et fan-out
 
-Le hub est un singleton par process (`getRealtimeHub()`, `RealtimeHub.ts:1451`). Il ne
+Le hub est un singleton par process (`getRealtimeHub()`, `RealtimeHub.ts:1432`). Il ne
 dépend de rien : ce sont les fabriques fournies par les contrôleurs qui portent les
 dépendances.
 
 ### Le provider partagé — un ticker, pas mille
 
-`RealtimeHub.subscribe()` (`RealtimeHub.ts:462`) applique une mécanique en trois temps :
+`RealtimeHub.subscribe()` (`RealtimeHub.ts:464`) applique une mécanique en trois temps :
 
 1. Le canal existe déjà ? On ajoute simplement le sink de cette connexion. Fin.
 2. Sinon, on inscrit le sink **avant** d'appeler la fabrique — de sorte que le tout premier
    paquet du producteur atteigne bien ce premier abonné.
 3. La fabrique du contrôleur rend `null` (canal inconnu de lui) ? Dernier recours : le
    registre des **canaux système** (`RealtimeHub.registerSystemChannel()`,
-   `RealtimeHub.ts:1297`), qu'un module bas niveau alimente au démarrage. Toujours `null` →
+   `RealtimeHub.ts:1278`), qu'un module bas niveau alimente au démarrage. Toujours `null` →
    l'abonnement est refusé et rien n'est alloué.
 
-Au dernier désabonnement, `RealtimeHub.unsubscribe()` (`RealtimeHub.ts:576`) appelle le
+Au dernier désabonnement, `RealtimeHub.unsubscribe()` (`RealtimeHub.ts:578`) appelle le
 `dispose` du producteur et retire le canal. Un producteur fautif qui lève une exception ne
 bloque pas le nettoyage.
 
@@ -496,22 +498,22 @@ Deux méthodes qui se ressemblent et ne font pas du tout la même chose :
 
 | Méthode                                 | Fan-out local |   Propagation aux autres process   | Qui l'appelle                       |
 | --------------------------------------- | :-----------: | :--------------------------------: | ----------------------------------- |
-| `publish()` (`RealtimeHub.ts:604`)      |      oui      | oui, **si** le canal est broadcast | producteurs, contrôleurs, services  |
-| `publishLocal()` (`RealtimeHub.ts:623`) |      oui      |             **jamais**             | l'arrivée d'un message du backplane |
+| `publish()` (`RealtimeHub.ts:610`)      |      oui      | oui, **si** le canal est broadcast | producteurs, contrôleurs, services  |
+| `publishLocal()` (`RealtimeHub.ts:629`) |      oui      |             **jamais**             | l'arrivée d'un message du backplane |
 
 C'est **la** règle qui empêche la tempête : un message reçu d'un pair est réinjecté
 localement et **ne repart pas**. Le câblage se fait une fois pour toutes dans
-`RealtimeHub.setBackplane()` (`RealtimeHub.ts:714`), qui branche l'arrivée du backplane
+`RealtimeHub.setBackplane()` (`RealtimeHub.ts:720`), qui branche l'arrivée du backplane
 directement sur `publishLocal`.
 
-Le fan-out lui-même (`RealtimeHub.ts:340`) est **isolé** : chaque livraison est protégée,
+Le fan-out lui-même (`RealtimeHub.ts:346`) est **isolé** : chaque livraison est protégée,
 une connexion fautive n'interrompt pas la diffusion aux autres.
 
 ### Le forward est OPT-IN — le défaut est l'isolement
 
 Par défaut, **aucun canal ne traverse le backplane**. Il faut déclarer un préfixe, via
-`@RealtimeBroadcast` sur ton contrôleur (`realtimeDecorators.ts:342`) ou
-directement `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:668`).
+`@RealtimeBroadcast` sur ton contrôleur (`realtimeDecorators.ts:420`) ou
+directement `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:674`).
 
 Trois raisons à ce choix, qui prend à contre-pied la plupart des bibliothèques temps réel :
 
@@ -578,7 +580,7 @@ resynchronise. Ne construis pas au-dessus une fiabilité que le support n'offre
 | ---------- | ----------------------------------------------- | -------------- | ---------------------------------- | :---------------: |
 | `loopback` | `LoopbackBackplane` (`LoopbackBackplane.ts:24`) | `local`        | aucun (no-op complet)              |        non        |
 | `cluster`  | `ClusterBackplane` (`ClusterBackplane.ts:89`)   | `ipc`          | les workers du même process maître |        non        |
-| `redis`    | `RedisBackplane` (`RedisBackplane.ts:161`)      | `redis-pubsub` | tous les pods abonnés au canal     |      **oui**      |
+| `redis`    | `RedisBackplane` (`RedisBackplane.ts:219`)      | `redis-pubsub` | tous les pods abonnés au canal     |      **oui**      |
 
 **`loopback`** est le défaut. En réalité, le hub garde son backplane à `null` en
 mono-process : le coût est un test de nullité, pas un appel. La classe existe pour
@@ -588,16 +590,16 @@ rien.
 **`cluster`** relie les workers d'un même hôte. Un worker Node ne peut parler qu'au maître :
 il émet vers lui (`ClusterBackplane.publish()`, `ClusterBackplane.ts:117`), le maître
 rediffuse aux autres. Le driver ne s'active qu'en rôle worker avec la variable
-`NF_CLUSTER=1` (`src/packages/@nodefony/realtime/index.ts:99`) ; ailleurs il rend
+`NF_CLUSTER=1` (`src/packages/@nodefony/realtime/index.ts:106`) ; ailleurs il rend
 `null`. Aucune infrastructure requise — c'est le banc d'essai qui stabilise l'architecture
 multi-process avant d'ajouter du réseau.
 
 **`redis`** franchit la frontière de l'hôte, sans dépendre de la bibliothèque `redis` : il
 consomme deux connexions du module `@nodefony/redis` via un adaptateur purement structurel,
-`createRedisServiceTransport()` (`RedisBackplane.ts:100`). Deux connexions et non une, parce
+`createRedisServiceTransport()` (`RedisBackplane.ts:137`). Deux connexions et non une, parce
 qu'un client Redis abonné ne peut plus émettre de commandes ordinaires. Module absent ou
 connexions indisponibles → avertissement, `null`, hub local, démarrage poursuivi
-(`src/packages/@nodefony/realtime/index.ts:108`).
+(`src/packages/@nodefony/realtime/index.ts:115`).
 
 ### Le registre de drivers — zéro nom en dur
 
@@ -606,7 +608,7 @@ brancherie. La sélection passe donc par un registre — `registerBackplaneDrive
 (`backplaneRegistry.ts:55`) et `getBackplaneDriver()` (`backplaneRegistry.ts:63`) : chaque
 driver porte son nom en membre statique, les natifs s'inscrivent au chargement du module, et
 le câblage résout une chaîne vers une fabrique sans connaître aucun littéral
-(`src/packages/@nodefony/realtime/index.ts:253`).
+(`src/packages/@nodefony/realtime/index.ts:260`).
 
 Une fabrique reçoit module, `originId`, rôle dans la topologie et configuration validée
 (`IBackplaneFactoryContext`, `backplaneRegistry.ts:27`), puis rend une instance ou `null`
@@ -620,7 +622,7 @@ et non une :
 
 1. **Côté hub** : l'arrivée passe par `publishLocal`, jamais par `publish`. Rien ne repart.
 2. **Côté backplane** : à la réception, on compare l'`originId` de l'enveloppe au sien et
-   on jette si c'est le même (`RedisBackplane.ts:209`, `ClusterBackplane.ts:134`).
+   on jette si c'est le même (`RedisBackplane.ts:235`, `ClusterBackplane.ts:134`).
 
 L'étiquette elle-même est calculée par `resolveBackplaneOriginId()` (`originId.ts:24`), et
 sa recette mérite qu'on s'y arrête :
@@ -648,7 +650,7 @@ applications sur un Redis mutualisé se parleraient.
 D'où le suffixe de cloison, calculé par `resolveRedisChannel()` (`RedisBackplane.ts:31`) :
 le canal effectif devient `nodefony:realtime:<namespace>`. Le namespace vient de la
 configuration ; à défaut, il est dérivé du nom de l'application
-(`src/packages/@nodefony/realtime/index.ts:132`).
+(`src/packages/@nodefony/realtime/index.ts:139`).
 
 > [!TIP]
 > Deux déploiements de la **même** application sur un Redis partagé (préproduction et
@@ -661,14 +663,14 @@ est ignoré, pas propagé (`RedisBackplane.ts:212`).
 ### Le démarrage, et ce qui se passe quand ça rate
 
 Le module valide sa configuration par Zod à l'enregistrement
-(`src/packages/@nodefony/realtime/index.ts:219`), puis câble tout au démarrage du noyau
-(`src/packages/@nodefony/realtime/index.ts:213`) — après l'initialisation des services (le
+(`src/packages/@nodefony/realtime/index.ts:226`), puis câble tout au démarrage du noyau
+(`src/packages/@nodefony/realtime/index.ts:220`) — après l'initialisation des services (le
 service Redis a donc ouvert ses connexions) et avant le trafic.
 
 Le `start()` du backplane est **attendu explicitement avant** d'être branché : un driver
 asynchrone brancherait sinon un abonnement incomplet et perdrait ses premiers messages. Et
 il est **borné par un délai** de cinq secondes
-(`src/packages/@nodefony/realtime/index.ts:83`), pour une raison très concrète : un
+(`src/packages/@nodefony/realtime/index.ts:90`), pour une raison très concrète : un
 transport réseau qui reste pendu gèlerait la phase de démarrage, et donc la montée des
 serveurs HTTP eux-mêmes.
 
@@ -680,7 +682,7 @@ Trois issues, toutes annoncées, jamais silencieuses :
 | driver inactif ici (loopback, mauvais rôle)  | hub local                            | `INFO`    |
 | driver inconnu, ou démarrage en échec/expiré | hub local, **le démarrage continue** | `WARNING` |
 
-Le module se déclare non critique (`src/packages/@nodefony/realtime/index.ts:144`) : son
+Le module se déclare non critique (`src/packages/@nodefony/realtime/index.ts:151`) : son
 échec ne tue jamais le process. C'est de la résilience **sans dégradation silencieuse** —
 tout repli est annoncé. Enfin, `enabled: false` rend le module totalement inerte : ni API
 d'administration, ni backplane, ni sonde.
@@ -718,8 +720,8 @@ code qui **appelle le builder lui-même** (un `Module` sur mesure, une intégrat
 programmatique). Une application qui configure via `use("@nodefony/realtime", …)` **ne
 l'atteint pas** : elle ne construit pas la config (le module appelle
 `defineRealtimeConfig(this.options)` sans second argument, `index.ts:216`), et une
-instance posée dans l'objet de config est retirée par la validation Zod (elle n'est pas
-au schéma). Pour une app, la voie « instance » est l'option 2 ci-dessus.
+instance posée dans l'objet de config est refusée par la validation Zod (clé inconnue du
+schéma strict). Pour une app, la voie « instance » est l'option 2 ci-dessus.
 
 Le registre s'introspecte : `listBackplaneDrivers()` (`backplaneRegistry.ts:68`) rend les
 noms disponibles — c'est ce que le message d'erreur affiche quand un driver déclaré est
@@ -733,29 +735,29 @@ refonte. Ici, seulement **où** ils sont ; le **quoi** et le **comment** sont da
 
 | Point de greffe              | Étage     | Moment         | Ancrage                     |
 | ---------------------------- | --------- | -------------- | --------------------------- |
-| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts:614`        |
-| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts:579`        |
-| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts:675`        |
-| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts:713`        |
-| Audit de frame               | protocole | sur refus      | `RealtimeController.ts:404` |
+| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts:620`        |
+| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts:585`        |
+| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts:681`        |
+| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts:719`        |
+| Audit de frame               | protocole | sur refus      | `RealtimeController.ts:522` |
 
 Deux propriétés architecturales méritent d'être notées ici, parce qu'elles expliquent des
 choix de conception visibles partout dans le module :
 
 **Coût nul quand la sécurité est absente.** Le verrou de frame n'est branché sur le peer que
-si une politique existe (`RealtimeHub.hasFrameAuthorizer()`, `RealtimeHub.ts:1058`, testé une
+si une politique existe (`RealtimeHub.hasFrameAuthorizer()`, `RealtimeHub.ts:1039`, testé une
 fois au handshake). Sans module de sécurité, `beforeDispatch` reste indéfini et le chemin
 chaud ne paie **rien** du tout.
 
 **Échec bruyant plutôt que faux sentiment de sécurité.** Si des canaux déclarent une
 politique sans qu'aucun décideur ne soit câblé, `hasUnenforcedChannelPolicies()`
-(`RealtimeHub.ts:1117`) le détecte et un avertissement est émis une fois par process
-(`RealtimeController.ts:487`). Un canal qui **se croit** gardé alors qu'il est ouvert est
+(`RealtimeHub.ts:1098`) le détecte et un avertissement est émis une fois par process
+(`RealtimeController.ts:639`). Un canal qui **se croit** gardé alors qu'il est ouvert est
 bien plus dangereux qu'un canal ouvertement public.
 
 ## 📡 Observabilité — la sonde et Studio
 
-`RealtimeHub.probe()` (`RealtimeHub.ts:865`) rend un instantané en **lecture pure** : aucune
+`RealtimeHub.probe()` (`RealtimeHub.ts:847`) rend un instantané en **lecture pure** : aucune
 allocation sur le chemin chaud, jamais d'exception. Les compteurs sont des primitives
 incrémentées en O(1) ; ils sont **monotones**, ce qui laisse au lecteur le soin de dériver
 un débit.
@@ -786,7 +788,7 @@ périodiquement sa santé au maître (`ClusterProbeClient.ts:179`), le maître a
 rediffuse, chaque worker met en cache. **N'importe lequel** sert alors la vue pod en O(1),
 sans latence de requête.
 
-L'agrégation, `mergeClusterHealth()` (`ClusterProbeClient.ts:46`), est une fonction pure :
+L'agrégation, `mergeClusterHealth()` (`ClusterProbeClient.ts:60`), est une fonction pure :
 elle somme les scalaires, mais prend le **maximum** de `maxBufferedAmount` — la santé d'une
 flotte se juge sur son pire membre, pas sur sa moyenne. `buildRealtimeHealth()`
 (`RealtimeAdminApi.ts:74`) choisit ensuite la vue agrégée si elle existe, la per-instance
@@ -794,9 +796,9 @@ sinon.
 
 Sonde désactivée ? Elle n'est pas muette : **elle n'existe pas**. Aucun client, donc aucun
 minuteur, aucun écouteur, aucun message IPC
-(`src/packages/@nodefony/realtime/index.ts:351`) — coupable par la configuration ou par une
+(`src/packages/@nodefony/realtime/index.ts:364`) — coupable par la configuration ou par une
 variable d'environnement. Enfin, le maître peut demander à un worker précis d'enrichir sa
-remontée (`requestEnrich()`, `ClusterProbeClient.ts:239`) : la sonde riche n'est allouée que
+remontée (`requestEnrich()`, `ClusterProbeClient.ts:259`) : la sonde riche n'est allouée que
 pendant l'inspection, puis libérée — on paie ce qu'on regarde.
 
 ## ⚡ Performance & mémoire
@@ -805,10 +807,10 @@ Le module suit une discipline stricte, lisible dans presque chaque champ privé
 
 **Allocation paresseuse partout.** Table des canaux, registre des connexions, registre des
 révocables, authentificateurs, politiques de canal, association peer→jeton : tout démarre à
-`null`. Un process sans abonné n'alloue **rien** (`RealtimeHub.ts:141` et suivants).
+`null`. Un process sans abonné n'alloue **rien** (`RealtimeHub.ts:142` et suivants).
 
 **Aucun minuteur au repos.** Le tick de révocation démarre au premier inscrit et s'arrête
-dès que le registre se vide — `RealtimeHub.unregisterRevocable()` (`RealtimeHub.ts:809`).
+dès que le registre se vide — `RealtimeHub.unregisterRevocable()` (`RealtimeHub.ts:804`).
 Les minuteurs sont détachés de la boucle d'événements : ils ne retiennent jamais l'arrêt du
 process.
 
@@ -824,25 +826,25 @@ désabonné.
 
 **Le vrai point de vigilance est la back-pressure**, pas le processeur : une file d'envoi
 non bornée multipliée par le nombre de clients, c'est la panne mémoire — et le multiplexage
-concentre le risque. D'où les deux seuils du transport, le comptage des consommateurs lents
+concentre le risque. D'où les réglages de contre-pression du transport, le comptage des consommateurs lents
 dans la sonde, et le plafond de canaux par connexion.
 
 ## ⚠️ Pièges
 
-| Symptôme                                                       | Cause                                                                      | Correction                                                                  |
-| -------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| Le chat marche en local, plus rien en cluster                  | le canal n'est pas déclaré broadcast (défaut : instance-local)             | déclarer le préfixe avec `@RealtimeBroadcast`                               |
-| Le client ne reçoit rien alors qu'il a un handler `on(...)`    | `on` reçoit, `subscribe` demande — il faut les **deux**                    | appeler `socket.subscribe(canal)`                                           |
-| Chaque message arrive **en double** en cluster                 | `publishLocal` court-circuité, ou `originId` non unique entre pods         | ne jamais republier une arrivée backplane ; vérifier `NF_POD_NAME`/hostname |
-| Deux applications se parlent sur un Redis mutualisé            | même canal dérivé (le numéro de base Redis ne cloisonne pas le pub/sub)    | poser un `backplane.namespace` explicite et distinct                        |
-| Producteur planté après le départ du premier abonné            | la fabrique a capturé le contexte de la connexion créatrice                | ne capturer que des valeurs à longue durée de vie                           |
-| Abonnement refusé avec `realtime:denied` motif `limit`         | plafond de canaux par connexion atteint (256 par défaut)                   | regrouper les canaux, ou relever le plafond en connaissance de cause        |
-| Fermeture `1013` sur un client lent                            | file d'envoi ≥ 8 MiB, jugée irrécupérable                                  | attendu ; le client se reconnecte et se resynchronise                       |
-| Fermeture `4001` en cours de session                           | identité révoquée, détectée par le tick de re-validation                   | se réauthentifier ; le comportement est voulu                               |
-| Frames envoyées juste après `connect()` perdues                | le transport n'est pas branché tant que le handshake n'est pas fini        | attendre `realtime:welcome` (`RealtimeClient` le fait déjà)                 |
-| Avertissement « channel policies … NOT enforced » au démarrage | des canaux déclarent une politique sans décideur câblé                     | charger `@nodefony/security` avec une zone realtime                         |
-| `ServerRealtimeSocket.request()` rejette systématiquement      | un handle posé sur le hub n'a pas d'interlocuteur unique                   | utiliser `RealtimeController.requestClient()` pour un appel ciblé           |
-| `TS2550: RegExp.escape does not exist` à la compilation        | `lib` du tsconfig sous ES2025 (les paquets exposent leurs types en source) | `"lib": ["ESNext", …]`, comme le tsconfig généré par `nodefony create app`  |
+| Symptôme                                                       | Cause                                                                                    | Correction                                                                  |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Le chat marche en local, plus rien en cluster                  | le canal n'est pas déclaré broadcast (défaut : instance-local)                           | déclarer le préfixe avec `@RealtimeBroadcast`                               |
+| Le client ne reçoit rien alors qu'il a un handler `on(...)`    | `on` reçoit, `subscribe` demande — il faut les **deux**                                  | appeler `socket.subscribe(canal)`                                           |
+| Chaque message arrive **en double** en cluster                 | `publishLocal` court-circuité, ou `originId` non unique entre pods                       | ne jamais republier une arrivée backplane ; vérifier `NF_POD_NAME`/hostname |
+| Deux applications se parlent sur un Redis mutualisé            | même canal dérivé (le numéro de base Redis ne cloisonne pas le pub/sub)                  | poser un `backplane.namespace` explicite et distinct                        |
+| Producteur planté après le départ du premier abonné            | la fabrique a capturé le contexte de la connexion créatrice                              | ne capturer que des valeurs à longue durée de vie                           |
+| Abonnement refusé avec `realtime:denied` motif `limit`         | plafond de canaux par connexion atteint (256 par défaut)                                 | regrouper les canaux, ou relever le plafond en connaissance de cause        |
+| Fermeture `1013` sur un client lent                            | file au-delà de `websocket.maxBackpressure` (4 MiB) pendant 1000 frames jetées d'affilée | attendu ; le client se reconnecte et se resynchronise                       |
+| Fermeture `4001` en cours de session                           | identité révoquée, détectée par le tick de re-validation                                 | se réauthentifier ; le comportement est voulu                               |
+| Frames envoyées juste après `connect()` perdues                | le transport n'est pas branché tant que le handshake n'est pas fini                      | attendre `realtime:welcome` (`NodefonySocket` le fait déjà)                 |
+| Avertissement « channel policies … NOT enforced » au démarrage | des canaux déclarent une politique sans décideur câblé                                   | charger `@nodefony/security` avec une zone realtime                         |
+| `ServerRealtimeSocket.request()` rejette systématiquement      | un handle posé sur le hub n'a pas d'interlocuteur unique                                 | utiliser `RealtimeController.requestClient()` pour un appel ciblé           |
+| `TS2550: RegExp.escape does not exist` à la compilation        | `lib` du tsconfig sous ES2025 (les paquets exposent leurs types en source)               | `"lib": ["ESNext", …]`, comme le tsconfig généré par `nodefony create app`  |
 
 ## 🧪 Tests & couverture
 
@@ -868,7 +870,7 @@ l'aperçu, régénérée depuis les résultats réels — jamais figés ici.
 > [!CAUTION]
 > Plusieurs de ces suites exigent une infrastructure (Redis, cluster). **Un test qui se
 > saute compte comme vert.** Avant de conclure « tout passe », vérifie que les variables
-> d'environnement d'infrastructure sont bien posées — la source unique est `vitest.gates.ts`
+> d'environnement d'infrastructure sont bien posées — la source unique est `scripts/test/vitest/gates.ts`
 > à la racine, dont le rapport s'affiche en fin d'exécution.
 
 Couverture : `npm run coverage` dans `@nodefony/realtime`. Pour la charge et la mémoire, les