---
title: "Socket temps réel — un canal, une enveloppe, un contrat pour les deux bouts"
source: docs/adr/0022-socket-temps-reel.md
url: https://nodefony.net/docs/adr/0022-socket-temps-reel/
---



> **Summary.** Nodefony's real-time socket serves chats, dashboards, games, sensors and agents
> through one JSON-RPC 2.0 peer shared by browser and server, and its protocol had to be settled
> before the 10.0 wire format froze. This ADR fixes what could not change later: the unit is the
> _channel_ (a named stream with a shared producer), there is a single JSON-RPC 2.0 envelope, and
> codecs are only its serialization, negotiated once per connection — JSON text
> (`nodefony.jsonrpc.v1`) by default, binary CBOR (RFC 8949, `nodefony.jsonrpc.cbor.v1`) as an
> opt-in, announced in the welcome frame. Whatever the codec, an application receives what JSON
> would deliver, with `Uint8Array` bytes kept intact, so a JSON client and a CBOR client on the
> same channel see the same data. One type-only contract, declared once, types both ends, and
> private channels, backpressure and resume are specified so that later additions stay
> non-breaking.

Le **comment** — grammaire des trames, négociation du codec, reconnexion — se lit dans le guide
[Protocole de la socket](../../modules/realtime/protocole/) et, pour le
binaire, dans [Codec CBOR](../../modules/core/cbor/) ; cet ADR porte le **pourquoi**.

## Statut

**Accepté** le 2026-10-29. Les §1 à §5 ont été validés décision par décision ; les §6 à §10, tous
« rupture si différé : NON », sont acceptés en bloc, après une revue d'architecture qui a jugé les
trois ADR du temps réel sans les contester (catalogue `scenarios/temps-reel.md`). Ce qui viendrait
les contredire s'ajoute en 10.x, sans rupture.

Les mentions « ouvert », « reste », « à prouver » décrivent l'état à la date de la décision ; le code
livré en 10.0 les a soldées (voir les guides).

- **Amendé le 2026-10-30** par la revue du gel : le même moule type socket, SSE et webhook (§4), et
  la décision 1 du §6 est tranchée sur la forme d'`allow` et son délai.
- **Précisé le 2026-11-09** (§6, décision 1 quater) : une politique de lecture et une politique
  d'écriture par nom de canal.
- **Précisé le 2026-11-11** par [ADR-0026](../0026-service-grpc-declare-par-un-module/) (D12) : le
  codec protobuf de la socket n'arrive pas avec le chantier gRPC (§2, lignes datées).
- **Précisé** par [ADR-0025](../0025-presence-repartie-d-un-canal/) (P1) : la présence d'un canal,
  d'abord laissée à l'application (§6), est portée par le framework.

Ce document porte sur la **socket**. Le socle commun aux livraisons est
[ADR-0021](../0021-temps-reel-evenement-et-livraisons/), dont les décisions S1 à S9 font foi ici ;
les webhooks sont [ADR-0023](https://github.com/nodefony/nodefony-core/blob/main/docs/adr/0023-webhooks-evenements-et-abonnements.md). Les huit décisions de gel
du protocole sont **déjà prises** (commit `1df6614c1`) : reprises, jamais rediscutées. Le média
(capture, codec audio) relève d'un ADR à part : rien ici ne le recouvre.

## Contexte

La socket de Nodefony est un pair JSON-RPC 2.0 **partagé** entre navigateur et serveur
(`src/nodefony/src/realtime/JsonRpcPeer.ts#JsonRpcPeer`), des canaux servis par un hub
(`src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub`) et un client
dans le cœur (`src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket`). Elle sert une
discussion, un tableau de bord, un jeu, un éditeur partagé, des capteurs, des notifications, un
flux de média, et des agents — sans être taillée pour aucun. Chaque décision ci-dessous porte
trois usages hétérogènes, dont un sans agent ni IA et un sans média (règle des trois usages, ADR-0021).

Cinq évolutions touchent son protocole dans le même jalon : binaire routé, admission par
identité, abonnés identifiables, transcription, voix. Après 10.0, un
changement de ce qu'une application reçoit est une rupture même à types identiques
([politique de compatibilité](../../guides/compatibilite/)). Ce document décide ce qui fermerait
une porte s'il était décidé plus tard, et laisse additif tout le reste.

**Constaté au code** (lecture seule, aucun test lancé) : octets en `Uint8Array` des deux côtés
(`src/nodefony/src/realtime/IRealtimeTransport.ts#RealtimeFrameData`), `request` hors du contrat
commun (`src/nodefony/src/realtime/IRealtimeSocket.ts#IRealtimeSocket`), code partagé compilé sans
Node ni DOM (`src/nodefony/tsconfig.shared.json`). Aucun sous-protocole annoncé
(`src/nodefony/src/client/realtime/BrowserWsTransport.ts#BrowserWsTransport.connect`), aucun
codec branché sur le pair, aucune notification `realtime:closed`, aucun curseur d'abonnement.

## Décision

### 1. Le canal, pas la room

**Décision (validée le 2026-10-28) :** l'unité de la socket est le **canal** : un flux nommé dont le producteur
est **partagé**, démarré au premier abonné et libéré au dernier
(`src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.subscribe`).
Une _room_ — une liste de diffusion tenue par le serveur, qui ne sait rien de ce qui produit —
s'obtient en ajoutant au canal une admission par identité (un prédicat) et un abonnement
décidé par le serveur. L'inverse ne se construit pas : une liste de diffusion n'a pas de
producteur. L'événement reste `(canal, charge)` nue (S1), sans identifiant du socle (S2), sans
propriétaire (S7).

- Usages : un tableau de bord (un producteur, N lecteurs), une partie de jeu (producteur partagé
  et membres), un flux de capteur (un producteur, aucun membre).
- Écarté : la room comme primitive ; un producteur par connexion (un seul usage connu, quand la règle en demande trois).
- **Rupture si différé après 10.0 : NON**, parce que l'admission par identité et les abonnés identifiables n'ajoutent qu'un membre
  optionnel et des notifications neuves (décisions de gel 5 et 8).

### 2. L'enveloppe JSON-RPC 2.0 et ses codecs

**Décision (validée le 2026-10-29, en deux temps : le principe, puis le calendrier des codecs) :** une seule enveloppe, JSON-RPC 2.0, et des **codecs** qui n'en sont que la
sérialisation, choisie une fois par connexion. Repris des décisions de gel : sans sous-protocole, le format est
celui d'aujourd'hui — JSON-RPC texte, nommé **`v1`** — pour toute la série 10 (décision 1) ; le
codec effectif se lit dans `realtime:welcome` par un champ optionnel (absent = texte), **jamais**
dans l'écho du handshake, et le défaut d'écho de `ws` ne change pas en 10.x (décision 2). Ajouté :

- **`IFrameCodec`** dans le code partagé : `encode(frame): string | Uint8Array`,
  `decode(data: string | Uint8Array): unknown`, un `protocol`. Par frame il remplace
  `JSON.stringify` / `JSON.parse` : aucun appel de plus ; le codec JSON **est** ces deux appels
  natifs. Un codec n'est éligible que s'il compile sous `tsconfig.shared.json` — ni `Buffer`, ni
  DOM — et borne longueur et profondeur d'une trame hostile (RFC 8949 §10).
- **Trois noms versionnés** : `nodefony.jsonrpc.v1`, `nodefony.jsonrpc.cbor.v1` (RFC 8949),
  `nodefony.jsonrpc.protobuf.v1`. Le client les offre (RFC 6455 §1.9), le serveur lit la liste
  au handshake (`src/packages/@nodefony/realtime/nodefony/interfaces/IRealtimeHandshake.ts#IRealtimeHandshake`)
  et annonce son choix dans l'accueil. Une enveloppe qui change = `v2` ajouté, `v1` gardé.
- **L'accueil est toujours une trame texte `v1`**, qui porte le codec choisi ; les frames
  suivantes l'emploient. Un serveur sans le branchement du codec n'émet pas ce champ, un client
  qui l'a reste donc en texte : le déploiement progressif tient malgré l'écho de `ws`, qui renvoie le premier
  sous-protocole offert (constaté sur `ws` 8.22, la version qu'installe `@nodefony/http` — le
  cœur ne l'a qu'en dépendance de développement).
- **Protobuf** : une enveloppe `.proto` **fixe** fournie par Nodefony (`id`, `method`, `error`,
  `params: bytes`, `result: bytes`) ; la charge est encodée par le message que le contrat
  déclare pour **cette** méthode ; sans schéma, la charge passe en CBOR dans les `bytes`.
  Bibliothèque : `@bufbuild/protobuf`, la seule que le framework aurait si le chantier gRPC (ADR-0026)
  aboutit. Elle n'est aujourd'hui dans l'arbre que par le module de test et l'outillage de build
  (`npm ls @bufbuild/protobuf`) : aucun paquet publié ne l'installe, l'ajouter serait une
  dépendance neuve pour chaque application.
- **Calendrier.** Les trois noms sont réservés dès 10.0. **Activation (revue du
  2026-10-29, une fois le codec CBOR écrit au cœur — remplace « optionnel, chargé par la seule
  application qui l'active », dont le motif était d'éviter une dépendance npm, disparue) :** CBOR
  s'active **par la configuration seule, sans paquet à installer**, et son code ne pèse que là où
  il est activé — rien dans le bundle d'une application qui ne l'active pas
  (`.size-budgets.json`). Côté navigateur : l'option `codec` de `NodefonySocket`, avec
  `CBOR_FRAME_CODEC` importé de `nodefony/cbor` (seul sous-chemin qui le contient). Côté serveur :
  une clé de la configuration du module temps réel, posée par le lot serveur du binaire routé, qui charge
  le codec au démarrage. Le paquet de base (`nodefony`, `nodefony/client`) ne contient que le
  codec JSON. Les codecs vivent dans le pair PARTAGÉ (`JsonRpcPeer`, §4 ligne (i)). Le codec
  **CBOR** est écrit, au cœur (`src/nodefony/src/realtime/codec/`, sous-chemin `nodefony/cbor`,
  hors de `nodefony` et de `nodefony/client`) ; son branchement — `IFrameCodec`, offre du
  sous-protocole par le client, choix annoncé dans l'accueil — revient au lot du binaire routé,
  **visé pour la publication de 10.0** : le binaire temps réel est la capacité stratégique du
  framework (décision du 2026-10-30), et ce lot ne se reporte pas pour tenir le
  calendrier. Il passe après le contrat typé (§4), qui le type, et les travaux qui fermeraient une porte gardent
  la priorité d'ordre ; s'il glissait malgré tout, rien ne casse — un serveur sans branchement
  n'émet pas le champ de codec. **Protobuf** n'arrive qu'avec le chantier gRPC :
  un seul usage connu d'ici là (règle des trois usages), et une dépendance que gRPC rendra de toute
  façon nécessaire ; son enveloppe ci-dessus est une intention, pas un engagement.
  _Précisé le 2026-11-11 par ADR-0026 (D12) : le chantier gRPC n'amène protobuf qu'en pair FACULTATIF
  de `@nodefony/http` et `@nodefony/framework`, jamais au cœur ni dans `nodefony/client`. Le
  codec protobuf de la socket n'en découle donc pas : il attend un usage à lui._
- **JSON est la référence de tous les codecs** (remplace la règle « refus à l'encodage »,
  décision du 2026-10-29, après le banc) : quel que soit le codec, on reçoit **ce que
  `JSON.stringify` puis `JSON.parse` rendraient** — une `Date` devient sa chaîne ISO, `NaN` devient
  `null`, `Map`/`Set` deviennent `{}`. Seule exception, les octets : un `Uint8Array` reste un
  `Uint8Array` (S8 ; base64 sous convention dans le codec JSON). Ainsi une connexion se rejoue en
  texte sans qu'une ligne métier bouge, et un client CBOR et un client JSON abonnés au même canal
  reçoivent la même chose — le relais entre exemplaires, en JSON (S6), l'imposait déjà.
  - **Les autres conteneurs d'octets sont REFUSÉS** : un tableau
    typé autre que `Uint8Array`, une `DataView` ou un `ArrayBuffer` partirait en `{"0":…}` ou en
    `{}` — contenu perdu sans un mot. Le codec CBOR et le codec JSON à octets lèvent à l'émission,
    avec un message qui nomme le geste (`codec/binaryView.ts#unsupportedBinaryMessage`, règle
    unique) ; côté serveur la trame n'est pas livrée et le pair le journalise une fois. Aucun
    format neuf : le profil reste « JSON + octets ». Le codec JSON par défaut, qui ne parcourt
    rien, reste tel que `JSON.stringify` le rend — comme pour un `Uint8Array`. **Normes et
    antériorités** : la RFC 8746 définit des étiquettes CBOR pour les tableaux typés (64 à 87) ;
    les transporter étendrait le profil gelé — amendement à écrire s'il est demandé, pas un
    correctif.
  - **Le type le montre** : le contrat type la valeur REÇUE par un `Jsonify<T>` (à écrire, absent
    du dépôt) — `debut: Date` à l'émission devient `debut: string` à la réception, visible dans
    l'éditeur, sans coût d'exécution. C'est la forme courante des bibliothèques d'appel
    typé de bout en bout : le type reçu est celui que JSON rend.
  - **Chaque codec est aligné et le prouve** : un test par codec rend, pour chaque valeur du banc
    (`NaN`, `Infinity`, `undefined` en tableau, `Date`, `Map`, `Set`, `-0`, `bigint`), exactement ce
    que rend JSON — `bigint` compris, que JSON refuse. Protobuf suit sa correspondance JSON
    canonique.
  - **Le développement prévient** : une valeur que JSON transforme (`Date`, `NaN`, `Map`…) donne un
    avertissement UNE fois par méthode ou canal — presque toujours un oubli. Rien en production.
  - Écarté : **tout refuser** (un parcours par message, et une rupture pour les applications qui
    publient une `Date` aujourd'hui) ; **tout transporter** par un JSON enrichi (format maison que ni
    un client d'un autre langage ni le relais ne lisent). Précédent du modèle commun : les
    routeurs de messagerie qui traduisent entre clients JSON, CBOR et MessagePack.
- **Les octets dans le codec JSON — activés, jamais payés par défaut.** **Décision (validée le 2026-10-31, après la mesure du §9) :** la convention déclarée est
  `{"$bytes":"<base64url sans bourrage>"}` (alphabet RFC 4648 §5, celui de la conversion CBOR → JSON
  de RFC 8949 §6.1), réanimée en `Uint8Array` à la réception ; le marqueur doit être SEUL dans son
  objet, sinon l'objet reste applicatif. Émettre la convention exige de DÉTECTER les octets, donc un
  parcours de la charge : mesuré **+27 %** (charge minuscule) à **+35 %** (sonde de console) sur
  `notify`, **+20 %** sur `inbound`
  (`.claude/skills/nodefony-load-test/scripts/micro/micro-realtime-frame-ab.mjs`, 2 × 15 runs, deux
  passages de même signe). Le parcours n'est donc armé **que si l'application active un codec
  binaire** côté serveur (l'activation qu'exige déjà le calendrier ci-dessus). Sans activation, le
  codec JSON reste les deux appels natifs — « aucun appel de plus » tient — et des octets imbriqués
  y arrivent déformés comme avant le binaire routé, l'application prévenue une fois. Code :
  `src/nodefony/src/realtime/jsonFrameCodec.ts`, gardé par `src/nodefony/src/tests/jsonFrameCodec.test.ts`.
  - Écarté : **parcours toujours armé** (chaque application paierait ~30 % par trame texte pour un
    service que la plupart n'emploient pas) ; **codec JSON sans convention** (contredit la décision
    du 2026-10-29 : le client texte rend un `Uint8Array`).
  - **Un marqueur FORGÉ est refusé à l'émission (validé le 2026-11-01).** Un objet
    applicatif qui a la forme exacte du marqueur (seule clé, valeur chaîne) sans venir d'octets —
    carte texte envoyée par un client CBOR, `params` relayés tels quels par l'application — serait
    relu en octets par un abonné texte, ou ferait jeter la trame entière si sa chaîne n'est pas du
    base64url, pendant qu'un abonné CBOR recevrait l'objet. Le codec à convention lève donc sur cet
    objet, en nommant sa clé et sans recopier la valeur ; la diffusion mutualisée laisse UN abonné
    dire l'échec (`src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#ChannelFrame.claimFailure`),
    jamais une ligne de journal et un encodage par abonné. Coût sur le chemin normal : un
    `includes` sur le texte produit, motif `$bytes` SANS guillemets (avec, V8 bascule sur une
    recherche à table reconstruite à chaque appel) — mesuré +12 % à l'encodage d'une trame de
    80 octets, +0,5 % à 11 Ko, et −19 % / −6 % au décodage, qui portait le motif à guillemets.
    Gardé par `src/nodefony/src/tests/jsonFrameCodec.test.ts` et
    `src/packages/@nodefony/realtime/nodefony/tests/integration/realtimeCodec.e2e.test.ts`.
    - Écarté : **échapper** l'objet sous une clé dédiée (`{"$escape": …}`) — fidèle, mais un
      second marqueur sur un fil gelé, et incompatible avec le reviver de `JSON.parse`, qui
      travaille des feuilles vers la racine.
- **Trois précisions de câblage (validées le 2026-11-01) :**
  - le champ de `realtime:welcome` qui porte le codec retenu s'appelle **`codec`**, et sa valeur
    est exactement `IFrameCodec.protocol` (`src/nodefony/src/realtime/frameCodecNegotiation.ts#adoptFrameCodec`) ;
    absent, la connexion reste en texte ;
  - le serveur **renvoie dans le handshake le sous-protocole qu'il a CHOISI** (RFC 6455 §4.2.2 :
    « the subprotocol the server is ready to use »), jamais le premier offert — défaut de `ws`
    8.22 sans `handleProtocols` (`protocols.values().next().value`), qui ferait dire à
    `socket.protocol` du navigateur `nodefony.jsonrpc.cbor.v1` sur une connexion restée en
    texte. Additif : le client lit toujours le codec dans l'accueil, jamais dans cet écho ;
  - sous codec **binaire**, toute trame binaire est une frame du codec : le flux brut
    (`NodefonySocket.onBinary`/`sendBinary`, `RealtimeController.onRealtimeBinary`) est refusé
    avec une notice et ne sert que les connexions texte. Des octets passent par les canaux, qui
    ont les portes B1 à B4 (§3).
- **Le client texte prend la convention sur ANNONCE du serveur (validé le
  2026-11-01).** Un serveur qui a activé un codec binaire émet `$bytes` sur ses connexions
  texte ; il le dit dans `realtime:welcome` par le champ **`bytes`** (valeur
  `IFrameCodec.bytesMarker`, `"$bytes"` ; la valeur nomme la convention, une autre serait
  ignorée par le client actuel), et le client passe alors au JSON à convention sans
  avoir rien importé (`src/nodefony/src/realtime/frameCodecNegotiation.ts#adoptFrameCodec`). Un
  codec texte choisi par l'application est gardé ; un marqueur inconnu laisse le JSON natif.
  Coût : le codec à convention et le base64url entrent dans le paquet client, mesuré
  **+0,57 Ko gzip** (esbuild minifié) ; aucun coût par trame tant que le serveur n'annonce rien.
  - Écarté : **réanimer `$bytes` par défaut au décodage** — sur le fil d'un serveur sans codec,
    un objet applicatif `{"$bytes": …}` deviendrait des octets, ou ferait jeter la trame entière
    si sa chaîne n'est pas du base64url (preuve :
    `src/nodefony/src/tests/jsonFrameCodec.test.ts`, « réanimer par défaut altérerait le fil ») ;
    **exporter le codec à convention et laisser la page l'importer** — sûr, mais le serveur sait
    ce que la page devrait deviner.
