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

package/docs/cadence-et-contre-pression.md

@@ -226,18 +226,27 @@ Deux réglages, et le second est celui qu'on oublie :
   `atelier:load:2000` ouvert à n'importe qui.
 
 ```ts
+// nodefony/config/http.ts — le fragment du module, importé par le manifeste
+import type { IHttpConfigInput } from "@nodefony/http";
+
+export const httpConfig = () =>
+  ({
+    websocket: { maxBackpressure: 1048576, backpressureCloseAfterDrops: 200 },
+    websocketSecure: {
+      maxBackpressure: 1048576,
+      backpressureCloseAfterDrops: 200,
+    },
+  }) satisfies IHttpConfigInput;
+```
+
+```ts ignore
 // nodefony.config.ts — extrait
 import { defineConfig, use } from "nodefony";
+import { httpConfig } from "./nodefony/config/http";
 
 export default defineConfig(() => ({
   modules: [
-    use("@nodefony/http", {
-      websocket: { maxBackpressure: 1048576, backpressureCloseAfterDrops: 200 },
-      websocketSecure: {
-        maxBackpressure: 1048576,
-        backpressureCloseAfterDrops: 200,
-      },
-    }),
+    use("@nodefony/http", httpConfig()),
     "@nodefony/framework",
     use("@nodefony/security", {
       // Préfixe : garde atelier:load ET atelier:load:2000, atelier:load:4000…
@@ -270,8 +279,8 @@ curl -sk https://127.0.0.1:5152/nodefony/realtime/api/health | jq '.backpressure
 ### La cadence vit dans le nom du canal
 
 Un canal d'état cadencé s'appelle `base` (cadence par défaut) ou `base:<ms>` (cadence explicite).
-Le client fabrique le nom avec `rateChannel()` (`channelRate.ts:44`), le serveur le relit et le
-**borne** avec `parseRate()` (`channelRate.ts:63`). Une même fonction pour les deux bords : la
+Le client fabrique le nom avec `rateChannel()` (`channelRate.ts#rateChannel`), le serveur le relit et le
+**borne** avec `parseRate()` (`channelRate.ts#parseRate`). Une même fonction pour les deux bords : la
 convention ne peut pas diverger.
 
 Conséquences voulues :
@@ -279,7 +288,7 @@ Conséquences voulues :
 - **1 canal = 1 cadence = 1 ticker.** Deux clients à 2 s partagent `base:2000` ; un troisième à 4 s
   ouvre `base:4000`. Le hub compte les abonnés et arrête le ticker au dernier.
 - **Le serveur garde la main.** Un client qui demande `base:10` obtient la borne basse : Studio
-  borne ses statistiques à 250 ms minimum (`RATE_BOUNDS`, `StudioRealtimeController.ts:61`).
+  borne ses statistiques à 250 ms minimum (`RATE_BOUNDS`, `StudioRealtimeController.ts#RATE_BOUNDS`).
 - **Aucun message de contrôle** : changer de cadence, c'est changer d'abonnement. Le protocole
   reste celui des canaux, rien de plus.
 
@@ -292,7 +301,7 @@ Conséquences voulues :
 
 ### Ce que le client mesure
 
-À chaque trame reçue, `AdaptiveRate.noteFrame()` (`AdaptiveRate.ts:137`) compare l'écart depuis
+À chaque trame reçue, `AdaptiveRate.noteFrame()` (`AdaptiveRate.ts#AdaptiveRate.noteFrame`) compare l'écart depuis
 la trame précédente à la cadence courante. Trois zones, et une seule décision par trame :
 
 ```mermaid
@@ -310,7 +319,7 @@ flowchart LR
 | **Bande morte** | entre les deux           | ne change rien, et **remet à zéro** le compte des bons échantillons  |
 
 Les seuils et la fenêtre sont des options (`starvationFactor`, `healthyFactor`, `recoveryWindow`),
-avec ces défauts (`AdaptiveRate.ts:100`).
+avec ces défauts (`AdaptiveRate.ts#AdaptiveRate.constructor`).
 
 > [!TIP]
 > La **bande morte** est ce qui empêche l'oscillation : un réseau « moyen » ne fait ni monter ni
