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

package/docs/cookbook-chat.md

@@ -35,6 +35,25 @@ coverageModule: realtime
 
 📍 [Documentation](../../../../../docs/index.md) › [@nodefony/realtime](index.md) › **Cookbook — un chat**
 
+## ⚡ Le geste — deux commandes avant d'écrire une ligne
+
+Une ressource REST et un canal temps réel ne s'écrivent pas à la main : les générateurs de
+l'application les posent, câblés et testés. Depuis la racine de l'application :
+
+```bash
+npx nodefony create entity Message body:text room:string:index --route /api/messages
+npx nodefony create controller room --kind realtime
+```
+
+| Commande                            | Ce qu'elle pose                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create entity`                     | la table (`nodefony/entity/Message.ts`), ses schémas de validation, un service CRUD, `MessageController` — REST sur `/api/messages`, et ses lectures répondent aussi par la socket —, un test unitaire et un test e2e, le tout inscrit dans `index.ts` — puis, si l'application versionne ses migrations (toute application complète), la migration de la table, écrite et appliquée à la base de développement ; sinon la table naît au prochain démarrage |
+| `create controller --kind realtime` | `RoomController` : la socket `/api/room/realtime`, le canal `room:events`, ses actions, et un test qui la pilote sans serveur ni navigateur                                                                                                                                                                                                                                                                                                                 |
+
+La suite de ce cookbook construit le même salon À LA MAIN, dans un seul contrôleur : c'est ce qui
+permet de comprendre ce que les générateurs écrivent, et de le retoucher. Pour avancer, partir des
+générateurs ; pour comprendre, lire la suite.
+
 ## 🎯 Ce qu'on construit
 
 **En une phrase** : un salon de discussion où plusieurs personnes échangent des messages et des
@@ -134,7 +153,7 @@ le moment venu.
 
 ```bash
 # 1. Créer l'application (profil complet : http, framework, realtime, sécurité, frontend)
-npx nodefony create app mon-chat --preset complete
+npm create nodefony@beta mon-chat -- --preset complete
 cd mon-chat
 
 # 2. Créer le module qui portera le salon
@@ -781,20 +800,23 @@ couvre le HTTP **et** le WebSocket qu'elle recouvre — c'est le défaut, et c'e
 zone protégée qui laisserait passer le WebSocket serait une porte dérobée.
 
 ```ts ignore