- **Débogage par décodage à l'observation**, jamais en changeant le fil : le traceur WS
  (`src/packages/@nodefony/http/nodefony/src/context/websocket/wsLogContent.ts#formatWsLogContent`),
  Studio et la barre de debug affichent une trame binaire décodée ; coût nul en production, où
  le traceur est fermé. Un interrupteur de développement force `nodefony.jsonrpc.v1` pour lire le
  fil brut dans le navigateur — une exception, pas la voie normale, car passer en texte change
  les conditions (taille, contre-pression).

- Usages : une discussion (JSON, lisible), un document partagé (CBOR, octets sans base64), un
  jeu à état figé (protobuf, un schéma par message).
- Écarté : MessagePack au socle (pas une norme IETF ; enfichable si un écosystème le réclame) ;
  BSON (stockage) ; un schéma obligatoire pour l'enveloppe ; un décodeur CBOR maison avant le
  banc. Le choix est sorti d'un banc contre `JSON.parse` natif (fait, ci-dessous) — et aucune
  bibliothèque ne l'a passé : le codec retenu est le NÔTRE (« Retenu » ci-dessous). Le banc a mesuré octets, µs par frame,
  poids dans `.size-budgets.json` — sur des critères écrits d'avance : objets ordinaires sans
  conversion par frame, aucun `Buffer` (le client est un navigateur), aucun module natif
  obligatoire (Windows), CBOR standard sans extension propriétaire (un pair d'un autre langage
  doit pouvoir lire), alignement sur la référence JSON. Candidats : `cbor-x`, `cborg`, et
  `@levischuck/tiny-cbor` en référence seulement — installé par `@nodefony/security`
  (`@simplewebauthn/server`), mais il ne rend que des `Map`, jamais un objet ordinaire, ce qui
  coûterait une conversion par frame. Une richesse de types (`Date`, `Set`, `bigint`) n'est pas
  un critère : la référence JSON ci-dessus la ramène à ce que JSON rend.
- **Banc fait (2026-10-29)** — Node 26.13, macOS x64, médiane de 5 ; 14 types (entiers, flottants,
  booléens, textes ASCII/unicode/8 Ko, tableaux, imbrications, binaire de 64 o à 1 Mo) et 9
  valeurs hors modèle. L'accélérateur C++ `cbor-extract` de `cbor-x` (vérifié actif) n'apporte
  rien, parfois moins (texte 8 Ko décodé 4,0 µs contre 2,6 µs). Sur un message ordinaire, JSON
  encode 2 à 4 fois plus vite que CBOR, qui gagne 30 à 45 % d'octets : **CBOR ne devient jamais
  le défaut**. Sur le binaire, CBOR décode une vue sans copie : 64 Ko en 1,2 µs contre 91 µs en
  JSON base64, 1 Mo en 1,2 µs contre 1,97 ms. Le banc a aussi révélé que le codec JSON transforme
  (`NaN` → `null`, `Date` → chaîne, `Map`/`Set` → `{}`) quand `cbor-x` garde tout : d'où la
  référence JSON ci-dessus.
- **Retenu : un codec CBOR propre à Nodefony** (décision du 2026-10-29), dans le code
  partagé `src/nodefony/src/realtime/codec/` — isomorphe, sans dépendance, sans `eval`. Aucune
  bibliothèque ne tenait les deux exigences à la fois :
  - `cbor-x` (la plus rapide) ne peut pas s'aligner sur JSON sans parcourir chaque message (aucun
    crochet sur les nombres ; une extension pour `Date` vaut pour tout le process), appelle
    `new Function('')` au chargement (violation sous notre CSP), et tire un module natif
    optionnel à script d'installation ;
  - `cborg` (stricte, alignable par ses `typeEncoders`) encode 4 à 5 fois plus lentement et copie
    chaque chaîne d'octets (1 Mo décodé en 545 µs contre 1,6 µs).

  Le prototype mesuré : **encodeur** qui suit l'algorithme de `JSON.stringify` (ECMA-262
  `SerializeJSONProperty`), donc aligné par construction (13/13 valeurs piégées), au niveau de
  `cbor-x` à l'encodage (50 objets : 51 µs contre 53 µs ; `cborg` 225 µs) ; **décodeur restreint au
  modèle** (JSON + octets ; étiquettes refusées), 10/10 messages hostiles refusés proprement,
  binaire en vue sans copie, à 1,2-1,5 fois de `cbor-x` sur les objets, 2 à 340 fois plus rapide
  que `cborg`. Exigences du codec livré : conformité RFC 8949 (sérialisation préférée §4.1,
  flottants au plus court, longueurs indéfinies acceptées au décodage, clés en double et UTF-8
  invalide refusés, bornes §10), vecteurs des appendices A et F en tests, chaque garde vue rouge.
  Témoins du banc (`micro-cbor-codec.mjs`) : `cbor-x` et `cborg`, références de mesure, jamais des
  dépendances.
  Ces deux bibliothèques ne sont que des références de banc (`micro-cbor-codec.mjs`), jamais des
  dépendances.

- **Rupture si différé après 10.0 : NON**, parce que les décisions de gel 1 et 2 rendent tout
  codec additif. Ce qui serait une rupture, et qui est écrit : le nom `v1` et la lecture du codec
  dans l'accueil — un format renommé ou un codec déduit de l'écho changerait le fil d'un client
  déjà déployé.

### 3. Le binaire, routé par canal, par les mêmes portes que le texte

**Décision (validée le 2026-10-29) :** une trame binaire routée **n'est pas une seconde grammaire** : c'est une
notification JSON-RPC dont la charge est, ou contient, un `Uint8Array` (S8), et le codec dit
comment il la porte — chaîne d'octets native en CBOR (type majeur 2), `bytes` en protobuf, base64
sous une convention déclarée pour le codec JSON. Elle passe donc par **les mêmes portes** que le
texte, sans seconde implémentation : verrou de trame
(`src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.runAuthorizer`,
B1), politique de canal (`#RealtimeHub.probeChannel`, `#RealtimeHub.subscribeClient`, B2), audit
des refus (B3), sonde (`#RealtimeHub.recordInbound`, B4 — membres optionnels, décision de gel 8,
vocabulaire S9). Le crochet brut
`src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.onRealtimeBinary`
reste hors du verrou pour toute la série, identité par `RequestContext` (décision de gel 3) :
il sert un protocole binaire écrit par l'application, sans canal.

- Usages : un capteur qui pousse des mesures compactées, un document partagé qui diffuse ses
  deltas binaires, la voix.
- Écarté : une trame binaire à en-tête maison sous le codec texte — une seconde grammaire, donc
  un second verrou et une seconde sonde, qui divergent en silence.