@@ -320,7 +329,7 @@ avec ces défauts (`AdaptiveRate.ts:100`).
 ### Ralentir vite, accélérer prudemment
 
 - **L'échelle** est géométrique : de la cadence désirée, doublée jusqu'à 60 s par défaut — `1 s,
-2 s, 4 s, 8 s, …, 60 s` (`deriveLadder()`, `AdaptiveRate.ts:67`). Une échelle sur mesure se passe
+2 s, 4 s, 8 s, …, 60 s` (`deriveLadder()`, `AdaptiveRate.ts#deriveLadder`). Une échelle sur mesure se passe
   par l'option `ladder`.
 - **Ralentir** = monter d'un cran (×2) **dès la première famine**. Plusieurs famines successives
   doublent plusieurs fois : c'est ce qui rend la décroissance multiplicative.
@@ -329,15 +338,15 @@ avec ces défauts (`AdaptiveRate.ts:100`).
 - **Après chaque changement**, la mesure repart de zéro : la première trame du nouveau canal ne sert
   que de référence.
 - **Famine totale** : si plus aucune trame n'arrive, `noteFrame()` ne serait jamais appelé. Un chien
-  de garde, réarmé à chaque cadence, appelle `checkStarvation()` (`AdaptiveRate.ts:174`) et ralentit
+  de garde, réarmé à chaque cadence, appelle `checkStarvation()` (`AdaptiveRate.ts#AdaptiveRate.checkStarvation`) et ralentit
   quand même.
 
 ### Changer de cadence sans trou
 
 **L'image** : on change de voie sur l'autoroute en s'insérant dans la nouvelle **avant** de quitter
-l'ancienne, jamais l'inverse. `bindAdaptiveChannel()` (`AdaptiveRate.ts:242`) fait pareil : il
+l'ancienne, jamais l'inverse. `bindAdaptiveChannel()` (`AdaptiveRate.ts#bindAdaptiveChannel`) fait pareil : il
 **s'abonne au nouveau canal, puis quitte l'ancien**, dans le même geste (`applyDecision()`,
-`AdaptiveRate.ts:295`).
+`AdaptiveRate.ts#bindAdaptiveChannel`).
 
 ```mermaid
 flowchart LR
@@ -394,12 +403,12 @@ rétabli. Il sonde prudemment, recule s'il s'est trompé, et ne le paie que de q
 Quand le serveur envoie une trame, la socket l'accepte et la place dans sa **file d'envoi** :
 `bufferedAmount` compte les octets qui attendent le réseau. Un client qui ne lit plus fait grossir
 cette file sans fin. Nodefony la plafonne à **`maxBackpressure`**, 4 Mio par défaut
-(`@nodefony/http/nodefony/config/config.ts:651`).
+(`@nodefony/http/nodefony/config/config.ts#websocketSchema`).
 
 La décision est prise **trame par trame**, par une seule fonction : `decideSend()`
-(`wsBackpressure.ts:89`). Elle sert à la fois le `send()`/`broadcast()` d'un contexte WebSocket de
+(`wsBackpressure.ts#decideSend`). Elle sert à la fois le `send()`/`broadcast()` d'un contexte WebSocket de
 `@nodefony/http` et chaque connexion temps réel (`WsConnectionTransport.send()`,
-`WsConnectionTransport.ts:82`). Une seule règle, deux usages.
+`WsConnectionTransport.ts#WsConnectionTransport.send`). Une seule règle, deux usages.
 
 ```mermaid
 flowchart LR
@@ -488,8 +497,8 @@ Le client **n'apprend jamais** les seuils : il ne reçoit que leur effet.
 - Une trame jetée **n'existe pas** pour lui : il voit seulement un écart plus long entre deux
   trames.
 - Une fermeture arrive avec le code `1013`. Il le classe **transitoire** : ce n'est pas un des codes
-  définitifs (`FATAL_CLOSE_CODES`, `notice.ts:176`), donc `isReconnectableCloseCode()`
-  (`notice.ts:192`) répond oui, et il se reconnecte avec une attente croissante.
+  définitifs (`FATAL_CLOSE_CODES`, `notice.ts#FATAL_CLOSE_CODES`), donc `isReconnectableCloseCode()`
+  (`notice.ts#isReconnectableCloseCode`) répond oui, et il se reconnecte avec une attente croissante.
 
 ## 🔌 Comment les deux étages se rencontrent
 
@@ -514,7 +523,7 @@ sans activer de trace.
 
 ### Ce que la sonde du hub expose
 
-`RealtimeHub.probe()` (`RealtimeHub.ts:847`) parcourt les connexions et rend un bloc
+`RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`) parcourt les connexions et rend un bloc
 `backpressure` :
 
 | Champ                 | Ce qu'il dit                                                                | Lecture                                                 |

package/docs/configuration.md