-// nodefony.config.ts (ajout de l'étape 5)
-use("@nodefony/security", {
-  areas: {
-    chat: {
-      pattern: "^/chat",
-      // Cookie de session (BFF) : le navigateur n'a aucun jeton à manipuler,
-      // et le cookie voyage naturellement avec la poignée de main WebSocket.
-      authenticators: ["session"],
+// nodefony/config/security.ts — (ajout de l'étape 5)
+import type { ISecurityConfigInput } from "@nodefony/security";
+
+export const securityConfig = () =>
+  ({
+    areas: {
+      chat: {
+        pattern: "^/chat",
+        // Cookie de session (BFF) : le navigateur n'a aucun jeton à manipuler,
+        // et le cookie voyage naturellement avec la poignée de main WebSocket.
+        authenticators: ["session"],
+      },
     },
-  },
-  roleHierarchy: {
-    ROLE_ADMIN: ["ROLE_USER"],
-  },
-});
+    roleHierarchy: {
+      ROLE_ADMIN: ["ROLE_USER"],
+    },
+  }) satisfies ISecurityConfigInput;
 ```
 
 > [!NOTE]
@@ -1603,23 +1625,23 @@ Pour qui veut lire l'implémentation derrière chaque étape :
 <!-- prettier-ignore -->
 | Ce que tu as utilisé | Où c'est écrit |
 | --- | --- |
-| Les trois décorateurs | `RealtimeAction()` (`realtimeDecorators.ts:191`), `RealtimeChannel()` (`realtimeDecorators.ts:240`), `RealtimeInbound()` (`realtimeDecorators.ts:278`) |
-| La porte WebSocket | `RealtimeController.handleRealtime()` (`RealtimeController.ts:344`) |
-| Le pont HTTP ⇄ WebSocket | `RealtimeController.realtimeApiRequest()` (`RealtimeController.ts:321`) |
-| L'abonnement et son cycle de vie | `RealtimeHub.subscribe()` (`RealtimeHub.ts:464`), `RealtimeController.startChannel()` (`RealtimeController.ts:869`) |
-| La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts:610`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts:629`) |
-| Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts:420`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:674`) |
-| Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts:720`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts:55`), cloison `resolveBackplaneOriginId()` (`originId.ts:24`) |
-| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts:20`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts:1124`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1098`) |
-| Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts:306`) |
-| Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts:269`), erreur `unauthorized` (`JsonRpcPeer.ts:449`), fermetures `origin not allowed` (`RealtimeController.ts:422`) et `unauthorized` (`RealtimeController.ts:444`) |
-| La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:815`) |
-| Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:66`), fermeture `slow consumer` (`RealtimeHub.ts:64`) |
-| Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts:981`) |
-| L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts:231`) |
-| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts:847`), `IRealtimeProbe` (`IRealtimeProbe.ts:61`), `IRealtimeChannelStat` (`IRealtimeProbe.ts:47`) |
-| Le point de mesure d'administration | `createRealtimeAdminApi()` (`RealtimeAdminApi.ts:98`), `buildRealtimeHealth()` (`RealtimeAdminApi.ts:74`), `buildOwnHealth()` (`RealtimeAdminApi.ts:52`) |
-| Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts:161`), `RealtimeService.probe()` (`RealtimeService.ts:218`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts:222`) |
-| Les hooks React | `useNodefony()` (`client/react/index.ts:255`), `useNodefonyState()` (`client/react/index.ts:273`), `useNodefonyIdentity()` (`client/react/index.ts:292`), `useNodefonyChannel()` (`client/react/index.ts:308`), `useNodefonyChannelData()` (`client/react/index.ts:332`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts:367`) |
-| Le client navigateur | `NodefonySocket.connect()` (`NodefonySocket.ts:592`), `NodefonySocket.subscribe()` (`NodefonySocket.ts:739`), `NodefonySocket.request()` (`NodefonySocket.ts:936`), `NodefonySocket.onDenied()` (`NodefonySocket.ts:678`) |
-| L'upload | `UploadedFile` (`routerDecorators.ts:1311`), `IUploadedFile` (`IUpload.ts:49`), `queryFile` (`Request.ts:215`) |
+| Les trois décorateurs | `RealtimeAction()` (`realtimeDecorators.ts#RealtimeAction`), `RealtimeChannel()` (`realtimeDecorators.ts#RealtimeChannel`), `RealtimeInbound()` (`realtimeDecorators.ts#RealtimeInbound`) |
+| La porte WebSocket | `RealtimeController.handleRealtime()` (`RealtimeController.ts#RealtimeController.handleRealtime`) |
+| Le pont HTTP ⇄ WebSocket | `RealtimeController.realtimeApiRequest()` (`RealtimeController.ts#RealtimeController.realtimeApiRequest`) |
+| L'abonnement et son cycle de vie | `RealtimeHub.subscribe()` (`RealtimeHub.ts#RealtimeHub.subscribe`), `RealtimeController.startChannel()` (`RealtimeController.ts#RealtimeController.startChannel`) |
+| La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts#RealtimeHub.publish`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts#RealtimeHub.publishLocal`) |
+| Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts#RealtimeBroadcast`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts#RealtimeHub.markBroadcastChannel`) |
+| Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts#RealtimeHub.setBackplane`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts#registerBackplaneDriver`), cloison `resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`) |
+| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts#IChannelPolicy`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.registerChannelPolicy`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts#RealtimeHub.hasUnenforcedChannelPolicies`) |
+| Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts#Firewall.#wireRealtime`) |
+| Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts#IRealtimeDenied`), erreur `unauthorized` (`JsonRpcPeer.ts#JsonRpcPeer.receive`), fermetures `origin not allowed` (`RealtimeController.ts#RealtimeController.notifyClient`) et `unauthorized` (`RealtimeController.ts#RealtimeController.onHandshake`) |
+| La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts#RealtimeHub.revalidateRevocable`) |
+| Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`), fermeture `slow consumer` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`) |
+| Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts#RealtimeHub.maxChannelsPerConnection`) |
+| L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts#IRealtimeWelcome`) |
+| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`), `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`), `IRealtimeChannelStat` (`IRealtimeProbe.ts#IRealtimeChannelStat`) |
+| Le point de mesure d'administration | `createRealtimeAdminApi()` (`RealtimeAdminApi.ts#createRealtimeAdminApi`), `buildRealtimeHealth()` (`RealtimeAdminApi.ts#buildRealtimeHealth`), `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) |
+| Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts#RealtimeService.publish`), `RealtimeService.probe()` (`RealtimeService.ts#RealtimeService.probe`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts#RealtimeService.markBroadcastChannel`) |
+| Les hooks React | `useNodefony()` (`client/react/index.ts#useNodefony`), `useNodefonyState()` (`client/react/index.ts#useNodefonyState`), `useNodefonyIdentity()` (`client/react/index.ts#useNodefonyIdentity`), `useNodefonyChannel()` (`client/react/index.ts#useNodefonyChannel`), `useNodefonyChannelData()` (`client/react/index.ts#useNodefonyChannelData`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts#useNodefonyAdaptiveChannel`) |
+| Le client navigateur | `NodefonySocket.connect()` (`NodefonySocket.ts#NodefonySocket.connect`), `NodefonySocket.subscribe()` (`NodefonySocket.ts#NodefonySocket.subscribe`), `NodefonySocket.request()` (`NodefonySocket.ts#NodefonySocket.request`), `NodefonySocket.onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`) |
+| L'upload | `UploadedFile` (`routerDecorators.ts#UploadedFile`), `IUploadedFile` (`IUpload.ts#IUploadedFile`), `files` (`Request.ts#HttpRequest.files`) |