- Constaté au code : contre-pression sortante et `maxPayload` couvrent déjà le binaire
  (`src/packages/@nodefony/realtime/nodefony/src/transport/WsConnectionTransport.ts#WsConnectionTransport.sendBinary`,
  `src/packages/@nodefony/http/nodefony/config/config.ts#websocketSchema`) ; B1 à B4 sont
  contournés parce que le binaire va droit au crochet (`#RealtimeController.receiveBinary`). À
  prouver avec le binaire routé : chaque porte vue rouge en la débranchant ; un `Uint8Array` intact par le
  pilote Redis, supposé corrompu (S8).
- **Rupture si différé après 10.0 : NON**, parce que le chemin routé n'existe pas encore et que
  le crochet brut est gelé par la décision de gel 3.

### 4. L'isomorphisme — le transport l'est, le contrat doit l'être

**Décision (validée le 2026-10-29) :** fermer les cinq trous d'isomorphisme relevés au cadrage, dont deux
le sont déjà.

| Trou                                 | État constaté                                                                                                                                                                                                                                                 | Geste                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| (i) binaire asymétrique              | **fermé** (gel) : `Uint8Array` des deux côtés, vue sans copie                                                                                                                                                                                                 | binaire routé : routage et codecs dans le pair **partagé**, jamais dans `RealtimeController` ni `NodefonySocket` |
| (ii) `request` promis sans être tenu | **fermé** (gel) : hors d'`IRealtimeSocket` ; `src/packages/@nodefony/realtime/nodefony/src/server/ServerRealtimeSocket.ts#ServerRealtimeSocket.request` reste, `@deprecated`, retrait à la majeure suivante                                                   | rien                                                                                                             |
| (iii) réception serveur non typée    | ouvert : `src/packages/@nodefony/realtime/nodefony/interfaces/IRealtimeController.ts#RealtimeInboundHandler` prend `params: unknown` ; `RealtimeController<Emit, Actions>` sans `Listen`                                                                      | contrat typé                                                                                                     |
| (iv) actions non vérifiées           | ouvert : `#RealtimeController.realtimeActions` rend `Record<string, RpcActionHandler>`, `#RealtimeController.realtimeChannels` rend `string[]`, `src/packages/@nodefony/realtime/nodefony/decorators/realtimeDecorators.ts#RealtimeAction` prend un nom libre | contrat typé, surface **opt-in** (décision de gel 6)                                                             |
| (v) inversion Emit/Listen à la main  | ouvert : la convention vit en commentaire (`src/nodefony/src/realtime/RealtimeEventMap.ts#EventsMap`)                                                                                                                                                         | contrat typé                                                                                                     |

**Forme du contrat unique.** Contraintes : coût d'exécution nul (génériques effacés, JS bâti
identique) ; un générique ne s'ajoute qu'**en fin** et **avec défaut** (décision de gel 6) ;
`NodefonySocket<Emit, Listen, Actions>`, `ServerRealtimeSocket<Emit, Listen, Actions>` et
`RealtimeController<Emit, Actions>` gardent leur ordre. Les deux options, vues de l'application.

**Option A — troisième générique `Listen` et types utilitaires.** Chaque côté dérive ses trois
cartes d'un contrat par des types nommés qui portent la direction.

```ts
interface ChatContract extends IRealtimeContract {
  // déclaré une fois, code partagé
  serverToClient: { "chat:room": { from: string; text: string } };
  clientToServer: { "chat:typing": { on: boolean } };
  serverMethods: { "chat:send": { in: { text: string }; out: { id: string } } };
}
// navigateur
const socket = new NodefonySocket<
  ClientEmit<ChatContract>,
  ClientListen<ChatContract>,
  ContractActions<ChatContract>
>({ url });
// serveur — `Listen` ajouté en 3ᵉ, défaut `DefaultEventsMap`
class ChatRt extends RealtimeController<
  ServerEmit<ChatContract>,
  ContractActions<ChatContract>,
  ServerListen<ChatContract>
> {
  @RealtimeAction("chat:send") send(p: { text: string }): { id: string } {
    /* … */
  }
}
```

Ferme (iii). Ne ferme (iv) que si le décorateur connaît le contrat, ce qu'un `MethodDecorator`
ne peut pas : il ne voit pas les génériques de la classe. Ne ferme pas (v) : la direction est
encore écrite par l'application, à chaque site, dans le bon ordre.

**Option B — générique de contrat, par une fabrique.** Le contrat est déclaré une fois ; une
fabrique en dérive les deux classes **et** les décorateurs. La direction vit dans la fabrique.

```ts
const chat = defineRealtimeContract<ChatContract>(); // une allocation, au chargement
// navigateur
const socket = new chat.Socket({ url }); // NodefonySocket<ClientEmit, ClientListen, Actions>
socket.on("chat:room", (m) => m.text); // typé
// serveur
class ChatRt extends chat.Controller {
  // RealtimeController<ServerEmit, Actions, ServerListen>
  @chat.RealtimeAction("chat:send") // nom contraint, signature vérifiée
  send(p: { text: string }): { id: string } {
    /* … */
  }
  protected override realtimeInbound() {
    // clés et params contraints par clientToServer
    return {
      "chat:typing": (p, reply) => {
        /* p: { on: boolean } */
      },
    };
  }
}
```

Deux autres formes d'un générique de contrat sont écartées : un quatrième générique positionnel
(il obligerait à écrire les trois défauts devant lui) et une surcharge du **premier** générique
par un type conditionnel (elle réécrit toutes les signatures publiées, et un contrat passé sans
marque serait lu comme une carte de trois canaux).

**Décision (validée le 2026-10-29) : le moule du contrat.** Le framework livre un
moule générique, `IRealtimeContract`, et ne déclare aucun contrat métier : chaque application
écrit le sien (`ChatContract` ci-dessus n'est qu'un exemple d'application), une fois, dans un
fichier partagé par ses deux côtés. Le moule a quatre clés, toutes facultatives (un tableau de
bord ne déclare que `serverToClient`) :

```ts
interface IRealtimeContract {
  serverToClient?: EventsMap; // événements poussés par le serveur
  clientToServer?: EventsMap; // événements envoyés par le client
  serverMethods?: ActionsMap; // méthodes du serveur : le client appelle, le serveur répond
  clientMethods?: ActionsMap; // méthodes du client : le serveur appelle, le client répond
}
```

- **Deux clés de méthodes, pas une.** Les appels circulent dans les deux sens :
  `src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.request` (le serveur répond)
  et `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.requestClient`
  (le client répond, par `#NodefonySocket.register`). Aujourd'hui le client range les deux sous le
  MÊME générique `Actions` ; une clé unique `actions` aurait reconduit ce mélange.
- **« Méthode », pas « action ».** Une méthode appartient à qui l'implémente — une seule lecture
  possible, quand `serverActions` se lit « ce que le serveur demande » OU « ce qu'il offre ». C'est
  le vocabulaire déjà publié : `src/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeWelcome`
  (`methods`), `#NodefonySocket.serverMethods`, et la norme JSON-RPC 2.0 (`method`). Le mot
  « action » reste dans l'API publiée (`@RealtimeAction`, `ActionsMap`, `realtimeActions()`), non
  renommée : la doc pose « une action est une méthode JSON-RPC exposée par le serveur ».
- **« Client », pas « navigateur »** : `NodefonySocket` tourne aussi dans un script ou un serveur.
- **Hors du contrat** : ce que le framework possède déjà — l'identité et le welcome, le message
  entre serveurs (§2).
- **À éprouver au code** : les canaux à motif (`` `user:${string}` ``) comme clés ; la lecture de
  `#RemoveIndexSignature` dit qu'ils passent, aucun test ne le prouve encore.
- Formes voisines constatées ailleurs : deux cartes d'événements nommées par direction (forme
  courante des sockets typées), canaux à opérations `send` / `receive` (AsyncAPI). Ce qui
  distingue ce moule : la direction est **calculée** d'une déclaration unique, jamais réécrite.

**Décision (validée le 2026-10-30, revue du gel) : le MÊME moule type les trois
livraisons.** `serverToClient` type aussi le flux SSE d'un canal et l'émission d'un webhook : une
application écrit un contrat, et ses trois livraisons le lisent. Aucune carte par livraison
(`sse?`, `webhooks?`) : elle réécrirait ce que S1 d'ADR-0021 pose déjà, un événement
`(canal, charge)` pour toutes.

- **Webhook** : `type` = le canal. Aucun champ n'est ajouté au corps figé `{ id, timestamp, type,
data }` (ADR-0023 W1, S-rt-22).
- **Flux SSE** : un flux d'un contrat dit lequel il est — **multiplexé** (`event:` = le canal,
  plusieurs canaux sur une connexion) ou **un flux = un canal** (`event:` absent). Les deux
  formes se lisent sur la même carte.
- **Flux hors contrat** : `renderSse()` sans paramètre de type reste valide et le reste toute la
  série. La porte MCP écrit du JSON-RPC brut en `data:`, sans canal
  (`src/packages/@nodefony/ai/nodefony/mcp/gate.ts`, S-rt-66) : ce n'est pas un canal, et rien ne
  l'oblige à le devenir.
- **Le type n'est pas une validation.** La garde de canal (politique, `allow`) s'applique aux
  trois livraisons ; un type ne protège rien à l'exécution.
- Le code suit en 10.x par génériques à défaut
  (`src/packages/@nodefony/framework/nodefony/src/Controller.ts#Controller.renderSse`,
  `src/packages/@nodefony/http/nodefony/src/context/http/SseStream.ts`) : ajouter un générique AVEC
  défaut ne casse rien. Seule la forme se fige ici.
- Usages : une mesure de capteur typée une fois, lue par la socket du tableau de bord, le flux
  SSE d'un écran et le webhook d'alerte vers le SI ; une commande typée une fois, poussée à
  l'écran et au SI ; une tâche d'agent typée une fois, suivie sur la socket et notifiée en
  webhook A2A.
- **Rupture si différé : OUI pour la forme du moule** : une carte par livraison ajoutée
  après 10.0 changerait le moule que les applications ont écrit. **NON pour le reste** :
  générique en fin, avec défaut.

**Décision (validée le 2026-10-29) : un contrat fait de types, une porte par côté.**
L'exemple de l'option B ci-dessous sort `chat.Socket` et `chat.Controller` d'un MÊME objet : le
fichier partagé importerait alors `@nodefony/realtime`, et le navigateur qui l'importe tirerait le
code serveur dans son paquet (budget de `nodefony/client` dépassé, ou build cassé sur un `node:`)
— défaut invisible à un test de types, révélé au premier build d'une application. Donc :

```ts
// shared/chat.ts — UNIQUEMENT des types : 0 octet compilé, aucun import de code possible
export interface ChatContract extends IRealtimeContract {
  /* … */
}
// navigateur — porte du client (nodefony/client)
const socket = NodefonySocket.fromContract<ChatContract>({ url });
// serveur — porte du serveur (@nodefony/realtime)
const chat = defineRealtimeContract<ChatContract>(); // { Controller, RealtimeAction }
```

- **Pourquoi une porte côté client** : `NodefonySocket` prend trois génériques (envoi, écoute,
  méthodes), l'application déclare UN contrat. Écrire la conversion à chaque `new` rouvrirait
  l'inversion à la main ; réutiliser le premier générique est écarté ci-dessous. La porte est un
  `new` typé, sans allocation de plus.
- **Les noms** (`fromContract`, `defineRealtimeContract`) ne sont PAS décidés : ils se fixent au
  code, signatures sous les yeux. Un nom dit ce qu'on obtient ; « contrat » désigne la déclaration
  de l'application, pas une technique.

**Décision (tranchée le 2026-10-29) : ce que j'envoie =
ce que j'ai déclaré, ce que je reçois = ce que JSON en fait.** `Jsonify<T>` (§2) s'applique aux
QUATRE points de réception, des deux côtés ; le type déclaré, tel quel, à chaque point d'émission.

| Qui reçoit                                           | Quoi             | Type reçu    |
| ---------------------------------------------------- | ---------------- | ------------ |
| le client, `on(…)`                                   | `serverToClient` | `Jsonify<T>` |
| le serveur, entrée d'un canal                        | `clientToServer` | `Jsonify<T>` |
| qui IMPLÉMENTE une méthode (serveur ou client)       | ses `in`         | `Jsonify<T>` |
| qui APPELLE une méthode (`request`, `requestClient`) | son `out`        | `Jsonify<T>` |

- Exemple : `serverToClient: { meeting: { start: Date } }` — `socket.on("meeting", (m) =>
m.start.getTime())` compile aujourd'hui et plante au navigateur ; avec la règle, `m.start` est
  `string` et l'éditeur le souligne. Même mensonge, côté serveur, pour `send(p: { start: Date })`.
- Exception (§2, S8) : `Uint8Array` reste `Uint8Array`.
- **Pourquoi les quatre d'un coup** : ne poser `Jsonify` qu'au `on()` du client obligerait à
  l'ajouter après 10.0 aux trois autres — le type des paramètres d'une méthode décorée
  changerait, nouvelles erreurs de compilation chez les applications. La règle survit à tout
  codec futur : protobuf suit sa correspondance JSON canonique (§2).
- Coût d'exécution nul (types effacés). `Jsonify<T>` s'écrit dans
  `src/nodefony/src/realtime/RealtimeEventMap.ts`, à côté de `#ContractParams`, avec un test de
  types par ligne du tableau, et une profondeur bornée (un type récursif sans borne ralentit le
  compilateur sur les charges profondes).
