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

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" });
+```
+
+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
 ```
 
-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).
+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
 
@@ -565,6 +966,7 @@ passe par le pont pour tout ce qui est déjà une route. Le détail du pont vit
 | `-32601 method not found`                                           | nom mal orthographié, ou action déclarée sur un **autre** endpoint                 | vérifier `socket.serverMethods` — c'est la liste réelle de CETTE connexion                   |
 | `-32603 internal error` sans détail                                 | un `throw` ordinaire est rendu opaque au client (Zero Trust)                       | lever une `RpcError` avec un code et un message publiables                                   |
 | `api.request` rejeté avec `data.status: 422`                        | la route invoquée valide son entrée (`schema`, ou une `ZodError` de l'action)      | lire `data.fields` : chaque champ fautif, sa partie (`in`) et son message                    |
+| `api.request` rejeté avec `data.status: 429`                        | la route borne le débit de l'appelant                                              | attendre `data.retryAfter` secondes (l'en-tête `Retry-After` de la même route en HTTP)       |
 | `-32001 unauthorized` sur une action légitime                       | le nom commence par `nodefony:`, le namespace réservé à la plateforme              | renommer hors de `nodefony:`, ou obtenir `ROLE_NODEFONY_ADMIN`                               |
 | Une action est refusée à un anonyme alors qu'on la croyait publique | une action est fermée par défaut (`{ authenticated: true }`)                       | déclarer `{ authenticated: false }` pour l'ouvrir ; un rôle se pose par une règle de préfixe |
 | Un travail relancé crée deux jobs                                   | action non idempotente rejouée après une reconnexion                               | action compagnon d'annulation, ou identifiant fourni par l'appelant + mémorisation           |