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

package/docs/protocole.md

@@ -31,7 +31,7 @@ source: "src/packages/@nodefony/realtime/docs/protocole.md"
 > **frames** dont la forme est normée. Trois formes existent, et une seule règle les distingue —
 > **la nature d'une frame se lit sur `method`, jamais sur `id`**. Cette page donne la grammaire
 > champ par champ, les méthodes que le serveur comprend nativement, et ce qui revient exactement
-> quand ça rate. Le moteur est `JsonRpcPeer` (`JsonRpcPeer.ts:271`), écrit une fois et branché des
+> quand ça rate. Le moteur est `JsonRpcPeer` (`JsonRpcPeer.ts#JsonRpcPeer`), écrit une fois et branché des
 > deux côtés du fil.
 
 📍 [Documentation](../../../../../docs/index.md) › [Realtime](index.md) › **Protocole**
@@ -52,12 +52,12 @@ cœur du protocole : il décide s'il faut répondre, à qui, et si une réponse
 
 ```mermaid
 flowchart TD
-  IN["Frame entrante (JSON déjà parsé)"] --> V{"jsonrpc = 2.0 ?"}
+  IN["Frame entrante (JSON déjà parsé)"] --> V{"frame JSON-RPC 2.0 valide ?"}
   V -->|non| INV["invalid — auditée, AUCUNE réponse"]
   V -->|oui| M{"method présent ?"}
   M -->|"method + id"| REQ["requête — un handler doit rendre result ou error"]
   M -->|"method seul"| NOT["notification — pub/sub, aucune réponse"]
-  M -->|"id seul"| RES["réponse — résout une requête sortante en attente"]
+  M -->|"id + result ou error"| RES["réponse — résout une requête sortante en attente"]
   REQ --> OUT["result · error"]
   NOT --> HUB["subscribe · unsubscribe · canal entrant"]
   RES --> PROM["la Promise de l'appelant"]
@@ -79,7 +79,7 @@ Deux conséquences que le reste de la page décline :
 | Pair (peer)      | Le moteur de protocole d'une connexion — `JsonRpcPeer`, identique client et serveur.  |
 | Requête          | Frame avec `method` **et** `id` — appelle exactement une réponse.                     |
 | Notification     | Frame avec `method` seul — aucune réponse, jamais.                                    |
-| Réponse          | Frame avec `id` seul, portant `result` **ou** `error`.                                |
+| Réponse          | Frame avec `id` sans `method`, portant `result` **ou** `error` bien formé.            |
 | Dispatch         | Classer une frame entrante puis la router vers son handler.                           |
 | Enveloppe        | Réponse qui joint des métadonnées serveur dans un champ **frère** du `result`.        |
 | Accueil, welcome | La 1ʳᵉ notification poussée par le serveur : protocole, canaux, actions, identité.    |
@@ -106,7 +106,7 @@ Nodefony ne l'a pas inventée. Le calcul, mis à plat :
 
 > [!NOTE]
 > **Le batch est une propriété de la norme, pas du moteur Nodefony.** `JsonRpcPeer.receive()`
-> (`JsonRpcPeer.ts:390`) attend un **objet** portant `jsonrpc: "2.0"` ; un tableau de frames n'en
+> (`JsonRpcPeer.ts#JsonRpcPeer.receive`) attend un **objet** portant `jsonrpc: "2.0"` ; un tableau de frames n'en
 > porte pas et tombe donc en `invalid`. Une frame = un objet. Le multiplexage rend le batch peu
 > utile ici : les canaux voyagent déjà dans la même connexion.
 
@@ -118,21 +118,25 @@ d'une action. La norme fournit la grammaire ; le vocabulaire est nodefonien.
 
 Trois partis pris distinguent cette implémentation d'un simple « serveur WebSocket qui parle JSON ».
 
-**Le même fichier tourne dans le navigateur et dans Node.** `JsonRpcPeer` (`JsonRpcPeer.ts:271`)
+**Le même fichier tourne dans le navigateur et dans Node.** `JsonRpcPeer` (`JsonRpcPeer.ts#JsonRpcPeer`)
 n'a aucune dépendance Node — seulement `setTimeout`. Classer, router, corréler les `id` : ce travail
 est identique des deux côtés, il est donc écrit **une seule fois**. Chaque côté l'entoure de son
 transport et de ses handlers. Historiquement, cette discrimination vivait à deux endroits qui