- Le codec ne change pas le type reçu : déjà acquis par « JSON est la référence de tous les
  codecs » (§2) — un client CBOR et un client JSON reçoivent le même `Jsonify<T>`.

**Décision (validée le 2026-10-29) : l'option B, bâtie sur les génériques de
l'option A, une porte par côté.** Le `chat.Socket` de l'exemple de l'option B n'existe pas : la
décision « un contrat fait de types » le remplace par la porte du client, et la fabrique du
serveur ne rend que `Controller` et `RealtimeAction`. `Listen` s'ajoute en
troisième position de `RealtimeController` avec défaut (nécessaire aux deux options) ; les types
utilitaires existent déjà en partie (`src/nodefony/src/realtime/RealtimeEventMap.ts#ContractParams`,
`#TypedRpcActionHandler`) ; la fabrique est la surface opt-in que le gel réserve à la vérification
des actions, et la **seule** voie par laquelle un décorateur connaît les noms du contrat. Un
contrôleur non paramétré reste permissif sur les deux voies (cas « rétro-compat » de
`src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeSharedContract.types.test.ts`, à
garder vert tel quel). Le pair reste rangé sous son contrat effacé sur la connexion et relu par
`src/nodefony/src/realtime/JsonRpcPeer.ts#JsonRpcPeer.requestAs` : la fabrique ne le
re-paramètre pas.

- Usages : une discussion (deux sens), un jeu (entrées client typées), un tableau de bord
  (canaux serveur seuls — `clientToServer` peut rester vide).
- **Rupture si différé après 10.0 : NON**, parce que tout est générique en fin avec défaut, ou
  fabrique opt-in. (ii) était la rupture, et elle est faite.
- **Reste au code** : soldé par la décision suivante.

**Décision (tranchée le 2026-10-31) :
deux portes à NOMS FIGÉS, sans fabrique.** Elle remplace l'emballage « fabrique » des décisions
ci-dessus (`defineRealtimeContract<C>()` → `{ Controller, RealtimeAction }`) ; le fond — un
contrat fait de types, une porte par côté, la direction CALCULÉE et jamais réécrite — ne bouge pas.

```ts
// shared/chat.ts — types seuls
export interface ChatContract extends IRealtimeContract {
  /* … */
}
// navigateur — porte du client (nodefony/client)
const socket = NodefonySocket.fromContract<ChatContract>({ url });
// serveur — porte du serveur (@nodefony/realtime)
@RealtimePolicy({ "chat:send": { roles: ["ROLE_USER"] } })
class ChatRt extends ContractRealtimeController<ChatContract> {
  protected realtimeActions() {
    return { "chat:send": (p: { text: string }) => ({ id: store(p.text) }) };
  }
}
```

- **Pourquoi des noms figés.** Un décorateur se reconnaît à son nom. `@chat.RealtimePolicy` en
  donnait un par application (`@chat.`, `@orders.`…) : un `grep` ne le trouve plus, la doc ne
  peut plus montrer une forme unique, et un agent ne le recopie pas.
- **Le contrat s'écrit UNE fois côté serveur**, sur `extends`.
  `src/packages/@nodefony/realtime/nodefony/src/server/ContractRealtimeController.ts#ContractRealtimeController`
  porte une étiquette de TYPE (`declare readonly [contractType]?: C`, aucun octet émis) que
  `src/packages/@nodefony/realtime/nodefony/decorators/realtimeDecorators.ts#RealtimePolicy`
  LIT sur la classe décorée : un nom hors contrat ne compile pas, et l'erreur le nomme
  (`notInContract`). Sur un contrôleur sans contrat, le même décorateur accepte tout nom.
- **(iv) se ferme par `realtimeActions()` abstraite et COMPLÈTE**, typée par `serverMethods`. Un
  décorateur ne voit jamais la classe entière : c'est la seule construction qui fait d'une
  méthode OUBLIÉE une erreur de compilation (§10, garde-fou 2). Un contrat sans `serverMethods`
  n'a rien à écrire : `ContractRealtimeController<C>` est un constructeur typé qui rend la forme
  STRICTE (`ContractRealtimeControllerStrict`, table abstraite) quand `C` déclare des méthodes,
  et le SOCLE (`ContractRealtimeControllerBase`, table vide héritée) sinon — une sous-classe vide
  de plus à l'exécution, rien d'autre. Les entrées client (`realtimeInbound()`) restent facultatives
  canal par canal : accepter une entrée est une permission, pas une promesse.
- **La table sert SEULE les méthodes d'un contrat — règle de perf.** Lui ajouter
  `@RealtimeAction` pour porter une politique fabriquait, à chaque connexion, un handler aussitôt
  écrasé par la table (`RealtimeController.ts#RealtimeController.onHandshake` fusionne
  `{ ...décorés, ...table }`), ajoutait un appel par requête, et court-circuitait l'injection des
  paramètres décorés (`@Body`). La politique se pose donc sur la classe, par `@RealtimePolicy`,
  écrite une fois à la définition de la classe : rien par connexion.
- **Canaux à motif** prouvés comme clés (`` `user:${string}` ``), et admis comme motif de
  politique (`user:*`).
- **Côté client, les noms de canaux restent ouverts** (canaux dynamiques, de plateforme) :
  `publish`/`on` acceptent tout nom, la charge d'un nom déclaré est typée. L'inversion se garde
  sur les cartes que la porte dérive (`ContractClientEmit` ≠ `ContractClientListen`) et côté
  serveur.
