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

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#JsonRpcPeer`) 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#RealtimeController.onHandshake`). Le serveur peut donc
 appeler le client, pas seulement l'inverse : c'est du vrai duplex, pas un aller-retour
 déguisé.
 
@@ -136,16 +136,16 @@ 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` (`ServerRealtimeSocket.ts#ServerRealtimeSocket`), obtenu par `serverSocket()`
+(`ServerRealtimeSocket.ts#serverSocket`) ; côté navigateur, `NodefonySocket`. Une exception, assumée
+et explicite : `ServerRealtimeSocket.request()` (`ServerRealtimeSocket.ts#ServerRealtimeSocket.request`) **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#RealtimeController.requestClient`).
 
 **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#RealtimeHub.subscribe`) : 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#RealtimeHub.publish`) — un choix de sûreté détaillé plus bas.
 
 ## 🚀 Démarrage rapide
 
@@ -164,25 +164,31 @@ trois fichiers, et il fonctionne en mono-process comme en cluster.
 ### 1. Charger le module et choisir le fond de panier
 
 ```ts
+// nodefony/config/realtime.ts — le fragment du module, importé par le manifeste
+import type { IRealtimeConfigInput } from "@nodefony/realtime";
+
+export const realtimeConfig = () =>
+  ({
+    // "loopback" = un seul process : le hub suffit, aucun transport réseau.
+    // "cluster" (workers IPC) ou "redis" (multi-pods) sans changer une ligne de code.
+    backplane: { driver: "loopback" },
+    // Défense CSRF de l'upgrade WebSocket : SameSite ne protège pas un handshake.
+    csrf: {
+      checkOrigin: {
+        enabled: true,
+        allowList: ["http://localhost:5151"],
+      },
+    },
+  }) satisfies IRealtimeConfigInput;
+```
+
+```ts ignore
 // nodefony.config.ts
 import { defineConfig, use } from "nodefony";
+import { realtimeConfig } from "./nodefony/config/realtime";
 
 export default defineConfig(() => ({
-  modules: [
-    "@nodefony/framework",
-    use("@nodefony/realtime", {
-      // "loopback" = un seul process : le hub suffit, aucun transport réseau.
-      // "cluster" (workers IPC) ou "redis" (multi-pods) sans changer une ligne de code.
-      backplane: { driver: "loopback" },
-      // Défense CSRF de l'upgrade WebSocket : SameSite ne protège pas un handshake.
-      csrf: {
-        checkOrigin: {
-          enabled: true,
-          allowList: ["http://localhost:5151"],
-        },
-      },
-    }),
-  ],
+  modules: ["@nodefony/framework", use("@nodefony/realtime", realtimeConfig())],
 }));
 ```
 
@@ -260,7 +266,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 +277,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 +297,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#Realtime.#wireBackplane`) :
 
 ```
 realtime backplane  driver=loopback kind=local cross-pod=no (hub local)
@@ -319,13 +325,13 @@ entre les deux **est** le facteur d'amplification du canal.
 
 La pile se lit de haut en bas ; chaque étage ne connaît que son voisin du dessous.
 
-| É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     |
-| 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 |
-| Backplane  | `IBackplane` (`IBackplane.ts:107`)                      | porter un message aux autres process    | ce qu'est un abonné           |
+| É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#JsonRpcPeer`)                               | étiqueter, corréler, refuser une frame  | par où passent les octets     |
+| Transport  | `WsConnectionTransport` (`WsConnectionTransport.ts#WsConnectionTransport`) | déplacer des octets, mesurer la file    | ce que veut dire un message   |
+| Hub        | `RealtimeHub` (`RealtimeHub.ts#RealtimeHub`)                               | table des abonnés locaux + fan-out      | qu'il existe d'autres process |
+| Backplane  | `IBackplane` (`IBackplane.ts#IBackplane`)                                  | porter un message aux autres process    | ce qu'est un abonné           |
 
 > [!NOTE]
 > Une part de la documentation historique décrit cette pile en « 5 étages » en comptant