-divergeaient ; c'est précisément la classe de bug que l'isomorphisme supprime.
+divergeaient ; c'est précisément la classe de bug que l'isomorphisme supprime. Le classement
+lui-même est `classifyJsonRpcFrame` (`jsonrpc/index.ts#classifyJsonRpcFrame`), la brique que partage aussi le
+serveur MCP du framework : les deux portes ne peuvent plus diverger sur ce qu'est une frame valide.
 
 **Le rôle se lit sur `method`, pas sur `id`.** La lecture naïve (« `id` présent = requête ») casse
 sur les réponses, qui portent un `id` sans être des appels. `JsonRpcPeer.receive()`
-(`JsonRpcPeer.ts:390`) teste donc `method` d'abord, puis la présence d'un `id`. Une frame `id` seul
-est une **réponse** et ne déclenche jamais `-32601` à tort.
+(`JsonRpcPeer.ts#JsonRpcPeer.receive`) teste donc `method` d'abord, puis la présence d'un `id` — chaîne ou nombre :
+un `id` `null`, objet ou booléen rend la frame `invalid`, il n'en fait pas une notification. Une
+frame `id` sans `method`, portant `result` ou une `error` bien formée, est une **réponse** et ne
+déclenche jamais `-32601` à tort ; sans l'un ni l'autre, elle est `invalid`.
 
 **Un échec ne raconte rien par défaut.** Un handler qui lève une exception ordinaire produit un
-`-32603 "internal error"` **générique** (`JsonRpcPeer.ts:528`) : ni message d'origine, ni pile
+`-32603 "internal error"` **générique** (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`) : ni message d'origine, ni pile
 d'appels. Pour exposer volontairement un refus au pair — un 404, un droit manquant — il existe une
-porte explicite, `RpcError` (`JsonRpcPeer.ts:70`), et elle seule.
+porte explicite, `RpcError` (`JsonRpcPeer.ts#RpcError`), et elle seule.
 
 ## 🚀 Démarrage rapide
 
@@ -202,14 +206,14 @@ export default ChatController;
 
 ```ts
 // frontend/src/chat.ts
-import { RealtimeClient, RpcError } from "nodefony/client";
+import { NodefonySocket, RpcError } from "nodefony/client";
 
 interface ChatHistory {
   messages: string[];
 }
 
 export async function joinChat(): Promise<void> {
-  const socket = new RealtimeClient({
+  const socket = new NodefonySocket({
     url: "wss://127.0.0.1:5152/chat/realtime",
   });
   await socket.connect();
@@ -265,10 +269,10 @@ Sur le fil, dans l'inspecteur réseau du navigateur, exactement cinq frames :
 ```
 
 L'accueil porte cinq champs — `ts`, `protocol`, `channels`, `methods`, `identity`
-(`IRealtimeWelcome`, `RealtimeEventMap.ts:231`) — plus un sixième, `env`, **uniquement hors
-production** (`welcomeEnv()`, `welcomeEnv.ts:19`) : c'est lui que porte l'exemple ci-dessus, capturé
+(`IRealtimeWelcome`, `RealtimeEventMap.ts#IRealtimeWelcome`) — plus un sixième, `env`, **uniquement hors
+production** (`welcomeEnv()`, `welcomeEnv.ts#welcomeEnv`) : c'est lui que porte l'exemple ci-dessus, capturé
 en développement. Émis par le contrôleur au handshake (`peer.notify("realtime:welcome")`,
-`RealtimeController.ts:708`). Il n'y a pas de champ `version`.
+`RealtimeController.ts#RealtimeController.onHandshake`). Il n'y a pas de champ `version`.
 
 ## 🔌 Anatomie d'une frame, champ par champ
 