package/docs/index.md

@@ -133,34 +133,34 @@ Quatre propriétés, toutes vérifiables dans le code — c'est ce qui justifie
 WebSocket brute.
 
 **Un contrôleur temps réel est un contrôleur.** `RealtimeController`
-(`RealtimeController.ts:203`) étend le `Controller` du framework : il se déclare avec les mêmes
+(`RealtimeController.ts#RealtimeController`) étend le `Controller` du framework : il se déclare avec les mêmes
 décorateurs de route, reçoit la même injection, passe par le même pare-feu. HTTP et WebSocket ne sont
 pas deux applications à écrire deux fois, mais deux entrées du même pipeline.
 
 **Une connexion, N canaux, dans les deux sens.** Le client s'abonne à autant de canaux qu'il veut sur
 la même socket. Trois formes de trafic coexistent : le serveur diffuse (`@RealtimeChannel`,
-`realtimeDecorators.ts:240`), le client appelle et attend une réponse (`@RealtimeAction`,
-`realtimeDecorators.ts:191`), le client pousse sans attendre (`@RealtimeInbound`,
-`realtimeDecorators.ts:278`). Rien n'est ouvert qui n'ait été déclaré.
+`realtimeDecorators.ts#RealtimeChannel`), le client appelle et attend une réponse (`@RealtimeAction`,
+`realtimeDecorators.ts#RealtimeAction`), le client pousse sans attendre (`@RealtimeInbound`,
+`realtimeDecorators.ts#RealtimeInbound`). Rien n'est ouvert qui n'ait été déclaré.
 
 **Le travail est fait une fois par processus, pas une fois par client.** Le `RealtimeHub`
-(`RealtimeHub.ts:214`) tient **un seul producteur par canal** : le premier abonné le démarre, le
+(`RealtimeHub.ts#RealtimeHub`) tient **un seul producteur par canal** : le premier abonné le démarre, le
 dernier départ l'arrête. Chaque connexion supplémentaire n'ajoute qu'une destination de diffusion.
 Un salon suivi par mille personnes coûte un producteur, pas mille.
 
 **Le backplane est un transport, jamais un magasin.** Il relaie les publications d'un processus vers
 les autres, et rien de plus : aucun historique, aucune reprise. Les drivers vivent dans un registre
-(`registerBackplaneDriver`, `backplaneRegistry.ts:55`) — `loopback` (un seul processus), `cluster`
+(`registerBackplaneDriver`, `backplaneRegistry.ts#registerBackplaneDriver`) — `loopback` (un seul processus), `cluster`
 (échanges entre workers d'un même pod), `redis` (entre machines) — et tu peux y inscrire le tien sans
 toucher au cœur.
 
 > [!IMPORTANT]
 > **Rien ne franchit la frontière du processus sans intention explicite.** Par défaut, un canal reste
 > local. Il faut le déclarer diffusable (`@RealtimeBroadcast`,
-> `realtimeDecorators.ts:420`) pour qu'il emprunte le backplane. C'est volontaire : un canal
+> `realtimeDecorators.ts#RealtimeBroadcast`) pour qu'il emprunte le backplane. C'est volontaire : un canal
 > d'observation qui décrit l'état d'**un** pod n'aurait aucun sens répliqué sur les autres.
 