@@ -338,11 +344,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#JsonRpcPeerOptions.beforeDispatch`) — 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#JsonRpcPeer.receive`).
+- `onFrameAudit` (`JsonRpcPeer.ts#JsonRpcPeerOptions.onFrameAudit`) — 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
@@ -355,28 +361,30 @@ au handshake, puis lue en O(1). C'est le compromis assumé, documenté dans
 Particularité contre-intuitive : côté serveur, le transport **n'écoute pas** d'événement
 socket. C'est le pipeline HTTP de `@nodefony/http` qui appelle la route WebSocket du
 contrôleur à chaque message reçu, laquelle pousse la charge dans
-`WsConnectionTransport.feed()` (`WsConnectionTransport.ts:150`). La fermeture arrive de la
+`WsConnectionTransport.feed()` (`WsConnectionTransport.ts#WsConnectionTransport.feed`). La fermeture arrive de la
 même façon, par le hook `onFinish` du contexte, qui déclenche `fireClose()`
-(`WsConnectionTransport.ts:155`).
+(`WsConnectionTransport.ts#WsConnectionTransport.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`).
+(`WsConnectionTransport.ts#WsConnectionTransport`) et documentées dans `@nodefony/http`
+(`http/nodefony/config/config.ts#httpConfigSchema`).
 
-| 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#SLOW_CONSUMER_BYTES`, 1 MiB) : ce seuil-là
 ne jette rien, il **compte** — c'est celui à partir duquel la sonde marque une connexion
 `slowConsumer`.
 
@@ -388,7 +396,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#RealtimeController.onHandshake`), appelé
 une seule fois par connexion, en chemin froid.
 
 ```mermaid
@@ -419,19 +427,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#RealtimeHub.checkOrigin`). 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#RealtimeHub.resolveAuthenticator`) 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#RealtimeHub.setTokenForPeer`), 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#RealtimeController.realtimeApiRequest`)
    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 +447,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#RealtimeController.onHandshake`) 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 +455,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`         |
+| 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#RealtimeController.onRealtimeNotification` |
+| Révocation d'identité | tick périodique ; `token.isValid()` rend `false` ou lève une exception | fermeture `4001` « session revoked »                | `RealtimeHub.ts#FrameAuthorizer`                                  |
 
 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#RealtimeHub.registerRevocable`) — 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#getRealtimeHub`). 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#RealtimeHub.subscribe`) 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#RealtimeHub.registerSystemChannel`), 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#RealtimeHub.unsubscribe`) appelle le
 `dispose` du producteur et retire le canal. Un producteur fautif qui lève une exception ne
 bloque pas le nettoyage.
 
@@ -494,24 +502,24 @@ bloque pas le nettoyage.
 
 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 |
+| Méthode                                                      | Fan-out local |   Propagation aux autres process   | Qui l'appelle                       |
+| ------------------------------------------------------------ | :-----------: | :--------------------------------: | ----------------------------------- |
+| `publish()` (`RealtimeHub.ts#RealtimeHub.publish`)           |      oui      | oui, **si** le canal est broadcast | producteurs, contrôleurs, services  |
+| `publishLocal()` (`RealtimeHub.ts#RealtimeHub.publishLocal`) |      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#RealtimeHub.setBackplane`), 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#RealtimeHub.#channelPolicyPatterns`) 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#RealtimeBroadcast`) ou
+directement `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts#RealtimeHub.markBroadcastChannel`).
 
 Trois raisons à ce choix, qui prend à contre-pied la plupart des bibliothèques temps réel :
 
@@ -547,21 +555,21 @@ coûte chaque abonné supplémentaire.
 
 ### Le contrat, en cinq méthodes
 