@@ -283,17 +287,17 @@ en développement. Émis par le contrôleur au handshake (`peer.notify("realtime
 }
 ```
 
-| Champ     | Obligatoire               | Type accepté         | Rôle exact                                                                |
-| --------- | ------------------------- | -------------------- | ------------------------------------------------------------------------- |
-| `jsonrpc` | oui, toujours             | `"2.0"` littéral     | Sans lui, `JsonRpcPeer.receive()` classe `invalid` (`JsonRpcPeer.ts:371`) |
-| `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       |
-| `id`      | sur une requête / réponse | nombre **ou** chaîne | Corrèle l'aller et le retour                                              |
+| Champ     | Obligatoire               | Type accepté         | Rôle exact                                                                                |
+| --------- | ------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
+| `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                       |
+| `id`      | sur une requête / réponse | nombre **ou** chaîne | Corrèle l'aller et le retour                                                              |
 
 > [!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
-> ignorée sans erreur (`JsonRpcPeer.handleResponse()`, `JsonRpcPeer.ts:556`) : elle ne peut, par
+> ignorée sans erreur (`JsonRpcPeer.handleResponse()`, `JsonRpcPeer.ts#JsonRpcPeer.handleResponse`) : elle ne peut, par
 > construction, correspondre à aucune requête émise par ce pair.
 
 ### La réponse — `result` ou `error`, jamais les deux
@@ -312,9 +316,9 @@ distinguer un 404 d'un refus d'autorisation sans analyser un message de texte.
 
 ### L'enveloppe — joindre une méta sans polluer le `result`
 
-Un handler peut rendre une `RpcEnvelope` (`JsonRpcPeer.ts:104`) au lieu d'une valeur nue. Le pair la
+Un handler peut rendre une `RpcEnvelope` (`JsonRpcPeer.ts#RpcEnvelope`) au lieu d'une valeur nue. Le pair la
 déballe : le `result` reste **exactement** la valeur, et la méta voyage dans un champ frère
-`meta` (`RpcMeta`, `JsonRpcPeer.ts:90`).
+`meta` (`RpcMeta`, `JsonRpcPeer.ts#RpcMeta`).
 
 ```jsonc
 {
@@ -335,37 +339,38 @@ rétro-compatible par construction.
 Ce que le serveur comprend **sans qu'aucun contrôleur ne l'ait déclaré**, plus les deux formes
 ouvertes à l'application. Colonne `id` : présent = requête (réponse due), absent = notification.
 
-| Méthode            | Direction     | `id` ?  | Rôle                                                                  | Ancrage                     |
-| ------------------ | ------------- | :-----: | --------------------------------------------------------------------- | --------------------------- |
-| `subscribe`        | client→server |   non   | « pousse-moi ce canal » — `params.channel`                            | `RealtimeController.ts:522` |
-| `unsubscribe`      | client→server |   non   | « arrête » — dernier abonné, le producteur est libéré                 | `RealtimeController.ts:775` |
-| `ping`             | client→server |   non   | Battement de cœur — **no-op serveur**, aucun pong                     | `RealtimeClient.ts:882`     |
-| `<canal>`          | server→client |   non   | Push d'un message : le **nom du canal est la `method`**               | `RealtimeController.ts:972` |
-| `<canal entrant>`  | client→server |   non   | Le client pousse sur un canal déclaré entrant                         | `RealtimeController.ts:736` |
-| `realtime:welcome` | server→client |   non   | L'accueil : 5 champs, dont l'identité résolue                         | `RealtimeController.ts:693` |
-| `realtime:denied`  | server→client |   non   | Rend OBSERVABLE le refus d'une notification                           | `RealtimeController.ts:496` |
-| `api.request`      | client→server | **oui** | Pont API — rejoue une route HTTP sur la socket (désactivé par défaut) | `RealtimeController.ts:582` |
-| `<action>`         | client→server | **oui** | Toute action déclarée par `@RealtimeAction`                           | `realtimeDecorators.ts:101` |
+| Méthode               | Direction     | `id` ?  | Rôle                                                                  | Ancrage                                                            |
+| --------------------- | ------------- | :-----: | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `subscribe`           | client→server |   non   | « pousse-moi ce canal » — `params.channel`                            | `RealtimeController.ts#RealtimeController.onHandshake`             |
+| `unsubscribe`         | client→server |   non   | « arrête » — dernier abonné, le producteur est libéré                 | `RealtimeController.ts#RealtimeController.onRealtimeNotification`  |
+| `ping`                | client→server |   non   | Battement de cœur — **no-op serveur**, aucun pong                     | `NodefonySocket.ts#NodefonySocket.ping`                            |
+| `<canal>`             | server→client |   non   | Push d'un message : le **nom du canal est la `method`** du `notify`   | `RealtimeController.ts#RealtimeController.startChannel`            |
+| `<canal entrant>`     | client→server |   non   | Le client pousse sur un canal déclaré entrant                         | `RealtimeController.ts#RealtimeController.onRealtimeNotification`  |
+| `realtime:welcome`    | server→client |   non   | L'accueil : 5 champs, dont l'identité résolue                         | `RealtimeController.ts#RealtimeController.onHandshake`             |
+| `realtime:denied`     | server→client |   non   | Rend OBSERVABLE le refus d'une notification                           | `RealtimeController.ts#RealtimeController.onHandshake`             |
+| `realtime:subscribed` | server→client |   non   | Acquitte un `subscribe` ACCEPTÉ — le flux est actif                   | `RealtimeController.ts#RealtimeController.acknowledgeSubscription` |
+| `api.request`         | client→server | **oui** | Pont API — rejoue une route HTTP sur la socket (désactivé par défaut) | `RealtimeController.ts#RealtimeController.onHandshake`             |
+| `<action>`            | client→server | **oui** | Toute action déclarée par `@RealtimeAction`                           | `realtimeDecorators.ts#RealtimeAction`                             |
 
 > [!TIP]
 > **L'accueil est ta carte du territoire.** `channels` ne liste que les canaux que ce visiteur
 > pourrait obtenir (filtrés par le même verrou que `subscribe`), `methods` les actions de l'endpoint
-> (`RealtimeController.ts:710`) : un client peut activer ou griser
+> (`RealtimeController.ts#RealtimeController.onHandshake`) : un client peut activer ou griser
 > ses commandes sans rien coder en dur. Côté navigateur, ils se lisent en `socket.serverMethods` et
 > `socket.serverChannels`.
 
 Les quatre formes de frame circulent en permanence sous tes yeux — ce schéma les montre sur la
 
 > [!WARNING]
-> `nodefony:kernel:ping` et `nodefony:kernel:gc` (`StudioRealtimeController.ts:114`) sont des exemples d'actions,
+> `nodefony:kernel:ping` et `nodefony:kernel:gc` (`StudioRealtimeController.ts#StudioRealtimeController.realtimeActions`) sont des exemples d'actions,
 > **pas des méthodes du cœur temps réel** : elles sont déclarées par le contrôleur
 > d'administration de `@nodefony/studio`. Un endpoint applicatif ne les expose pas. Le helper
-> `RealtimeClient.ping()` (`RealtimeClient.ts:878`) mesure le RTT en les appelant — il suppose donc
+> `NodefonySocket.ping()` (`NodefonySocket.ts#NodefonySocket.ping`) mesure le RTT en les appelant — il suppose donc
 > un endpoint qui les déclare, contrairement à la notification `ping` du battement de cœur, qui
 > n'attend jamais de réponse.
 
 `subscribe` et `unsubscribe` ne sont **pas** des actions enregistrées : elles sont traitées dans
-`onRealtimeNotification()` (`RealtimeController.ts:784`). Envoyées avec un `id`, elles seraient
+`onRealtimeNotification()` (`RealtimeController.ts#RealtimeController.onRealtimeNotification`). Envoyées avec un `id`, elles seraient
 classées « requête », ne trouveraient aucun handler et récolteraient un `-32601`.
 
 ## Une conversation type, de bout en bout
@@ -397,52 +402,79 @@ 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:499`)       | requête vers une action non enregistrée             | `method not found: <nom>`                      |
-| `-32603` | même méthode (`JsonRpcPeer.ts:528`)                        | le handler a levé une exception **ordinaire**       | `internal error` — générique, rien d'autre     |
-| `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts:400`)         | `beforeDispatch` a dit non **sur une requête**      | `unauthorized`, sans jamais dire pourquoi      |
-| `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts:74`) | le handler expose volontairement son refus          | le message ET le `data` choisis par le handler |
-| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts:787`)  | `api.request` appelé avec un `params.path` invalide | message explicite (l'appel est malformé)       |
+| 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 |
+
+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`).
 
 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>`
-(`JsonRpcPeer.ts:428`). Défaut de 30 000 ms, réglable par appel. Aucun octet ne part sur le fil : c'est une décision du
+(`JsonRpcPeer.ts#JsonRpcPeer.startCall`). Défaut de 30 000 ms, réglable par appel. Aucun octet ne part sur le fil : c'est une décision du
 client, le serveur peut très bien répondre après, sa réponse sera ignorée.
 
+L'inverse n'attend pas : une frame qui porte l'`id` d'une requête en attente sans être une réponse
+valide — ni `result` ni `error` bien formé — fait échouer l'appel **aussitôt**, en `RpcError`
+`-32603` « réponse JSON-RPC invalide » (`JsonRpcPeer.ts#JsonRpcPeer.settleUnreadableResponse`). Si elle porte `result` ET une `error`
+bien formée (la norme l'interdit), l'erreur annoncée est rendue telle quelle. Rien ne part sur le
+fil : c'est un échec local, et la frame est auditée `invalid`.
+
 ### Les deux codes de la norme que Nodefony n'émet jamais
 
 `-32700 Parse error` et `-32600 Invalid Request` figurent dans la norme, mais **aucune frame ne les
 porte** ici :
 
 - un JSON illisible n'atteint même pas le pair — le contrôleur l'abandonne à la lecture
-  (`RealtimeController.ts:446`) ;
-- une frame lisible mais non conforme (pas d'objet, `jsonrpc` absent ou faux) est classée `invalid`,
-  signalée à l'audit, et **rien n'est renvoyé** (`JsonRpcPeer.ts:429`).
+  (`RealtimeController.ts#RealtimeController.onHandshake`) ;
+- une frame lisible mais non conforme — pas d'objet, un lot, `jsonrpc` absent ou faux, `id` `null`,
+  objet ou booléen, `method` non chaîne, réponse sans `result` ni `error` bien formé, ou avec les
+  deux — est classée `invalid`, signalée à l'audit, et **rien n'est renvoyé** (`JsonRpcPeer.ts#JsonRpcPeer.receive`).
 
 Le choix est délibéré : une frame cassée n'a pas d'`id` digne de confiance, donc pas de corrélation
 possible ; et répondre systématiquement à du bruit offre à un attaquant un amplificateur gratuit.
-Le refus reste **traçable** — c'est le motif `invalid` de `FrameAuditReason` (`JsonRpcPeer.ts:155`),
+Le refus reste **traçable** — c'est le motif `invalid` de `FrameAuditReason` (`JsonRpcPeer.ts#FrameAuditReason`),
 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:192`), mais leurs conséquences diffèrent
+aux notifications (`beforeDispatch`, `JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`), mais leurs conséquences diffèrent
 radicalement :
 
-| La frame refusée est… | Ce qui part                                                     | Pourquoi                                             |
-| --------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
-| une **requête**       | `-32001 "unauthorized"` (`JsonRpcPeer.ts:413`)                  | Un `id` existe : il y a un canal de réponse          |
-| une **notification**  | la notification `realtime:denied` (`RealtimeController.ts:496`) | Aucun `id` : sans elle, le client se croirait abonné |
+| La frame refusée est… | Ce qui part                                                                                | Pourquoi                                             |
+| --------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| une **requête**       | `-32001 "unauthorized"` (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                             | Un `id` existe : il y a un canal de réponse          |
+| une **notification**  | la notification `realtime:denied` (`RealtimeController.ts#RealtimeController.onHandshake`) | Aucun `id` : sans elle, le client se croirait abonné |
 
-`IRealtimeDenied` (`RealtimeEventMap.ts:269`) porte `channel` et `reason` — plus un `detail` optionnel, posé hors production seulement — et le motif
+`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:811`) et `unknown`
+`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()` (`RealtimeClient.ts:469`) branche un handler dessus.
+`onDenied()` (`NodefonySocket.ts#NodefonySocket.onDenied`) branche un handler dessus.
+
+### L'abonnement accepté s'acquitte
+
+Le pendant du refus : un `subscribe` ACCEPTÉ reçoit `realtime:subscribed { channel }`
+(`IRealtimeSubscribed`), y compris pour un canal que la connexion suivait déjà — sans quoi un
+`subscribe` réémis attendrait une réponse qui ne vient jamais. Un abonnement reçoit l'un OU
+l'autre, jamais les deux.
+
+**Garantie** : tout événement publié sur le canal APRÈS l'émission de l'acquittement est livré
+à la connexion. Le producteur s'attache AVANT : une première charge (un tick initial) peut arriver
+avant l'acquittement — « rien n'arrive avant » n'est pas promis. L'abonnement d'une connexion est
+local au pod, le backplane n'y prend aucune part : l'acquittement local suffit.
+
+Le welcome annonce la capacité (`subscriptionAcks: true`). Un client qui ne la voit pas — serveur
+antérieur — répute l'abonnement actif dès le rejeu, au lieu d'attendre pour toujours. Côté client,
+`whenSubscribed(canal)` se résout à l'acquittement et se rejette sur un refus du même canal ;
+`onSubscribed()` rappelle un écouteur à chaque acquittement.
 
 > [!CAUTION]
 > Un `-32403 Forbidden` circule dans d'anciennes notes. **Ce code n'existe pas** dans Nodefony, et il
@@ -461,7 +493,7 @@ en découlent :
    politique du canal ; la demande a exactement la même forme qu'un abonnement autorisé, seule la
    réponse diffère.
 3. **Le client ne pousse que là où c'est déclaré.** Un canal n'accepte d'entrée que si un handler
-   entrant existe pour ce nom (`RealtimeController.ts:608`) ; sinon la notification est ignorée en
+   entrant existe pour ce nom (`RealtimeController.ts#RealtimeController.onHandshake`) ; sinon la notification est ignorée en
    silence. Le défaut est fermé.
 
 Les mécanismes eux-mêmes — authenticator, verrou de frame, politique de canal, révocation — sont
@@ -469,19 +501,21 @@ 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:592`)               | L'émettre sans `id` — `socket.subscribe(canal)`                                   |
-| Le handler passé à `subscribe` n'est jamais appelé               | `RealtimeClient.subscribe()` prend **un seul** argument (`RealtimeClient.ts:532`)                               | `subscribe(canal)` **et** `on(canal, handler)`, deux gestes distincts             |
-| `request()` expire immédiatement, ou ignore le délai             | Signature **positionnelle** `(méthode, params, ms)` (`RealtimeClient.ts:727`) — 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` (`JsonRpcPeer.ts:371`)              | 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:396`)                                   | Lire le motif `invalid` côté serveur, pas la réponse                              |
-| L'exception du serveur n'arrive jamais au client                 | Zero Trust : tout throw ordinaire devient `-32603` générique (`JsonRpcPeer.ts:528`)                             | 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:151`)                                     | Écouter `realtime:denied` via `onDenied()` (`RealtimeClient.ts:471`)              |
-| `nodefony:kernel:ping` répond `-32601` sur mon endpoint          | L'action `nodefony:kernel:ping` est déclarée par `@nodefony/studio` (`StudioRealtimeController.ts:114`)         | 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:791`)                                       | Pour mesurer un RTT, utiliser une action RPC — `ping()` (`RealtimeClient.ts:878`) |
-| Une réponse reçue est ignorée sans message                       | Corrélation sur `id` **numériques** seulement (`JsonRpcPeer.ts:537`)                                            | 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     | 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à                                                                               |
 
 ## 🧪 Tests & couverture
 
@@ -491,7 +525,7 @@ carte de l'aperçu, régénérée depuis les résultats réels — jamais figés
 
 - **Le moteur, dans le cœur** (`src/nodefony/src/tests/`) : `JsonRpcPeer.test.ts` (classement des
   frames, corrélation, timeout, erreurs), `JsonRpcPeer.types.test.ts` (le contrat générique tient à
-  la compilation), et la famille `RealtimeClient*.test.ts` — dispatch, identité annoncée par
+  la compilation), et la famille `NodefonySocket*.test.ts` — dispatch, identité annoncée par
   l'accueil, transport, `ping`. Ces suites **ne sont pas comptées** dans la carte du module
   `@nodefony/realtime` : elles appartiennent au workspace `nodefony`.
 - **Le câblage serveur, dans ce module** : `RealtimeController.test.ts` couvre les réponses
@@ -508,7 +542,7 @@ Couverture : `npm run coverage` dans `@nodefony/realtime` et dans le workspace `
 > [!CAUTION]
 > Plusieurs suites bout en bout exigent une infrastructure. **Un test sauté compte comme vert** :
 > avant de conclure « tout passe », vérifier les variables d'environnement — la source unique est
-> `vitest.gates.ts` à la racine, dont le rapport s'affiche en fin d'exécution.
+> `scripts/test/vitest/gates.ts` à la racine, dont le rapport s'affiche en fin d'exécution.
 
 ## 🔗 Pour aller plus loin