-Le module se déclare par ailleurs **non critique** (`Realtime.critical`, `index.ts:144`) et son
+Le module se déclare par ailleurs **non critique** (`Realtime.critical`, `index.ts#IRealtimeHarness.call`) et son
 démarrage de backplane est borné dans le temps : un Redis injoignable n'empêche pas l'application de
 monter, le hub reste local, et la dégradation est annoncée dans les journaux plutôt que subie.
 
@@ -172,24 +172,35 @@ fichiers.
 ### 1. Déclarer le module
 
 ```ts
+// nodefony/config/realtime.ts — le fragment du module, importé par le manifeste
+import type { IRealtimeConfigInput } from "@nodefony/realtime";
+
+export const realtimeConfig = () =>
+  ({
+    // Un seul processus en développement : le hub distribue localement,
+    // aucun transport réseau n'est ouvert. Passer à "redis" en production.
+    backplane: { driver: "loopback" },
+    // Défense CSRF à la poignée de main (RFC 6455 §10.2) : sans elle, un site
+    // tiers peut ouvrir une socket avec les cookies de ton utilisateur.
+    csrf: {
+      checkOrigin: {
+        enabled: true,
+        allowList: ["https://127.0.0.1:5152"],
+      },
+    },
+  }) satisfies IRealtimeConfigInput;
+```
+
+```ts ignore
 // nodefony.config.ts — l'orchestrateur de l'application
+import { defineConfig, use } from "nodefony";
+import { realtimeConfig } from "./nodefony/config/realtime";
+
 export default defineConfig(() => ({
   modules: [
     "@nodefony/http",
     "@nodefony/framework",
-    use("@nodefony/realtime", {
-      // Un seul processus en développement : le hub distribue localement,
-      // aucun transport réseau n'est ouvert. Passer à "redis" en production.
-      backplane: { driver: "loopback" },
-      // Défense CSRF à la poignée de main (RFC 6455 §10.2) : sans elle, un site
-      // tiers peut ouvrir une socket avec les cookies de ton utilisateur.
-      csrf: {
-        checkOrigin: {
-          enabled: true,
-          allowList: ["https://127.0.0.1:5152"],
-        },
-      },
-    }),
+    use("@nodefony/realtime", realtimeConfig()),
   ],
 }));
 ```
@@ -305,7 +316,7 @@ reste local et le dit.
 ## 🧰 Surface publique
 
 Côté serveur : `RealtimeController` (la classe à étendre), les décorateurs `RealtimeChannel`,
-`RealtimeAction` et `RealtimeInbound`, le service `RealtimeService` (`RealtimeService.ts:50`) pour
+`RealtimeAction` et `RealtimeInbound`, le service `RealtimeService` (`RealtimeService.ts#RealtimeService`) pour
 publier depuis n'importe quel service injecté, le `RealtimeHub` et sa sonde, les trois backplanes
 natifs, et le registre de drivers pour brancher le tien.
 
@@ -318,7 +329,7 @@ jamais recopiées ici : elles divergeraient en silence.
 ## ⚙️ Configuration
 
 Un seul point d'entrée : `use("@nodefony/realtime", { … })` dans `nodefony.config.ts`, validé au boot
-contre le schéma du module (`realtimeConfigSchema`, `config.ts:259`). Six blocs :
+contre le schéma du module (`realtimeConfigSchema`, `config.ts#realtimeConfigSchema`). Six blocs :
 
 - `backplane` — le driver de fan-out et son espace de nommage. Ce cloisonnement devient
   indispensable dès que **deux déploiements partagent le même Redis** : sans lui, leurs publications
@@ -340,7 +351,7 @@ vue de tous les workers d'un pod.
 
 Le data plane admin expose `/nodefony/realtime/api/health` — canaux et abonnés, compteurs de
 diffusion, connexions, octets et frames, pression d'écriture. C'est la même donnée que celle rendue à
-l'écran, servie par la sonde du hub (`RealtimeHub.probe()`, `RealtimeHub.ts:847`).
+l'écran, servie par la sonde du hub (`RealtimeHub.probe()`, `RealtimeHub.ts#RealtimeHub.probe`).
 
 ## 🧪 Tests & couverture
 

package/docs/observabilite.md

@@ -96,7 +96,7 @@ temps de réponse — elle mesure **ce qui n'est pas encore parti**.
 Trois partis pris, tous lisibles dans le code.
 
 **1. La sonde est une lecture pure, jamais un collecteur.** `RealtimeHub.probe()`