@@ -125,19 +125,19 @@ fichiers, jamais trois**.
 | `nodefony/config/config.ts`             | **le quoi**    | le schéma Zod commenté, source **unique** des valeurs d'usine, et les défauts matérialisés        |
 | `nodefony/config/defineModuleConfig.ts` | **le comment** | le builder pur : analyse, surcharge d'environnement, gel — il ne retape jamais une valeur d'usine |
 
-Le schéma `realtimeConfigSchema` (`config.ts:259`) porte chaque valeur en `.default()` et chaque
+Le schéma `realtimeConfigSchema` (`config.ts#realtimeConfigSchema`) porte chaque valeur en `.default()` et chaque
 explication en `.describe()`. Les défauts effectifs sont **dérivés** du schéma lui-même
-(`realtimeConfigSchema.parse({})`, `config.ts:231`) : il n'existe pas de second endroit où une valeur
+(`realtimeConfigSchema.parse({})`, `config.ts#clientLogsSchema`) : il n'existe pas de second endroit où une valeur
 d'usine serait écrite, donc pas de dérive silencieuse possible entre la doc du champ et son
 comportement.
 
-Le builder `defineRealtimeConfig()` (`defineModuleConfig.ts:39`) reste **pur** : il analyse l'entrée
+Le builder `defineRealtimeConfig()` (`defineModuleConfig.ts#defineRealtimeConfig`) reste **pur** : il analyse l'entrée
 et gèle le résultat. Il ne lit aucune variable d'environnement. Les trois variables du module
 (`NF_REALTIME_DRIVER`, `NF_REALTIME_BACKPLANE_NAMESPACE`, `NF_REALTIME_BACKPLANE_SECRET`) sont
-déclarées sur leur champ dans le schéma (`.meta({ env })`, `config.ts:59`, `:76`, `:93`) et posées
+déclarées sur leur champ dans le schéma (`.meta({ env })`, `config.ts#backplaneSchema`) et posées
 par le Kernel **avant** l'analyse : le schéma les valide comme une valeur écrite dans le fichier.
 
-Le module **augmente le registre de types** (`index.ts:167`) : `use("@nodefony/realtime", { … })`
+Le module **augmente le registre de types** (`index.ts#tick`) : `use("@nodefony/realtime", { … })`
 propose ses clés en autocomplétion et **refuse** une clé inconnue à la compilation.
 
 > [!IMPORTANT]
@@ -157,31 +157,42 @@ On garde le fond de panier local, on ferme la porte d'entrée, on abaisse le pla
 dont l'application a réellement besoin.
 
 ```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 : le hub diffuse localement, aucun transport n'est ouvert.
+    backplane: { driver: "loopback" },
+
+    // Défense CSWSH (RFC 6455 §10.2). Sans elle, une page tierce ouvre une socket
+    // avec les cookies de ton utilisateur : le navigateur n'applique pas CORS ici.
+    csrf: {
+      checkOrigin: {
+        enabled: true,
+        allowList: ["https://127.0.0.1:5152"],
+        // Un client non-navigateur n'envoie pas d'en-tête Origin. Le laisser à
+        // false n'a de sens que si tout ton trafic vient d'un navigateur.
+        allowMissingOrigin: false,
+      },
+    },
+
+    // Garde anti-saturation : le défaut de 256 est généreux. Un écran qui suit
+    // dix canaux n'a aucune raison d'en ouvrir plus de quelques dizaines.
+    limits: { maxChannelsPerConnection: 32 },
+  }) satisfies IRealtimeConfigInput;
+```
+
+```ts ignore
 // nodefony.config.ts — le manifeste 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 : le hub diffuse localement, aucun transport n'est ouvert.
-      backplane: { driver: "loopback" },
-
-      // Défense CSWSH (RFC 6455 §10.2). Sans elle, une page tierce ouvre une socket
-      // avec les cookies de ton utilisateur : le navigateur n'applique pas CORS ici.
-      csrf: {
-        checkOrigin: {
-          enabled: true,
-          allowList: ["https://127.0.0.1:5152"],
-          // Un client non-navigateur n'envoie pas d'en-tête Origin. Le laisser à
-          // false n'a de sens que si tout ton trafic vient d'un navigateur.
-          allowMissingOrigin: false,
-        },
-      },
-
-      // Garde anti-saturation : le défaut de 256 est généreux. Un écran qui suit
-      // dix canaux n'a aucune raison d'en ouvrir plus de quelques dizaines.
-      limits: { maxChannelsPerConnection: 32 },
-    }),
+    use("@nodefony/realtime", realtimeConfig()),
   ],
 }));
 ```