-`IBackplane` (`IBackplane.ts:107`) est délibérément minuscule : le backplane ne connaît ni
+`IBackplane` (`IBackplane.ts#IBackplane`) est délibérément minuscule : le backplane ne connaît ni
 les abonnés ni les canaux logiques. Tout l'état vit dans le hub.
 
-| Membre                                            | Rôle                                                            |
-| ------------------------------------------------- | --------------------------------------------------------------- |
-| `originId` (`IBackplane.ts:109`)                  | l'étiquette de CE process, lue par l'anti-écho                  |
-| `start()` (`IBackplane.ts:115`)                   | ouvrir le transport. Idempotent, synchrone ou asynchrone        |
-| `publish(channel, payload)` (`IBackplane.ts:121`) | propager aux **autres** pairs. Ne refait pas le fan-out local   |
-| `onMessage(handler)` (`IBackplane.ts:127`)        | recevoir des pairs. Un seul gestionnaire à la fois              |
-| `stop()` (`IBackplane.ts:130`)                    | libérer connexions et écouteurs. Idempotent                     |
-| `describe()` (`IBackplane.ts:136`)                | la carte d'identité : driver, nature, origine, cross-pod, canal |
+| Membre                                                           | Rôle                                                            |
+| ---------------------------------------------------------------- | --------------------------------------------------------------- |
+| `originId` (`IBackplane.ts#IBackplane.originId`)                 | l'étiquette de CE process, lue par l'anti-écho                  |
+| `start()` (`IBackplane.ts#IBackplane.start`)                     | ouvrir le transport. Idempotent, synchrone ou asynchrone        |
+| `publish(channel, payload)` (`IBackplane.ts#IBackplane.publish`) | propager aux **autres** pairs. Ne refait pas le fan-out local   |
+| `onMessage(handler)` (`IBackplane.ts#IBackplane.onMessage`)      | recevoir des pairs. Un seul gestionnaire à la fois              |
+| `stop()` (`IBackplane.ts#IBackplane.stop`)                       | libérer connexions et écouteurs. Idempotent                     |
+| `describe()` (`IBackplane.ts#IBackplane.describe`)               | la carte d'identité : driver, nature, origine, cross-pod, canal |
 
 Deux absences volontaires. Il n'y a **pas** de `subscribe`/`unsubscribe` par canal : le
 transport porte **un seul** canal physique, et les canaux logiques voyagent **dans**
-l'enveloppe (`IBackplaneMessage`, `IBackplane.ts:51`). Un seul abonnement au démarrage,
+l'enveloppe (`IBackplaneMessage`, `IBackplane.ts#IBackplaneMessage`). Un seul abonnement au démarrage,
 zéro (dés)abonnement dynamique — et le hub reste seul maître de la table des canaux.
 
 `describe()`, lui, alimente **trois sorties cohérentes** depuis une source unique : la ligne
@@ -574,11 +582,11 @@ resynchronise. Ne construis pas au-dessus une fiabilité que le support n'offre
 
 ### Les drivers natifs
 
-| Driver     | Classe                                          | Nature         | Pairs                              | Traverse les pods |
-| ---------- | ----------------------------------------------- | -------------- | ---------------------------------- | :---------------: |
-| `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**      |
+| Driver     | Classe                                                         | Nature         | Pairs                              | Traverse les pods |
+| ---------- | -------------------------------------------------------------- | -------------- | ---------------------------------- | :---------------: |
+| `loopback` | `LoopbackBackplane` (`LoopbackBackplane.ts#LoopbackBackplane`) | `local`        | aucun (no-op complet)              |        non        |
+| `cluster`  | `ClusterBackplane` (`ClusterBackplane.ts#ClusterBackplane`)    | `ipc`          | les workers du même process maître |        non        |
+| `redis`    | `RedisBackplane` (`RedisBackplane.ts#RedisBackplane`)          | `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
@@ -586,30 +594,30 @@ matérialiser le contrat et prouver, en test, que brancher un backplane sans pai
 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
+il émet vers lui (`ClusterBackplane.publish()`, `ClusterBackplane.ts#ClusterBackplane.publish`), 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`) ; 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#createRedisServiceTransport`). 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`).
 
 ### Le registre de drivers — zéro nom en dur
 
 Choisir le driver par une cascade de `if (driver === "redis")` trahirait la promesse de
 brancherie. La sélection passe donc par un registre — `registerBackplaneDriver()`