- **SSE** : `Controller.ts#Controller.renderSse` prend la carte en générique EN FIN avec défaut
  (`renderSse<ContractServerEmit<C>>()`) ; flux multiplexé (`send(data, { event })`) ou un flux
  = un canal (carte d'un canal, `send(data)`). Sans paramètre, le flux reste libre (porte MCP).
- **Les trois limites du contrat, tranchées par une revue contradictoire** (sur le chat de référence,
  messages privés compris ; **décisions tranchées le 2026-10-31, la page de référence validée le même
  jour**). Règle de méthode qui en sort : une API se juge à la LIGNE que le développeur écrit pour
  le cas courant, la mécanique vient après.
  - **Diffusion (D2)** : une seule forme, partout — contrôleur, service, tâche, boucle de jeu :
    `getRealtimeHub<C>().publish(canal, charge)`, par SURCHARGE : sans paramètre, le hub entier
    (`RealtimeHub`), libre comme avant ; avec, `IContractRealtimeHub<C>` — mêmes méthodes, seul
    `publish` typé. Même objet hub, aucune conversion, JS émis identique : une interface à
    signature de MÉTHODE que `RealtimeHub` satisfait par bivariance — prouvé au compilateur ; la charge est
    `EventPayload<…> & object`, si bien qu'une charge scalaire, refusée à l'exécution par
    `src/nodefony/src/realtime/payload.ts#isRealtimePayload`, l'est désormais à la compilation.
    Écarté : un `this.broadcast` propre au contrôleur (deux formes pour un geste).
  - **Fabriques (D7)** : `ContractRealtimePublish<C>` type le `publish` reçu par
    `@RealtimeChannel` ET par la surcharge `createRealtimeChannel` — la fonction reçue reste la
    forme libre, que le type contractuel admet.
  - **Nommage de la porte** : trois mots, trois sens, sans
    recouvrement. `Contract…<C>` = la même chose que sa forme libre, lue à travers le contrat
    ENTIER (`ContractRealtimeController`, `ContractRealtimePublish`, `IContractRealtimeHub`,
    `ContractRealtimeMethodHandlers`, et au cœur `Contract{Server,Client}{Emit,Listen,Actions}`).
    `Typed…<…>` = la version typée d'un type libre par ses types DIRECTS (charge, réponse, carte,
    clé : `TypedRpcActionHandler`, `TypedRealtimeInboundHandler`). `…Of<X>` = LECTURE du X
    porté par un nom ou une classe (`RealtimeContractOf`, `ConfigOf`). Les noms neufs du client
    (type rendu par `fromContract`, hooks) suivent la même règle.
  - **Actions (D4)** : le type d'une action du pont vient du SCHÉMA de sa route, seule source —
    celle que le serveur valide (`src/packages/@nodefony/framework/nodefony/src/routeSchema.ts#IRouteSchema`).
    Le contrat la RÉFÉRENCE par une clé additive `serverRoutes` (`"POST /chat/send": { body:
typeof SendBody; result: … }`, import de type seul) ; un contrôle au démarrage refuse une
    entrée sans route montée de même méthode et même schéma. Les méthodes du client prennent le
    nom du verbe HTTP que la route déclare — `get`, `post` (et les autres verbes si le pont les
    sert) — et la clé d'idempotence se pose seule ; `request` et `mutate` sont renommés avant
    10.0 stable (pré-versions, semver 2.0 §9). Écarté : faire de `send` une `serverMethods` — elle
    perdrait la re-validation d'identité à chaque appel, `@Idempotent` et la validation, que le
    pont porte (`RealtimeController.ts#RealtimeController.invokeApiRequest`) ; recopier la forme
    du corps dans le contrat (deux sources).
    **Décision (validée le 2026-11-02) :** une route à paramètre de chemin se
    déclare par son GABARIT — la clé est le chemin de la route, `"GET /chat/messages/{id}"` — et
    s'appelle en le nommant (`chat.get("/chat/messages/{id}", { params: { id } })`) ; la socket
    le remplit (`src/nodefony/src/runtime/routePath.ts#fillRoutePath`), chaque valeur encodée pour
    SON segment, et refuse une valeur manquante, vide, `.` ou `..` (la normalisation la
    résoudrait). `params` = entrée du schéma `params` de la route, sinon les `{noms}` du gabarit.
    Seuls des segments `{nom}` entiers se déclarent (`routePath.ts#isSimpleRouteTemplate`, refus
    au démarrage) ; une contrainte passe par `requirements`. Une seule lecture de la forme simple
    au cœur (`routePathParams`, partagée avec le catalogue d'administration), confrontée au
    Router par `src/packages/@nodefony/framework/nodefony/tests/unit/routePathParity.test.ts`.
    Écarté : appeler par l'URL concrète typée par un motif (`"GET /m/${string}"`) — une clé en
    motif échappe à `ContractRouteSchemas`, et le contrôle au démarrage se taisait (constaté à la
    compilation). Corollaire : le pont route le chemin dans la forme que HTTP lui donne
    (`parseRequestTarget`, `@nodefony/http`), sinon `/x/` divergeait d'une porte à l'autre.
  - **Lecture côté navigateur (D3)** : les hooks React et Vue prennent la socket typée
    (`useNodefonyChannelData(chat, "chat:presence", initial)`) ; nom et charge déduits, plus de
    `<T>` écrit par le lecteur. Studio, premier consommateur, porte son contrat partagé et
    supprime son miroir `HealthPayload`.
  - **Canal ou route — la règle enseignée** : le canal porte les FLUX (diffusés, éphémères,
    attribués par l'identité de la connexion, §6) ; la route porte les GESTES qui changent un état
    (identité revérifiée, droits, validation, idempotence, réponse, appelable en HTTP).
  - Page de référence du chat : `src/packages/@nodefony/realtime/docs/cookbook-chat.md`.
- **Webhook** : l'émission applicative n'existe pas encore (ADR-0023 W3, en 10.1). Elle se
  typera par la même carte `ContractServerEmit<C>` — exigence que portera l'émission applicative (ADR-0023 W3).
- Preuves : `src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeSharedContract.types.test.ts`
  (chaque `@ts-expect-error` vu mordre), un consommateur compilé contre les tarballs, et le JS
  bâti de `RealtimeController` identique avant/après (types effacés).

### 5. Contre-pression et bornes

**Décision (validée le 2026-10-29) :** **une règle, trois endroits.** Sortante serveur :
`src/packages/@nodefony/http/nodefony/src/context/websocket/wsBackpressure.ts#decideSend` reste
l'unique arbitre — jeter au-delà du seuil, fermer `1013` sur un solde de refus — texte et binaire.
**C1**, sortante client : la **même** règle sur `WebSocket.bufferedAmount` du navigateur (voir
la décision C1 ci-dessous). **C2**, débit entrant par connexion : le patron du canal des
journaux (`src/packages/@nodefony/realtime/nodefony/src/server/syslogUplink.ts#SyslogUplinkHandlerOptions`
— fenêtre par connexion, compteur alloué paresseusement) généralisé au transport, dans
`@nodefony/http` à côté de `maxPayload` ; au-delà, trame **écartée et comptée**, puis fermeture
`1008` sur un solde, calqué sur `backpressureCloseAfterDrops`. Les deux naissent **désactivées**
en 10.x (décision de gel 7).

**Décision C1 (validée le 2026-10-29) : décider au cœur, agir de chaque côté.**
`#decideSend` n'est PAS pure : elle tient ses compteurs sur la socket (`_nfDrops`,
`_nfDropStreak`, par un `ws as unknown as IBackpressureSocket`) et ferme elle-même en `1013`. Or
un navigateur refuse ce code : `WebSocket.close(code)` n'admet que `1000` et `3000`-`4999`, sinon
il lève `InvalidAccessError` (WHATWG WebSockets) — déplacée telle quelle, la fonction planterait
au moment de fermer. Donc :

- le code partagé (`src/nodefony/src/realtime/`) ne porte que la **décision pure** : file
  d'envoi, seuil, politique et solde de refus en entrée → `send` / `drop` / `close` et le solde
  suivant en sortie ; aucun effet de bord, aucune écriture sur la socket ;
- chaque côté **agit** : le serveur garde ses compteurs et ferme en `1013`, comportement
  inchangé ; `NodefonySocket` tient son solde dans son propre état et ferme par un code privé neuf
  rangé dans `src/nodefony/src/realtime/closeCodes.ts`, puis sa reconnexion prend le relais ;
- le `as unknown as` disparaît avec la sortie des compteurs ;
- désactivée côté client pendant toute la série 10 ; la règle reste UNE, puisqu'elle est écrite une fois.

```ts
// navigateur, 30 emit("move") par seconde, le réseau cale dans un tunnel :
// sans C1 → 300 coups périmés en file au bout de 10 s, partis en rafale à la sortie ;
// avec C1 → au-delà du seuil, les coups sont jetés et comptés, puis la socket se ferme
//          et se reconnecte si le solde de refus ne redescend pas.
```

**Décision C2 (validée le 2026-10-29) : compter les trames avant de les décoder.**
Exemple : un capteur pousse 5 000 petites trames par seconde sur une connexion ; chacune passe
`maxPayload`, qui borne la TAILLE et pas le NOMBRE, et chacune est décodée, routée, autorisée.

- On compte des **trames**, pas des octets — une addition ; les octets restent bornés par
  `maxPayload` × trames.
- Le compte se fait à l'arrivée de la trame BRUTE, à côté de `maxPayload`, **avant** tout codec :
  une trame jetée ne coûte ni `JSON.parse` ni décodage CBOR.
- Fenêtre et compteur par connexion, **créés au premier usage** ; borne à `0` (désactivée) =
  un seul test, aucune lecture d'horloge, aucune allocation.
- Au-delà du seuil : trame **écartée et comptée** (compteur exposé par la sonde) ;
  fermeture `1008` sur un **solde** de refus, jamais au premier dépassement — une reconnexion qui
  rejoue ses abonnements est une rafale légitime.
- Texte et binaire, même règle.
- **Désactivée pendant toute la série 10** (opt-in, config `@nodefony/http`). Une activation par
  défaut est un changement de comportement, donc une majeure : elle ne peut venir qu'en 11.0,
  avec un seuil documenté qui laisse passer un flux audio de 50 trames/s avec marge. Aucun travail
  prévu d'ici là.

- Usages : un tableau de bord diffusé à N lecteurs dont un lent, un jeu sur réseau mobile qui
  pousse ses coups (C1), un capteur qui émet trop vite (C2).
- Écarté : une copie de `decideSend` côté client gardée par un test de comparaison (la décision
  pure partagée suffit) ; un déplacement de `decideSend` telle quelle (effets de bord, `1013`
  refusé par le navigateur) ; une fermeture immédiate pour C2 (un pic passager n'est pas une
  attaque) ; un compte en octets pour C2 (`maxPayload` les borne déjà).
- **Rupture si différé après 10.0 : NON**, parce que les bornes neuves naissent désactivées et
  que la décision partagée est interne. Activer un défaut est en revanche une rupture (un flux
  audio de 50 trames/s couperait) : réservé à 11.0, aucun travail prévu d'ici là.

### 6. Les canaux privés

**Décision (acceptée le 2026-10-29) :**

- **Décision 1 (validée le 2026-10-29 ; (a) et (d) tranchés le 2026-10-30 par la
  revue du gel ; (b), (c), (e) à l'écriture du code) : admission demandée une fois, réponse
  retenue.** `allow` — flèche `(channel, who: ISubscriberIdentity)` ou classe `@injectable`
  implémentant `IChannelAdmission` (ADR-0021 §S10 bis) ; `who` est l'identité d'admission commune
  aux trois livraisons, une donnée plate et non le jeton (ADR-0021 §S10) —, membre optionnel de
  `src/nodefony/src/realtime/channelAdmission.ts#IChannelPolicy`, évalué
  APRÈS `authenticated` / `roles` / `scopes`.
  - Appelé **une seule fois, au `subscribe`** : un salon privé ou une invitation par courriel
    vivent en base, et l'abonnement est un chemin rare — une requête y est normale.
  - La réponse est **retenue sur la connexion** (registre sink ↔ connexion des abonnés identifiables, alloué au
    `subscribe`). Une trame entrante sur un canal à `allow` ne rappelle JAMAIS `allow` : elle
    exige que CETTE connexion y soit admise, en une lecture. Écrire sur un canal à `allow` suppose
    donc de s'y être abonné — sans rupture, `allow` étant neuf. (Constaté : aujourd'hui la branche
    « inbound » de `src/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#buildFrameAuthorizer`
    réévalue la politique à CHAQUE trame, sans exiger l'abonnement.)
  - L'accueil **n'appelle pas** `allow` : il annonce sur la politique fixe — autant de requêtes
    que de canaux par connexion, sinon, et un motif ne s'énumère pas ;
    `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.probeChannel`
    le pose déjà : le verrou protège, pas l'annonce.
  - `allow` qui lève = refus `forbidden`, détail hors production. Un **délai dépassé** ou une
    saturation = motif `unavailable`, que le client réessaie (ADR-0021 §S10 bis point 3 ; tranché
    le 2026-10-30 par la revue du gel).
  - **Prix assumé** : une réponse retenue ne se périme pas seule — un membre retiré reste abonné
    jusqu'à son éjection explicite (`realtime:closed { reason: "evicted" }`).
  - Le nom : `allow` (pas `admit`, qui ne se devine pas). Une liste de membres est **une** façon
    d'écrire `allow`, pas une primitive (S7).
  - **Tranché le 2026-10-30 par la revue du gel** : (a) l'accès aux services — PAS de troisième
    argument : `allow` est une flèche `(channel, who)` OU une classe `@injectable` qui implémente
    `IChannelAdmission`, résolue au démarrage du noyau (ADR-0021 §S10 bis point 1) ; (d) le délai
    — la clé `realtime.allowTimeoutMs`, son défaut fixé à l'écriture du code, et le motif
    `unavailable` au dépassement. **Reste à l'écriture du code, sans rupture** : (b) le miroir
    structurel de `IChannelPolicy` dans
    `src/packages/@nodefony/security/nodefony/src/realtime/realtimeContracts.ts` — un test compare
    les deux formes ; (c) la garde `isChannelPolicy` des décorateurs accepte une fonction ET une
    classe, distinguées par la métadonnée `@injectable` ; (e) ce que montre une introspection des
    politiques (une fonction ne se sérialise pas ; une classe se montre par son nom).
- **Décision 1 bis (validée le 2026-10-29) : autoriser une fois à l'entrée, pour
  TOUS les canaux.** Une trame entrante sur un canal où CETTE connexion a déjà été acceptée ne
  refait aucun contrôle de politique : une lecture, « admise ? ». La décision 1 en est le cas
  particulier où l'entrée est le `subscribe`.
  - Constaté : `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#RealtimeHub.runAuthorizer`
    appelle le verrou à CHAQUE trame, qui réévalue la politique entière (et `getRoles()` des
    jetons recopie le tableau des rôles à chaque appel). Mesuré
    (`.claude/skills/nodefony-load-test/scripts/micro/micro-frame-authorizer.mjs`, médiane de 7,
    côté contrôleur, hors décodage réseau) : le verrou ajoute **+24 %** à la trame sur un canal
    libre et **+35 %** sur un canal à rôles ; un verdict retenu (prototype) ramène l'écart à
    **+9 %**.
  - **Où** : la mémoire vit dans realtime, au point d'appel du verrou (`#runAuthorizer`) ;
    `@nodefony/security` reste le seul juge et son contrat ne change pas. Elle est attachée à la
    connexion, `null` jusqu'à sa première trame entrante, libérée à la fermeture.
  - **Portée** : les trames entrantes sur un canal déclaré (`@RealtimeInbound`, nom exact ou
    motif). Les autres trames — `subscribe`, méthodes, `api.request` — passent par le verrou
    comme aujourd'hui : elles sont rares, rien à gagner.
  - **Garde-fou 1 — seuls les noms connus se retiennent.** Un nom sans gestionnaire n'entre
    jamais en mémoire. Un motif (`room:*`) admet une infinité de noms : la mémoire d'une
    connexion est **bornée** (plafond fixé au code) ; au-delà, la trame est contrôlée sans être
    retenue — le comportement d'aujourd'hui, jamais pire. Sans cette borne, un client qui écrit
    sur `room:1` … `room:1000000` remplit la mémoire du pod.
  - **Garde-fou 2 — seul le « oui » se retient.** Un refus est réévalué et audité à chaque trame,
    comme aujourd'hui ; c'est le décompte des trames de C2 (§5) qui borne un client qui insiste.
  - **Garde-fou 3 — un compteur de version des politiques.** Toute (ré)inscription d'une
    politique au hub l'incrémente ; un verdict retenu porte la version de son calcul, et une
    version périmée le fait recalculer. Coût : une comparaison d'entiers.
  - **L'identité** : un verdict retenu suppose une identité fixe pour la vie de la connexion.
    C'est le cas aujourd'hui — un changement d'identité ferme la connexion
    (`src/nodefony/src/realtime/closeCodes.ts#IDENTITY_REFRESH_CLOSE_CODE`, 4005), et la mémoire
    meurt avec elle. **À prouver au code** : aucun chemin ne change le jeton d'une connexion
    ouverte sans la fermer.
  - **Usage qui la motive** : un flux à haute fréquence — les déplacements d'un jeu, 60 coups par
    seconde et par joueur — où l'autorisation se paie une fois par canal et par connexion, plus
    à chaque coup. Le reste du coût d'un tel flux tient au décodage (binaire routé, §3) et aux
    coups périmés (C1, §5), pas à l'autorisation.
  - **Rupture : NON.** Politiques et identité étant fixes pour la vie d'une connexion, les
    verdicts sont identiques ; un test le prouve sur une matrice (canal libre, rôles, scopes,
    motif, refus, politique réinscrite).
  - **Critère de validation** : un banc de bout en bout (vrai serveur, vrais clients WebSocket,
    flux de déplacements sur un canal à rôles), verrou par trame contre verdict retenu, en paires
    alternées.
- **Décision 1 ter (validée le 2026-10-30) : tout se calcule à l'ouverture, jamais
  sur la route de la trame.** Généralise la décision 1 bis : le verdict retenu n'est plus une
  optimisation, c'est la règle. Trois moments, et trois seulement :
  1. **À l'ouverture (poignée de main), une fois** — tout ce qui dépend de l'identité : identité
     gelée, rôles DÉPLIÉS par la hiérarchie en un ensemble figé, scopes, émetteur. À la
     reconnexion, les canaux reviennent par le rejeu des `subscribe` (une trame de contrôle par
     canal,
     `src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions`) :
     chacun suit le moment 2 ; rien n'est admis à l'accueil, et le rejeu attend son tour au-delà
     du plafond d'appels d'`allow` en vol (ADR-0021 §S10 bis point 3).
  2. **À l'entrée sur un canal, une fois par canal et par connexion** — le nom d'un canal n'arrive
     qu'avec son `subscribe` (trame de contrôle, rare) : politique complète puis `allow`
     (asynchrone), évalués **HORS du verrou des trames**, sans bloquer le pipeline de la connexion ;
     le verdict est posé sur la connexion.
  3. **Sur la trame de données, aucun calcul** — un canal sans politique ne coûte rien, un canal à
     politique coûte une lecture (« cette connexion est-elle admise ? ») : ni boucle sur des
     règles, ni balayage de chaîne, ni copie de tableau, ni parcours de hiérarchie.
  - **Constaté, contraire à la règle** (à corriger avec l'admission par identité) : toute trame dont `method` est une
    chaîne — `ping`, `unsubscribe`, une action — entre dans
    `src/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#authorizeChannel`,
    qui boucle sur les règles système et balaye deux fois le nom (`:health`, `:stats`) ; sur un
    canal à rôles, `satisfies` recopie les rôles
    (`src/packages/@nodefony/security/nodefony/src/realtime/UserRealtimeToken.ts#UserRealtimeToken.getRoles`)
    et parcourt la hiérarchie à CHAQUE trame. Mesuré (décision 1 bis) : +24 % à +35 % par trame.
  - **Verrou de procédure — le verrou des trames est la pièce la plus sensible du temps réel.**
    Toute modification de `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeHub.ts#FrameAuthorizer`,
    de `frameAuthorizer.ts#buildFrameAuthorizer`, de `RealtimeHub.ts#RealtimeHub.runAuthorizer`
    ou du branchement `beforeDispatch` exige, AVANT le commit : (1) une relecture du diff par le mainteneur ; (2) une campagne d'attaque
    sur le verrou, menace d'abord ; (3) le micro-banc `micro-frame-authorizer.mjs` avant et après,
    médiane de 7 ; (4) le gate mémoire. Jamais d'`await` dans le verrou ; `allow` ne s'y insère
    jamais.
  - **Gardé par** : un test prouve qu'une trame `ping` ne consulte ni les règles système ni
    le résolveur de politiques ; un test prouve qu'une trame sur un canal admis ne lit ni
    `getRoles()` ni la hiérarchie ; la matrice de la décision 1 bis rend les mêmes verdicts.
- **Décision 1 quater (validée le 2026-11-09) : une politique de LECTURE et
  une politique d'ÉCRITURE par nom — chacune s'applique telle qu'elle est déclarée.**
  - **Constaté** : `@RealtimeChannel(nom, p)` et `@RealtimeInbound(nom, q)` écrivaient la même
    case du registre des politiques (une seule métadonnée par nom) ;
    la seconde déclaration effaçait la première sans un mot, selon l'ordre des méthodes. Une règle
    de sécurité déclarée pouvait donc ne s'appliquer nulle part, et « tout le monde lit, seuls les
    connectés écrivent » n'était pas exprimable.
  - **La règle** : `subscribe` exige la LECTURE (`@RealtimeChannel`) ; une trame entrante —
    notification sur un canal plein-duplex ou requête d'action — exige la LECTURE **et**
    l'ÉCRITURE (`@RealtimeInbound`, `@RealtimeAction`). L'écriture n'est donc jamais moins stricte
    que la lecture : le motif « on ne pousse pas sur un canal protégé » tient toujours.
  - **Héritage, indépendant de l'ordre des méthodes** : une lecture absente hérite de l'écriture
    explicite (une application qui ne garde que `@RealtimeInbound` reste protégée en lecture) ;
    une action sans politique explicite hérite de ce que son nom EXACT déclare ; s'il ne déclare
    rien, le défaut FERMÉ (`#DEFAULT_ACTION_POLICY`) devient son écriture — un motif de lecture
    public (`orders:*` ouvert) s'y ajoute sans l'ouvrir. `@RealtimePolicy({ nom: p })` pose les
    deux sortes. Deux classes qui déclarent des sortes DIFFÉRENTES d'un même nom se complètent.
  - **Plus d'écrasement silencieux** : deux déclarations explicites non équivalentes d'une même
    sorte, dans une même classe ou entre deux classes, refusent le démarrage en nommant le canal et
    les classes. Une sous-classe qui redéclare son parent le surcharge. `allow` reste une règle de
    lecture : posé sur une écriture distincte de la lecture, il refuse le démarrage.
  - **Précédence — la lecture appartient, l'écriture descend** (`channelPolicyResolution.ts#resolveDeclaredPolicies`) :
    la LECTURE d'un nom appartient à la déclaration la plus spécifique qui déclare quelque chose
    sur lui (nom exact, puis motif au littéral le plus long) — déclarée, ou héritée de sa propre
    écriture ; l'ÉCRITURE vient de la plus spécifique qui déclare une écriture, motifs compris.
    L'écriture s'ajoute à la lecture, elle ne peut que durcir : une écriture de famille (`mix:*`
    réservée) n'est plus perdue sur un nom exact qui ne déclare que sa lecture (attaque A3 de la
    campagne red-team). La lecture, elle, ne descend pas : une commande `task:start` déclarée sous une
    famille `task:*` à `allow` ne devient pas un canal à membres, et une écriture exacte ne voit
    pas sa lecture s'ouvrir par un motif plus général. Écarté : résoudre chaque sorte séparément
    — vu rouge sur trois cas d'usage documentés, et ouvrant une lecture au moment de la mise à jour.
  - **Canal personnel** : un nom `user:…` garde sa politique intégrée (son canal seulement) tant
    qu'aucune déclaration ne VISE `user:` (nom exact, ou motif dont le littéral commence par
    `user:`) — un motif attrape-tout (`*`) ne la retire plus (attaque K1, antérieure à cette décision).
  - **Coût** : la vue fusionnée de chaque nom exact est recalculée à chaque inscription (à
    froid) ; une trame sur un nom exact reste UNE lecture de `Map`. Le plancher système balaye les
    conventions `:health`/`:stats` de `:` en `:` (`frameAuthorizer.ts#reservedConventionAt`)
    au lieu de chaque position : verrou seul −42 % sur un canal libre, −32 % sur un canal à rôles
    (`micro-frame-authorizer.mjs`, médiane de 15, code d'avant cette décision en référence).
  - **`allow` n'admet plus d'office l'écriture** : la première trame entrante d'un canal à `allow`
    exige l'abonnement puis passe le verrou (lecture et écriture), et son verdict est retenu comme
    celui de tout canal entrant (décision 1 bis). Sans quoi l'admission contournerait l'écriture.
  - **Garde de version** : aucun paquet ne lie `@nodefony/realtime` à `@nodefony/security`. Un juge
    qui ne sait pas juger l'écriture face à un hub qui en porte une distincte refuse le démarrage,
    plutôt que de laisser l'écriture ouverte.
  - **Écarté — interdire le doublon sans séparer** : la faille se fermait, mais la limite d'usage
    devenait officielle et obligeait à recoder à la main une règle de sécurité.
  - **Rupture : de comportement, pas de signature.** Seul change le code qui déclare les DEUX
    sortes, différentes — c'est-à-dire celui dont une règle n'était pas appliquée. L'écriture n'y
    devient jamais plus permissive ; la lecture devient celle qui est écrite. Annoncée au changelog
    (`Changed`).
  - **Gardé par** : `src/packages/@nodefony/realtime/nodefony/tests/unit/channelPolicySplit.test.ts`
    (vu rouge sur le code d'avant), `…/tests/unit/channelPolicy.attack.test.ts` (39 attaques de la
    red-team), et des mutations basculées une à une (chacune vue rouge).
- **Abonnés identifiables** : le registre d'un canal associe chaque sink à sa connexion,
  alloué au `subscribe` seulement ; le fan-out reste une boucle sans allocation. API serveur :
  ce qui désigne une **connexion** (lister, abonner d'office, éjecter une connexion) est **local
  au pod** ; ce qui désigne un **nom** (fermer un canal, éjecter un utilisateur) traverse les pods
  (décision 4). Il porte aussi la marque
  « admise » de la décision 1 : abonner d'office la **pose**, éjecter et fermer la **retirent**.
- **Décision 2 (validée le 2026-10-29) : abonnement imposé — `allow` reste la seule
  source de vérité.** Exemple : la recherche de partie place quatre joueurs dans `room:42`.
  - La politique fixe passe par la **même sonde** que l'accueil
    (`#RealtimeHub.probeChannel`, synchrone) ; sur un canal à `allow`, l'abonnement imposé
    **appelle `allow`** ensuite. L'API serveur est donc async — chemin rare, une requête par
    membre imposé, rien sur le chemin des trames. Refus de `allow` = pas d'abonnement, rendu à
    l'appelant (jamais un abonnement qui contourne `allow`).
  - **Pourquoi pas de contournement** : le client rejoue ses abonnements à chaque reconnexion
    (`src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions`), et
    ce rejeu passe par `allow`. Un membre imposé que `allow` ne connaît pas serait éjecté à la
    première coupure réseau — un défaut qu'on ne voit qu'en production, sur mobile. Conséquence
    pour l'application : elle écrit l'appartenance là où `allow` la lit.
  - **Le client est notifié** : `realtime:subscribed { channel, imposed: true }` — champ
    optionnel ajouté à `src/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeSubscribed`, pas
    de notification neuve. Le marqueur est nécessaire : aujourd'hui
    `#NodefonySocket.ingestSubscribed` IGNORE un acquittement pour un canal qu'il ne suit pas (le
    cas d'un `unsubscribe` croisé avec l'acquittement), et doit continuer. Avec `imposed`, le
    client inscrit le canal dans ses abonnements (un consommateur) : il le rejoue donc à la
    reconnexion, et ses `on(channel, …)` reçoivent les messages comme pour tout canal. Le client
    peut s'en désabonner : quitter reste son droit.
  - Sans `allow`, rien ne change : la politique fixe décide seule, à l'imposition comme au rejeu.
  - Connexion fermée pendant l'`await allow` : réponse jetée, aucune marque (même règle que le
    `subscribe`).
  - **Locale au pod en 10.x** : on n'impose qu'à une connexion servie par ce pod ; l'ordre ne
    traverse pas le backplane (S6). Un client ancien qui ignore `imposed` reçoit les messages
    mais ne rejoue pas : dégradé, pas cassé — d'où l'ajout sans rupture.
  - Usages hétérogènes : la recherche de partie d'un jeu, l'appelé d'un appel, le flux
    d'une tâche d'agent auquel le serveur abonne le demandeur, l'attribution d'une conversation
    de support à un conseiller.
- **Décision 3 (validée le 2026-10-29) : fermeture — éjecter coupe, seul `allow`
  exclut.** `realtime:closed { channel, reason }` (S4), motif **fermé** — `ended` (le canal est
  terminé) ou `evicted` (cette connexion en est retirée) — déclarée à côté de
  `src/nodefony/src/realtime/RealtimeEventMap.ts#IRealtimeDenied`. Le client retire l'abonnement
  et **ne le rejoue pas** ; `RealtimeDeniedReason` ne bouge pas (décision de gel 5).
  - **Ne pas rejouer est une politesse du client, pas une protection** : une page rechargée ou
    un client hostile refait `subscribe`. Sur un canal à `allow`, l'éjecté revient si
    l'application n'a pas retiré l'appartenance là où `allow` la lit ; sur un canal **sans**
    `allow`, la politique fixe le laisse rentrer — éjecter n'y exclut personne.
  - D'où la règle, écrite dans le TSDoc de l'action « éjecter » et dans la page publique :
    **éjecter coupe la connexion du canal, seul `allow` exclut.** Exclure d'un canal sans
    `allow`, c'est lui en donner un.
  - Le pendant pour `ended` est déjà écrit par ADR-0021 S4 : **la fabrique d'un canal terminé
    rend `null`**, et qui refait `subscribe` reçoit `realtime:denied { reason: "unknown" }`. Seul
    `allow` exclut une personne ; seule la fabrique clôt un canal.
  - Éjecter retire la marque « admise » et le verdict retenu de la connexion pour ce canal
    (décision 1 bis) ; `ended` les retire de toutes les connexions du canal.
  - **Contraintes relevées au code (revue du 2026-10-29)** :
    - Serveur : une connexion tient ses canaux dans `ctx.__nfRealtime.channels`, et
      `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#RealtimeController.startChannel`
      répond « déjà suivi » sans rouvrir quand le nom y est. Éjecter en retirant le seul sink du
      hub laisserait l'entrée : le `subscribe` suivant serait acquitté sans rien rouvrir —
      **abonné fantôme**, qui ne reçoit plus rien — et le plafond par connexion compterait un
      canal mort. L'éjection passe donc par le MÊME chemin que
      `#RealtimeController.stopChannel` (hub ET état de connexion), jamais un second.
    - Client : `src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.ingestDenied`
      **garde** le canal refusé dans ses abonnements (il est rejoué à la reconnexion — utile
      quand l'identité change). `realtime:closed` fait l'inverse, et ne doit donc pas le
      recopier : retirer l'entrée **quel que soit le nombre de consommateurs locaux** (un hook
      et un magasin partagent un seul abonnement), rejeter les attentes d'acquittement, et
      émettre un événement local (comme `__denied__`) pour que l'écran cesse de se croire
      abonné.
    - Un composant qui se remonte rappelle `subscribe` : c'est attendu, et c'est `allow` qui
      tranche — conforme à la règle ci-dessus.
  - **Écarté** : une liste noire dans le framework — seconde source de vérité, locale au pod,
    perdue au redémarrage, divergente de `allow` en silence.
- **Décision 4 (validée le 2026-10-29) : ce qui traverse le backplane — les
  publications, et des ordres qui ne font qu'ENLEVER.**
  - **Publications** : `{ channel, payload, originId }` des seuls canaux déclarés diffusables
    (S6, `#RealtimeHub.markBroadcastChannel`). Un message venu du bus n'atteint que des abonnés
    **déjà admis** sur leur pod. Ni politiques, ni acquittements ne traversent ; les membres,
    seulement sur les canaux de présence (ADR-0025 P2), comptés par identité, jamais leurs
    connexions.
  - **Ordres par NOM — traversent** : fermer un canal (`ended`) et éjecter un utilisateur par son
    identifiant. Sans eux, une fin de partie ou une modération décidée sur le pod B laisse ouverts
    les abonnés du pod A — un défaut qui marche en développement et une fois sur N en production.
    Chaque pod applique l'ordre à SES connexions, par le chemin unique de la décision 3.
  - **Ordres par CONNEXION — restent locaux** : abonner d'office, éjecter une connexion. Une
    connexion n'existe que dans le pod qui l'a acceptée ; une connexion inconnue de ce pod rend
    `false`, jamais un no-op muet.
  - **Transport** : un **message ordinaire** du backplane (`IBackplane.publish`), sur un canal de
    contrôle INTERNE au hub, l'ordre dans `payload` — l'enveloppe ne gagne aucun champ (S6) et
    `src/packages/@nodefony/realtime/nodefony/interfaces/IBackplane.ts#IBackplane` aucune méthode :
    tout driver, y compris écrit par un tiers (Kafka, NATS), le transporte sans le savoir. Ce canal
    ne passe PAS par `#RealtimeHub.markBroadcastChannel`, qui refuse à raison l'espace réservé
    (injection dans tous les pods) : il a sa branche dédiée à l'entrée, AVANT le contrôle par
    préfixe (`#RealtimeHub.#admitFromBackplane`), qui n'accepte qu'une **liste fermée** d'ordres
    de forme vérifiée (`src/packages/@nodefony/realtime/nodefony/src/backplane/controlOrder.ts#readControlOrder`,
    même garde à l'émission) ; tout autre contenu, et tout ordre visant un canal de la
    plateforme, est rejeté et compté (`ingressRejectedTotal`) — sauf un TYPE d'ordre inconnu de
    cette version, compté dans `ingressUnknownDiscardedTotal` (ADR-0025). Son nom vient de la table du cœur
    (`PLATFORM_BUS_CHANNELS.control`) ; il n'est jamais diffusé aux abonnés locaux. **Livré.**
  - **Pourquoi c'est sûr** : un ordre ne fait qu'**enlever** — seul `allow` fait entrer. Il est
    **scellé comme toute publication** : sur un bus partagé, le secret du bus
    (`NF_REALTIME_BACKPLANE_SECRET`) pose un HMAC sur origine, canal et charge
    (`src/packages/@nodefony/realtime/nodefony/src/backplane/envelope.ts#sealBackplaneEnvelope`,
    ADR-0021 S6) ; un ordre forgé sans le secret est rejeté. Sans secret, qui écrit sur le bus
    peut couper des abonnés, jamais en admettre.
  - **Le rejeu change de portée — à écrire dans le TSDoc du sceau.** Le sceau assume aujourd'hui
    le rejeu hors portée, parce qu'un message rejoué ne fait que rediffuser une charge déjà
    diffusée (`envelope.ts#SEAL_FIELD`). Un ordre rejoué, lui, **recoupe** : un « fermer
    `room:42` » capté puis republié plus tard couperait une partie rouverte. L'effet reste
    soustractif (jamais d'admission) ; un anti-rejeu par horloge reste écarté (horloges des pods
    non alignées, comme au sceau). La parade dépend de l'ordre (amendé le 2026-11-02,
    après revue contradictoire) :
    - Une **fin** vise un canal qui porte son identifiant d'instance (`room:42:<partie>`, S4) :
      rejouée, elle ne désigne plus rien de vivant.
    - Une **éjection** vise **`(canal, compte)`**. Rejouée sur un canal DURABLE (`chat:general`),
      elle recoupe le compte à chaque réadmission : déni ciblé, sans le secret, qu'aucun compteur
      ne voit (S-rt-48). **Risque accepté en 10.0**, borné par trois faits : l'effet reste une
      coupure, jamais une admission ; il exige d'écrire sur le bus ; changer le secret rend
      caduques les ordres déjà captés. La page d'exploitation l'écrit : bus privé exigé.
    - **La parade est réservée sans rupture.** La forme vérifiée de l'ordre d'éjection accepte
      dès 10.0 un champ optionnel `generation` (entier ; absent = toutes les générations). Un
      exemplaire qui ne sait pas s'en servir l'ignore et éjecte toutes les générations — plus
      large, jamais moins. En 10.x, une génération d'appartenance lue par `allow` et augmentée à
      chaque réadmission l'alimentera : rejoué, l'ordre viserait une génération morte. Sans
      horloge et sans mémoire des ordres déjà vus.
    - Écartés : un identifiant d'admission frappé par le pod — les admissions sont locales, le
      modérateur ne nommerait que l'onglet qu'il voit et les autres onglets du compte (S-rt-4)
      resteraient servis ; la génération dès 10.0 — elle élargit le contrat d'`allow`, publié
      avec 10.0 (ADR-0021 S10 bis), et ferait porter à chaque application un compteur que le cas
      courant n'emploie pas.
  - **Ce que le contrat suffit à porter** : « au plus une fois, ordre par émetteur, aucun entre
    pairs » (ADR-0021 S5, et l'en-tête de `IBackplane.ts`). Un ordre qui enlève le supporte : reçu
    deux fois = appliqué une fois ; perdu ou en retard = une coupure tardive ; venu d'un autre
    pair qu'une publication = au pire un message de trop à l'éjecté. Un pod démarré après l'ordre
    ne le connaît pas : pour une **éjection**, c'est `allow`, qui lit l'état partagé, qui le
    rattrape ; pour une **fin** (`ended`), c'est la fabrique du canal qui rend `null` à un canal
    terminé (ADR-0021 S4) — la même règle que pour un client ancien qui rejoue.
  - **Exigences d'un driver**, à écrire dans le TSDoc de `IBackplane` : chaque pod reçoit TOUT
    (un groupe de lecteurs par pod pour un journal partitionné — un groupe partagé répartirait
    les messages en silence) ; l'**ordre par émetteur** de S5 tenu (journal partitionné : une
    clé par émetteur, `originId`, jamais par canal) ; aucun rejeu au démarrage (lire à partir du
    dernier message) ; aucune attente de regroupement à l'émission ; un ordre de contrôle
    jamais jeté pour faire place aux publications (voie hors quota de la file d'envoi ; un
    ordre que le bus refuse se compte, `controlLostTotal`, et s'annonce) ; le sceau appliqué
    (`sealBackplaneEnvelope`, mutualisé pour les drivers tiers) ; sa dépendance npm vit dans le
    driver, jamais au cœur.
  - **Suite de conformité exportée** (`@nodefony/realtime/testing`) : diffusion à tous les pairs,
    ordre par émetteur, pas de rejeu au démarrage, sceau vérifié (message non scellé ou mal
    scellé refusé quand un secret est posé), ordres de contrôle transportés, y compris sous
    une rafale qui sature la file d'envoi, espace réservé injecté refusé. Les drivers
    livrés qui ont des pairs (cluster, Redis) la passent — `loopback`, sans pair, n'a rien
    à y prouver ; un driver tiers s'y prouve. Une définition du contrat, pas une par driver.
    **Livré** : `src/packages/@nodefony/realtime/nodefony/testing/backplaneConformance.ts#runBackplaneConformance`,
    lanceur de tests passé par l'appelant ; le sceau exporté pour les drivers tiers
    (`sealBackplaneEnvelope`, `openBackplaneEnvelope` dans `@nodefony/realtime`). Vue rouge
    sur trois faux drivers (diffusion à un seul pair, rejeu au démarrage, secret ignoré) ;
    elle a trouvé un défaut du driver `cluster` : arrêté, il livrait encore à un handler reposé.
  - **Preuve** : fermeture et éjection par utilisateur à DEUX pods, bus de cluster ET Redis — le
    banc Redis saute sans `NF_REDIS_TEST_URL`, et la CI doit l'exercer (un saut compte vert).
- **Cas `transcript:<id>` en multi-pod** : l'audio arrive sur un pod, l'abonné au texte
  peut être ailleurs. Décision : préfixe `transcript:` déclaré diffusable **et** prédicat `allow`
  sur le motif `transcript:*` — la charge traverse, l'admission se rejoue sur chaque pod.
  L'affinité de pod est une option de déploiement, pas une règle. La fermeture traverse les pods
  par l'ordre de contrôle de la décision 4. À
  prouver : un éjecté sur le pod A, abonné sur le pod B, n'est pas servi par B.

- Usages : une notification `user:42` (sans média, sans agent), un salon fermé de jeu ou de
  collaboration, un appel.
- Écarté : un propriétaire dans l'événement (S7) ; une appartenance sur le bus (elle étendrait
  l'enveloppe, S6) ; une seconde voie d'application du prédicat dans realtime — sans
  `@nodefony/security`, rien n'est refusé et un avertissement le dit
  (`src/packages/@nodefony/realtime/nodefony/tests/unit/realtimeUnenforcedPolicy.attack.test.ts`).
- **Rupture si différé après 10.0 : NON**, parce que membre optionnel, notification neuve et API
  neuve sont additifs. Écrire maintenant « appartenance locale, ordres par nom diffusés » évite
  qu'une application s'appuie sur une portée cluster qu'on ne tient pas (S5).

**Décision (validée le 2026-10-31, revue contradictoire) : livrer à une identité est
une brique du framework (D1).** Le développeur écrit son chat — contrat, actions, base,
historique, salons ; le framework garantit qu'un message adressé à une personne
n'atteint qu'elle, sur tous ses onglets et tous les pods. La présence
d'un canal, d'abord laissée à l'application par cette décision, est portée par le framework
depuis ADR-0025 (P1).

- Surface : `getRealtimeHub<C>().publishToUser(id, charge)` côté serveur, `socket.onUser(handler)`
  côté navigateur — rien à déclarer.
- Mécanique, écrite une fois : le canal `user:<id>` (ADR-0021 §S10, `id` stable) ; une politique
  INTÉGRÉE — connexion authentifiée, admission par **égalité de chaîne** avec l'`id` du
  demandeur, jamais par découpage ; une fabrique intégrée ; le préfixe déclaré diffusable par le
  framework. Le verrou passant avant la fabrique et l'admission ne lisant que l'identité du
  demandeur, `user:999` (inexistant) et `user:bob` (pas le sien) reçoivent le MÊME refus : ni
  oracle d'existence, ni oracle de présence.
- Jamais d'abonnement d'office : l'onglet s'abonne quand son écran écoute. Mesuré sur le hub
  (10 000 canaux, trois passes) : **494 octets par onglet abonné**, envoi ~60 ns (~185 ns nom
  construit) — une application qui ne s'en sert pas paie zéro.
  Script : `.claude/skills/nodefony-load-test/scripts/micro/micro-user-channel.mjs`.
- Usages qui la justifient (socle : ≥ 3 hétérogènes) : notifier l'utilisateur 42 (S-rt-31), trois
  onglets (S-rt-4), alerte machine à un opérateur, inventaire privé d'un joueur, message privé.
- Réservée aux COMPTES : un visiteur anonyme n'a pas d'identifiant qui survive à une reconnexion ;
  le chat de support anonyme passe par un salon privé de l'application (`support:<id>` + `allow`).
- Écartés : l'assemblage à la main par chaque application (une dizaine de lignes, chaque oubli
  silencieux) ; un canal par paire `dm:<a>:<b>` (tri canonique, découpage d'un `:`, croissance
  en n²) ; un registre identité → connexions (`notifyUser`) — oracle de présence, annuaire, et
  hors canal il casse l'enveloppe figée (S6) ou devient un canal déguisé ; l'abonnement d'office.
- Les canaux de l'APPLICATION restent opt-in (`@RealtimeBroadcast`) : certains sont propres à un
  pod par nature (forage de Studio). L'oubli devient visible : compteur `localOnlyTotal` quand un
  bus est configuré, préfixes diffusés listés au démarrage (D5).
- Elle s'appuie sur `RealtimeIdentity.id`, l'identité d'admission.

**Décision (validée le 2026-10-31) : le handler d'entrée reçoit l'identité.**
`@RealtimeInbound` et `realtimeInbound()` reçoivent `who` (la même identité d'admission que
`allow`) en troisième argument, sans allocation par trame. Un flux attribué à haute fréquence —
frappe en cours, coups d'un joueur, mesures d'une sonde — passe ainsi par le canal, l'auteur pris
au serveur et non déclaré par le client. Limite écrite : identité figée au handshake, coupée au
tick de révocation ; un geste qui change un état passe par une route.

**Précision (validée le 2026-11-14) : la frappe d'un salon PRIVÉ parmi plusieurs passe
par une route.** Une entrée de canal est appelée par son nom EXACT (`chat:typing`), jamais par la
famille de salons (`chat:room:*`) : elle reçoit le salon visé en paramètre, et rien ne prouve que
l'émetteur y est admis — sans contrôle, n'importe quel connecté injecte « Untel écrit » dans un
salon privé. Le contrôle d'appartenance coûte alors autant dans l'entrée que dans une route, sans
les garanties de la route (identité revérifiée, schéma, `@IsGranted`). D'où la règle :

| Cas                                            | Le signal de frappe passe par                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------ |
| un salon UNIQUE, ou un canal sans appartenance | une entrée de canal (`@RealtimeInbound`, auteur pris au serveur)         |
| plusieurs salons dont certains PRIVÉS          | une route appelée sur la socket (`socket.post`), qui vérifie l'admission |

C'est la forme du chat de la démo (`ChatController.ts.tpl`, route `demo-chat-typing`) et la règle
enseignée par le skill livré `nodefony-add-realtime-channel` (« Route ou entrée de canal ? »). Écarté
pour l'instant : exposer au gestionnaire d'entrée « cette connexion est-elle admise sur ce canal ? »
(la marque existe par connexion) — cela rendrait l'entrée par salon sûre et gratuite, mais aucun
besoin mesuré ne le justifie aujourd'hui ; un ajout additif reste possible.

### 7. La reprise côté socket

**Décision (acceptée le 2026-10-29) :** aujourd'hui, la reconnexion **rejoue** chaque abonnement au `welcome`
(`src/nodefony/src/client/realtime/NodefonySocket.ts#NodefonySocket.replaySubscriptions`), sans
curseur ; la fabrique est rejouée au premier abonné. Demain (10.2, S3) : `subscribe
{ channel, since? }`. Le curseur est **par abonné** alors que la fabrique est partagée et
appelée une fois : il l'atteint par un retour élargi — à côté du `dispose` d'aujourd'hui, un objet
`{ dispose, resume?(since, reply) }`, où `reply` ne pousse qu'à **cette** connexion. La fabrique
décide : la suite depuis le curseur, l'état courant, ou rien. Sans curseur, rien ne change.

- Constaté par lecture : un serveur 10.0 **ignore** un champ inconnu dans `params` d'un
  `subscribe` — `src/packages/@nodefony/realtime/nodefony/src/server/RealtimeController.ts#channelParam`
  ne lit que `channel`, `src/nodefony/src/jsonrpc/index.ts#classifyJsonRpcFrame` ne juge pas
  `params`, `src/packages/@nodefony/security/nodefony/src/realtime/frameAuthorizer.ts#authorizeChannel`
  ne lit que le canal. C'est la condition de S3 ; elle se **prouve** par le contrôle de
  compatibilité entre versions (section 10).
- À écrire dans `src/packages/@nodefony/realtime/docs/protocole.md`, qui ne le dit pas : la
  reconnexion (rejeu au `welcome`, acquittement, curseur) et la fin de flux (`realtime:closed`).
- Conséquence de §6 décision 1 : le rejeu rappelle `allow` pour chaque canal qui le déclare — un
  exemplaire qui redémarre provoque N clients × M canaux appels en rafale. Prix normal d'« une
  fois par abonnement », écrit dans le TSDoc d'`allow` avec sa parade (cache court côté
  application) ; prouvé par les tests de l'admission.