-(`RealtimeHub.ts:847`) ne fait qu'additionner des primitives déjà tenues à jour par le chemin chaud.
+(`RealtimeHub.ts#RealtimeHub.probe`) ne fait qu'additionner des primitives déjà tenues à jour par le chemin chaud.
 Aucune entrée-sortie, aucune exception possible, aucun état de lecture conservé. Appeler la sonde
 mille fois par seconde ne changerait rien à ce que le hub fait par ailleurs.
 
@@ -107,7 +107,7 @@ divergence entre deux consommateurs, et un rafraîchissement qui se choisit libr
 
 **3. La mesure voyage sur la socket qu'elle décrit.** Le même producteur alimente l'endpoint HTTP
 (premier affichage, sans attendre un tick) et le canal temps réel (le suivi). Un seul code, deux
-portes — `buildRealtimeHealth()` (`RealtimeAdminApi.ts:74`).
+portes — `buildRealtimeHealth()` (`RealtimeAdminApi.ts#buildRealtimeHealth`).
 
 Le compromis assumé : cette sonde est **per-instance par nature**. Un pod à quatre workers rend quatre
 vérités partielles. Nodefony ne les moyenne pas au hasard de la requête — il pousse une vue agrégée
@@ -247,26 +247,26 @@ socket.subscribe("shop:health");
 
 ## 🧰 Ce que la sonde expose, champ par champ
 
-Le contrat est `IRealtimeProbe` (`IRealtimeProbe.ts:61`). Quatre familles, un discriminant.
+Le contrat est `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`). Quatre familles, un discriminant.
 
 ### Canaux — qui vit, qui écoute
 
-| Champ                    | Ce qu'il dit                                                                                             |
-| ------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `channels[]`             | Une entrée par canal **actif** (au moins un abonné), cf `IRealtimeChannelStat` (`IRealtimeProbe.ts:47`). |
-| `channels[].channel`     | Le nom exact souscrit, **suffixe de cadence compris** (`nodefony:orm:health:2000`).                      |
-| `channels[].subscribers` | Abonnés locaux vivants. Instantané, pas un cumul.                                                        |
-| `channels[].messages`    | Publications cumulées sur ce canal.                                                                      |
-| `channelCount`           | Nombre de canaux actifs sur ce processus.                                                                |
+| Champ                    | Ce qu'il dit                                                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `channels[]`             | Une entrée par canal **actif** (au moins un abonné), cf `IRealtimeChannelStat` (`IRealtimeProbe.ts#IRealtimeChannelStat`). |
+| `channels[].channel`     | Le nom exact souscrit, **suffixe de cadence compris** (`nodefony:orm:health:2000`).                                        |
+| `channels[].subscribers` | Abonnés locaux vivants. Instantané, pas un cumul.                                                                          |
+| `channels[].messages`    | Publications cumulées sur ce canal.                                                                                        |
+| `channelCount`           | Nombre de canaux actifs sur ce processus.                                                                                  |
 
 ### Fan-out — l'amplification réelle du broker
 
-| Champ                  | Ce qu'il dit                                                                                                       |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `publishTotal`         | Appels à `publish`. **Ce que le serveur a voulu envoyer.**                                                         |
-| `fanoutTotal`          | Livraisons effectives (`publish` × abonnés). **Ce que ça a réellement coûté.**                                     |
-| `inboundTotal`         | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts:836`). |
-| `ingressRejectedTotal` | Messages venus du **backplane** et jetés parce que leur canal n'est pas déclaré diffusable.                        |
+| Champ                  | Ce qu'il dit                                                                                                                             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `publishTotal`         | Appels à `publish`. **Ce que le serveur a voulu envoyer.**                                                                               |
+| `fanoutTotal`          | Livraisons effectives (`publish` × abonnés). **Ce que ça a réellement coûté.**                                                           |
+| `inboundTotal`         | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts#RealtimeHub.recordInbound`). |
+| `ingressRejectedTotal` | Messages venus du **backplane** et jetés parce que leur canal n'est pas déclaré diffusable.                                              |
 
 Le rapport `fanoutTotal / publishTotal` est la mesure la plus parlante de la page : c'est la **taille
 moyenne d'un salon**. S'il vaut 1, chaque publication ne touche qu'une personne — un canal par client,
@@ -314,9 +314,9 @@ deux autres. Le débit en octets par seconde se dérive de deux photos.
 | `backpressure.slowConsumers`       | Connexions au-dessus du seuil de comptage.                                          |
 | `backpressure.drops`               | Cumul des frames **jetées** pour protéger la mémoire.                               |
 