-(`backplaneRegistry.ts:55`) et `getBackplaneDriver()` (`backplaneRegistry.ts:63`) : chaque
+(`backplaneRegistry.ts#registerBackplaneDriver`) et `getBackplaneDriver()` (`backplaneRegistry.ts#getBackplaneDriver`) : 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#Realtime.onKernelBoot`).
 
 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`
+(`IBackplaneFactoryContext`, `backplaneRegistry.ts#IBackplaneFactoryContext`), puis rend une instance ou `null`
 (« inactif ici »). Elle ne démarre rien : c'est le câblage qui appelle `start()`.
 
 ### L'anti-écho et l'`originId`
@@ -620,9 +628,9 @@ 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#RedisBackplane.originId`, `ClusterBackplane.ts#ClusterBackplane.#ingress`).
 
-L'étiquette elle-même est calculée par `resolveBackplaneOriginId()` (`originId.ts:24`), et
+L'étiquette elle-même est calculée par `resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`), et
 sa recette mérite qu'on s'y arrête :
 
 | Étape              | Valeur                 | Pourquoi                                                                                              |
@@ -641,14 +649,14 @@ sa recette mérite qu'on s'y arrête :
 
 ### Le cloisonnement du canal Redis
 
-Le canal pub/sub de base est `nodefony:realtime` (`RedisBackplane.ts:20`). Problème : le
+Le canal pub/sub de base est `nodefony:realtime` (`RedisBackplane.ts#REDIS_RT_CHANNEL`). Problème : le
 numéro de base Redis **ne cloisonne pas** le pub/sub, qui est global au serveur. Deux
 applications sur un Redis mutualisé se parleraient.
 
-D'où le suffixe de cloison, calculé par `resolveRedisChannel()` (`RedisBackplane.ts:31`) :
+D'où le suffixe de cloison, calculé par `resolveRedisChannel()` (`RedisBackplane.ts#resolveRedisChannel`) :
 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`).
 
 > [!TIP]
 > Deux déploiements de la **même** application sur un Redis partagé (préproduction et
@@ -656,19 +664,19 @@ configuration ; à défaut, il est dérivé du nom de l'application
 > namespace **explicite et distinct** dans ces cas-là.
 
 L'entrée est par ailleurs blindée : un JSON malformé publié par un tiers sur le même canal
-est ignoré, pas propagé (`RedisBackplane.ts:212`).
+est ignoré, pas propagé (`RedisBackplane.ts#RedisBackplane`).
 
 ### 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#Realtime.onKernelRegister`), puis câble tout au démarrage du noyau
