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

package/docs/configuration.md

@@ -57,8 +57,8 @@ est validé puis **gelé** avant que le moindre canal existe.
 flowchart TD
   SCHEMA["Schéma Zod du module<br/>realtimeConfigSchema — les valeurs d'usine"]
   APP["Ton application<br/>use('@nodefony/realtime', { … }) dans nodefony.config.ts"]
-  ENVGEN["Déploiement<br/>NF__REALTIME__&lt;CHEMIN&gt;=valeur"]
-  BUILD["Builder<br/>defineRealtimeConfig() : parse Zod → NF_REALTIME_DRIVER → freeze"]
+  ENVGEN["Déploiement<br/>NF_REALTIME_DRIVER · NF__REALTIME__&lt;CHEMIN&gt;=valeur"]
+  BUILD["Builder<br/>defineRealtimeConfig() : parse Zod → freeze"]
   HUB["RealtimeHub<br/>garde d'origine · plafond de canaux · seuil de sonde"]
   BP["Driver de backplane<br/>résolu par nom dans le registre"]
   SCHEMA --> APP --> ENVGEN --> BUILD
@@ -125,18 +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:35`) reste **pur** : il analyse l'entrée,
-applique les variables d'environnement dédiées (`NF_REALTIME_DRIVER`,
-`NF_REALTIME_BACKPLANE_NAMESPACE`, `NF_REALTIME_BACKPLANE_SECRET` — toutes prioritaires sur le
-fichier), et gèle le résultat. Il ne décide rien.
+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#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]
@@ -156,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()),
   ],
 }));
 ```
@@ -190,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",
@@ -201,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)),
   ],
 }));
 ```
@@ -251,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:279`) 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é
@@ -288,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:239`), 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,
@@ -304,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 :
@@ -326,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:132`) — 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.
@@ -341,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
@@ -349,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
@@ -369,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
@@ -377,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:391`). 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:865`).
+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
@@ -439,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:815`).
+`RealtimeController.ts#RealtimeController.startChannel`).
 
 Quatre propriétés qui décident du bon réglage :
 
@@ -450,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:217`), 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.
@@ -462,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:986`). 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                                                                 |
 | ------------------------------------------------ | ------------------------------------------------------------------------ |
@@ -527,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:99`) ; 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
@@ -552,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:100`). 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.
 