- Usages : une discussion reprise au dernier message vu, une courbe au dernier point, des
  notifications manquées.
- Écarté : « l'instantané puis la suite » comme règle (un choix de protocole, S3) ; un curseur
  passé à la fabrique partagée par son premier appel (il ne servirait que le premier abonné).
- **Rupture si différé après 10.0 : NON**, parce que paramètre optionnel et retour élargi d'un
  rappel implémenté par l'application sont additifs.

### 8. La voix, au niveau transport seulement

**Décision (acceptée le 2026-10-29) :** un flux binaire **à sens unique** va sur un canal binaire de la socket
(section 3) : la transcription y suffit, la latence y compte moins. Une conversation **dans
les deux sens** choisit entre WebSocket et WebRTC **par la mesure**, selon un critère nommé
une fois ici : latence de bout en bout mesurée, comportement sur réseau mobile, annulation d'écho
haut-parleur ouvert. Opus par WebCodecs sur la socket et les options Opus de WebRTC sont deux
couches distinctes. Capture, contraintes micro, codec audio, découpage en trames et détection de
parole appartiennent à l'ADR média.

- Usages d'un flux binaire à sens unique : une dictée, la télémétrie d'un capteur, la
  synchronisation d'un document.
- Écarté : décider WebRTC ou WebSocket ici, sans mesure.
- **Rupture si différé après 10.0 : NON**, parce que tout vit sous des sous-chemins neufs.