+(`src/packages/@nodefony/realtime/index.ts#Realtime.onKernelRegister`) — 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#BACKPLANE_START_TIMEOUT_MS`), 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 +688,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`) : 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.
@@ -710,18 +718,18 @@ registerBackplaneDriver(
 
 **2. Déclarer un service** nommé `realtimeBackplane` dans le conteneur d'injection —
 **la voie « instance » pour une application**. `RealtimeService.init()`
-(`RealtimeService.ts:79`) le résout et le branche **avant** le registre : une instance
+(`RealtimeService.ts#RealtimeService.init`) le résout et le branche **avant** le registre : une instance
 déjà fournie court-circuite la sélection par nom.
 
 **3. Passer une instance** en second argument de `defineRealtimeConfig()` — réservé au
 code qui **appelle le builder lui-même** (un `Module` sur mesure, une intégration
 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
+`defineRealtimeConfig(this.options)` sans second argument, `index.ts#createRealtimeHarness`), et une
 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
+Le registre s'introspecte : `listBackplaneDrivers()` (`backplaneRegistry.ts#listBackplaneDrivers`) rend les
 noms disponibles — c'est ce que le message d'erreur affiche quand un driver déclaré est
 introuvable.
 
@@ -731,31 +739,31 @@ L'architecture prévoit des points de greffe pour que `@nodefony/security` s'y b
 refonte. Ici, seulement **où** ils sont ; le **quoi** et le **comment** sont dans
 [la page sécurité](./securite.md).
 
-| 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` |
+| Point de greffe              | Étage     | Moment         | Ancrage                                                |
+| ---------------------------- | --------- | -------------- | ------------------------------------------------------ |
+| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts#RealtimeHub.publishLocal`              |
+| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.unsubscribe`               |
+| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts#RealtimeHub.markBroadcastChannel`      |
+| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.setBackplane`              |
+| Audit de frame               | protocole | sur refus      | `RealtimeController.ts#RealtimeController.onHandshake` |
 
 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#RealtimeHub.hasFrameAuthorizer`, 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#RealtimeHub.hasUnenforcedChannelPolicies`) le détecte et un avertissement est émis une fois par process
+(`RealtimeController.ts#RealtimeController.onHandshake`). 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#RealtimeHub.probe`) 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.
@@ -768,35 +776,35 @@ un débit.
 | Back-pressure  | `maxBufferedAmount`, `totalBufferedAmount`, `slowConsumers`, `drops` | le risque mémoire numéro un      |
 | Fond de panier | `backplane` (la carte d'identité de `describe()`)                    | ce qui est réellement branché    |
 
-Le contrat complet est `IRealtimeProbe` (`IRealtimeProbe.ts:61`). La version enrichie
-`buildOwnHealth()` (`RealtimeAdminApi.ts:52`) y ajoute l'identifiant d'instance et la sonde
+Le contrat complet est `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`). La version enrichie
+`buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) y ajoute l'identifiant d'instance et la sonde
 process, plus — si elles sont disponibles — les sondes ORM et les compteurs d'erreurs. Deux
 chemins de lecture, un seul producteur :
 
 - **HTTP** : `GET /nodefony/realtime/api/health`, exposé par `createRealtimeAdminApi()`
-  (`RealtimeAdminApi.ts:98`) ;
+  (`RealtimeAdminApi.ts#createRealtimeAdminApi`) ;
 - **Canal temps réel** : `nodefony:socket`, poussé par un ticker.
 
 ### En cluster : la vue « pod » plutôt que « worker »
 
 Interroger la santé en cluster pose un problème sournois : la requête atterrit sur **un**
 worker au hasard, dont l'instantané ne dit rien des autres. D'où `ClusterProbeClient`
-(`ClusterProbeClient.ts:138`), qui applique un modèle **push** — chaque worker remonte
-périodiquement sa santé au maître (`ClusterProbeClient.ts:179`), le maître agrège et
+(`ClusterProbeClient.ts#ClusterProbeClient`), qui applique un modèle **push** — chaque worker remonte
+périodiquement sa santé au maître (`ClusterProbeClient.ts#ClusterProbeClient.constructor`), le maître agrège et
 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#mergeClusterHealth`), 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
+(`RealtimeAdminApi.ts#buildRealtimeHealth`) choisit ensuite la vue agrégée si elle existe, la per-instance
 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#Realtime.#startWithTimeout`) — 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#ClusterProbeClient.requestEnrich`) : 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 +813,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#IRevocableConnection` 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#RealtimeHub.unregisterRevocable`).
 Les minuteurs sont détachés de la boucle d'événements : ils ne retiennent jamais l'arrêt du
 process.
 
@@ -839,7 +847,7 @@ dans la sonde, et le plafond de canaux par connexion.
 | 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` (`RealtimeClient` le fait déjà)                 |
+| 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`  |
@@ -868,7 +876,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