@@ -191,8 +202,39 @@ export default defineConfig(() => ({
 Passer à N pods sur N machines ne change **ni le contrôleur, ni le client, ni un seul canal** : on
 remplace le nom du driver, et on déclare le module qui fournit les connexions pub/sub.
 
-```ts
+```ts ignore
+// nodefony/config/realtime.ts — le fragment du module, importé par le manifeste
+import type { ConfigContext } from "nodefony";
+import type { IRealtimeConfigInput } from "@nodefony/realtime";
+import type { env } from "../../env";
+
+export const realtimeConfig = (ctx: ConfigContext<typeof env>) =>
+  ({
+    backplane: {
+      // En production seulement : en développement, le fond de panier local évite
+      // d'exiger une infrastructure pour lancer l'application.
+      driver: ctx.isProd ? "redis" : "loopback",
+
+      // La cloison. Le numéro de base Redis ne cloisonne PAS le pub/sub : sans ce
+      // nom, préproduction et production sur un même Redis échangeraient leurs
+      // diffusions. À poser explicitement, et différemment par déploiement.
+      namespace: ctx.isProd ? "boutique.prod" : "boutique.dev",
+    },
+    csrf: {
+      checkOrigin: {
+        enabled: true,
+        allowList: ["https://boutique.example.com"],
+      },
+    },
+    limits: { maxChannelsPerConnection: 32 },
+  }) satisfies IRealtimeConfigInput;
+```
+
+```ts ignore
 // nodefony.config.ts — la même application, déployée en plusieurs répliques
+import { defineConfig, use } from "nodefony";
+import { realtimeConfig } from "./nodefony/config/realtime";
+
 export default defineConfig((ctx) => ({
   modules: [
     "@nodefony/http",
@@ -202,25 +244,7 @@ export default defineConfig((ctx) => ({
     // module. Sans lui déclaré, le hub reste local — et le dit dans les journaux.
     "@nodefony/redis",
 
-    use("@nodefony/realtime", {
-      backplane: {
-        // En production seulement : en développement, le fond de panier local évite
-        // d'exiger une infrastructure pour lancer l'application.
-        driver: ctx.isProd ? "redis" : "loopback",
-
-        // La cloison. Le numéro de base Redis ne cloisonne PAS le pub/sub : sans ce
-        // nom, préproduction et production sur un même Redis échangeraient leurs
-        // diffusions. À poser explicitement, et différemment par déploiement.
-        namespace: ctx.isProd ? "boutique.prod" : "boutique.dev",
-      },
-      csrf: {
-        checkOrigin: {
-          enabled: true,
-          allowList: ["https://boutique.example.com"],
-        },
-      },
-      limits: { maxChannelsPerConnection: 32 },
-    }),
+    use("@nodefony/realtime", realtimeConfig(ctx)),
   ],
 }));
 ```
@@ -252,7 +276,7 @@ regarder quand un message ne traverse pas.
 
 > [!TIP]
 > Ces quatre lignes viennent du même endroit du code (`Realtime.#wireBackplane()`,
-> `src/packages/@nodefony/realtime/index.ts:292`) et de la carte d'identité que chaque driver publie.
+> `src/packages/@nodefony/realtime/index.ts#Realtime.#wireBackplane`) et de la carte d'identité que chaque driver publie.
 > Aucun repli n'est silencieux : si le fan-out est dégradé, c'est écrit.
 
 ## ⚙️ Le schéma, clé par clé
@@ -289,8 +313,8 @@ contre-pression, eux, se règlent sur le serveur WebSocket de `@nodefony/http`
 
 Poser `false` charge le module sans rien activer. Concrètement : pas d'API d'administration
 enregistrée, pas de backplane câblé, pas de sonde de pod
-(`Realtime.onKernelBoot()`, `src/packages/@nodefony/realtime/index.ts:246`), et le service devient
-inerte (`RealtimeService.init()`, `RealtimeService.ts:77`).
+(`Realtime.onKernelBoot()`, `src/packages/@nodefony/realtime/index.ts#Realtime.onKernelBoot`), et le service devient
+inerte (`RealtimeService.init()`, `RealtimeService.ts#RealtimeService.init`).
 
 > [!WARNING]
 > **`enabled: false` désarme aussi tes gardes.** Le hub garde son plafond interne de 256 canaux,
@@ -305,7 +329,7 @@ désactiver vraiment, retire le module du manifeste.
 
 C'est **le** réglage du module. Le champ est une chaîne libre et non une énumération, volontairement :
 la liste réelle est celle du **registre** de drivers (`listBackplaneDrivers()`,
-`backplaneRegistry.ts:68`), ouverte aux drivers que tu écris toi-même. Une énumération figée dans le
+`backplaneRegistry.ts#listBackplaneDrivers`), ouverte aux drivers que tu écris toi-même. Une énumération figée dans le
 schéma fermerait cette porte.
 
 Trois noms sont enregistrés par le module au chargement :
@@ -327,10 +351,10 @@ de frappe dans une variable de déploiement ne doit pas empêcher l'application
 ### `backplane.namespace` — la cloison sur un bus partagé
 
 Ne concerne que les drivers qui traversent les machines. Le canal de transport devient
-`nodefony:realtime:<namespace>` (`resolveRedisChannel()`, `RedisBackplane.ts:31`).
+`nodefony:realtime:<namespace>` (`resolveRedisChannel()`, `RedisBackplane.ts#resolveRedisChannel`).
 
 Le défaut est **dérivé du nom de l'application**
-(`src/packages/@nodefony/realtime/index.ts:139`) — ce qui suffit à séparer deux applications
+(`src/packages/@nodefony/realtime/index.ts`) — ce qui suffit à séparer deux applications
 distinctes sur un Redis mutualisé, et **ne suffit pas** à séparer deux déploiements de la **même**
 application. Préproduction et production portent le même nom d'application, donc le même canal
 dérivé, donc le même flux.
@@ -342,7 +366,7 @@ dérivé, donc le même flux.
 > utilisateurs. Pose-la dès que deux environnements partagent un Redis.
 
 Caractères acceptés : lettres, chiffres, `_`, `.`, `-` — le motif est validé par le schéma
-(`backplaneSchema`, `config.ts:45`), donc un nom fautif arrête le démarrage plutôt que de produire un
+(`backplaneSchema`, `config.ts#backplaneSchema`), donc un nom fautif arrête le démarrage plutôt que de produire un
 canal exotique.
 
 ### `backplane.secret` — sceller ce qui circule sur le bus
@@ -350,7 +374,7 @@ canal exotique.
 Ne concerne, là aussi, que les transports **partagés**. Un bus pub/sub ne dit pas _qui_ a publié :
 sans secret, tout ce qui atterrit sur le canal — venu d'un pod ou d'un tiers qui sait écrire dans ce
 Redis — est traité comme un message légitime. Poser un secret fait porter à chaque message un sceau
-HMAC-SHA256, vérifié à l'arrivée (`openBackplaneEnvelope()`, `envelope.ts:112`) : un message non
+HMAC-SHA256, vérifié à l'arrivée (`openBackplaneEnvelope()`, `envelope.ts#openBackplaneEnvelope`) : un message non
 scellé, altéré ou repointé vers un autre canal est **ignoré**, sans exception possible.
 
 Le secret doit être **identique sur tous les pods** — c'est lui qui les reconnaît entre eux. En
@@ -370,7 +394,7 @@ sonde de santé — il reste à zéro en régime normal.
 Sans effet hors d'un worker lancé par `nodefony cluster`. Dans ce contexte, la sonde remonte
 périodiquement la santé de **son** processus au maître, qui la consolide, et redistribue
 l'instantané : n'importe quel worker peut alors servir la vue « pod entier » sans interroger les
-autres (`ClusterProbeClient`, `ClusterProbeClient.ts:138`).
+autres (`ClusterProbeClient`, `ClusterProbeClient.ts#ClusterProbeClient`).
 
 Le coût est faible mais réel : un minuteur (déréférencé, il n'empêche pas le processus de sortir) et
 un écouteur IPC par worker. Poser `false` produit un **contournement complet** — le client n'est
@@ -378,13 +402,13 @@ jamais instancié, donc zéro minuteur, zéro message IPC — et l'endpoint de s
 de l'instance courante.
 
 Deux leviers coupent la sonde, et **l'un ou l'autre suffit** : cette clé, ou la variable
-`NF_CLUSTER_PROBE=0` (`src/packages/@nodefony/realtime/index.ts:404`). C'est ce qui permet
+`NF_CLUSTER_PROBE=0` (`src/packages/@nodefony/realtime/index.ts#Realtime.#wireClusterProbe`). C'est ce qui permet
 d'éteindre une sonde sur un pod en incident sans redéployer une configuration.
 
 ### `slowConsumer.bytes` — un compteur, pas un frein
 
 Seuil de `bufferedAmount` — les octets en attente d'envoi sur une socket — au-delà duquel la sonde
-compte la connexion comme « lente » (`RealtimeHub.probe()`, `RealtimeHub.ts:847`).
+compte la connexion comme « lente » (`RealtimeHub.probe()`, `RealtimeHub.ts#RealtimeHub.probe`).
 
 > [!IMPORTANT]
 > **Cette clé observe, elle n'agit pas.** Elle ne change que le compteur `slowConsumers` de la
@@ -440,7 +464,7 @@ des canaux d'état, où seul le dernier instantané compte.
 Chaque canal ouvert coûte un producteur côté hub, un minuteur le plus souvent, et une entrée de table
 côté connexion. Sans borne, **un seul** client peut s'abonner jusqu'à épuiser la mémoire du
 processus. Le plafond est vérifié à chaque abonnement (`RealtimeController.startChannel()`,
-`RealtimeController.ts:869`).
+`RealtimeController.ts#RealtimeController.startChannel`).
 
 Quatre propriétés qui décident du bon réglage :
 
@@ -451,7 +475,7 @@ Quatre propriétés qui décident du bon réglage :
 - Un réabonnement à un canal **déjà tenu** ne consomme pas de place — l'idempotence est vérifiée
   avant le plafond. Un client qui redemande son canal n'est pas puni.
 - La garde existe **même sans configuration** : le hub porte le même défaut de 256
-  (`RealtimeHub.ts:218`), il n'y a pas de fenêtre où elle serait absente.
+  (`RealtimeHub.ts#RealtimeHub`), il n'y a pas de fenêtre où elle serait absente.
 
 `null` retire la borne. C'est un retrait explicite, à réserver aux déploiements dont tu maîtrises
 les clients — un tableau de bord interne qui compose des dizaines de flux, par exemple.
@@ -463,13 +487,13 @@ les clients — un tableau de bord interne qui compose des dizaines de flux, par
 ### `csrf.checkOrigin` — qui a le droit d'ouvrir la socket
 
 Trois clés qui forment une seule politique, appliquée à l'ouverture de la connexion
-(`RealtimeHub.checkOrigin()`, `RealtimeHub.ts:967`). Une origine refusée ferme la socket avec le code
+(`RealtimeHub.checkOrigin()`, `RealtimeHub.ts#RealtimeHub.checkOrigin`). Une origine refusée ferme la socket avec le code
 `4003`.
 
 Le défaut est **désactivé**. C'est le seul défaut du module qui n'est pas le réglage recommandé :
 active-le dès que ta socket est joignable depuis un navigateur.
 
-Le comportement se lit en trois lignes (`buildOriginGuard()`, `RealtimeService.ts:313`) :
+Le comportement se lit en trois lignes (`buildOriginGuard()`, `RealtimeService.ts#buildOriginGuard`) :
 
 | Situation                                        | Résultat                                                                 |
 | ------------------------------------------------ | ------------------------------------------------------------------------ |
@@ -528,7 +552,7 @@ use("@nodefony/realtime", { backplane: { driver: "cluster" } });
 **Ce qui se passe.** Un worker Node ne peut parler qu'au maître. Il lui envoie ses publications, et le
 maître les redistribue aux autres workers. Le driver ne s'active qu'en **rôle worker** et avec la
 variable `NF_CLUSTER=1`, posée par la commande de cluster
-(`src/packages/@nodefony/realtime/index.ts:106`) ; ailleurs, il rend `null` et le hub reste local.
+(`src/packages/@nodefony/realtime/index.ts`) ; ailleurs, il rend `null` et le hub reste local.
 
 **Pourquoi c'est précieux.** C'est le banc d'essai qui stabilise l'architecture multi-processus avant
 d'ajouter du réseau. Ton contrôleur, tes canaux diffusables et ton client voient un vrai fan-out
@@ -553,7 +577,7 @@ use("@nodefony/realtime", {
 
 **Comment il se branche.** Le driver ne dépend pas de la bibliothèque `redis` : il consomme deux
 connexions du module `@nodefony/redis` par un adaptateur purement structurel
-(`createRedisServiceTransport()`, `RedisBackplane.ts:137`). Deux et non une, parce qu'un client Redis
+(`createRedisServiceTransport()`, `RedisBackplane.ts#createRedisServiceTransport`). Deux et non une, parce qu'un client Redis
 abonné ne peut plus émettre de commandes ordinaires — le module fournit précisément des connexions
 nommées `publish` et `subscribe` dans ses défauts.
 
@@ -563,7 +587,7 @@ coupure. C'est acceptable pour un salon de discussion — le message est en base
 un bus d'événements critiques. Ne construis pas au-dessus une fiabilité que le support n'offre pas.
 
 **Si Redis est injoignable.** Le démarrage du backplane est attendu **explicitement**, et **borné à
-cinq secondes** (`src/packages/@nodefony/realtime/index.ts:90`). Au-delà, ou en cas d'échec, le
+cinq secondes** (`src/packages/@nodefony/realtime/index.ts#BACKPLANE_START_TIMEOUT_MS`). Au-delà, ou en cas d'échec, le
 module renonce, ferme proprement ce qu'il avait ouvert, et laisse le hub local — le démarrage
 continue. Une base de messages en panne ne doit pas empêcher tes serveurs HTTP de monter.
 
@@ -637,21 +661,21 @@ Quatre points que la fabrique doit respecter :
    délai.
 2. Elle peut rendre **`null`** pour dire « inactif dans ce contexte » — mauvais rôle, infrastructure
    absente. Le hub reste alors local, sans erreur.
-3. Elle reçoit un contexte complet (`IBackplaneFactoryContext`, `backplaneRegistry.ts:27`) : le
+3. Elle reçoit un contexte complet (`IBackplaneFactoryContext`, `backplaneRegistry.ts#IBackplaneFactoryContext`) : le
    module, l'`originId` déjà résolu, le rôle dans la topologie et la configuration validée.
 4. `describe()` alimente **trois** sorties depuis une source unique : la ligne de journal, la sonde
    de santé et l'écran Studio. Remplis-la honnêtement, en particulier `crossPod`.
 
 **L'autre voie : fournir une instance déjà construite.** Déclare un service nommé
 `realtimeBackplane` dans le conteneur d'injection de ton module. `RealtimeService.init()`
-(`RealtimeService.ts:77`) le lit et le branche **avant** que le registre soit consulté : une instance
+(`RealtimeService.ts#RealtimeService.init`) le lit et le branche **avant** que le registre soit consulté : une instance
 présente court-circuite la sélection par nom.
 
 > [!WARNING]
 > Le builder accepte aussi une instance en second argument (`defineRealtimeConfig(config, {
 backplane })`), et la documentation d'architecture présente cette voie. En pratique elle n'est pas
 > atteignable depuis `nodefony.config.ts` : le module appelle le builder avec la seule configuration
-> fusionnée (`src/packages/@nodefony/realtime/index.ts:230`), et le schéma Zod est strict : une clé
+> fusionnée (`src/packages/@nodefony/realtime/index.ts#Realtime.onKernelRegister`), et le schéma Zod est strict : une clé
 > inconnue, dont une instance de classe posée dans `backplane`, fait échouer le boot. Pour brancher un objet déjà construit, utilise
 > le service `realtimeBackplane`.
 
@@ -680,7 +704,7 @@ L'ordre de recouvrement, du plus faible au plus fort :
 2. **La configuration de l'application** — ton `use("@nodefony/realtime", { … })`.
 3. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`** et
    **`NF_REALTIME_BACKPLANE_SECRET`** — posées par le Kernel après la fusion et **avant** la
-   validation Zod (`applyEnvShortcuts`, `Kernel.ts:1989`) : une valeur fausse **arrête le démarrage** en nommant la
+   validation Zod (`applyEnvShortcuts`, `Kernel.ts#Kernel.applyEnvConfigOverrides`) : une valeur fausse **arrête le démarrage** en nommant la
    variable (un secret de moins de 32 caractères, un espace de noms qui contient `:`). Chacune
    accepte aussi sa forme `<NOM>_FILE` (secret monté par Docker ou Kubernetes).
 4. **`NF__REALTIME__<CHEMIN>`** — même moment, même validation. Un chemin introuvable produit un
@@ -712,10 +736,10 @@ NF_CLUSTER_PROBE=0        # couper la sonde de pod sur une réplique en incident
 
 Deux fonctions publiques, utiles surtout aux tests et aux outils.
 
-`defineRealtimeConfig(config?, options?)` (`defineModuleConfig.ts:39`) analyse et **gèle**. Appelé
+`defineRealtimeConfig(config?, options?)` (`defineModuleConfig.ts#defineRealtimeConfig`) analyse et **gèle**. Appelé
 hors Kernel (un test, un outil), il ne voit pas les variables d'environnement : c'est le Kernel
 qui les pose. Le module l'appelle lui-même à l'enregistrement
-(`Realtime.onKernelRegister()`, `src/packages/@nodefony/realtime/index.ts:221`) : tu n'as pas à
+(`Realtime.onKernelRegister()`, `src/packages/@nodefony/realtime/index.ts#Realtime.onKernelRegister`) : tu n'as pas à
 l'invoquer dans une application. En revanche, c'est l'outil qui permet de vérifier une configuration
 sans démarrer un serveur.
 
@@ -727,15 +751,15 @@ const cfg = defineRealtimeConfig({ backplane: { driver: "redis" } });
 // Une valeur invalide ou une clé inconnue lève une BootConfigurationError, avec le chemin exact du champ fautif.
 ```
 
-`realtimeConfigJsonSchema()` (`defineModuleConfig.ts:99`) produit le schéma JSON du module, chaque
+`realtimeConfigJsonSchema()` (`defineModuleConfig.ts#realtimeConfigJsonSchema`) produit le schéma JSON du module, chaque
 champ portant sa description. C'est ce que consomme la page module de Studio pour afficher la
 configuration attendue. L'instance de backplane éventuelle en est absente : une classe n'a rien à
 faire dans un schéma sérialisable.
 
 Un message d'erreur de validation est reformaté par le cœur avant d'être levé (`parseModuleConfig`,
 appelé par `defineRealtimeConfig`) : chaque problème apparaît sous la forme `chemin : message`
-(`src/nodefony/src/kernel/moduleConfig.ts:42`), séparés par des points médians
-(`src/nodefony/src/kernel/moduleConfig.ts:58`). Tu lis quel champ est fautif, pas une trace Zod
+(`src/nodefony/src/kernel/moduleConfig.ts#formatConfigIssue`), séparés par des points médians
+(`src/nodefony/src/kernel/moduleConfig.ts#formatConfigIssues`). Tu lis quel champ est fautif, pas une trace Zod
 brute.
 
 ## 📡 Observabilité — relire ce qui s'applique vraiment
@@ -758,16 +782,16 @@ Trois endroits, par ordre de fiabilité décroissante.
 
 ## ⚠️ Pièges
 
-| Symptôme                                                                            | Cause                                                                                            | Correction                                                                                 |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                    | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                           |
-| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles  | déclarer le module ; vérifier que Redis répond                                             |
-| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal | poser un namespace explicite et distinct par environnement                                 |
-| Le démarrage échoue avec `clé inconnue : …`                                         | clé absente du schéma strict (faute de frappe, ou clé retirée)                                   | corriger ou retirer la clé que nomme le message                                            |
-| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                         | cette clé ne pilote que le **comptage** de la sonde                                              | régler `websocketSecure.maxBackpressure` / `.backpressureCloseAfterDrops` (@nodefony/http) |
-| Toutes les connexions tombent en `4003` après activation du contrôle d'origine      | `allowList` vide, ou origine non identique au caractère près (port, schéma, sous-domaine)        | inscrire l'origine exacte ; un client non-navigateur relève de `allowMissingOrigin`        |
-| `enabled: false` posé « pour désactiver », et la garde d'origine ne s'applique plus | le service devient inerte et ne pose plus les politiques sur le hub                              | retirer le module du manifeste plutôt que l'éteindre                                       |
-| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts:218`)   | vérifier le motif de refus `realtime:denied` côté client                                   |
+| Symptôme                                                                            | Cause                                                                                                  | Correction                                                                                 |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                          | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                           |
+| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles        | déclarer le module ; vérifier que Redis répond                                             |
+| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal       | poser un namespace explicite et distinct par environnement                                 |
+| Le démarrage échoue avec `clé inconnue : …`                                         | clé absente du schéma strict (faute de frappe, ou clé retirée)                                         | corriger ou retirer la clé que nomme le message                                            |
+| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                         | cette clé ne pilote que le **comptage** de la sonde                                                    | régler `websocketSecure.maxBackpressure` / `.backpressureCloseAfterDrops` (@nodefony/http) |
+| Toutes les connexions tombent en `4003` après activation du contrôle d'origine      | `allowList` vide, ou origine non identique au caractère près (port, schéma, sous-domaine)              | inscrire l'origine exacte ; un client non-navigateur relève de `allowMissingOrigin`        |
+| `enabled: false` posé « pour désactiver », et la garde d'origine ne s'applique plus | le service devient inerte et ne pose plus les politiques sur le hub                                    | retirer le module du manifeste plutôt que l'éteindre                                       |
+| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts#RealtimeHub`) | vérifier le motif de refus `realtime:denied` côté client                                   |
 
 ## 🧪 Tests & couverture
 

package/docs/cookbook-chat.md

@@ -134,7 +134,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 +781,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 +1606,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`) |