### 9. La règle d'admission perf d'une évolution

**Décision (acceptée le 2026-10-29) :** rien n'entre sur le chemin d'une frame sans trois preuves, dans l'ordre :
(1) le **JS bâti** du chemin chaud comparé à la référence `HEAD`, bâtie hors de l'arbre par
`git archive` — jamais en copiant le `dist` courant ; (2) le banc A/B
`.claude/skills/nodefony-load-test/scripts/micro/micro-realtime-frame-ab.mjs`, chemins `inbound`,
`notify`, `binary` (et `publish`, à ajouter avant les abonnés identifiables), `--runs 15`, verdict sur **deux passages
de même signe** ; (3) le gate mémoire (`cd src/packages/@nodefony/http && npm run test:memory`,
ligne `[retention] WS JSON-RPC peer round-trips`, référence 0,29 Ko/itération).
Chiffres dans le commit si l'écart dépasse 5 %. Un générique effacé ne paie rien ; une vue sans
copie, une allocation à l'abonnement, un codec remplaçant `JSON.parse` se mesurent.

- **Rupture si différé après 10.0 : NON** — une méthode, pas une surface.

### 10. Les garde-fous — condition d'admission de toute évolution

**Décision (acceptée le 2026-10-29) :** les cinq contrôles ci-dessous, chacun vu **rouge** une fois.

