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

package/docs/actions.md

@@ -274,10 +274,11 @@ Le trajet complet d'une requête, des étapes qu'elle traverse aux branches par
 
 ### Deux voies, un même registre
 
-| Voie                                                                             | Quand la choisir                                            |
-| -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `@RealtimeAction("nom")` (`realtimeDecorators.ts#RealtimeAction`)                | le cas courant — un nom fixe, une méthode, déclaratif       |
-| `realtimeActions()` (`RealtimeController.ts#RealtimeController.realtimeActions`) | la table est **calculée** (noms dynamiques, boucle, config) |
+| Voie                                                                             | Quand la choisir                                                                                                       |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `@RealtimeAction("nom")` (`realtimeDecorators.ts#RealtimeAction`)                | le cas courant — un nom fixe, une méthode, déclaratif                                                                  |
+| `realtimeActions()` (`RealtimeController.ts#RealtimeController.realtimeActions`) | la table est **calculée** (noms dynamiques, boucle, config)                                                            |
+| `realtimeActions()` **complète** d'un `ContractRealtimeController<C>`            | le contrôleur implémente un **contrat** : une méthode oubliée ne compile pas (voir « Un contrat pour les deux bouts ») |
 
 Les deux sont fusionnées au handshake, et **l'override gagne** en cas de conflit de nom : une
 classe peut ainsi remplacer une action héritée sans toucher au parent
@@ -304,6 +305,347 @@ Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts#Js
 > chercher d'erreur maison dans `@nodefony/realtime` : il n'y en a pas, et
 > `tests/unit/errorSurface.test.ts` refuse d'en exporter une que personne ne lève.
 