@@ -562,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:83`). 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.
 
@@ -636,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:216`), 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`.
 
@@ -665,7 +690,7 @@ processus se raccorde — et c'est pour cela qu'elles ne vivent pas dans un fich
 
 | Variable                          | Portée                 | Effet                                                                      |
 | --------------------------------- | ---------------------- | -------------------------------------------------------------------------- |
-| `NF_REALTIME_DRIVER`              | ce module              | remplace `backplane.driver`. **Précédence maximale**                       |
+| `NF_REALTIME_DRIVER`              | ce module              | remplace `backplane.driver` — nom libre, un pilote inconnu est signalé     |
 | `NF_REALTIME_BACKPLANE_NAMESPACE` | ce module              | remplace `backplane.namespace` — sépare deux déploiements de la même app   |
 | `NF_REALTIME_BACKPLANE_SECRET`    | ce module              | remplace `backplane.secret` — scelle le transport partagé (≥ 32 car.)      |
 | `NF__REALTIME__<CHEMIN>`          | mécanisme du cœur      | remplace n'importe quelle clé, par son chemin. Ex. `NF__REALTIME__ENABLED` |
@@ -677,13 +702,15 @@ L'ordre de recouvrement, du plus faible au plus fort :
 
 1. **Les valeurs d'usine du schéma** — ce que tu obtiens sans rien écrire.
 2. **La configuration de l'application** — ton `use("@nodefony/realtime", { … })`.
-3. **`NF__REALTIME__<CHEMIN>`** — appliqué après la fusion et **avant** la validation Zod, donc la
-   valeur venue de l'environnement est validée comme les autres. Un chemin introuvable produit un
-   avertissement avec une suggestion, jamais une clé fantôme.
-4. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`** et
-   **`NF_REALTIME_BACKPLANE_SECRET`** — appliqués **après** l'analyse, dans le builder
-   (`defineModuleConfig.ts:41`). Ils gagnent sur tout le reste, y compris sur le mécanisme
-   générique `NF__REALTIME__BACKPLANE__…`.
+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#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
+   avertissement avec une suggestion, jamais une clé fantôme. Viser le **même** champ qu'une des
+   trois variables ci-dessus est une ambiguïté : refusée en production, et en développement
+   `NF__…` l'emporte avec un avertissement qui nomme les deux.
 
 Le mécanisme générique mérite d'être connu : le double tiret bas sépare les niveaux, les segments
 sont insensibles à la casse, et les valeurs sont converties (booléens, nombres, listes séparées par
@@ -700,17 +727,19 @@ NF_CLUSTER_PROBE=0        # couper la sonde de pod sur une réplique en incident
 
 > [!TIP]
 > `NF_REALTIME_DRIVER` existe **en plus** du mécanisme générique parce qu'il est la variable qu'on
-> pose en premier sur un déploiement, et qu'elle doit rester fiable quel que soit le moment où la
-> configuration de l'application fusionne. C'est le levier d'urgence : ramener un cluster à
-> `loopback` pour isoler une panne de bus se fait par une variable, sans redéployer de code.
+> pose en premier sur un déploiement : son nom ne dépend pas de la structure interne de la
+> configuration. C'est le levier d'urgence : ramener un cluster à `loopback` pour isoler une panne
+> de bus se fait par une variable, sans redéployer de code. `npx nodefony env` la liste avec sa
+> valeur et sa provenance.
 
 ## 🧰 Le builder et le schéma exportable
 
 Deux fonctions publiques, utiles surtout aux tests et aux outils.
 
-`defineRealtimeConfig(config?, options?)` (`defineModuleConfig.ts:35`) analyse, applique la variable
-de driver et **gèle**. Le module l'appelle lui-même à l'enregistrement
-(`Realtime.onKernelRegister()`, `src/packages/@nodefony/realtime/index.ts:213`) : tu n'as pas à
+`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#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.
 
@@ -722,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:69`) 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
@@ -753,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:217`)   | 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
@@ -353,7 +353,7 @@ gaspillerait une socket par écran.
 
 ```ts
 // frontend/src/realtime.ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 // `wss` si la page est en HTTPS, `ws` sinon. Une application Nodefony sert en
 // HTTPS par défaut, y compris en développement : ce sera donc `wss` chez toi.
@@ -366,7 +366,7 @@ const scheme = window.location.protocol === "https:" ? "wss" : "ws";
  * La reconnexion automatique, le renvoi des abonnements après une coupure et le
  * heartbeat sont inclus — rien à écrire pour ça.
  */