| #   | Contrôle                                                                                                                                                                                                                                                       | État                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Qui le lance                                                                    |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 1   | compilation **neutre** du code partagé (`lib: ["ES2022"]`, `types: []`)                                                                                                                                                                                        | **livré** : `src/nodefony/tsconfig.shared.json`, vu rouge sur `Blob` puis `Buffer`                                                                                                                                                                                                                                                                                                                                                                            | `npm run typecheck` du cœur                                                     |
| 2   | contrat vérifié **dans les deux sens**                                                                                                                                                                                                                         | **livré** : `realtimeSharedContract.types.test.ts` — action manquante, forme fausse, entrée mal lue, canal hors `Emit`, inversion, nom de politique hors contrat, SSE — chacune un `@ts-expect-error` vu mordre                                                                                                                                                                                                                                               | `npm run typecheck` du paquet (`tsconfig.tests.json`)                           |
| 3   | suite de conformité **unique** d'`IRealtimeSocket`, contre les deux implémentations                                                                                                                                                                            | **livré** : `src/packages/@nodefony/realtime/nodefony/tests/helpers/socketConformance.ts#describeSocketConformance`, jouée contre `NodefonySocket` (câble en boucle) et `ServerRealtimeSocket` ; vue rouge sur chacune                                                                                                                                                                                                                                        | `npm test` du paquet realtime                                                   |
| 4   | fixtures d'octets **dorées** : accueil, requête, réponse, erreur, notification, trame à octets, par codec — **et l'enveloppe backplane**, trois champs plus sceau (`src/packages/@nodefony/realtime/nodefony/src/backplane/envelope.ts#sealBackplaneEnvelope`) | **livré dans Node** : `src/nodefony/src/tests/frameGolden.test.ts` (3 codecs) et `src/packages/@nodefony/realtime/nodefony/tests/unit/backplaneEnvelopeGolden.test.ts`, références sous `fixtures/golden/`, vues rouges sur une mutation symétrique ; dans un vrai navigateur : lot distinct. Un octet changé = rupture de fil **déclarée**, fixtures régénérées (`-u`) dans le même commit                                                                   | `npm test` du cœur et du paquet realtime ; navigateur : lot distinct            |
| 5   | compatibilité **entre versions** : client de la dernière version publiée ↔ serveur courant, et l'inverse                                                                                                                                                       | **livré** : `scripts/release/compat.mjs`, banc `src/packages/@nodefony/realtime/nodefony/tests/compat/crossVersion.compat.test.ts` ; référence lue sur npm (`scripts/release/release-core.mjs#referenceDeCompat`) ; vu rouge dans les deux sens. Rupture face à une référence en pré-version : acceptée et annoncée (semver §9) ; face à une stable : bloque (`scripts/release/release-core.mjs#verdictCompat`). Le serveur garde `v1` tant qu'il est annoncé | `npm run release:compat` — job `compat` de `release.yml`, dont `publier` dépend |

Gardé aussi : `src/packages/@nodefony/realtime/tsconfig.json` compile le **serveur** sans
le DOM (`lib: ["ESNext"]`, `types: ["node"]`) — un `window` y rougit au `npm run typecheck` du
paquet ; seul `tsconfig.tests.json` le réintroduit, ses tests important le client navigateur. Une
rupture de fil suit la politique de l'API : majeure, et une version de sous-protocole de plus.

- **Rupture si différé après 10.0 : NON** — mais sans le contrôle 5 une rupture de fil ne se
  verrait pas, et le contrôle 4 fixe les octets que la série 10 promet.

### Normes

| Norme                        | Ce qu'elle tranche ici                                                                                                                                                                                                                                      |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RFC 6455 §1.9, §4.2.2, §11.5 | le serveur choisit **un** sous-protocole parmi ceux offerts, ou aucun ; un nom se préfixe par un domaine, enregistrable à l'IANA — d'où `nodefony.jsonrpc.*.v1`                                                                                             |
| RFC 6455 §4.1                | le client **doit** échouer si le serveur répond un sous-protocole non offert : l'écho de `ws` ne viole rien, et ne décide rien (section 2)                                                                                                                  |
| RFC 6455 §5.6, §7.4.1        | une trame binaire est « arbitrary binary data whose interpretation is solely up to the application layer » — le routage par canal est une décision applicative ; `1008` politique (C2), `1009` trop gros (`maxPayload`), `1013` réessayer (contre-pression) |
| JSON-RPC 2.0 §1, §4.1, §5.1  | « transport agnostic » : une enveloppe, trois codecs ; une notification est une requête sans `id` (le canal) ; codes réservés, plage serveur `-32000` à `-32099` (refus du verrou)                                                                          |
| RFC 8949 §3.1, §8, §10       | type majeur 2 = octets sans base64 ; la notation diagnostique « is not meant to be parsed » — observation, jamais le fil ; longueurs et imbrication hostiles : borner avant d'allouer                                                                       |

### Contrôle de non-blocage — A2A

Une liaison A2A **personnalisée** sur WebSocket peut-elle se bâtir sur la socket sans que la socket
la connaisse ? Lu dans A2A 1.0.1 §5.8 et §12 (figé hors ligne).

| Ce que la liaison doit fournir                            | Par quoi, sans rien ajouter à la socket                                               |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| une URI versionnée par rupture (§5.8)                     | le sous-protocole versionné ou l'URL de l'endpoint — choix du contrôleur consommateur |
| opérations, résultats, erreurs équivalents (§12.1, §12.4) | des actions JSON-RPC d'un `RealtimeController` ; erreurs = objets JSON-RPC            |
| paramètres de service sans en-têtes (§12.3)               | un champ de `params`, nommé par la liaison                                            |
| flux, ordre, reconnexion, fin (§12.5)                     | canaux ; ordre S5 ; rejeu et curseur (section 7) ; `realtime:closed` (S4)             |
| authentification (§12.6)                                  | handshake, authentificateur, verrou de trame — déjà là                                |

**Pas empêché.** Seul écart, documentaire : `docs/protocole.md` doit écrire la reconnexion et la
fin de flux (section 7). Aucun vocabulaire d'A2A n'entre dans la socket.

## Alternatives écartées

- **Une room comme primitive** (1) : sans producteur, elle ne couvre pas le canal.
- **MessagePack, BSON, un décodeur maison avant le banc** (2).
- **Un format binaire à en-tête maison** (3) : une seconde grammaire, donc un second verrou.
- **Un quatrième générique positionnel, ou un premier générique surchargé** (4).
- **Deux copies de `decideSend`** (5) : deux règles qui divergent en silence.
- **L'appartenance sur le bus** (6) : elle étendrait l'enveloppe figée (S6).
- **Le curseur passé à la fabrique partagée** (7) : il ne servirait que le premier abonné.

## Conséquences

- Engagements de la série 10, au même titre que les décisions de gel : le nom `v1`, la
  lecture du codec dans l'accueil, l'accueil toujours en texte, le crochet brut hors verrou, les
  bornes neuves désactivées, l'appartenance locale au pod, les ordres par nom (fermer, éjecter un
  utilisateur) diffusés par un message ordinaire du backplane, sans méthode neuve sur `IBackplane`.
- Le contrat typé livre la forme figée d'`IRealtimeContract` au cœur (§4 : quatre clés, `Jsonify<T>` aux
  quatre points de réception, socket + SSE + webhook), `Listen` en troisième générique de
  `RealtimeController` avec défaut, les types utilitaires et `defineRealtimeContract` ; le lot du binaire routé BRANCHE le codec CBOR déjà écrit et publié
  (`src/nodefony/src/realtime/codec/`, `nodefony/cbor`) par `IFrameCodec`, les trois noms de
  sous-protocole et le routage par canal ; l'admission par identité et les abonnés identifiables, les canaux
  privés ; les garde-fous, les contrôles 2 à 5.
- **Preuves à apporter** : B1 à B4 vus rouges en débranchant ; un `Uint8Array` intact par
  le pilote Redis (S8) ; un champ inconnu dans `subscribe` ignoré par un serveur publié
  (contrôle 5) ; un éjecté sur un pod non servi par un autre ; le codec CBOR
  maison branché sur le pair, octets intacts sans copie au décodage ; le poids du moteur
  protobuf dans `nodefony/client` face à `.size-budgets.json` (avec le codec protobuf de la
  socket, le jour où il a un usage — §2 ; le chantier gRPC ne l'amène pas au client, ADR-0026 D12).
- Reste à décider : un tsconfig neutre pour le serveur du paquet realtime (section 10).
- `docs/protocole.md` écrit la reconnexion et la fin de flux avant qu'un protocole tiers s'y appuie.

## Références

- [ADR-0021](../0021-temps-reel-evenement-et-livraisons/) — le socle (S1 à S9) ·
  [ADR-0023](https://github.com/nodefony/nodefony-core/blob/main/docs/adr/0023-webhooks-evenements-et-abonnements.md) — les webhooks ·
  [ADR-0007](https://github.com/nodefony/nodefony-core/blob/main/docs/adr/0007-clientkernel-isomorphe-contrat-runtime-client.md) — le client isomorphe
- RFC 6455, The WebSocket Protocol — <https://www.rfc-editor.org/rfc/rfc6455>
- JSON-RPC 2.0 — <https://www.jsonrpc.org/specification>
- RFC 8949, CBOR — <https://www.rfc-editor.org/rfc/rfc8949>
- Protobuf, correspondance JSON canonique — <https://protobuf.dev/programming-guides/json/>
- A2A 1.0.1 — <https://a2a-protocol.org/v1.0.0/specification> (§5.8, §12)
- [Politique de compatibilité](../../guides/compatibilite/)
- Décisions de gel du protocole — commit `1df6614c1`
