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

package/docs/index.md

@@ -46,7 +46,9 @@ Quatre parcours selon ce que tu viens faire. L'ordre compte : chaque étape supp
 2. [Ce que le module apporte](#-ce-que-le-module-apporte) — pourquoi une couche de plus au-dessus de
    la WebSocket, et ce qu'elle t'évite d'écrire.
 3. [Architecture](./architecture.md) — le trajet complet d'une frame, du câble jusqu'à ta méthode.
-4. [Cookbook — un chat](./cookbook-chat.md) — l'exemple intégrateur, de bout en bout.
+4. [Cas d'usage](./cas-d-usage.md) — jeu, salon privé, sonde, notification, tâche : l'exemple
+   court qui correspond à ton besoin, et le piège qui l'accompagne.
+5. [Cookbook — un chat](./cookbook-chat.md) — l'exemple intégrateur, de bout en bout.
 
 **Je passe d'un processus à plusieurs** — le moment où le temps réel casse sans prévenir. En
 mono-processus tout marchait ; à deux répliques, un message publié sur l'une n'atteint jamais un
@@ -93,6 +95,8 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce q
 | [Actions RPC](./actions.md)                                   | appeler le serveur et attendre une réponse         | tu veux savoir si l'appel a marché            |
 | [Observabilité](./observabilite.md)                           | la sonde, les canaux de santé, les écrans          | tu te demandes si ta socket va bien           |
 | [Cadence et contre-pression](./cadence-et-contre-pression.md) | un client trop lent : ralentir, refuser, couper    | un écran prend du retard, ou la mémoire monte |
+| [Canal à membres](./canaux-a-membres.md)                      | abonner d'office, éjecter, terminer un canal       | le serveur décide qui est dans le canal       |
+| [Cas d'usage](./cas-d-usage.md)                               | un exemple court par besoin, et son piège          | tu sais ce que tu veux construire             |
 | [Cookbook — un chat](./cookbook-chat.md)                      | l'exemple complet, client et serveur               | tu veux du code qui marche tout de suite      |
 
 ```nodefony-cards
@@ -121,6 +125,12 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce q
   { "icon": "🚦", "title": "cadence-et-contre-pression", "href": "./cadence-et-contre-pression.md",
     "desc": "Deux étages qui ne se parlent pas et se rencontrent quand même : le client ralentit la cadence de ses canaux d'état (AIMD), le serveur refuse d'empiler au-delà de 4 Mio puis ferme en 1013. Avec les courbes calculées par le vrai code, et les sondes qui le montrent en production.",
     "meta": "un écran prend du retard, ou la mémoire du serveur monte" },
+  { "icon": "👥", "title": "canaux-a-membres", "href": "./canaux-a-membres.md",
+    "desc": "Une partie à quatre, un salon fermé, un appel : le serveur abonne une connexion d'office, en éjecte une, termine le canal pour tous — et allow reste seul juge de qui entre.",
+    "meta": "le serveur décide qui est dans le canal" },
+  { "icon": "🎯", "title": "cas-d-usage", "href": "./cas-d-usage.md",
+    "desc": "Un jeu, un salon sur invitation, des capteurs, une notification personnelle, la progression d'une tâche : l'exemple de chaque besoin, exécuté par la suite de tests, avec le choix qui le justifie et l'erreur qui ne se voit qu'en production.",
+    "meta": "tu sais ce que tu veux construire" },
   { "icon": "🍳", "title": "cookbook-chat", "href": "./cookbook-chat.md",
     "desc": "Un salon de discussion complet : configuration, service métier, contrôleur, client navigateur, puis le passage en cluster.",
     "meta": "du code qui tourne, à déformer vers ton besoin" }

package/docs/observabilite.md

@@ -247,26 +247,29 @@ socket.subscribe("shop:health");
 
 ## 🧰 Ce que la sonde expose, champ par champ
 
-Le contrat est `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`). Quatre familles, un discriminant.
+Le contrat est `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.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#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.                                                                                  |
+| Champ                    | Ce qu'il dit                                                                                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `channels[]`             | Une entrée par canal **actif** (au moins un abonné), cf `IRealtimeChannelStat` (`nodefony/src/realtime/platformHealth.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#RealtimeHub.recordInbound`). |
-| `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.                                              |
+| `sealRejectedTotal`            | Messages venus du **backplane** et jetés parce que leur sceau ne se vérifie pas. `0` sans bus scellé.                                    |
+| `ingressUnknownDiscardedTotal` | Messages venus du **backplane** et jetés parce que d'une version **plus récente** : canal `nodefony:bus:*` ou type d'ordre inconnus.     |
+| `localOnlyTotal`               | Publications restées sur ce serveur alors qu'un bus est branché (canal non diffusable). `0` sans bus.                                    |
 
 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,
@@ -296,14 +299,83 @@ lectures possibles quand il grimpe :
 Le canal visé n'est délibérément pas exposé : un compteur d'observabilité ne doit pas devenir un
 moyen de sonder ce que le système accepte.
 
-⚠️ Ce compteur ne voit pas tout : un message **mal scellé** est écarté par le transport, avant
-d'atteindre le hub, donc sans être compté ici. Un bus scellé peut ainsi rester à zéro alors qu'il est
-attaqué — le signe est alors l'absence de trafic légitime, pas ce compteur.
+### Messages du bus d'une version plus récente — compté à part
+
+Une version suivante peut ajouter des messages au bus : un canal du territoire `nodefony:bus:`, ou un
+nouveau type d'ordre sur le canal de contrôle. Pendant un déploiement progressif, un serveur resté sur
+l'ancienne version les reçoit sans les connaître. Il les **jette** — aucun abonné n'en reçoit rien —
+et les compte dans `ingressUnknownDiscardedTotal`, **jamais** dans `ingressRejectedTotal` : sinon
+chaque déploiement déclencherait de fausses alertes d'injection, et une vraie attaque passerait
+inaperçue dans ce bruit. Le journal le signale une seule fois par motif, en `INFO`, sans recopier le
+nom reçu.
+
+Il monte pendant un déploiement, puis s'arrête quand tous les serveurs portent la même version. S'il
+continue de monter ensuite, un serveur est resté sur une version plus ancienne. Ce qui reste
+suspect reste compté comme une injection : un autre canal de la plateforme, une variante de casse du
+territoire, un ordre d'un type connu mais de forme fausse, ou qui vise un canal de la plateforme.
+
+Un message **mal scellé** n'entre pas dans ce compteur : le transport l'écarte avant le hub, et le
+compte à part dans `sealRejectedTotal` (relayé au même niveau de la sonde, et dans
+`backplane.sealRejectedTotal`). Quand celui-là grimpe, trois lectures : une rotation du secret en
+cours (des exemplaires n'ont pas encore le même), un producteur mal configuré, ou quelqu'un qui
+écrit sur votre bus sans connaître le secret.
+
+### Restés sur ce serveur — l'oubli de diffusion rendu visible
+
+`localOnlyTotal` compte les publications restées sur **ce** serveur alors qu'un bus est branché :
+leur canal n'est pas déclaré diffusable (`@RealtimeBroadcast`). Sans bus, il vaut toujours zéro —
+la question ne se pose pas. Coût : un `++` sur un chemin déjà froid, aucune allocation.
+
+Deux lectures quand il grimpe :
+
+- **voulue** — un canal propre au serveur par nature : le forage de Studio, la barre de débogage,
+  la sonde d'un exemplaire ;
+- **oubli** — un canal applicatif (`chat:`, `alertes:`) dont les abonnés des AUTRES serveurs ne
+  reçoivent rien, sans erreur. Ajouter `@RealtimeBroadcast("chat:")` sur son contrôleur.
+
+Au démarrage, la ligne `realtime diffusion entre serveurs : …` liste les préfixes diffusés (le
+canal personnel `user:` y figure d'office dès qu'un bus est branché) : tout ce qui n'y est pas
+reste local.
+
+### Admission — les refus par cause
+
+Quatre compteurs monotones disent POURQUOI un abonné n'est pas entré, quand la cause n'est pas son
+droit. Un refus de droit (`forbidden`) n'est pas compté ici : c'est le comportement normal d'un canal
+gardé. Ce que comptent ceux-ci, c'est une infrastructure qui ne suit plus, ou une configuration
+incomplète (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`).
+
+<!-- prettier-ignore -->
+| Champ | Unité | Ce qu'il compte | Quand il monte |
+| --- | --- | --- | --- |
+| `authenticateTimedOutTotal` | une poignée de main | connexions fermées en `1013` faute d'authentification dans `authenticateTimeoutMs` | la base ou le service qui porte les identités ne répond plus ; les clients reculent puis reviennent |
+| `allowTimedOutTotal` | un appel d'`allow` | règles d'admission restées sans réponse dans `allowTimeoutMs` ; l'abonné a reçu `unavailable` et réessaie | la base que lisent les règles ne suit plus ; 50 en 5 s ouvrent le coupe-circuit |
+| `allowSaturatedTotal` | une demande | demandes rendues `unavailable` SANS appeler la règle : plafond `maxPendingAllowsTotal` atteint, coupe-circuit ouvert, ou délai épuisé dans la file d'une connexion | une tempête de reconnexion, ou une base lente qui fait déborder les places |
+| `systemFloorDeniedTotal` | un abonnement | canaux de plateforme (`syslog:`, `orm:`…) refusés faute de module de sécurité chargé | une configuration incomplète autant qu'une tentative d'accès — dans les deux cas, quelque chose est à regarder |
+
+Les trois premiers vont ensemble : `allowTimedOutTotal` qui monte puis `allowSaturatedTotal` qui
+s'envole, c'est la base qui a cessé de répondre et le serveur qui se protège — la base reçoit au plus
+`maxPendingAllowsTotal` appels à la fois, jamais une rafale proportionnelle au nombre de clients. Un
+`WARNING` limité à un par fenêtre de 10 s accompagne chaque famille dans le journal. Les réglages et
+leur raison : [`configuration.md`](./configuration.md) ; le comportement vu par l'abonné :
+[`securite.md`](./securite.md).
+
+### Trames écartées à l'entrée
+
+Deux compteurs monotones disent combien de trames reçues n'ont pas pu être lues. Elles ne reçoivent
+aucune réponse et la connexion reste ouverte : répondre à une trame illisible offrirait à un client
+défectueux une boucle, et à un curieux un écho de ce que le décodeur accepte. Le journal en dit la
+première de chaque connexion, jamais les suivantes.
+
+<!-- prettier-ignore -->
+| Champ | Unité | Ce qu'il compte | Quand il monte |
+| --- | --- | --- | --- |
+| `binaryDiscardedTotal` | une trame reçue | trames binaires reçues sur une connexion texte dont le contrôleur ne lit pas les octets bruts (`onRealtimeBinary`) | un client envoie un flux que personne n'attend, ou le lecteur a été oublié côté serveur |
+| `malformedDiscardedTotal` | une trame reçue | trames illisibles pour le codec de la connexion : JSON invalide, CBOR tronqué | un client défectueux, ou quelqu'un qui sonde le décodeur |
 
 ### Connexions et volume
 
 `connectionCount`, `bytesSentTotal`, `messagesSentTotal` — vivants pour la première, cumulés pour les
-deux autres. Le débit en octets par seconde se dérive de deux photos.
+deux autres, connexions fermées comprises. Le débit en octets par seconde se dérive de deux photos.
 
 ### Back-pressure — le risque numéro un
 
@@ -353,12 +425,15 @@ Trois champs n'apparaissent que lorsqu'ils ont un sens :
   signale une perte **volontaire** : la mémoire du processus a été préservée au prix de messages non
   relayés aux autres répliques. Il doit rester à zéro ; s'il bouge, regarder l'état du bus avant de
   relever le plafond (`backplane.maxQueueBytes`) — un plafond plus haut ne rattrape pas un bus en
-  retard, il repousse l'échéance.
+  retard, il repousse l'échéance. Les **ordres** (terminer un canal, éjecter un compte) ne sont
+  jamais abandonnés pour faire place : ils passent hors plafond. Un ordre que le bus refuse (bus
+  injoignable) est compté à part, `controlLostTotal`, et annoncé une fois par épisode — s'il bouge,
+  une éjection n'a pas été appliquée par les autres répliques.
 
 ### La couche d'identité, au-dessus
 
 `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) enrichit ce snapshot pur pour produire
-`IRealtimeHealth` (`IRealtimeProbe.ts#IRealtimeHealth`) : `instanceId`, la santé **process** du worker
+`IRealtimeHealth` (`nodefony/src/realtime/platformHealth.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.
@@ -475,10 +550,11 @@ mérite d'être connue :
 | ---------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
 | `publishTotal`, `fanoutTotal`, `connectionCount`, octets, frames | **somme**   | Le pod fait la somme de ce que font ses workers.                           |
 | `ingressRejectedTotal`                                           | somme       | Un refus reste un refus, quel que soit le worker qui l'a opposé.           |
+| `localOnlyTotal`                                                 | somme       | Une publication restée locale l'est sur le worker qui l'a émise.           |
 | `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#IRealtimeClusterHealth`) :
+Le discriminant est le champ `cluster: true` de `IRealtimeClusterHealth` (`nodefony/src/realtime/platformHealth.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.
 

package/docs/protocole.md

@@ -274,6 +274,18 @@ production** (`welcomeEnv()`, `welcomeEnv.ts#welcomeEnv`) : c'est lui que porte
 en développement. Émis par le contrôleur au handshake (`peer.notify("realtime:welcome")`,
 `RealtimeController.ts#RealtimeController.onHandshake`). Il n'y a pas de champ `version`.
 
+Un septième champ, **`codec`**, est réservé au codec de trame retenu pour les frames qui suivent
+(`RealtimeEventMap.ts#IRealtimeWelcome.codec`, ADR-0022 §2) : un des sous-protocoles que le client a
+offerts au handshake. **Absent, il vaut `nodefony.jsonrpc.v1`** — JSON-RPC texte —, et le codec ne se
+déduit jamais de l'écho `Sec-WebSocket-Protocol`, que `ws` renvoie qu'il parle le sous-protocole ou
+non. Le client sait l'offrir et l'adopter (`frameCodecNegotiation.ts#adoptFrameCodec`) ; le serveur le
+choisit quand l'application active `codec: "cbor"`, et renvoie ce choix dans le handshake.
+
+Un huitième, **`bytes`**, dit qu'une connexion restée en texte reçoit les octets sous la convention
+`{"$bytes":"<base64url>"}` (`RealtimeEventMap.ts#IRealtimeWelcome.bytes`) : le serveur l'émet quand il a
+activé un codec binaire que le client n'a pas pris, et le client relit alors des `Uint8Array` sans rien
+importer. Absent : JSON natif. La valeur nomme la convention ; une valeur inconnue laisse le JSON natif.
+
 ## 🔌 Anatomie d'une frame, champ par champ
 
 ### Le tronc commun
@@ -282,7 +294,7 @@ en développement. Émis par le contrôleur au handshake (`peer.notify("realtime
 {
   "jsonrpc": "2.0", // signature de protocole — OBLIGATOIRE, sinon la frame est `invalid`
   "method": "subscribe", // ce qu'on demande — sa PRÉSENCE fait de la frame un appel
-  "params": { "channel": "nodefony:orm:health" }, // la charge ; forme libre, jamais fiable côté serveur
+  "params": { "channel": "nodefony:orm:health" }, // la charge : objet ou tableau, jamais fiable côté serveur
   "id": 42, // PRÉSENT = requête (réponse due) · ABSENT = notification
 }
 ```
@@ -291,9 +303,25 @@ en développement. Émis par le contrôleur au handshake (`peer.notify("realtime
 | --------- | ------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
 | `jsonrpc` | oui, toujours             | `"2.0"` littéral     | Sans lui, `JsonRpcPeer.receive()` classe `invalid` (`JsonRpcPeer.ts#JsonRpcPeer.receive`) |
 | `method`  | sur un appel              | chaîne               | Décide de la nature ET de l'aiguillage (canal, action, verbe pub/sub)                     |
-| `params`  | non                       | tout JSON            | Charge applicative. Vient du réseau : **jamais** digne de confiance                       |
+| `params`  | non                       | objet ou tableau     | Charge applicative. Vient du réseau : **jamais** digne de confiance                       |
 | `id`      | sur une requête / réponse | nombre **ou** chaîne | Corrèle l'aller et le retour                                                              |
 
+> [!IMPORTANT]
+> **La charge d'un canal est un objet ou un tableau, ou absente.** JSON-RPC 2.0 (§4.2) exige un
+> `params` structuré : une bibliothèque JSON-RPC stricte, dans un autre langage, refuserait la trame
+> d'un scalaire. `publish` lève donc une `TypeError` qui nomme le canal et le type reçu, à la ligne
+> fautive, des deux côtés de la socket (`payload.ts#isRealtimePayload`) :
+>
+> ```ts
+> const temperature = 42;
+> hub.publish("capteur:temp", temperature); // TypeError — un scalaire
+> hub.publish("capteur:temp", { value: temperature }); // conforme
+> hub.publish("build:done"); // conforme : part sans `params`, arrive `undefined`
+> ```
+>
+> Des octets restent admis. Une charge absente arrive `undefined` chez l'abonné, quel que soit le bus
+> entre les serveurs, scellé ou non.
+
 > [!IMPORTANT]
 > Le pair accepte un `id` **chaîne** en entrée (conforme à la norme), mais il n'attribue jamais que
 > des `id` **numériques** à ses propres appels sortants. Une réponse portant un `id` chaîne est donc
@@ -334,6 +362,60 @@ obtenue par la socket est **identique** à ce que rendrait la même route en RES
 dans le `result` casserait cette égalité. Un pair qui ne connaît pas `meta` l'ignore — le champ est
 rétro-compatible par construction.
 
+### Des octets dans la charge — une frame comme les autres
+
+**Une trame binaire routée est une notification JSON-RPC dont la charge est, ou contient, un
+`Uint8Array` ; le codec dit seulement comment il la porte sur le fil** (ADR-0022 §3). Il n'existe
+pas de seconde grammaire, ni d'en-tête d'octets maison du type `[n° de canal][charge]` : un tel
+en-tête aurait demandé un second verrou et une seconde sonde, qui finissent toujours par diverger
+du premier.
+
+```ts
+// côté serveur — la même publication, quel que soit le codec de chaque abonné
+const frame = new Uint8Array([0x01, 0x02, 0x03]);
+hub.publish("capteur:raw", { seq: 42, frame });
+```
+
+| Connexion de l'abonné             | Ce qui passe sur le fil                                               | Ce que reçoit `on("capteur:raw")`                                                                                                 |
+| --------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| CBOR                              | trame binaire : `frame` en chaîne d'octets native (type majeur 2)     | `{ seq: 42, frame: Uint8Array }`                                                                                                  |
+| texte, serveur en `codec: "cbor"` | trame texte : `"frame":{"$bytes":"AQID"}` (base64url)                 | `{ seq: 42, frame: Uint8Array }`                                                                                                  |
+| texte, serveur en `codec: "json"` | trame texte, sans convention d'octets : `"frame":{"0":1,"1":2,"2":3}` | un objet déformé, plus un `Uint8Array` (`jsonFrameCodec.ts#JSON_FRAME_CODEC`) — d'où `codec: "cbor"` dès que des octets circulent |
+
+Parce que c'est la même frame, elle passe par **les mêmes portes** que le texte : verrou de frame,
+politique de canal, audit des refus, sonde du hub ([sécurité](./securite.md)). Le codec se négocie
+au handshake et s'annonce dans l'accueil (champs `codec` et `bytes`, voir plus haut) ; il se règle
+côté serveur par la clé [`codec`](./configuration.md#codec--la-forme-des-frames-sur-le-fil), côté
+navigateur par l'option `codec` de la socket.
+
+**La règle du `$bytes` forgé.** Sur une connexion texte, le récepteur relit en octets tout objet
+dont la **seule** clé est `$bytes` et dont la valeur est une chaîne. Un objet applicatif qui a
+exactement cette forme sans venir d'octets changerait donc de nature selon le codec de l'abonné :
+objet pour un client CBOR, octets pour un client texte. L'encodeur texte le **refuse** plutôt que
+d'envoyer une donnée qui serait mal relue (`jsonFrameCodec.ts#JSON_BYTES_FRAME_CODEC`) :
+
+```ts ignore
+socket.publish("prix", { montant: { $bytes: "12 euros" } });
+// TypeError : codec JSON : objet {"$bytes": …} non issu d'octets sous la clé "montant"
+//   — le récepteur le relirait en octets ; envoyer un Uint8Array, ou ajouter une autre clé à l'objet
+
+socket.publish("prix", { montant: { $bytes: "12 euros", devise: "EUR" } }); // conforme : deux clés
+```
+
+- **Côté navigateur**, l'émission lève à la ligne fautive.
+- **Côté serveur**, une publication diffusée qui contient un tel objet n'atteint pas les abonnés
+  texte ; une seule ligne `ERROR` est écrite par publication, pas une par abonné
+  (`RealtimeHub.ts#ChannelFrame.claimFailure`). La clé citée est tronquée à 64 caractères et
+  échappée, pour qu'un client ne puisse pas forger de ligne de journal (CWE-117).
+- **Limite assumée** : un tel objet **conservé** par l'application, par exemple l'état initial
+  qu'un canal renvoie à chaque nouvel abonné, sera refusé aux abonnés texte **à chaque envoi**.
+  Renommer la clé ou en ajouter une seconde règle le cas une fois pour toutes.
+
+Le refus est préféré à un échappement (envelopper l'objet dans une seconde clé réservée) : échapper
+coûterait un parcours de chaque trame, et imposerait une seconde convention aux deux côtés du fil.
+Le refus ne coûte qu'une recherche de `$bytes` dans le texte déjà produit. Il ne vaut que sous la
+convention d'octets : avec `codec: "json"`, `$bytes` est une clé comme une autre.
+
 ## 🧰 Les méthodes nominales
 
 Ce que le serveur comprend **sans qu'aucun contrôleur ne l'ait déclaré**, plus les deux formes
@@ -381,7 +463,7 @@ sequenceDiagram
   participant P as JsonRpcPeer (serveur)
   participant H as RealtimeHub
   C->>P: handshake WebSocket
-  P-->>C: realtime:welcome — ts, protocol, channels, methods, identity
+  P-->>C: realtime:welcome — ts, protocol, channels, methods, identity, codec?, bytes?
   C->>P: subscribe — params.channel = "nodefony:orm:health"
   Note over P,H: le hub crée le producteur au 1er abonné
   P-->>C: nodefony:orm:health — params { queries: 42 }
@@ -402,16 +484,16 @@ Voici **tout** ce que le moteur produit. Les codes de la plage `-32000`…`-3209
 la norme aux erreurs applicatives serveur ; Nodefony y place son refus d'autorisation et le défaut
 de `RpcError`.
 
-| Code     | Émis par                                                                                     | Déclencheur                                            | Ce que voit le pair                                     |
-| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
-| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                   | requête vers une action non enregistrée                | `method not found: <nom>`                               |
-| `-32603` | même méthode (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                    | le handler a levé une exception **ordinaire**          | `internal error` — générique, rien d'autre              |
-| `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                           | `beforeDispatch` a dit non **sur une requête**         | `unauthorized`, sans jamais dire pourquoi               |
-| `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts#RpcError`)                             | le handler expose volontairement son refus             | le message ET le `data` choisis par le handler          |
-| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts#RealtimeController.actionParamsWrapper`) | `api.request` appelé avec un `params.path` invalide    | message explicite (l'appel est malformé)                |
-| `-32000` | le pont API (`RealtimeController.ts#RealtimeController.invokeApiRequest`)                    | la route invoquée REFUSE : 401, 403, 404, 405, **422** | le message, `data.status` — et `data.fields` sur un 422 |
+| Code     | Émis par                                                                                     | Déclencheur                                                 | Ce que voit le pair                                                                                      |
+| -------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                   | requête vers une action non enregistrée                     | `method not found: <nom>`                                                                                |
+| `-32603` | même méthode (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                    | le handler a levé une exception **ordinaire**               | `internal error` — générique, rien d'autre                                                               |
+| `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                           | `beforeDispatch` a dit non **sur une requête**              | `unauthorized`, sans jamais dire pourquoi                                                                |
+| `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts#RpcError`)                             | le handler expose volontairement son refus                  | le message ET le `data` choisis par le handler                                                           |
+| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts#RealtimeController.actionParamsWrapper`) | `api.request` appelé avec un `params.path` invalide         | message explicite (l'appel est malformé)                                                                 |
+| `-32000` | le pont API (`RealtimeController.ts#RealtimeController.invokeApiRequest`)                    | la route invoquée REFUSE : 401, 403, 404, 405, **422**, 429 | le message, `data.status` — `data.fields` sur un 422, `data.retryAfter` si l'action a posé `Retry-After` |
 
-Un refus de la route invoquée par le pont garde la forme d'un `fetch` dont `ok` est faux : le statut HTTP voyage dans `data.status`. Une erreur de validation — `ZodError` levée par l'action, ou entrée refusée par le `schema` de la route — est un **422** dont `data.fields` nomme chaque champ et sa partie (`{ field, message, in }`), exactement le `error.fields` du même appel en HTTP. Tout autre `throw` reste opaque (`-32603`).
+Un refus de la route invoquée par le pont garde la forme d'un `fetch` dont `ok` est faux : le statut HTTP voyage dans `data.status`. Une erreur de validation — `ZodError` levée par l'action, ou entrée refusée par le `schema` de la route — est un **422** dont `data.fields` nomme chaque champ et sa partie (`{ field, message, in }`), exactement le `error.fields` du même appel en HTTP. Un refus passager (429, 503) dont l'action a posé `Retry-After` (RFC 9110 §10.2.3) porte l'attente dans `data.retryAfter`, en secondes — une date HTTP y est ramenée à l'écart : une socket ouverte n'a plus d'en-tête, et le même code de contrôleur (`this.response?.setHeader("Retry-After", n)` puis le refus) sert les deux transports. Seul cet en-tête traverse : rien d'autre posé par l'action ne fuit sur une trame. Tout autre `throw` reste opaque (`-32603`).
 
 Et un échec qui n'est **pas** une frame : l'expiration. `startCall()` ne reçoit rien dans le délai
 imparti, supprime l'entrée en attente et rejette localement avec `RPC timeout: <méthode>`
@@ -443,7 +525,7 @@ qui alimente le journal d'audit avec le pair concerné.
 ### Le refus d'une notification n'est pas une erreur
 
 C'est la subtilité la plus importante de la page. Le verrou de frame s'applique aux requêtes **et**
-aux notifications (`beforeDispatch`, `JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`), mais leurs conséquences diffèrent
+aux notifications (`beforeDispatch`, `JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`), mais leurs conséquences diffèrent
 radicalement :
 
 | La frame refusée est… | Ce qui part                                                                                | Pourquoi                                             |
@@ -453,11 +535,25 @@ radicalement :
 
 `IRealtimeDenied` (`RealtimeEventMap.ts#IRealtimeDenied`) porte `channel` et `reason` — plus un `detail` optionnel, posé hors production seulement — et le motif
 est **générique**. Jamais « il te manque `ROLE_ADMIN` » : ce serait un oracle d'autorisation, un
-attaquant y lirait la carte des droits. Trois motifs circulent : `forbidden` (le verrou a dit non),
-`limit` (le plafond de canaux de la connexion est atteint, `RealtimeController.ts#RealtimeController.onRealtimeNotification`) et `unknown`
-(aucun producteur ne sert ce nom — jamais un oracle : un canal gardé rend `forbidden`, qu'il existe ou
-non). Côté client,
-`onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`) branche un handler dessus.
+attaquant y lirait la carte des droits. Quatre motifs circulent, et l'union est FERMÉE
+(`RealtimeEventMap.ts#RealtimeDeniedReason`) — un motif inconnu reçu d'un serveur plus récent est
+replié sur `forbidden` :
+
+<!-- prettier-ignore -->
+| Motif | Sens | Le client réessaie ? |
+| --- | --- | --- |
+| `forbidden` | le verrou ou la règle d'admission `allow` a dit non | jamais — le droit ne changera pas en réessayant |
+| `limit` | le plafond de canaux de la connexion est atteint (`RealtimeController.ts#RealtimeController.onRealtimeNotification`) | jamais |
+| `unknown` | aucun producteur ne sert ce nom — jamais un oracle : un canal gardé rend `forbidden`, qu'il existe ou non | jamais |
+| `unavailable` | la règle `allow` n'a pas répondu à temps, ou le serveur protège sa base (plafond, coupe-circuit) | **oui**, le seul : trois fois au plus |
+
+`unavailable` peut porter `retryAfterMs` : le délai, en millisecondes, pendant lequel le serveur
+n'appellera plus la règle (coupe-circuit ouvert). Le client attend ce délai, puis ajoute un recul
+exponentiel à **gigue complète** — un tirage uniforme entre zéro et 1 s, 2 s, puis 4 s — pour que
+mille clients refusés au même instant ne reviennent pas au même instant. Il ne rejoue que le
+`subscribe` concerné, jamais la connexion. Côté client,
+`onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`) branche un handler dessus ; il ne voit que le
+refus DÉFINITIF, après le dernier réessai.
 
 ### L'abonnement accepté s'acquitte
 
@@ -481,6 +577,18 @@ antérieur — répute l'abonnement actif dès le rejeu, au lieu d'attendre pour
 > n'est réservé par aucune norme. Le refus d'autorisation est `-32001` sur une requête, et une
 > notification `realtime:denied` sur une notification.
 
+### La fermeture qui dit « reviens plus tard »
+
+Une frame refusée laisse la connexion ouverte ; certaines causes, elles, la ferment. Le code de
+fermeture dit alors ce que le client doit faire (`closeCodes.ts`, le registre complet est dans
+[`securite.md`](./securite.md)). Un seul est une invitation à revenir : `1013` « try again later »
+(RFC 6455 §7.4.1). Le serveur l'émet quand l'authentification n'a pas répondu à temps à la poignée
+de main (`authenticateTimeoutMs`), ou quand le client ne vide plus sa file d'envoi. Le client le
+range parmi les fermetures reconnectables (`notice.ts#isReconnectableCloseCode`) : il recule, puis
+rouvre une connexion neuve, rejoue son `welcome` et ses abonnements. Un navigateur ne peut pas
+émettre `1013` lui-même (`WebSocket.close()` n'accepte que `1000` et `3000`-`4999`) : c'est
+toujours le serveur qui ferme.
+
 ## 🔐 Ce que le protocole ne décide pas
 
 Le protocole transporte et classe. Il ne décide ni de l'identité, ni des droits — trois règles qui
@@ -501,21 +609,22 @@ décrits dans [la page sécurité](./securite.md).
 
 ## ⚠️ Pièges
 
-| Symptôme                                                         | Cause                                                                                                                                            | Correction                                                                                                                         |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `subscribe` répond `-32601 method not found`                     | Envoyé **avec un `id`** : classé requête, or c'est une notification (`RealtimeController.ts#RealtimeController.onHandshake`)                     | L'émettre sans `id` — `socket.subscribe(canal)`                                                                                    |
-| Le handler passé à `subscribe` n'est jamais appelé               | `NodefonySocket.subscribe()` prend **un seul** argument (`NodefonySocket.ts#NodefonySocket.subscribe`)                                           | `subscribe(canal)` **et** `on(canal, handler)`, deux gestes distincts                                                              |
-| `request()` expire immédiatement, ou ignore le délai             | Signature **positionnelle** `(méthode, params, ms)` (`NodefonySocket.ts#NodefonySocket.request`) — un objet d'options n'est pas lu               | `request(m, p, 5000)` ; le défaut est 30 000 ms                                                                                    |
-| Un tableau de frames n'obtient aucune réponse                    | Le batch n'est pas implémenté : un tableau n'a pas de `jsonrpc` → `invalid` (`jsonrpc/index.ts#classifyJsonRpcFrame`)                            | Une frame = un objet ; le multiplexage remplace le batch                                                                           |
-| Une frame malformée ne renvoie **aucune** erreur                 | Ni `-32700` ni `-32600` ne sont émis — silence + audit (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                                                    | Lire le motif `invalid` côté serveur, pas la réponse                                                                               |
-| Une trame binaire envoyée au client n'arrive à aucun handler     | Le protocole est du texte : le client l'écarte, la compte et émet une notice `-32700` (`NodefonySocket.ts#NodefonySocket.binaryFramesDiscarded`) | Un flux binaire se lit par `onBinary()` (`NodefonySocket.ts#NodefonySocket.onBinary`), hors JSON-RPC                               |
-| Une trame binaire envoyée au serveur n'arrive à aucune action    | Même règle côté serveur : écartée, comptée (`WsConnectionTransport.ts#WsConnectionTransport.binaryDiscarded`), journalisée une fois en WARNING   | Surcharger `onRealtimeBinary()` (`RealtimeController.ts#RealtimeController.onRealtimeBinary`) ; émettre par `sendBinaryToClient()` |
-| L'exception du serveur n'arrive jamais au client                 | Zero Trust : tout throw ordinaire devient `-32603` générique (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                        | Lever une `RpcError` pour exposer volontairement code et `data`                                                                    |
-| Une notification refusée disparaît sans trace côté client        | Sans `id`, aucune réponse possible (`beforeDispatch`, `JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`)                                        | Écouter `realtime:denied` via `onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`)                                           |
-| `nodefony:kernel:ping` répond `-32601` sur mon endpoint          | L'action `nodefony:kernel:ping` est déclarée par `@nodefony/studio` (`StudioRealtimeController.ts#StudioRealtimeController.realtimeActions`)     | Déclarer la sienne, ou lire `serverMethods` avant d'appeler                                                                        |
-| Le battement de cœur ne renvoie aucun pong                       | La notification `ping` est un no-op serveur (`RealtimeController.ts#RealtimeController.onHandshake`)                                             | Pour mesurer un RTT, utiliser une action RPC — `ping()` (`NodefonySocket.ts#NodefonySocket.ping`)                                  |
-| Une réponse reçue est ignorée sans message                       | Corrélation sur `id` **numériques** seulement (`JsonRpcPeer.ts#JsonRpcPeer.handleResponse`)                                                      | Ne pas fabriquer soi-même de réponse à `id` chaîne                                                                                 |
-| Les premières frames envoyées après `connect()` semblent perdues | Le transport n'est branché qu'une fois le handshake terminé                                                                                      | Attendre `realtime:welcome` — le client le fait déjà                                                                               |
+| Symptôme                                                         | Cause                                                                                                                                                                                       | Correction                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscribe` répond `-32601 method not found`                     | Envoyé **avec un `id`** : classé requête, or c'est une notification (`RealtimeController.ts#RealtimeController.onHandshake`)                                                                | L'émettre sans `id` — `socket.subscribe(canal)`                                                                                                                                                                                                                                                                                                                             |
+| Le handler passé à `subscribe` n'est jamais appelé               | `NodefonySocket.subscribe()` prend **un seul** argument (`NodefonySocket.ts#NodefonySocket.subscribe`)                                                                                      | `subscribe(canal)` **et** `on(canal, handler)`, deux gestes distincts                                                                                                                                                                                                                                                                                                       |
+| `request()` expire immédiatement, ou ignore le délai             | Signature **positionnelle** `(méthode, params, ms)` (`NodefonySocket.ts#NodefonySocket.request`) — un objet d'options n'est pas lu                                                          | `request(m, p, 5000)` ; le défaut est 30 000 ms                                                                                                                                                                                                                                                                                                                             |
+| Un tableau de frames n'obtient aucune réponse                    | Le batch n'est pas implémenté : un tableau n'a pas de `jsonrpc` → `invalid` (`jsonrpc/index.ts#classifyJsonRpcFrame`)                                                                       | Une frame = un objet ; le multiplexage remplace le batch                                                                                                                                                                                                                                                                                                                    |
+| Une frame malformée ne renvoie **aucune** erreur                 | Ni `-32700` ni `-32600` ne sont émis — silence + audit (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                                                                                               | Lire le motif `invalid` côté serveur, pas la réponse                                                                                                                                                                                                                                                                                                                        |
+| Une trame binaire envoyée au client n'arrive à aucun handler     | Sur une connexion JSON-RPC texte, une trame binaire n'a pas de canal : le client l'écarte, la compte et émet une notice `-32700` (`NodefonySocket.ts#NodefonySocket.binaryFramesDiscarded`) | Un flux binaire se lit par `onBinary()` (`NodefonySocket.ts#NodefonySocket.onBinary`), hors JSON-RPC ; des octets routés par canal passent par un codec binaire (`codec`)                                                                                                                                                                                                   |
+| Une trame binaire envoyée au serveur n'arrive à aucune action    | Même règle côté serveur : écartée, comptée (`WsConnectionTransport.ts#WsConnectionTransport.binaryDiscarded`), journalisée une fois en WARNING                                              | Des octets **par canal** : `codec: "cbor"` et `publish`. Un protocole binaire propre à l'application : surcharger `onRealtimeBinary()` (`RealtimeController.ts#RealtimeController.onRealtimeBinary`), émettre par `sendBinaryToClient()` — ⚠️ hors du verrou de frame et des gardes d'action et de canal : toute décision d'accès sur ces octets appartient à l'application |
+| `TypeError : codec JSON : objet {"$bytes": …} non issu d'octets` | Un objet applicatif a la forme exacte du marqueur d'octets ; un client texte le relirait en octets (`jsonFrameCodec.ts#JSON_BYTES_FRAME_CODEC`)                                             | Envoyer un vrai `Uint8Array`, renommer la clé, ou en ajouter une seconde — [la règle](#des-octets-dans-la-charge--une-frame-comme-les-autres)                                                                                                                                                                                                                               |
+| L'exception du serveur n'arrive jamais au client                 | Zero Trust : tout throw ordinaire devient `-32603` générique (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                                                                   | Lever une `RpcError` pour exposer volontairement code et `data`                                                                                                                                                                                                                                                                                                             |
+| Une notification refusée disparaît sans trace côté client        | Sans `id`, aucune réponse possible (`beforeDispatch`, `JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`)                                                                                    | Écouter `realtime:denied` via `onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`)                                                                                                                                                                                                                                                                                    |
+| `nodefony:kernel:ping` répond `-32601` sur mon endpoint          | L'action `nodefony:kernel:ping` est déclarée par `@nodefony/studio` (`StudioRealtimeController.ts#StudioRealtimeController.realtimeActions`)                                                | Déclarer la sienne, ou lire `serverMethods` avant d'appeler                                                                                                                                                                                                                                                                                                                 |
+| Le battement de cœur ne renvoie aucun pong                       | La notification `ping` est un no-op serveur (`RealtimeController.ts#RealtimeController.onHandshake`)                                                                                        | Pour mesurer un RTT, utiliser une action RPC — `ping()` (`NodefonySocket.ts#NodefonySocket.ping`)                                                                                                                                                                                                                                                                           |
+| Une réponse reçue est ignorée sans message                       | Corrélation sur `id` **numériques** seulement (`JsonRpcPeer.ts#JsonRpcPeer.handleResponse`)                                                                                                 | Ne pas fabriquer soi-même de réponse à `id` chaîne                                                                                                                                                                                                                                                                                                                          |
+| Les premières frames envoyées après `connect()` semblent perdues | Le transport n'est branché qu'une fois le handshake terminé                                                                                                                                 | Attendre `realtime:welcome` — le client le fait déjà                                                                                                                                                                                                                                                                                                                        |
 
 ## 🧪 Tests & couverture