-export const chatSocket = new RealtimeClient({
+export const chatSocket = new NodefonySocket({
   url: `${scheme}://${window.location.host}/chat/realtime`,
 });
 ```
@@ -445,7 +445,9 @@ import { ChatRoom } from "./ChatRoom";
 
 // La connexion s'ouvre UNE fois, au démarrage de l'application. Les hooks ne
 // gèrent que les abonnements : le cycle de vie de la socket reste à toi.
-void chatSocket.connect();
+// `connect()` rejette si cette première tentative échoue (serveur absent) ;
+// la socket se reconnecte seule ensuite, et l'état se lit par les hooks.
+chatSocket.connect().catch(() => {});
 
 createRoot(document.getElementById("app")!).render(
   <NodefonyProvider client={chatSocket}>
@@ -779,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]
@@ -847,6 +852,7 @@ fonctionnent :
 // modules/chat/nodefony/controllers/ChatController.ts
 // → remplace `@RealtimeInbound("chat:send")` par une ACTION
 import { Body, CurrentUser, IsGranted } from "@nodefony/framework";
+import type { IUser } from "@nodefony/user";
 
 /**
  * L'envoi devient une action, joignable en POST HTTP comme par la socket.
@@ -860,7 +866,7 @@ import { Body, CurrentUser, IsGranted } from "@nodefony/framework";
 @IsGranted(["ROLE_USER"])
 async send(
   @Body() payload: { text?: string },
-  @CurrentUser() user?: { identifier?: string },
+  @CurrentUser() user: IUser,
 ) {
   const text = typeof payload?.text === "string" ? payload.text.trim() : "";
   if (text.length === 0 || text.length > 2000) {
@@ -869,7 +875,7 @@ async send(
 
   // L'auteur vient du SERVEUR. Le client ne peut plus mentir dessus.
   const message: ChatMessage = {
-    author: user?.identifier ?? "inconnu",
+    author: user.identifier,
     text,
     sentAt: Date.now(),
   };
@@ -1218,6 +1224,7 @@ import {
 import type { RealtimePublish } from "@nodefony/realtime";
 import { HttpError } from "@nodefony/http";
 import type { ContextType, IUploadedFile } from "@nodefony/http";
+import type { IUser } from "@nodefony/user";
 
 /** Un message tel qu'il circule sur le canal du salon. */
 export interface ChatMessage {
@@ -1288,14 +1295,14 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async send(
     @Body() payload: { text?: string },
-    @CurrentUser() user?: { identifier?: string },
+    @CurrentUser() user: IUser,
   ): Promise<{ ok: true; sentAt: number }> {
     const text = typeof payload?.text === "string" ? payload.text.trim() : "";
     if (text.length === 0 || text.length > 2000) {
       throw new HttpError("message vide ou trop long", 400);
     }
     const message: ChatMessage = {
-      author: user?.identifier ?? "inconnu",
+      author: user.identifier,
       text,
       sentAt: Date.now(),
     };
@@ -1312,13 +1319,13 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async upload(
     @UploadedFile() file?: IUploadedFile,
-    @CurrentUser() user?: { identifier?: string },
+    @CurrentUser() user: IUser,
   ): Promise<{ ok: true; filename: string; size: number }> {
     if (!file) {
       throw new HttpError("aucun fichier reçu", 400);
     }
     const announcement: ChatAttachment = {
-      author: user?.identifier ?? "inconnu",
+      author: user.identifier,
       filename: file.filename,
       size: file.size,
       mimeType: file.mimeType,
@@ -1599,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:101`), `RealtimeChannel()` (`realtimeDecorators.ts:192`), `RealtimeInbound()` (`realtimeDecorators.ts:231`) |
-| La porte WebSocket | `RealtimeController.handleRealtime()` (`RealtimeController.ts:299`) |
-| Le pont HTTP ⇄ WebSocket | `RealtimeController.realtimeApiRequest()` (`RealtimeController.ts:276`) |
-| L'abonnement et son cycle de vie | `RealtimeHub.subscribe()` (`RealtimeHub.ts:462`), `RealtimeController.startChannel()` (`RealtimeController.ts:815`) |
-| La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts:604`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts:623`) |
-| Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts:342`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:668`) |
-| Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts:714`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts:55`), cloison `resolveBackplaneOriginId()` (`originId.ts:24`) |
-| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts:20`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts:1143`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1117`) |
-| Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts:279`) |
-| Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts:269`), erreur `unauthorized` (`JsonRpcPeer.ts:417`), fermetures `origin not allowed` (`RealtimeController.ts:327`) et `unauthorized` (`RealtimeController.ts:397`) |
-| La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:826`) |
-| Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:56`), fermeture `slow consumer` (`RealtimeHub.ts:63`) |
-| Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts:1000`) |
-| L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts:231`) |
-| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts:865`), `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:213`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts:222`) |
-| Les hooks React | `useNodefony()` (`client/react/index.ts:145`), `useNodefonyState()` (`client/react/index.ts:163`), `useNodefonyIdentity()` (`client/react/index.ts:182`), `useNodefonyChannel()` (`client/react/index.ts:198`), `useNodefonyChannelData()` (`client/react/index.ts:221`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts:255`) |
-| Le client navigateur | `RealtimeClient.connect()` (`RealtimeClient.ts:389`), `RealtimeClient.subscribe()` (`RealtimeClient.ts:530`), `RealtimeClient.request()` (`RealtimeClient.ts:729`), `RealtimeClient.onDenied()` (`RealtimeClient.ts:471`) |
-| L'upload | `UploadedFile` (`routerDecorators.ts:1286`), `IUploadedFile` (`IUpload.ts:49`), `queryFile` (`Request.ts:226`) |
+| 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`) |