-La source par connexion est `IRealtimeConnProbe` (`IRealtimeProbe.ts:25`), implémentée par le
+La source par connexion est `IRealtimeConnProbe` (`IRealtimeProbe.ts#IRealtimeConnProbe`), implémentée par le
 transport. Les seuils d'ACTION sont distincts du seuil de comptage, et ils sont
-**configurables** (`@nodefony/http`, `http/nodefony/config/config.ts:1226`) : au-delà de
+**configurables** (`@nodefony/http`, `http/nodefony/config/config.ts#httpConfigSchema`) : au-delà de
 `websocket.maxBackpressure` (4 MiB par défaut) la politique `websocket.backpressurePolicy`
 s'applique — `drop` par défaut, la frame est **jetée**. Sur un canal d'état c'est sans
 conséquence, le prochain instantané la remplace ; mais le rejet ne trie rien, et une réponse RPC
@@ -357,8 +357,8 @@ Trois champs n'apparaissent que lorsqu'ils ont un sens :
 
 ### La couche d'identité, au-dessus
 
-`buildOwnHealth()` (`RealtimeAdminApi.ts:52`) enrichit ce snapshot pur pour produire
-`IRealtimeHealth` (`IRealtimeProbe.ts:121`) : `instanceId`, la santé **process** du worker
+`buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) enrichit ce snapshot pur pour produire
+`IRealtimeHealth` (`IRealtimeProbe.ts#IRealtimeHealth`) : `instanceId`, la santé **process** du worker
 (CPU, mémoire, boucle d'événements), et — si elles ont été branchées — la santé ORM et les compteurs
 d'erreurs du journal. Ces trois derniers champs sont **additifs et optionnels** : un consommateur qui
 ne les connaît pas les ignore.
@@ -370,22 +370,22 @@ resterait vide jusqu'au premier tick.
 
 ### L'instantané HTTP
 
-`GET /nodefony/realtime/api/health`, monté par `createRealtimeAdminApi()` (`RealtimeAdminApi.ts:98`)
+`GET /nodefony/realtime/api/health`, monté par `createRealtimeAdminApi()` (`RealtimeAdminApi.ts#createRealtimeAdminApi`)
 sous le namespace `realtime` du data plane admin. Sert le premier affichage, les sondes de liveness,
 et tout script qui ne veut pas ouvrir une socket.
 
 ### Le canal temps réel
 
 `nodefony:socket`. Le producteur est un minuteur qui rappelle **le même endpoint** à travers le
-courtier admin (`StudioRealtimeController.createRealtimeChannel()`, `StudioRealtimeController.ts:212`,
-via `createBrokerTicker()` (`providers.ts:465`)). Rien n'est dupliqué : le canal est un endpoint
+courtier admin (`StudioRealtimeController.createRealtimeChannel()`, `StudioRealtimeController.ts#StudioRealtimeController.createRealtimeChannel`,
+via `createBrokerTicker()` (`providers.ts#createBrokerTicker`)). Rien n'est dupliqué : le canal est un endpoint
 rejoué.
 
 ### La cadence vit dans le nom du canal
 
 Convention isomorphe, partagée par les deux bords : `base` nu = cadence par défaut du serveur ;
-`base:<ms>` = cadence explicite. Le client fabrique le nom avec `rateChannel()` (`channelRate.ts:44`),
-le serveur le résout et le **borne** avec `parseRate()` (`channelRate.ts:63`).
+`base:<ms>` = cadence explicite. Le client fabrique le nom avec `rateChannel()` (`channelRate.ts#rateChannel`),
+le serveur le résout et le **borne** avec `parseRate()` (`channelRate.ts#parseRate`).
 
 Conséquence voulue : **un canal = une cadence = un compteur de références**. `nodefony:socket:500` et
 `nodefony:socket` sont deux minuteurs distincts, jamais réconciliés — et deux consommateurs qui
@@ -394,23 +394,23 @@ veulent tous deux le défaut partagent un seul minuteur, parce que la cadence pa
 
 ### Les canaux de santé qui circulent sur la socket
 
-Les bornes sont déclarées dans `RATE_BOUNDS` (`StudioRealtimeController.ts:59`), les noms dans
-`CHANNELS` (`providers.ts:98`). Une cadence hors bornes est **ramenée dans l'intervalle**, jamais
+Les bornes sont déclarées dans `RATE_BOUNDS` (`StudioRealtimeController.ts#RATE_BOUNDS`), les noms dans
+`CHANNELS` (`providers.ts#CHANNELS`). Une cadence hors bornes est **ramenée dans l'intervalle**, jamais
 refusée.
 
-| Canal                  | Qui le produit                                                     | Cadence par défaut | Bornes        |
-| ---------------------- | ------------------------------------------------------------------ | ------------------ | ------------- |
-| `nodefony:socket`      | La sonde du hub, rejouée depuis l'endpoint admin `realtime`        | 2 s                | 500 ms – 60 s |
-| `nodefony:supervision` | `createStatsTicker()` (`providers.ts:222`) — CPU, mémoire, GC, ELU | 1 s                | 250 ms – 60 s |
-| `nodefony:debugbar`    | Le même producteur, canal séparé pour la barre de débogage         | 1 s                | 250 ms – 60 s |
-| `nodefony:orm:health`  | Endpoint admin `orm/connection/health`, rejoué                     | 5 s                | 1 s – 60 s    |
-| `nodefony:orm:flow`    | Endpoint admin `orm/flow` (débit de requêtes)                      | 2 s                | 500 ms – 60 s |
-| `nodefony:syslog`      | `createSyslogBridge()` (`providers.ts:145`)                        | **événementiel**   | — (coalescé)  |
+| Canal                  | Qui le produit                                                                   | Cadence par défaut | Bornes        |
+| ---------------------- | -------------------------------------------------------------------------------- | ------------------ | ------------- |
+| `nodefony:socket`      | La sonde du hub, rejouée depuis l'endpoint admin `realtime`                      | 2 s                | 500 ms – 60 s |
+| `nodefony:supervision` | `createStatsTicker()` (`providers.ts#createStatsTicker`) — CPU, mémoire, GC, ELU | 1 s                | 250 ms – 60 s |
+| `nodefony:debugbar`    | Le même producteur, canal séparé pour la barre de débogage                       | 1 s                | 250 ms – 60 s |
+| `nodefony:orm:health`  | Endpoint admin `orm/connection/health`, rejoué                                   | 5 s                | 1 s – 60 s    |
+| `nodefony:orm:flow`    | Endpoint admin `orm/flow` (débit de requêtes)                                    | 2 s                | 500 ms – 60 s |
+| `nodefony:syslog`      | `createSyslogBridge()` (`providers.ts#createSyslogBridge`)                       | **événementiel**   | — (coalescé)  |
 
 > [!WARNING]
 > **`nodefony:dashboard` n'est servi par aucun fournisseur.** Le canal de supervision s'appelle
 > `nodefony:supervision`. Le nom survit pourtant comme constante exportée, dépréciée
-> (`PLATFORM_CHANNELS.dashboard`, `platformChannels.ts:58`, retrait en 11.0.0) — c'est ce qui le rend piégeux. S'abonner à un canal inconnu ne lève **aucune
+> (`PLATFORM_CHANNELS.dashboard`, `platformChannels.ts#PLATFORM_CHANNELS`, retrait en 11.0.0) — c'est ce qui le rend piégeux. S'abonner à un canal inconnu ne lève **aucune
 > erreur** — le provider rend `null` et rien n'arrive jamais. C'est le piège numéro un de la page.
 
 `nodefony:syslog` est le seul de la liste à ne pas être cadencé : il **relaie** au lieu de sonder. Comme
@@ -441,11 +441,11 @@ après fusion et validation — la seule vue qui dit ce qui s'applique, plutôt
 
 ## ⚙️ Configuration
 
-| Clé                      | Défaut | Effet                                                                     |
-| ------------------------ | ------ | ------------------------------------------------------------------------- |
-| `slowConsumer.bytes`     | 1 Mio  | Seuil de **comptage** de `slowConsumers` dans la sonde (`config.ts:121`). |
-| `cluster.probe.enabled`  | `true` | Branche la sonde agrégée pod en worker de cluster (`config.ts:30`).       |
-| `NF_CLUSTER_PROBE` (env) | —      | Mis à `0`, coupe la sonde pod quelle que soit la configuration.           |
+| Clé                      | Défaut | Effet                                                                                    |
+| ------------------------ | ------ | ---------------------------------------------------------------------------------------- |
+| `slowConsumer.bytes`     | 1 Mio  | Seuil de **comptage** de `slowConsumers` dans la sonde (`config.ts#slowConsumerSchema`). |
+| `cluster.probe.enabled`  | `true` | Branche la sonde agrégée pod en worker de cluster (`config.ts#probeSchema`).             |
+| `NF_CLUSTER_PROBE` (env) | —      | Mis à `0`, coupe la sonde pod quelle que soit la configuration.                          |
 
 > [!CAUTION]
 > `slowConsumer.bytes` ne pilote **que la métrique**. Les seuils qui jettent une frame ou ferment une
@@ -454,7 +454,7 @@ après fusion et validation — la seule vue qui dit ce qui s'applique, plutôt
 > ne change rien au comportement de la socket.
 
 Couper la sonde cluster est un **contournement total**, pas une mise en sourdine : sans elle, il n'y a
-ni client, ni minuteur, ni écouteur, ni message IPC (`Realtime.wireClusterProbe()`, `index.ts:351`), et
+ni client, ni minuteur, ni écouteur, ni message IPC (`Realtime.wireClusterProbe()`, `index.ts#createRealtimeHarness`), et
 l'endpoint retombe sur la vue per-instance. Aucun coût « au cas où ».
 
 ## 🏗️ En cluster — par pod ou par worker ?
@@ -464,11 +464,11 @@ instantané est exact — et ne dit rien des trois autres. Pire : deux appels co
 sur deux workers et sembler se contredire.
 
 **La réponse de Nodefony est un modèle _push_.** Chaque worker remonte périodiquement sa santé au
-maître via `ClusterProbeClient.start()` (`ClusterProbeClient.ts:190`) ; le maître fusionne et
+maître via `ClusterProbeClient.start()` (`ClusterProbeClient.ts#ClusterProbeClient.start`) ; le maître fusionne et
 rediffuse ; chaque worker met le résultat en cache. **N'importe lequel** sert alors la vue pod en temps
-constant, sans latence de requête (`ClusterProbeClient.getClusterHealth()`, `ClusterProbeClient.ts:306`).
+constant, sans latence de requête (`ClusterProbeClient.getClusterHealth()`, `ClusterProbeClient.ts#ClusterProbeClient.getClusterHealth`).
 
-La fusion, `mergeClusterHealth()` (`ClusterProbeClient.ts:60`), est une fonction pure — et sa règle
+La fusion, `mergeClusterHealth()` (`ClusterProbeClient.ts#mergeClusterHealth`), est une fonction pure — et sa règle
 mérite d'être connue :
 
 | Grandeur                                                         | Agrégation  | Pourquoi                                                                   |
@@ -478,14 +478,14 @@ mérite d'être connue :
 | `backpressure.maxBufferedAmount`                                 | **maximum** | La santé d'une flotte se juge sur son **pire** membre, pas sur sa moyenne. |
 | `slowConsumers`, `drops`                                         | somme       | Ce sont des dénombrements.                                                 |
 
-Le discriminant est le champ `cluster: true` de `IRealtimeClusterHealth` (`IRealtimeProbe.ts:178`) :
+Le discriminant est le champ `cluster: true` de `IRealtimeClusterHealth` (`IRealtimeProbe.ts#IRealtimeClusterHealth`) :
 un consommateur sait immédiatement s'il lit une vue pod ou une vue per-instance, et `instances[]`
 garde le détail par worker pour le forage.
 
 ### On paie ce qu'on regarde
 
 Les sondes coûteuses ne tournent pas en permanence. Le maître peut demander à un worker précis
-d'**enrichir** sa remontée — `ClusterProbeClient.requestEnrich()` (`ClusterProbeClient.ts:259`) — quand
+d'**enrichir** sa remontée — `ClusterProbeClient.requestEnrich()` (`ClusterProbeClient.ts#ClusterProbeClient.requestEnrich`) — quand
 un humain ouvre le forage de ce `pid`. La sonde riche (espaces mémoire, cycles de ramasse-miettes,
 descripteurs actifs) est alors allouée ; à la fermeture de l'écran, elle est libérée et son observateur
 détaché.
@@ -506,8 +506,8 @@ l'orchestrateur finit par le tuer de force à l'expiration du délai de grâce.
 
 La règle est tenue partout dans le code, y compris là où on ne l'attendrait pas — le tick de
 revalidation d'identité du hub, qui ne démarre qu'au premier inscrit, est lui aussi détaché
-(`RealtimeHub.ts:443`), tout comme le report de la sonde cluster (`ClusterProbeClient.ts:170`) et le
-minuteur générique des canaux (`providers.ts:465`).
+(`RealtimeHub.ts#RealtimeHub.subscribeClient`), tout comme le report de la sonde cluster (`ClusterProbeClient.ts#ClusterProbeClient.#ormRich`) et le
+minuteur générique des canaux (`providers.ts#createBrokerTicker`).
 
 ```ts ignore
 const timer = setInterval(tick, 2000);