+## 🤝 Un contrat pour les deux bouts
+
+Sans contrat, chaque côté type ce qu'il **envoie**, jamais ce que l'autre **reçoit** ou
+**implémente**. Le navigateur appelle `request("orders:quote", …)` ; le serveur peut n'avoir
+aucune action de ce nom, ou lui donner une autre forme — tout compile, et l'erreur sort en
+production (`-32601`, ou une réponse de forme fausse). Un **contrat** se déclare UNE fois, et le
+compilateur vérifie les deux bouts.
+
+### Le contrat, les deux portes, le flux SSE
+
+Le contrat est une interface de **types seuls** : son fichier, partagé par les deux côtés,
+compile en zéro octet, et le navigateur qui l'importe ne tire aucun code serveur. Chaque côté
+entre ensuite par **sa** porte, et la direction (ce que j'envoie, ce que je reçois) est
+**calculée** — jamais réécrite à la main.
+
+```ts
+// ── shared/orders.ts — le contrat, déclaré UNE fois (types seuls) ──────────
+import type { IRealtimeContract } from "nodefony/client";
+
+export interface OrdersContract extends IRealtimeContract {
+  // ce que le serveur pousse (socket, flux SSE, webhook)
+  serverToClient: {
+    "orders:status": { orderId: string; at: Date };
+    [channel: `orders:user:${string}`]: { unread: number };
+  };
+  // ce que le client envoie sur un canal
+  clientToServer: { "orders:typing": { on: boolean } };
+  // les méthodes du serveur : le client appelle, le serveur répond
+  serverMethods: {
+    "orders:quote": { in: { orderId: string }; out: { total: number } };
+  };
+  // les méthodes du client : le serveur appelle, le client répond
+  clientMethods: {
+    "ui:confirm": { in: { text: string }; out: { ok: boolean } };
+  };
+}
+
+// ── frontend/src/orders.ts — la porte du CLIENT ─────────────────────────────
+import { NodefonySocket } from "nodefony/client";
+
+const socket = NodefonySocket.fromContract<OrdersContract>({
+  url: "/orders/realtime",
+});
+socket.on("orders:status", (m) => console.log(m.orderId, m.at)); // m.at : string (JSON)
+const quote = await socket.request("orders:quote", { orderId: "A-1" }); // { total: number }
+socket.register("ui:confirm", (p) => ({ ok: p.text.length > 0 }));
+void quote;
+
+// ── nodefony/controllers/OrdersRealtime.ts — la porte du SERVEUR ────────────
+import type { ContextType } from "@nodefony/http";
+import type { ContractServerEmit } from "nodefony";
+import { ContractRealtimeController, RealtimePolicy } from "@nodefony/realtime";
+
+@RealtimePolicy({ "orders:quote": { roles: ["ROLE_USER"] } })
+export class OrdersRealtime extends ContractRealtimeController<OrdersContract> {
+  constructor(context: ContextType) {
+    super("orders", context);
+  }
+
+  // TOUTES les méthodes du contrat, et cette table SEULE les sert.
+  protected realtimeActions() {
+    return {
+      "orders:quote": (p: { orderId: string }) => ({
+        total: p.orderId.length * 100,
+      }),
+    };
+  }
+
+  // Facultatif, canal par canal : accepter une entrée est une permission.
+  protected override realtimeInbound() {
+    return {
+      "orders:typing": (p: { on: boolean }) => {
+        void p.on; // NON FIABLE : le type n'est pas une validation
+      },
+    };
+  }
+
+  // Le flux SSE lit la MÊME carte que la socket.
+  async statusStream(): Promise<void> {
+    const sse = await this.renderSse<ContractServerEmit<OrdersContract>>();
+    await sse.send(
+      { orderId: "A-1", at: new Date() },
+      { event: "orders:status" },
+    );
+    sse.close();
+  }
+}
+```
+
+| Porte                                             | Ce qu'elle dérive du contrat                                                                                             |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `NodefonySocket.fromContract<C>()` (client)       | émet `clientToServer` · reçoit `serverToClient` · appelle `serverMethods` · implémente `clientMethods`                   |
+| `extends ContractRealtimeController<C>` (serveur) | émet `serverToClient` · reçoit `clientToServer` · implémente `serverMethods` · appelle `clientMethods` (`requestClient`) |
+| `getRealtimeHub<C>()` (service, tâche, jeu)       | `publish` n'accepte que les canaux de `serverToClient`, avec leur charge                                                 |
+| `ContractRealtimePublish<C>` (fabrique de canal)  | le `publish` reçu par `@RealtimeChannel` / `createRealtimeChannel`, même règle                                           |
+| `renderSse<ContractServerEmit<C>>()` (serveur)    | `event:` = un canal de `serverToClient`, la charge est celle du canal                                                    |
+| `@RealtimePolicy({ … })` (serveur)                | chaque nom doit être une méthode ou un canal du contrat                                                                  |
+
+Les quatre clés sont **facultatives** : un tableau de bord ne déclare que `serverToClient`, et son
+contrôleur n'écrit rien de plus que `extends ContractRealtimeController<C> {}` — la table des
+méthodes n'est due que si le contrat déclare des `serverMethods`. Une direction non déclarée reste
+libre.
+
+### Diffuser depuis un service — le même contrat
+
+Le cas le plus courant ne passe par aucun contrôleur : un service, une tâche, une boucle de jeu
+publient. Le hub se lit à travers le contrat, et une faute de frappe ne compile plus :
+
+```ts
+import { getRealtimeHub } from "@nodefony/realtime";
+import type { ChatContract } from "../shared/chat";
+
+const chat = getRealtimeHub<ChatContract>(); // même objet hub : 0 octet, 0 ns de plus
+chat.publish("chat:room", message); // charge vérifiée par le contrat
+getRealtimeHub().publish("n'importe:quoi", { x: 1 }); // sans paramètre : libre, comme avant
+```
+
+Une fabrique de canal déclare son `publish` de la même façon :
+`presence(_channel: string, publish: ContractRealtimePublish<ChatContract>)`. Le contrat est choisi
+par l'appelant : c'est le fichier partagé qui fait foi.
+
+> [!NOTE]
+> **Lire les noms.** `Contract…<C>` est la même chose que sa forme libre, lue à travers le contrat :
+> `RealtimeController` → `ContractRealtimeController<C>`, `RealtimePublish` →
+> `ContractRealtimePublish<C>`, `RealtimeHub` → `IContractRealtimeHub<C>`. `Typed…` type un handler
+> par ses types directs ; `…Of<X>` lit ce que porte une classe (`RealtimeContractOf`).
+
+### Deux cas réels — l'atelier et la partie
+
+**L'atelier : une mesure typée une fois, trois lecteurs.** Chaque machine pousse sa télémétrie
+sur son propre canal (`machine:<id>`). Le tableau de bord la lit par la socket, l'écran d'atelier
+— un simple navigateur, sans socket — par un flux SSE, et l'opérateur peut arrêter une machine.
+Un seul contrat, et la charge est la MÊME aux trois endroits.
+
+```ts
+// ── shared/plant.ts ─────────────────────────────────────────────────────────
+import type { IRealtimeContract } from "nodefony/client";
+
+export interface PlantContract extends IRealtimeContract {
+  serverToClient: {
+    [machine: `machine:${string}`]: {
+      temperature: number;
+      rpm: number;
+      at: Date;
+    };
+  };
+  serverMethods: {
+    "machine:stop": {
+      in: { machineId: string; reason: string };
+      out: { stopped: boolean };
+    };
+  };
+}
+
+// ── frontend/src/dashboard.ts — le tableau de bord ──────────────────────────
+import { NodefonySocket } from "nodefony/client";
+
+const plant = NodefonySocket.fromContract<PlantContract>({
+  url: "/plant/realtime",
+});
+plant.on("machine:press-07", (m) => {
+  if (m.temperature > 90) {
+    void plant.request("machine:stop", {
+      machineId: "press-07",
+      reason: "surchauffe",
+    });
+  }
+});
+
+// ── nodefony/controllers/PlantRealtime.ts — le serveur ──────────────────────
+import type { ContextType } from "@nodefony/http";
+import type { ContractServerEmit } from "nodefony";
+import { ContractRealtimeController, RealtimePolicy } from "@nodefony/realtime";
+
+@RealtimePolicy({
+  "machine:stop": { roles: ["ROLE_OPERATOR"] }, // arrêter une machine : un rôle
+  "machine:*": { authenticated: true }, // lire la télémétrie : être connecté
+})
+export class PlantRealtime extends ContractRealtimeController<PlantContract> {
+  constructor(context: ContextType) {
+    super("plant", context);
+  }
+
+  protected realtimeActions() {
+    return {
+      "machine:stop": (p: { machineId: string; reason: string }) => ({
+        stopped: p.machineId.length > 0 && p.reason.length > 0,
+      }),
+    };
+  }
+
+  // L'écran d'atelier : UN flux = UN canal, sans champ `event:`.
+  async machineStream(machineId: string): Promise<void> {
+    const sse =
+      await this.renderSse<
+        Pick<ContractServerEmit<PlantContract>, `machine:${string}`>
+      >();
+    await sse.send({ temperature: 71, rpm: 1450, at: new Date() });
+    void machineId;
+    sse.close();
+  }
+}
+```
+
+**La partie : les entrées du joueur, typées jusque dans le serveur.** Le client envoie ses
+déplacements soixante fois par seconde ; le serveur les reçoit typés, sans jamais les croire, et
+pousse l'état de la partie. Aucune méthode n'est demandée au serveur : la table est vide.
+
+```ts
+// ── shared/arena.ts ─────────────────────────────────────────────────────────
+import type { IRealtimeContract } from "nodefony/client";
+
+export interface ArenaContract extends IRealtimeContract {
+  clientToServer: { "arena:input": { dx: number; dy: number; seq: number } };
+  serverToClient: {
+    "arena:state": {
+      tick: number;
+      players: Array<{ id: string; x: number; y: number }>;
+    };
+  };
+}
+
+// ── frontend/src/arena.ts — le joueur ───────────────────────────────────────
+import { NodefonySocket } from "nodefony/client";
+
+const arena = NodefonySocket.fromContract<ArenaContract>({
+  url: "/arena/realtime",
+});
+let seq = 0;
+arena.publish("arena:input", { dx: 1, dy: 0, seq: ++seq });
+arena.on("arena:state", (s) => console.log(s.tick, s.players.length));
+
+// ── nodefony/controllers/ArenaRealtime.ts — le serveur ──────────────────────
+import type { ContextType } from "@nodefony/http";
+import { ContractRealtimeController } from "@nodefony/realtime";
+
+const MAX_STEP = 1;
+
+export class ArenaRealtime extends ContractRealtimeController<ArenaContract> {
+  constructor(context: ContextType) {
+    super("arena", context);
+  }
+
+  // Aucune méthode serveur dans ce contrat : aucune table à écrire.
+
+  // L'entrée est TYPÉE, mais vient du réseau : bornée avant d'être appliquée.
+  protected override realtimeInbound() {
+    return {
+      "arena:input": (input: { dx: number; dy: number; seq: number }) => {
+        const dx = Math.max(-MAX_STEP, Math.min(MAX_STEP, input.dx));
+        const dy = Math.max(-MAX_STEP, Math.min(MAX_STEP, input.dy));
+        this.notifyClient("arena:state", {
+          tick: input.seq,
+          players: [{ id: "p1", x: dx, y: dy }],
+        });
+      },
+    };
+  }
+}
+```
+
+Le serveur d'une vraie partie ne pousse évidemment pas l'état à chaque entrée : il les accumule et
+diffuse l'état à cadence fixe, par un canal partagé — voir
+[`cadence-et-contre-pression.md`](./cadence-et-contre-pression.md).
+
+### Ce que chaque bout reçoit — ce que JSON en fait
+
+Ce que j'**envoie** est le type déclaré ; ce que je **reçois** est `Jsonify<T>` : ce que JSON rend
+de ce type, quel que soit le codec. Une `Date` arrive en `string`, un membre fonction ou
+`undefined` disparaît, `bigint` n'a pas de forme JSON. Seul `Uint8Array` reste `Uint8Array` — en
+chaîne d'octets native sous le codec CBOR, sous la convention `{"$bytes":"<base64url>"}` sur une
+connexion texte dont l'application a activé le binaire, annoncée par le champ `bytes` de l'accueil :
+un client sans codec les relit aussi en `Uint8Array` (ADR-0022 §2).
+
+| 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                           | son `in`         | `Jsonify<T>` |
+| qui **appelle** une méthode (`request`, `requestClient`) | son `out`        | `Jsonify<T>` |
+| un composant, hook de canal (socket en tête)             | `serverToClient` | `Jsonify<T>` |
+
+`serverToClient: { meeting: { start: Date } }` : sans cette règle, `m.start.getTime()` compilait
+et plantait au navigateur ; avec elle, `m.start` est une `string` et l'éditeur le souligne.
+
+### Lire dans une vue — le hook prend la socket du contrat
+
+Dans React, Vue, Svelte ou Angular, la lecture passe par la **même** socket typée, donnée en
+premier argument du hook de canal. Le nom est contraint aux canaux de `serverToClient`, la charge
+est déduite — aucun générique écrit à la main, aucune carte recopiée.
+
+```ts
+export const chat = NodefonySocket.fromContract<ChatContract>({
+  url: "/chat/realtime",
+});
+
+const presence = useNodefonyChannelData(chat, "chat:presence", { present: [] }); // React, Vue
+useNodefonyChannel(chat, "chat:room", (m) => add(m)); // m : Jsonify<ChatMessage>
+nodefonyChannelData(chat, "chat:presence"); // Svelte
+injectNodefonyChannelData(chat, "chat:presence"); // Angular
+```
+
+Les hooks lisent les cartes de `NodefonySocket.on` (`client/realtime/observe.ts#ChannelPayload`) :
+une seule règle, quatre liaisons. La socket reste celle de l'application — le hook ne l'ouvre ni
+ne la ferme. La forme historique `useNodefonyChannelData<T>("canal")` reste valide, mais son `<T>`
+n'est vérifié par rien : une charge qui change côté serveur n'y casse aucune compilation.
+
+### Ce que le compilateur refuse
+
+| Faute                                                                | Où elle est refusée                                                  |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| une méthode de `serverMethods` **oubliée**                           | `realtimeActions()` du contrôleur                                    |
+| un handler de **forme fausse** (paramètres ou résultat)              | `realtimeActions()` / `realtimeInbound()`                            |
+| un nom de **politique** hors contrat (`"orders:qoute"`)              | `@RealtimePolicy` — l'erreur affiche `notInContract: "orders:qoute"` |
+| un canal émis **hors** `serverToClient`                              | `notifyClient`, `realtimeChannels()`, `renderSse`                    |
+| une entrée acceptée sur un canal que le **serveur** émet (inversion) | `realtimeInbound()`                                                  |
+| une charge fausse sur un canal ou une méthode connus                 | client et serveur                                                    |
+| une diffusion de service hors contrat (nom ou charge)                | `getRealtimeHub<C>().publish`, `ContractRealtimePublish<C>`          |
+| une charge **scalaire** (`3`, `"ok"`) — refusée aussi à l'exécution  | `getRealtimeHub<C>().publish`, `ContractRealtimePublish<C>`          |
+| un canal lu **hors** `serverToClient` dans une vue                   | hooks de canal React, Vue, Svelte, Angular (socket en tête)          |
+
+> [!IMPORTANT]
+> **La table sert SEULE les méthodes d'un contrat — c'est une règle de performance.** N'ajoute pas
+> `@RealtimeAction` à une méthode déjà servie par la table : au handshake, le décorateur fabrique
+> un handler que la table écrase aussitôt, à **chaque connexion**, avec un appel de plus par
+> requête, et l'injection des paramètres décorés (`@Body`…) saute sans un mot. La politique d'une
+> méthode se pose sur la classe, par `@RealtimePolicy`, écrite une seule fois. Des handlers qui
+> n'ont pas besoin de `this` se rangent dans une table **constante** du module, rendue telle
+> quelle : aucune allocation par connexion.
+
+À savoir encore :
+
+- **Le type n'est pas une validation.** Les paramètres reçus restent NON FIABLES ; la garde de
+  canal (politique, `allow`) s'applique à toutes les livraisons.
+- **Côté client, les noms de canaux restent ouverts** (canaux dynamiques, de plateforme) :
+  `publish` et `on` acceptent tout nom, et typent la charge d'un nom déclaré.
+- **`realtimeChannels()` surchargée** : TypeScript ne donne pas son type de retour à une méthode
+  qui surcharge ; écrire `["orders:status" as const]` ou annoter le retour.
+- **Un `renderSse()` sans paramètre** reste un flux libre (la porte MCP en est un).
+- **Le webhook** lira la même carte quand l'émission applicative existera (en 10.1, #70).
+
 ## 🔐 Autorisation — qui peut appeler quoi
 
 > [!IMPORTANT]
@@ -339,7 +681,24 @@ browse() { … }
 ```
 
 Ouvrir une action reste donc possible — mais c'est désormais un acte **délibéré et lisible à la
-déclaration**, au lieu d'un silence. Si une politique est déjà déclarée sous le même nom (canal
+déclaration**, au lieu d'un silence.
+
+Une action servie par la **table** de `realtimeActions()` n'a pas de décorateur où écrire sa
+politique : elle prend le même défaut fermé, et sa politique se pose **sur la classe**, par
+`@RealtimePolicy` (`realtimeDecorators.ts#RealtimePolicy`) — écrite une fois, à la définition de
+la classe, dans le même registre :
+
+```ts ignore
+@RealtimePolicy({
+  "orders:quote": { roles: ["ROLE_SALES"] },
+  "orders:user:*": { authenticated: true }, // un motif garde une famille de canaux
+})
+class OrdersRealtime extends ContractRealtimeController<OrdersContract> { … }
+```
+
+Sur un contrôleur de contrat, `@RealtimePolicy` lit le contrat sur la classe : un nom mal
+orthographié ne compile pas, au lieu de garder un canal fantôme pendant que le vrai reste au
+défaut. Si une politique est déjà déclarée sous le même nom (canal
 homonyme), elle est conservée : le défaut ne rétrograde jamais une règle plus stricte.
 
 ### Situation 2 — les namespaces réservés portent un plancher
@@ -406,7 +765,7 @@ rien ne change pour elle, ni comportement ni coût.
 > ferme la socket en `4001` si la session est morte (`RealtimeHub.ts#RealtimeHub.probe`). Après une
 > déconnexion, une action peut donc encore voir l'ancien utilisateur pendant cette fenêtre. Pour
 > une écriture sensible — paiement, droits, suppression — passe par une route
-> `POST + WEBSOCKET` appelée par `socket.mutate()` : ce pont revalide l'identité à **chaque**
+> `POST + WEBSOCKET` appelée par `socket.post()` : ce pont revalide l'identité à **chaque**
 > appel et porte la clé d'idempotence.
 
 ### La règle DEV-only
@@ -472,21 +831,23 @@ fois ? »**.
 | ------------------------------ | ------------------------------ | ------------------------------------ |
 | `nodefony:kernel:ping`         | oui — lecture pure             | oui                                  |
 | `nodefony:kernel:gc`           | oui — l'effet est un cycle GC  | oui, mais coûteux (pause du process) |
+| `nodefony:realtime:throughput` | oui — charge déterministe      | oui, mais jusqu'à 1 Mo par appel     |
 | `api.request` en lecture       | oui — c'est un `GET`           | oui                                  |
 | `nodefony:scaffold:cancel`     | oui — annuler deux fois annule | oui                                  |
 | `nodefony:scaffold:run`        | **non** — crée un travail      | **non** : deux appels, deux jobs     |
-| une mutation (`socket.mutate`) | **non** par nature             | oui, **avec une clé d'idempotence**  |
+| une écriture (`socket.post`)   | **non** par nature             | oui, **avec une clé d'idempotence**  |
 
-Pour les mutations passant par le pont API, la clé n'est pas une convention : elle est **exigée
-par la signature** de `mutate()` (`NodefonySocket.ts#NodefonySocket.mutate`), et c'est la garde `@Idempotent`
+Pour les écritures passant par le pont API, la clé n'est pas une convention : la socket la **pose
+seule** sur chaque `post`/`put`/`patch`/`delete` (`NodefonySocket.ts#NodefonySocket.post`), la
+trame rejouée après une reconnexion porte la même, et c'est la garde `@Idempotent`
 (`routerDecorators.ts#Idempotent`) qui, côté serveur, reconnaît le rejeu et rend la réponse déjà calculée
 au lieu de refaire l'effet.
 
 ```ts ignore
-await socket.mutate("/nodefony/security/api/apikeys/42/revoke", {
-  method: "POST",
-  idempotencyKey: crypto.randomUUID(), // rejouer cette frame ne révoque qu'une fois
-});
+// rejouer cette trame ne révoque qu'une fois — la clé est posée par la socket
+await socket.post("/nodefony/security/api/apikeys/42/revoke");
+// dédoublonner une INTENTION (double clic) : l'écran fournit sa clé
+await socket.post("/orders", panier, { idempotencyKey: panier.id });
 ```
 
 > [!IMPORTANT]
@@ -548,13 +909,53 @@ socket, avec la même garde et le même résultat qu'en REST — `invokeApiReque
 `realtimeApiRequest()` (`RealtimeController.ts#RealtimeController.realtimeApiRequest`).
 
 ```ts ignore
-const modules = await socket.request("/nodefony/kernel/api/modules");
+const modules = await socket.get("/nodefony/kernel/api/modules");
+const { sentAt } = await socket.post("/chat/send", { text: "salut" });
 ```
 
-La forme se discrimine toute seule : un chemin commence par `/`, jamais un nom d'action —
-`NodefonySocket.request()` (`NodefonySocket.ts#NodefonySocket.request`). Écris une action RPC pour ce qui n'a de sens **que** sur la socket ;
-passe par le pont pour tout ce qui est déjà une route. Le détail du pont vit dans le
-[vocabulaire](./vocabulaire.md) et l'[architecture](./architecture.md).
+Chaque méthode porte le **verbe HTTP** que la route déclare — `get`, `post`, `put`, `patch`,
+`delete` (`NodefonySocket.ts#NodefonySocket.get`) : une route `methods: ["POST", "WEBSOCKET"]` s'appelle
+`socket.post(…)`, rien d'autre à apprendre. `request()` reste l'appel d'une **action RPC** par son nom.
+Écris une action RPC pour ce qui n'a de sens **que** sur la socket ; passe par le pont pour tout ce
+qui est déjà une route. Le détail du pont vit dans le [vocabulaire](./vocabulaire.md) et
+l'[architecture](./architecture.md).
+
+### Le contrat type les routes
+
+Sans contrat, `get` et `post` rendent `unknown` et acceptent n'importe quel corps. Le contrat de
+l'application (`IRealtimeContract`, `RealtimeEventMap.ts#IRealtimeContract`) les type par la clé
+`serverRoutes` : `"<VERBE> <chemin>"` → le schéma que la route **valide**, référencé par `typeof`
+(une seule source — jamais une copie), et ce qu'elle rend.
+
+```ts ignore
+// shared/chatContract.ts — types seuls, aucun octet dans le navigateur
+import type { SendBody } from "./chatSchemas";
+export interface ChatContract extends IRealtimeContract {
+  serverRoutes: {
+    "POST /chat/send": { body: typeof SendBody; result: { sentAt: number } };
+  };
+}
+
+// navigateur
+const chat = NodefonySocket.fromContract<ChatContract>({
+  url: "/chat/realtime",
+});
+await chat.post("/chat/send", { text: "salut" }); // { sentAt: number }
+await chat.post("/chat/send", { texte: "x" }); // ✗ ne compile pas
+```
+
+Le contrat est un **type** : il ferait compiler un appel vers une route absente. Le contrôleur qui
+l'implémente déclare donc la **valeur** — la table statique `serverRoutes`, `satisfies
+ContractRouteSchemas<C>` — et le démarrage la confronte aux routes montées
+(`contractRoutes.ts#assertContractRoutes`) : route absente, route sans transport `WEBSOCKET` pour ce
+verbe, ou autre schéma que celui que la route valide → démarrage refusé, l'entrée nommée. Un
+chemin hors contrat reste libre. Une route à **paramètre de chemin** se déclare par son gabarit
+(`"GET /chat/messages/{id}": { params: typeof IdParams; result }`) et s'appelle en le nommant :
+`chat.get("/chat/messages/{id}", { params: { id } })` — la socket encode chaque valeur pour son
+segment (`runtime/routePath.ts#fillRoutePath`) et refuse une valeur manquante, vide, `.` ou `..`.
+Seuls des segments `{nom}` entiers se déclarent (`routePath.ts#isSimpleRouteTemplate`) : une
+contrainte passe par `requirements`. Le chat complet, messages privés compris :
+[cookbook](./cookbook-chat.md#quatre--un-contrat-pour-les-deux-côtés--lenvoi-et-les-messages-privés-typés).
 
 ## ⚠️ Pièges
 
@@ -638,7 +1039,28 @@ describe("ChatController — actions", () => {
 C'est l'attribut `user` du jeton que `@CurrentUser()` rend. Pour éprouver un **refus** (`@IsGranted`,
 `policy` de canal), il faut en plus le verrou de frame de `@nodefony/security`, passé en
 `frameAuthorizer` : `@nodefony/realtime` ne connaît pas la sécurité, et sans ce verrou une règle
-déclarée n'est appliquée par personne — en test comme en production. La table des membres du
+déclarée n'est appliquée par personne — en test comme en production.
+
+`@nodefony/security/testing` fournit les deux pièces, et c'est la forme à préférer au jeton écrit à
+la main ci-dessus : `createTestIdentity({ identifier, roles })`
+(`security/nodefony/testing/index.ts#createTestIdentity`) rend l'identité authentifiée, et
+`createTestFrameAuthorizer(getRealtimeHub())` (`security/nodefony/testing/index.ts#createTestFrameAuthorizer`) le **vrai**
+verrou du pare-feu — même fabrique, même hiérarchie de rôles, mêmes canaux système qu'au runtime.
+Un verrou factice qui ne regarde que `isAuthenticated()` laisse passer au vert un canal mal protégé.
+
+````ts ignore
+import { getRealtimeHub } from "@nodefony/realtime";
+import { createRealtimeHarness } from "@nodefony/realtime/testing";
+import {
+  createTestFrameAuthorizer,
+  createTestIdentity,
+} from "@nodefony/security/testing";
+
+const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+  identity: createTestIdentity({ identifier: "bob", roles: ["ROLE_USER"] }),
+  frameAuthorizer: createTestFrameAuthorizer(getRealtimeHub()),
+});
+``` La table des membres du
 harnais et l'exemple de refus sont dans le `README.md` du paquet, section « Tester un controller ».
 `nodefony create controller --kind realtime` génère ce test, identité comprise, quand l'application
 porte la sécurité.
@@ -656,3 +1078,4 @@ Couverture : `npm run coverage` dans `@nodefony/realtime`.
 - La garde qui décide, côté HTTP comme WebSocket → [firewall](../../security/docs/firewall.md)
 - Les signatures exactes ne sont pas recopiées ici : elles vivent dans le graphe symbolique
   `.ai/symbols.json`, régénéré depuis les TSDoc du code.
+````

package/docs/architecture.md

@@ -344,11 +344,11 @@ La pile se lit de haut en bas ; chaque étage ne connaît que son voisin du dess
 dispatch des notifications, gestion des erreurs, `dispose()` propre. Deux points
 d'interception y sont posés :
 
-- `beforeDispatch` (`JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`) — un verrou **synchrone** appelé avant tout
+- `beforeDispatch` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`) — un verrou **synchrone** appelé avant tout
   traitement de frame. Il rend `true`/`false`. Un refus sur une requête produit
   `-32001 unauthorized` ; sur une notification, la frame est jetée
   (`JsonRpcPeer.ts#JsonRpcPeer.receive`).
-- `onFrameAudit` (`JsonRpcPeer.ts#JsonRpcPeerOptions.onFrameAudit`) — la trace des événements protocolaires notables
+- `onFrameAudit` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.onFrameAudit`) — la trace des événements protocolaires notables
   (frame invalide, refusée, méthode inconnue, erreur interne).
 
 La contrainte de synchronisme n'est pas un oubli : un `await` par frame coûterait une
@@ -445,7 +445,8 @@ Les étapes, dans l'ordre exact du code :
    est révocable, préfixes de canaux broadcast, canaux entrants.
 6. **Message de bienvenue** `realtime:welcome` : canaux et méthodes découvrables, plus
    l'identité résolue (type, authentifié ou non, rôles, portées). Le client sait **qui il
-   est** sans appeler la moindre route.
+   est** sans appeler la moindre route. Le champ `codec`, quand il est posé, dit le codec de
+   trame des frames suivantes ; absent, c'est JSON-RPC texte (ADR-0022 §2).
 
 À la fermeture, un unique `onFinish` (`RealtimeController.ts#RealtimeController.onHandshake`) fait le ménage complet :
 désabonnement de chaque canal tenu, retrait des deux registres, `fireClose()` du transport,
@@ -647,6 +648,38 @@ sa recette mérite qu'on s'y arrête :
 > celle qui ne lève aucune erreur. L'`originId` est résolu à la construction : coût nul par
 > message.
 
+### Des octets sur le bus
+
+JSON ne sait pas porter des octets : un `Uint8Array` y devient un objet ordinaire
+(`{"0":1,"1":2}`), sans erreur. Les octets traversent donc le bus par une voie à eux, ouverte
+quand le serveur a un codec binaire (`codec: "cbor"`, [configuration](configuration.md)) :
+
+- **`redis`** : un **second canal**, nommé d'après le codec
+  (`nodefony:realtime:<cloison>:nodefony.jsonrpc.cbor.v1`,
+  `RedisBackplane.ts#resolveRedisBytesChannel`). Il porte la même enveloppe
+  `{ channel, payload, originId }`, encodée en CBOR, octets natifs dans `payload`, scellée
+  comme le texte. Une charge sans octets garde le canal texte : un serveur plus ancien, qui
+  n'écoute pas le second canal, continue de recevoir tout le reste.
+- **`cluster`** : le master forke ses workers en sérialisation `advanced` (clonage
+  structuré) — un `Uint8Array` traverse le relais tel quel, sans codec ni sceau : l'IPC ne
+  quitte pas la machine.
+
+Le hub ne confie des octets au bus que si le driver les accepte
+(`IBackplane.enableBytes`, `RealtimeHub.ts#RealtimeHub.publish`). Sinon il les garde sur le
+serveur qui les publie, et un avertissement de plateforme, émis une seule fois, nomme le canal.
+
+| Charge publiée sur un canal diffusé    | Abonnés de ce serveur | Autres serveurs, codec binaire + driver capable | Autres serveurs, sinon         |
+| -------------------------------------- | --------------------- | ----------------------------------------------- | ------------------------------ |
+| valeur JSON (`{ text: "bonjour" }`)    | reçue                 | reçue                                           | reçue                          |
+| `Uint8Array`                           | reçue, intacte        | reçue, intacte                                  | **non envoyée**, avertissement |
+| objet qui **contient** un `Uint8Array` | reçue, intacte        | reçue, intacte                                  | **non envoyée**, avertissement |
+| autre vue typée, `ArrayBuffer`         | reçue, intacte        | **non envoyée**, avertissement                  | **non envoyée**, avertissement |
+
+Sans codec binaire, seule la charge de premier niveau est examinée : chercher des octets au
+fond d'un objet coûterait sur chaque publication d'une application qui n'en publie pas. Un
+objet qui contient des octets sans codec binaire reste donc déformé sur le bus — comme il
+l'est déjà pour les navigateurs, qui le reçoivent en JSON.
+
 ### Le cloisonnement du canal Redis
 
 Le canal pub/sub de base est `nodefony:realtime` (`RedisBackplane.ts#REDIS_RT_CHANNEL`). Problème : le
@@ -693,6 +726,48 @@ Le module se déclare non critique (`src/packages/@nodefony/realtime/index.ts`)
 tout repli est annoncé. Enfin, `enabled: false` rend le module totalement inerte : ni API
 d'administration, ni backplane, ni sonde.
 
+### Écrire un driver, et le prouver
+
+Un driver mal réglé compile, démarre et perd des messages sans un mot. Les exigences qui
+l'en gardent sont écrites sur le contrat (`IBackplane.ts#IBackplane`) ; trois d'entre elles
+piègent tout journal partitionné :
+
+- **chaque serveur lit TOUT** — un groupe de lecteurs par serveur ; un groupe partagé
+  répartirait les messages, et un serveur sur deux ne verrait qu'une partie du trafic ;
+- **l'ordre par émetteur** — la clé de partition est l'`originId`, jamais le canal ;
+- **aucun rejeu au démarrage** — on lit à partir du dernier message : relue depuis le
+  début, une fin de partie fermerait la partie rouverte depuis.
+
+Dès que le bus quitte la machine, le driver **scelle** ses messages avec le sceau des
+drivers livrés, exporté pour lui : `sealBackplaneEnvelope` à l'émission,
+`openBackplaneEnvelope` à la réception (`envelope.ts#sealBackplaneEnvelope`).
+
+La preuve est la même pour tous : `runBackplaneConformance`, exportée par
+`@nodefony/realtime/testing` (`backplaneConformance.ts#runBackplaneConformance`). Elle
+relie plusieurs pairs du driver sur un même bus et vérifie la diffusion à tous, l'ordre,
+l'absence de rejeu, le sceau, le transport des ordres de contrôle, le refus de l'espace
+réservé à l'entrée du hub, le remplacement du handler et l'arrêt. Les drivers `cluster` et
+`redis` la passent dans le dépôt ; `loopback`, qui n'a aucun pair, n'a rien à y prouver.
+
+```typescript
+import { describe, it } from "vitest";
+import { runBackplaneConformance } from "@nodefony/realtime/testing";
+
+// Chaque appel rend un pair NEUF, relié au même bus, non démarré.
+runBackplaneConformance(
+  "mon-bus",
+  (secret) => new MonBackplane({ url, secret }),
+  {
+    describe,
+    it,
+  },
+);
+```
+
+Le lanceur de tests est passé, pas importé : la suite tourne sous n'importe quel lanceur
+qui fournit `describe` et `it`. Un bus lent relève `quietMs`, le silence attendu avant de
+conclure qu'un message refusé n'arrivera pas.
+
 ## 🧩 Extension — brancher son propre fond de panier
 
 Trois voies, de la plus déclarative à la plus directe.
@@ -741,10 +816,10 @@ refonte. Ici, seulement **où** ils sont ; le **quoi** et le **comment** sont da
 
 | Point de greffe              | Étage     | Moment         | Ancrage                                                |
 | ---------------------------- | --------- | -------------- | ------------------------------------------------------ |
-| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts#RealtimeHub.publishLocal`              |
-| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.unsubscribe`               |
-| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts#RealtimeHub.markBroadcastChannel`      |
-| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.setBackplane`              |
+| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts#RealtimeHub.checkOrigin`               |
+| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.useAuthenticator`          |
+| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts#RealtimeHub.setFrameAuthorizer`        |
+| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.registerChannelPolicy`     |
 | Audit de frame               | protocole | sur refus      | `RealtimeController.ts#RealtimeController.onHandshake` |
 
 Deux propriétés architecturales méritent d'être notées ici, parce qu'elles expliquent des
@@ -776,7 +851,7 @@ un débit.
 | Back-pressure  | `maxBufferedAmount`, `totalBufferedAmount`, `slowConsumers`, `drops` | le risque mémoire numéro un      |
 | Fond de panier | `backplane` (la carte d'identité de `describe()`)                    | ce qui est réellement branché    |
 
-Le contrat complet est `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`). La version enrichie
+Le contrat complet est `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`). La version enrichie
 `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) y ajoute l'identifiant d'instance et la sonde
 process, plus — si elles sont disponibles — les sondes ORM et les compteurs d'erreurs. Deux
 chemins de lecture, un seul producteur :