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

package/docs/decorateurs.md

@@ -49,10 +49,10 @@ flowchart TD
 
 1. **À l'import**, chaque décorateur appelle `Reflect.defineMetadata` et rend la main. Zéro route
    créée, zéro service résolu.
-2. **Au montage**, `controller()` (`routerDecorators.ts:189`) relit ces métadonnées et fabrique les
-   objets `Route` ; `controllers()` (`routerDecorators.ts:111`) accroche le contrôleur au module sur
+2. **Au montage**, `controller()` (`routerDecorators.ts#controller`) relit ces métadonnées et fabrique les
+   objets `Route` ; `controllers()` (`routerDecorators.ts#controllers`) accroche le contrôleur au module sur
    le hook `onBoot` du kernel.
-3. **À la première requête** de chaque route, `resolveActionMeta()` (`routerDecorators.ts:1669`)
+3. **À la première requête** de chaque route, `resolveActionMeta()` (`routerDecorators.ts#resolveActionMeta`)
    consolide toutes les étiquettes de l'action en **un objet figé** posé sur la route. Les requêtes
    suivantes ne lisent plus aucune métadonnée.
 
@@ -100,21 +100,23 @@ décorateur supprime la double vérité** : la déclaration vit sur l'action qu'
 
 ### Le contrat TypeScript — décorateurs _legacy_, et pourquoi ça compte
 
-Nodefony utilise le format **legacy** de TypeScript : `experimentalDecorators: true` **et**
-`emitDecoratorMetadata: true` (`tsconfig.json:5-6`, repris par le module —
-`framework/tsconfig.json:5-6`). Ce n'est pas un détail historique, c'est ce qui rend possible :
+Nodefony utilise le format **legacy** de TypeScript : `experimentalDecorators: true` (dans le
+`tsconfig.json` racine, repris par le module — `framework/tsconfig.json`). Ce n'est pas un détail
+historique : c'est ce qui rend possibles les **décorateurs de paramètre** (`@Param`, `@Body`…, et
+`@Inject("nom")` côté conteneur) — le format standard ES ne les propose pas.
 
-- les **décorateurs de paramètre** (`@Param`, `@Body`…) — le format standard ES ne les propose pas ;
-- l'**injection par type** du conteneur : `emitDecoratorMetadata` fait émettre au compilateur la
-  liste des types du constructeur sous la clé `design:paramtypes`, que l'injecteur relit pour
-  résoudre les dépendances sans les nommer (cf `injectable()`, `kernelDecorator.ts:135`).
+`emitDecoratorMetadata`, en revanche, vaut **`false`** : Nodefony ne lit aucun type émis par le
+compilateur. Une dépendance de constructeur se **nomme** par `@Inject("nom")`
+(`kernelDecorator.ts#Inject`) ; un paramètre non nommé reçoit l'argument positionnel, ou
+`undefined`, quel que soit son type ([ADR-0018](../../../../../docs/adr/0018-decorateurs-sans-metadonnees-de-type.md)).
+Ne le repasser à `true` que pour une bibliothèque tierce qui lit les métadonnées `design:*`.
 
-Concrètement, dans une app générée par `nodefony create app`, ces deux options sont **déjà** dans le
-`tsconfig.json`. Tu n'as rien à faire — sauf si tu pars d'un `tsconfig` à toi : sans elles, les
-décorateurs ne compilent pas.
+Concrètement, dans une app générée par `nodefony create app`, ces options sont **déjà** dans le
+`tsconfig.json`. Tu n'as rien à faire — sauf si tu pars d'un `tsconfig` à toi : sans
+`experimentalDecorators`, les décorateurs ne compilent pas.
 
 > [!WARNING]
-> `reflect-metadata` doit être chargé **avant** tout décorateur. `routerDecorators.ts:1` l'importe
+> `reflect-metadata` doit être chargé **avant** tout décorateur. `routerDecorators.ts` l'importe
 > pour toi dès que tu importes un décorateur du framework — mais si tu écris ton propre décorateur
 > dans un fichier chargé plus tôt, mets-y `import "reflect-metadata";` en tête.
 
@@ -124,16 +126,16 @@ Trois partis pris expliquent la forme de cette surface, et un développeur qui l
 jamais surprendre.
 
 **1 — Un décorateur n'écrit QUE des métadonnées.** Aucun décorateur du framework ne contient de
-logique de sécurité, de session ou d'idempotence. `IsGranted()` (`routerDecorators.ts:903`) pose une
+logique de sécurité, de session ou d'idempotence. `IsGranted()` (`routerDecorators.ts#IsGranted`) pose une
 clause ; c'est le `Resolver` qui appellera le moteur d'autorisation, **résolu par son nom** dans le
-conteneur (`Resolver._enforceSecurity()`, `Resolver.ts:853`). Pourquoi ce détour : `@nodefony/framework`
+conteneur (`Resolver._enforceSecurity()`, `Resolver.ts#Resolver._enforceSecurity`). Pourquoi ce détour : `@nodefony/framework`
 ne dépend **pas** de `@nodefony/security` — sans ça, les deux modules formeraient un cycle. Le prix à
 payer est visible : une route gardée alors que le module `security` est absent renvoie **403**, pas
-une erreur de démarrage (fail-closed, `Resolver.ts:860`).
+une erreur de démarrage (fail-closed, `Resolver.ts#Resolver._enforceSecurity`).
 
 **2 — Tout est figé une fois, puis relu en O(1).** Les métadonnées de l'action sont consolidées au
-premier passage dans `computeActionMeta()` (`routerDecorators.ts:1632`) puis gelées sur la route.
-L'objet `RouteActionMeta` (`routerDecorators.ts:1436`) est **partagé par toutes les requêtes** — le
+premier passage dans `computeActionMeta()` (`routerDecorators.ts#computeActionMeta`) puis gelées sur la route.
+L'objet `RouteActionMeta` (`routerDecorators.ts#RouteActionMeta`) est **partagé par toutes les requêtes** — le
 framework ne le mute jamais, et ton code non plus. Une action non décorée obtient des champs à `null`,
 ce qui vaut **zéro branche** dans le chemin chaud.
 
@@ -274,7 +276,7 @@ Six familles, **36 décorateurs**, un seul fichier source. Le tableau de synthè
 | **Méthodes HTTP** | Quand l'action répond | `@Get` `@Post` `@Put` `@Patch` `@Delete` `@Options` `@Head` `@All` |
 | **Paramètres** | Ce que l'action reçoit en arguments | `@Param` `@Query` `@Body` `@Headers` `@Cookie` `@Session` `@CurrentUser` `@Req` `@Res` `@UploadedFile` `@UploadedFiles` |
 | **Réponse** | Statut, en-têtes, redirection | `@HttpCode` `@Header` `@Redirect` |
-| **Sécurité** | Qui passe, qui décide, quelles défenses | `@IsGranted` `@RequireScope` `@Anonymous` `@BypassFirewall` `@Csp` `@CsrfProtect` `@CsrfExempt` |
+| **Sécurité** | Qui passe, qui décide, quelles défenses | `@IsGranted` `@RequireScope` `@RequireAuthentication` `@Anonymous` `@BypassFirewall` `@Csp` `@CsrfProtect` `@CsrfExempt` |
 | **Cycle de la requête** | Session, anti-rejeu | `@UseSession` `@Idempotent` |
 
 > Tous s'importent depuis `"@nodefony/framework"` — jamais par un chemin relatif interne.
@@ -284,43 +286,43 @@ Six familles, **36 décorateurs**, un seul fichier source. Le tableau de synthè
 <!-- prettier-ignore -->
 | Décorateur | Cible | Effet | Exemple |
 | --- | --- | --- | --- |
-| `@controllers([…])` | **module** | Rattache des contrôleurs au module sur le hook `onBoot` ; sans lui, aucune route n'est servie (`controllers()`, `routerDecorators.ts:111`) | `@controllers([BookController])` |
-| `@controller("/prefix")` | **classe** | Pose le préfixe d'URL **et déclenche la création des routes** de la classe (`controller()`, `routerDecorators.ts:189`) | `@controller("/api/books")` |
-| `@route(nom, options)` | méthode | Forme complète : nom explicite, chemin, `requirements`, `defaults`, hôte (`route()`, `routerDecorators.ts:287`) | `@route("ws-echo", { path: "/echo", requirements: { methods: ["WEBSOCKET"] } })` |
-| `@Domain(motif \| motifs)` | **dual** | Restreint la route (ou la classe) à un ou plusieurs vhosts ; hors domaine → **403** (`Domain()`, `routerDecorators.ts:664`) | `@Domain("*.cdn.example.com")` |
-| `@Scope("request")` | **classe** | Une instance de contrôleur par requête — par connexion en WebSocket — au lieu de l'instance partagée par défaut (`Scope()`, `routerDecorators.ts:795`) | `@Scope("request")` |
+| `@controllers([…])` | **module** | Rattache des contrôleurs au module sur le hook `onBoot` ; sans lui, aucune route n'est servie (`controllers()`, `routerDecorators.ts#controllers`) | `@controllers([BookController])` |
+| `@controller("/prefix")` | **classe** | Pose le préfixe d'URL **et déclenche la création des routes** de la classe (`controller()`, `routerDecorators.ts#controller`) | `@controller("/api/books")` |
+| `@route(nom, options)` | méthode | Forme complète : nom explicite, chemin, `requirements`, `defaults`, hôte (`route()`, `routerDecorators.ts#route`) | `@route("ws-echo", { path: "/echo", requirements: { methods: ["WEBSOCKET"] } })` |
+| `@Domain(motif \| motifs)` | **dual** | Restreint la route (ou la classe) à un ou plusieurs vhosts ; hors domaine → **403** (`Domain()`, `routerDecorators.ts#Domain`) | `@Domain("*.cdn.example.com")` |
+| `@Scope("request")` | **classe** | Une instance de contrôleur par requête — par connexion en WebSocket — au lieu de l'instance partagée par défaut (`Scope()`, `routerDecorators.ts#Scope`) | `@Scope("request")` |
 
 **`@controller` est le déclencheur.** Il relit les métadonnées posées par `@route`/`@Get`/… puis les
-**efface** (`Reflect.deleteMetadata`, `routerDecorators.ts:135`) : une classe ne se monte qu'une
+**efface** (`Reflect.deleteMetadata`, `routerDecorators.ts#controllers`) : une classe ne se monte qu'une
 fois. Il traite au passage la route « magique » `path: "*"` en **dernier**, quel que soit son ordre
-d'écriture (`hasMagic`, `routerDecorators.ts:254`) — sinon un attrape-tout masquerait les routes précises.
+d'écriture (`hasMagic`, `routerDecorators.ts#controller`) — sinon un attrape-tout masquerait les routes précises.
 
 **Le singleton — le défaut — est un contrat.** L'instance étant partagée, l'action ne doit lire ni
 écrire **aucun** état de requête sur `this` : tout passe par les arguments décorés et les accesseurs,
-qui retrouvent la requête courante via l'ALS (`ControllerScope`, `Controller.ts:151`). `@Scope("request")`
+qui retrouvent la requête courante via l'ALS (`ControllerScope`, `Controller.ts#ControllerScope`). `@Scope("request")`
 rend une instance par requête : pour injecter un service de portée `request`, préparer chaque
 requête dans `initialize()`, ou garder un état sur `this`.
 
 > [!NOTE]
 > Le core `nodefony` exporte lui aussi un `Scope` (les portées du conteneur d'injection). Celui des
 > contrôleurs s'importe **depuis `@nodefony/framework`** — l'homonymie est signalée dans le code
-> (`routerDecorators.ts:785`).
+> (`routerDecorators.ts#Scope`).
 
 ### Méthodes HTTP
 
-Toutes les fabriques sortent du même moule, `httpMethodDecorator()` (`routerDecorators.ts:489`) :
+Toutes les fabriques sortent du même moule, `httpMethodDecorator()` (`routerDecorators.ts#httpMethodDecorator`) :
 elles nomment la route automatiquement `ClasseName::methode` et posent `requirements.methods`.
 
-| Décorateur               | Méthode filtrée | Ancre                                 | Exemple             |
-| ------------------------ | --------------- | ------------------------------------- | ------------------- |
-| `@Get(path?, opts?)`     | `GET`           | `Get` (`routerDecorators.ts:535`)     | `@Get("/{id}")`     |
-| `@Post(path?, opts?)`    | `POST`          | `Post` (`routerDecorators.ts:536`)    | `@Post("")`         |
-| `@Put(path?, opts?)`     | `PUT`           | `Put` (`routerDecorators.ts:537`)     | `@Put("/{id}")`     |
-| `@Delete(path?, opts?)`  | `DELETE`        | `Delete` (`routerDecorators.ts:538`)  | `@Delete("/{id}")`  |
-| `@Patch(path?, opts?)`   | `PATCH`         | `Patch` (`routerDecorators.ts:539`)   | `@Patch("/{id}")`   |
-| `@Options(path?, opts?)` | `OPTIONS`       | `Options` (`routerDecorators.ts:540`) | `@Options("/{id}")` |
-| `@Head(path?, opts?)`    | `HEAD`          | `Head` (`routerDecorators.ts:541`)    | `@Head("/{id}")`    |
-| `@All(path?, opts?)`     | **aucune**      | `All()` (`routerDecorators.ts:548`)   | `@All("/proxy/*")`  |
+| Décorateur               | Méthode filtrée | Ancre                                     | Exemple             |
+| ------------------------ | --------------- | ----------------------------------------- | ------------------- |
+| `@Get(path?, opts?)`     | `GET`           | `Get` (`routerDecorators.ts#Get`)         | `@Get("/{id}")`     |
+| `@Post(path?, opts?)`    | `POST`          | `Post` (`routerDecorators.ts#Post`)       | `@Post("")`         |
+| `@Put(path?, opts?)`     | `PUT`           | `Put` (`routerDecorators.ts#Put`)         | `@Put("/{id}")`     |
+| `@Delete(path?, opts?)`  | `DELETE`        | `Delete` (`routerDecorators.ts#Delete`)   | `@Delete("/{id}")`  |
+| `@Patch(path?, opts?)`   | `PATCH`         | `Patch` (`routerDecorators.ts#Patch`)     | `@Patch("/{id}")`   |
+| `@Options(path?, opts?)` | `OPTIONS`       | `Options` (`routerDecorators.ts#Options`) | `@Options("/{id}")` |
+| `@Head(path?, opts?)`    | `HEAD`          | `Head` (`routerDecorators.ts#Head`)       | `@Head("/{id}")`    |
+| `@All(path?, opts?)`     | **aucune**      | `All()` (`routerDecorators.ts#All`)       | `@All("/proxy/*")`  |
 
 Deux points qu'un dev découvre sinon à ses dépens :
 
@@ -332,8 +334,8 @@ Deux points qu'un dev découvre sinon à ses dépens :
   méthodes, ne serait-ce que pour l'en-tête `Allow`.
 
 Le second argument accepte les options de route non redondantes — `Omit<RouteOptions, "path" | "method">`
-(`routerDecorators.ts:338`), soit `defaults`, `requirements`, `host`, `bypassFirewall`
-(`RouteOptions`, `Route.ts:156`) :
+(`routerDecorators.ts#route`), soit `defaults`, `requirements`, `host`, `bypassFirewall`
+(`RouteOptions`, `Route.ts#RouteOptions`) :
 
 ```typescript
 @Get("/{page}", { defaults: { page: "1" }, requirements: { scheme: "https" } })
@@ -342,42 +344,43 @@ async index(@Param("page") page: string) { /* … */ }
 
 ### Paramètres — ce que l'action reçoit
 
-Onze décorateurs, tous produits par `paramDecoratorFactory()` (`routerDecorators.ts:1191`) sauf
+Onze décorateurs, tous produits par `paramDecoratorFactory()` (`routerDecorators.ts#paramDecoratorFactory`) sauf
 `@Body`, qui accepte une option supplémentaire. Chacun pose `{ source, key, index }` ; la valeur est
-calculée par `resolveParamArg()` (`routerDecorators.ts:1326`), une fonction **pure** — ce qui la rend
+calculée par `resolveParamArg()` (`routerDecorators.ts#resolveParamArg`), une fonction **pure** — ce qui la rend
 testable sans démarrer de serveur.
 
-| Décorateur          | Sans clé renvoie…                    | Avec clé renvoie…                          | Ancre                                        |
-| ------------------- | ------------------------------------ | ------------------------------------------ | -------------------------------------------- |
-| `@Param("id")`      | toutes les variables d'URL (objet)   | la variable d'URL nommée                   | `Param` (`routerDecorators.ts:1212`)         |
-| `@Query("q")`       | toute la query string                | un paramètre de la query string            | `Query` (`routerDecorators.ts:1213`)         |
-| `@Body("field")`    | le corps parsé entier                | un champ du corps parsé                    | `Body()` (`routerDecorators.ts:1253`)        |
-| `@Headers("x-foo")` | tous les en-têtes de requête         | un en-tête (**lookup en minuscules**)      | `Headers` (`routerDecorators.ts:1279`)       |
-| `@Cookie("sid")`    | la map des cookies                   | un cookie (objet `Cookie`, champ `.value`) | `Cookie` (`routerDecorators.ts:1280`)        |
-| `@Session("user")`  | l'objet `Session` vivant             | `session.get(clé)`                         | `Session` (`routerDecorators.ts:1281`)       |
-| `@CurrentUser()`    | l'utilisateur résolu par le firewall | —                                          | `CurrentUser` (`routerDecorators.ts:1283`)   |
-| `@Req()`            | la requête brute du contexte         | —                                          | `Req` (`routerDecorators.ts:1284`)           |
-| `@Res()`            | la réponse du contexte               | —                                          | `Res` (`routerDecorators.ts:1285`)           |
-| `@UploadedFile()`   | le **premier** fichier téléversé     | —                                          | `UploadedFile` (`routerDecorators.ts:1286`)  |
-| `@UploadedFiles()`  | tous les fichiers téléversés         | —                                          | `UploadedFiles` (`routerDecorators.ts:1287`) |
-
-La liste des sources possibles est fermée et typée : `ParamSource` (`routerDecorators.ts:385`).
+| Décorateur          | Sans clé renvoie…                    | Avec clé renvoie…                          | Ancre                                                 |
+| ------------------- | ------------------------------------ | ------------------------------------------ | ----------------------------------------------------- |
+| `@Param("id")`      | toutes les variables d'URL (objet)   | la variable d'URL nommée                   | `Param` (`routerDecorators.ts#Param`)                 |
+| `@Query("q")`       | toute la query string                | un paramètre de la query string            | `Query` (`routerDecorators.ts#Query`)                 |
+| `@Body("field")`    | le corps parsé entier                | un champ du corps parsé                    | `Body()` (`routerDecorators.ts#Body`)                 |
+| `@Headers("x-foo")` | tous les en-têtes de requête         | un en-tête (**lookup en minuscules**)      | `Headers` (`routerDecorators.ts#Headers`)             |
+| `@Cookie("sid")`    | la map des cookies                   | un cookie (objet `Cookie`, champ `.value`) | `Cookie` (`routerDecorators.ts#Cookie`)               |
+| `@Session("user")`  | l'objet `Session` vivant             | `session.get(clé)`                         | `Session` (`routerDecorators.ts#Session`)             |
+| `@CurrentUser()`    | l'utilisateur résolu par le firewall | —                                          | `CurrentUser` (`routerDecorators.ts#CurrentUser`)     |
+| `@Req()`            | la requête brute du contexte         | —                                          | `Req` (`routerDecorators.ts#Req`)                     |
+| `@Res()`            | la réponse du contexte               | —                                          | `Res` (`routerDecorators.ts#Res`)                     |
+| `@UploadedFile()`   | le **premier** fichier téléversé     | —                                          | `UploadedFile` (`routerDecorators.ts#UploadedFile`)   |
+| `@UploadedFiles()`  | tous les fichiers téléversés         | —                                          | `UploadedFiles` (`routerDecorators.ts#UploadedFiles`) |
+
+La liste des sources possibles est fermée et typée : `ParamSource` (`routerDecorators.ts#ParamSource`).
 
 #### Trois comportements à connaître
 
 **`@CurrentUser` lit l'ALS, jamais un argument caché.** La valeur vient de `RequestContext.getUser()`
-(`routerDecorators.ts:1279`) : l'utilisateur posé par le firewall. C'est **l'utilisateur**, jamais le
-justificatif (mot de passe, jeton). Hors zone authentifiée, la valeur est `undefined` — le décorateur
-n'authentifie rien, il expose ce qui a déjà été prouvé.
+(`routerDecorators.ts#CurrentUser`) : l'utilisateur posé par le firewall. C'est **l'utilisateur**, jamais le
+justificatif (mot de passe, jeton). Hors zone authentifiée, la valeur est `undefined` — y compris
+pour l'anonyme d'une zone qui l'accepte — : le décorateur n'authentifie rien, il expose ce qui a déjà
+été prouvé. Sans décorateur, la même valeur se lit par `this.user` dans le contrôleur.
 
 **`@Session` active la session à lui seul.** La simple présence d'un paramètre `@Session` vaut
-déclaration d'intention : `resolveSessionIntent()` (`routerDecorators.ts:858`) la détecte et pose
+déclaration d'intention : `resolveSessionIntent()` (`routerDecorators.ts#resolveSessionIntent`) la détecte et pose
 l'intent, exactement comme `@UseSession()`. Une route sans l'un ni l'autre ne paie aucune session.
 
 **`@Body({ stream: true })` court-circuite le parsing.** Pour un gros téléversement (vidéo,
 sauvegarde), on injecte le **flux brut** de la requête au lieu du corps chargé en mémoire ; le
 pipeline saute alors le parsing pour cette route, décision prise en amont par
-`routeExpectsBodyStream()` (`routerDecorators.ts:1408`) :
+`routeExpectsBodyStream()` (`routerDecorators.ts#routeExpectsBodyStream`) :
 
 ```typescript
 @Post("/upload")
@@ -389,79 +392,125 @@ async upload(@Body({ stream: true }) stream: NodeJS.ReadableStream) {
 
 > [!TIP]
 > L'ordre d'écriture des paramètres décorés n'a aucune importance : chaque valeur est placée à son
-> **index déclaré** par `buildParamArgs()` (`routerDecorators.ts:1390`), et les trous restent
+> **index déclaré** par `buildParamArgs()` (`routerDecorators.ts#buildParamArgs`), et les trous restent
 > `undefined`. Tu peux mélanger décorés et non décorés — les non décorés reçoivent `undefined`.
 
-#### Le corps n'est pas validé — et c'est un choix
+### Routes à schéma — l'entrée validée ET typée
 
-`@Body()` injecte le corps **tel qu'il a été parsé**. Le type écrit à côté n'est pas vérifié à
-l'exécution : `@Body() dto: CreateOrder` compile, et un client peut très bien envoyer autre chose.
+Un décorateur de paramètre **affirme** un type sans le vérifier : `@Body() dto: CreateOrder` compile,
+et un client peut envoyer autre chose. L'option `schema` des décorateurs de route (`@route`, `@Get`,
+`@Post`…) **déclare** le contrat de l'action, partie par partie, et le framework le fait respecter
+avant de l'exécuter (ADR-0018) :
 
-Ce n'est pas un oubli. Valider ici ne garderait que la porte **HTTP** — la même écriture arrivant
-par WebSocket ou par une commande CLI passerait à côté — et la validation devrait rester
-**synchrone**, puisque `resolveParamArg()` l'est ; la rendre asynchrone coûterait une microtâche à
-toute requête à paramètres décorés, y compris celles qui ne valident rien.
+```typescript
+import { Post, type RouteInput } from "@nodefony/framework";
+import { z } from "zod";
+
+const postParams = z.object({ id: z.coerce.number().int().positive() });
+const postBody = z.object({ title: z.string().min(3) });
 
-La validation vit donc **plus bas**, là où tous les chemins se rejoignent.
+@Post("/posts/{id}", { schema: { params: postParams, body: postBody } })
+update(input: RouteInput<{ params: typeof postParams; body: typeof postBody }>) {
+  return { id: input.params.id, title: input.body.title }; // id : number
+}
+```
 
-**Une entité → les hooks du service.** `AbstractCrudService` appelle `beforeCreate` et
-`beforeUpdate` en `await` (`orm-core/nodefony/src/AbstractCrudService.ts:150` et `:175`) : une règle
-asynchrone — vérifier qu'un courriel est libre — y est donc possible, et le contrôle s'applique à
-REST, à la socket et à la CLI d'un seul geste. C'est exactement ce que `nodefony create entity`
-génère :
+| Partie    | Ce qu'elle valide                                                                        |
+| --------- | ---------------------------------------------------------------------------------------- |
+| `params`  | les variables de l'URL (`/posts/{id}`)                                                   |
+| `query`   | la query — sur le pont WebSocket, celle du chemin **invoqué**                            |
+| `body`    | le corps **décodé** (JSON, formulaire) — sur le pont WebSocket, celui porté par la trame |
+| `headers` | les en-têtes, clés en minuscules — sur WebSocket, ceux de la poignée de main             |
+
+**Ce que fait le framework, dans l'ordre :**
+
+- chaque partie déclarée est un [Standard Schema](https://standardschema.dev) — Zod, Valibot,
+  ArkType… ; l'interface est recopiée au cœur (`runtime/standardSchema.ts#IStandardSchemaV1`), aucune
+  dépendance n'est imposée ;
+- la validation a lieu **après** les gardes (`@IsGranted` : un 403 ne révèle pas le contrat) et
+  **avant** l'instanciation du contrôleur : une entrée invalide ne construit rien
+  (`Resolver.ts#Resolver.executeAction`) ;
+- elle est **synchrone** tant que chaque validateur l'est ; un raffinement asynchrone (« ce slug
+  est-il libre ? ») la fait attendre, et seulement lui (`routeSchema.ts#validateRouteInput`) ;
+- les quatre parties sont jugées ensemble : un échec rend **toutes** les anomalies en une fois, dans
+  une `SchemaValidationError` (`runtime/standardSchema.ts#SchemaValidationError`) — **422**, la même
+  forme qu'une `ZodError`, sur HTTP (`error.fields`) comme sur le pont WebSocket (`data.fields`).
+  Chaque champ porte sa partie : `{ "field": "title", "in": "body", "message": "…" }` ;
+- l'action reçoit **un seul argument**, `input`, qui porte toujours les quatre parties : la
+  **sortie** du schéma (coercitions, valeurs par défaut) pour une partie déclarée, la valeur brute
+  pour les autres.
+
+**La signature est vérifiée à la compilation.** Un `input` dont un champ diverge du schéma, ou un
+second argument, ne compile pas (`routerDecorators.ts#IHttpMethodDecorator`). L'identité se lit par
+`this.user`, pas par `@CurrentUser`.
+
+**Exclusif des décorateurs de paramètre.** Une action à schéma reçoit un argument unique : la mêler de
+`@Body`, `@Query`… est refusé **au démarrage**, par une erreur qui nomme la route
+(`routerDecorators.ts#assertRouteSchemaDeclaration`, appelé par `Router.setController`). Même refus pour
+une partie inconnue (`bodies`) et pour une valeur qui n'est pas un Standard Schema.
+
+**Un gros corps en flux : `bodyStream: true`.** Il remplace `@Body({ stream: true })` : `input.body`
+est alors le flux brut, jamais lu en mémoire. `bodyStream` et `schema.body` s'excluent — un flux non
+lu ne se valide pas —, et `bodyStream` **exige** un schéma : sans `input`, le flux ne serait livré à
+personne. La compilation refuse les deux fautes, le démarrage aussi ; une action sans schéma demande
+son flux par `@Body({ stream: true })`.
 
 ```typescript
-protected override beforeCreate(data: Partial<PostRow>): Partial<PostRow> {
-  return createPostSchema.parse(data) as Partial<PostRow>;
+const uploadQuery = z.object({ name: z.string() });
+
+@Post("/upload", { schema: { query: uploadQuery }, bodyStream: true })
+async upload(input: RouteInput<{ query: typeof uploadQuery }, true>) {
+  await pipeline(input.body, createWriteStream(`/data/${input.query.name}`));
 }
 ```
 
-**Un cas isolé → le schéma en tête d'action.** Même geste qu'`assertPageQuery()`, la garde de
-pagination du cœur : une fonction appelée en première ligne, qui lève. Rien d'autre à écrire — une
-`ZodError` qui remonte devient un **422** portant `error.fields` :
+**Des octets se valident tels quels.** La valeur passée au schéma est celle que le transport a
+**décodée** — ni recopiée, ni re-sérialisée : `z.instanceof(Uint8Array)` valide un corps binaire
+sans copie, ce qui tiendra quand la socket portera du binaire.
+
+**Sans schéma, rien ne change** — et rien n'est alloué de plus : la route garde ses décorateurs de
+paramètre, et le Resolver ne paie qu'une comparaison.
+
+**Une route créée par programme** (`Router.createRoute`) n'accepte ni `schema` ni `bodyStream` : ils
+se rangent sur la méthode par un décorateur, et les ignorer en silence mentirait — l'appel est refusé.
+
+#### Et une entité ?
+
+`nodefony create entity` génère les deux étages : la route déclare `createPostSchema` /
+`updatePostSchema` (422 à la porte, avant tout appel au service), et le service les revalide dans
+`beforeCreate` / `beforeUpdate` (`orm-core/nodefony/src/AbstractCrudService.ts#AbstractCrudService.create`)
+pour ses autres portes — CLI, actions temps réel —, où une règle asynchrone (unicité en base) reste
+possible. Le schéma d'entrée ne décrit pas la table : ni `id` ni horodatages n'y figurent, et les
+champs inconnus sont **retirés** — un client qui glisserait `{ "role": "admin" }` ne s'auto-promeut pas.
+
+#### Sans schéma, le corps n'est pas validé
+
+`@Body()` injecte le corps **tel qu'il a été lu**. Pour un cas isolé hors route à schéma, le geste
+reste le schéma en tête d'action — une `ZodError` qui remonte devient le même **422**, reconnu par sa
+forme (`http/nodefony/service/error-renderer.ts#toValidationFields`) et non par `instanceof` :
 
 ```typescript
 @Post("/subscribe")
 subscribe(@Body() body: unknown) {
   const dto = subscribeSchema.parse(body); // lève → 422 + fields
-  return this.renderJson({ ok: true, email: dto.email });
+  return { ok: true, email: dto.email };
 }
 ```
 
-Le rendu est assuré par `toValidationFields()` (`http/nodefony/service/error-renderer.ts:126`), qui
-reconnaît l'erreur **par sa forme** (`name` + `issues`) et non par `instanceof` — une application
-qui embarque sa propre copie de zod est donc servie pareil. Le client reçoit **422** (RFC 9110
-§15.5.21 : le corps est lisible, c'est son contenu qui viole le contrat) et la liste des champs
-fautifs, avec pour chacun son message et la règle qui a échoué.
-
-**Comment typer le paramètre**, puisque le décorateur ne promet rien :
-
-| Écriture                      | Ce que ça annonce                                   | Verdict                 |
-| ----------------------------- | --------------------------------------------------- | ----------------------- |
-| `@Body() b: Partial<PostRow>` | la ligne de **table** — `id` et horodatages compris | promet trop             |
-| `@Body() b: unknown`          | rien, honnêtement                                   | juste, mais peu commode |
-| `@Body() b: CreatePost`       | le contrat d'**entrée**, `z.infer` du schéma        | ✅ à préférer           |
-
-`CreatePost` et `UpdatePost` sont générés à côté du schéma (`nodefony/entity/Post.schema.ts`) : le
-type et la validation dérivent de la même source, ils ne peuvent donc pas diverger. Un schéma
-d'entrée ne décrit d'ailleurs pas la table — ni `id` ni horodatages n'y figurent, ils sont posés par
-le serveur —, et zod **retire** les champs inconnus : un client qui glisserait `{ "role": "admin" }`
-ne s'auto-promeut pas.
-
 ### Réponse — statut, en-têtes, redirection
 
-| Décorateur                | Cible   | Effet                                                                                      | Exemple                               |
-| ------------------------- | ------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
-| `@HttpCode(201)`          | méthode | Fixe le statut **avant** l'exécution de l'action (`HttpCode()`, `routerDecorators.ts:582`) | `@HttpCode(204)`                      |
-| `@Header("X-Foo", "bar")` | méthode | Ajoute un en-tête ; **s'empile** (plusieurs `@Header` cumulent, `routerDecorators.ts:603`) | `@Header("Cache-Control","no-store")` |
-| `@Redirect("/url", 302)`  | méthode | Redirige **si** l'action ne renvoie rien (`Redirect()`, `routerDecorators.ts:649`)         | `@Redirect("/login", 302)`            |
+| Décorateur                | Cible   | Effet                                                                                           | Exemple                               |
+| ------------------------- | ------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `@HttpCode(201)`          | méthode | Fixe le statut **avant** l'exécution de l'action (`HttpCode()`, `routerDecorators.ts#HttpCode`) | `@HttpCode(204)`                      |
+| `@Header("X-Foo", "bar")` | méthode | Ajoute un en-tête ; **s'empile** (plusieurs `@Header` cumulent, `routerDecorators.ts#Header`)   | `@Header("Cache-Control","no-store")` |
+| `@Redirect("/url", 302)`  | méthode | Redirige **si** l'action ne renvoie rien (`Redirect()`, `routerDecorators.ts#Redirect`)         | `@Redirect("/login", 302)`            |
 
-Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts:955`) **avant**
+Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts#Resolver._applyResponseMeta`) **avant**
 l'appel de l'action : ton code peut donc les écraser ensuite (`this.renderJson(data, 202)` gagne).
 
 `@Redirect` a une subtilité utile : si l'action **retourne un objet** portant `url` (et
 éventuellement `statusCode`), cet objet **prend le dessus** sur les valeurs du décorateur
-(`Resolver._handleRedirect()`, `Resolver.ts:980`) — la cible peut donc être calculée à l'exécution :
+(`Resolver._handleRedirect()`, `Resolver.ts#Resolver._handleRedirect`) — la cible peut donc être calculée à l'exécution :
 
 ```typescript
 @Get("/go")
@@ -482,20 +531,21 @@ async go(@Query("to") to?: string) {
 Sept décorateurs, **tous duals** (classe ou méthode) et **tous sans logique** : ils posent une
 étiquette que le `Resolver` ou le firewall consommera.
 
-| Décorateur                               | Effet                                                                                                    | Ancre                                         |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| `@IsGranted(attr \| attrs, { subject })` | Exige un attribut (rôle `ROLE_*` ou règle métier). Tableau = **OU** ; empilés = **ET** ; refus → **403** | `IsGranted()` (`routerDecorators.ts:903`)     |
-| `@RequireScope(scope \| scopes)`         | Exige un scope `api:action` d'un **jeton machine** ; no-op pour une session humaine                      | `RequireScope()` (`routerDecorators.ts:1002`) |
-| `@Anonymous()`                           | Rend l'action publique : annule l'autorisation **et** l'authentification (le « permitAll »)              | `Anonymous()` (`routerDecorators.ts:953`)     |
-| `@BypassFirewall`                        | Court-circuite le firewall (sonde de liveness, webhook signé, endpoint de login). **Sans parenthèses**   | `BypassFirewall` (`routerDecorators.ts:725`)  |
-| `@Csp({ "frame-src": [...] })`           | Ajoute des directives CSP **à cette réponse** ; classe + méthode fusionnent additivement                 | `Csp()` (`routerDecorators.ts:1071`)          |
-| `@CsrfProtect()`                         | Opt-**in** au jeton anti-CSRF (double-submit signé) en plus de la défense globale                        | `CsrfProtect` (`routerDecorators.ts:1133`)    |
-| `@CsrfExempt()`                          | Opt-**out** de la défense CSRF **en gardant** l'authentification (webhook, POST cross-origin légitime)   | `CsrfExempt` (`routerDecorators.ts:1142`)     |
+| Décorateur                                | Effet                                                                                                                                                             | Ancre                                                                   |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `@IsGranted(attr \| attrs, { subject })`  | Exige un attribut (rôle `ROLE_*` ou règle métier). Tableau = **OU** ; empilés = **ET** ; refus → **403**                                                          | `IsGranted()` (`routerDecorators.ts#IsGranted`)                         |
+| `@RequireScope(scope \| scopes)`          | Exige un scope `api:action` d'un **jeton machine** ; no-op pour une session humaine                                                                               | `RequireScope()` (`routerDecorators.ts#RequireScope`)                   |
+| `@RequireAuthentication({ maxAge, amr })` | Exige une connexion **récente** (`maxAge`, s) et/ou faite avec certains moyens (`amr` RFC 8176, ex. `otp`) ; évalué après `@IsGranted` ; refus → **401** RFC 9470 | `RequireAuthentication()` (`routerDecorators.ts#RequireAuthentication`) |
+| `@Anonymous()`                            | Rend l'action publique : annule l'autorisation **et** l'authentification (le « permitAll »)                                                                       | `Anonymous()` (`routerDecorators.ts#Anonymous`)                         |
+| `@BypassFirewall`                         | Court-circuite le firewall (sonde de liveness, webhook signé, endpoint de login). **Sans parenthèses**                                                            | `BypassFirewall` (`routerDecorators.ts#BypassFirewall`)                 |
+| `@Csp({ "frame-src": [...] })`            | Ajoute des directives CSP **à cette réponse** ; classe + méthode fusionnent additivement                                                                          | `Csp()` (`routerDecorators.ts#Csp`)                                     |
+| `@CsrfProtect()`                          | Opt-**in** au jeton anti-CSRF (double-submit signé) en plus de la défense globale                                                                                 | `CsrfProtect` (`routerDecorators.ts#CsrfProtect`)                       |
+| `@CsrfExempt()`                           | Opt-**out** de la défense CSRF **en gardant** l'authentification (webhook, POST cross-origin légitime)                                                            | `CsrfExempt` (`routerDecorators.ts#CsrfExempt`)                         |
 
 #### Rôles et scopes — deux axes, un seul verdict
 
 `@IsGranted` et `@RequireScope` écrivent dans **deux jeux de métadonnées distincts**, puis
-`computeSecurityRequirement()` (`routerDecorators.ts:1544`) les fusionne en une exigence unique dont
+`computeSecurityRequirement()` (`routerDecorators.ts#computeSecurityRequirement`) les fusionne en une exigence unique dont
 toutes les clauses sont en **ET**. Une seule chaîne d'application côté `Resolver`, deux jurés
 différents côté `security` (le voteur de rôles, le voteur de scopes).
 
@@ -531,7 +581,7 @@ Trois façons d'ouvrir une porte, trois portées — les confondre coûte cher :
 | `@CsrfExempt()`   |  **conservée**   |  **conservée**   |   ignorée    | webhook signé, API cross-origin       |
 
 `@Anonymous()` pose en réalité **deux** marqueurs : « pas d'autorisation » et « pas de firewall »
-(`routerDecorators.ts:953-979`) — c'est un `@BypassFirewall` doublé d'une annulation des clauses
+(`routerDecorators.ts#Anonymous`) — c'est un `@BypassFirewall` doublé d'une annulation des clauses
 héritées de la classe.
 
 > [!CAUTION]
@@ -542,17 +592,17 @@ héritées de la classe.
 
 ### Cycle de la requête — session et anti-rejeu
 
-| Décorateur                   | Cible | Effet                                                                                                      | Ancre                             |
-| ---------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `@UseSession({ readOnly? })` | dual  | Déclare le besoin d'une session serveur ; **méthode > classe** (`UseSession()`, `routerDecorators.ts:800`) | `@UseSession({ readOnly: true })` |
-| `@Idempotent({ required? })` | dual  | Protège une mutation du double effet via `Idempotency-Key` (`Idempotent()`, `routerDecorators.ts:1171`)    | `@Idempotent()`                   |
+| Décorateur                   | Cible | Effet                                                                                                             | Ancre                             |
+| ---------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `@UseSession({ readOnly? })` | dual  | Déclare le besoin d'une session serveur ; **méthode > classe** (`UseSession()`, `routerDecorators.ts#UseSession`) | `@UseSession({ readOnly: true })` |
+| `@Idempotent({ required? })` | dual  | Protège une mutation du double effet via `Idempotency-Key` (`Idempotent()`, `routerDecorators.ts#Idempotent`)     | `@Idempotent()`                   |
 
 **`@UseSession` est la seule façon d'ouvrir une session** (avec un paramètre `@Session`, ou la reprise
 d'un cookie existant). Il n'existe plus de « démarrer partout » global : une route qui ne déclare rien
 ne coûte aucune lecture de stockage. Une seule option : `readOnly` (lire sans jamais persister —
 zéro écriture). La régénération de l'identifiant après authentification est faite par le login
 (`AuthFlow`), pas par une option du décorateur.
-La forme exacte est celle de `SessionIntent` (`ISession.ts:18`).
+La forme exacte est celle de `SessionIntent` (`ISession.ts#SessionIntent.readOnly`).
 
 **`@Idempotent` est strict par défaut** : une mutation sans `Idempotency-Key` reçoit **400**. Le mode
 souple s'obtient par `@Idempotent({ required: false })` — sans effet en WebSocket, toujours strict
@@ -565,15 +615,14 @@ identité et les stockages distribués sont traités dans la page dédiée →
 Ils ne viennent pas de `@nodefony/framework`, mais complètent la même DX ; on les cite pour éviter les
 recherches inutiles.
 
-| Décorateur                          | Paquet               | Rôle                                                                                           |
-| ----------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
-| `@services([…])`                    | `nodefony`           | Déclare les services d'un module (`services()`, `kernelDecorator.ts:53`)                       |
-| `@injectable()`                     | `nodefony`           | Rend une classe résoluble par le conteneur (`injectable()`, `kernelDecorator.ts:135`)          |
-| `@inject("nom")`                    | `nodefony`           | Injecte un service à une position de constructeur (`inject()`, `kernelDecorator.ts:186`)       |
-| `@Inject("nom")`                    | `nodefony`           | Idem, sur une propriété (`Inject()`, `kernelDecorator.ts:215`)                                 |
-| `@RealtimeAction("méthode")`        | `@nodefony/realtime` | Expose une action JSON-RPC sur socket (`RealtimeAction()`, `realtimeDecorators.ts:101`)        |
-| `@RealtimeChannel("canal", policy)` | `@nodefony/realtime` | Déclare un canal temps réel et sa politique (`RealtimeChannel()`, `realtimeDecorators.ts:192`) |
-| `@RealtimeInbound("méthode")`       | `@nodefony/realtime` | Traite un message entrant typé (`RealtimeInbound()`, `realtimeDecorators.ts:231`)              |
+| Décorateur                          | Paquet               | Rôle                                                                                                       |
+| ----------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `@services([…])`                    | `nodefony`           | Déclare les services d'un module (`services()`, `kernelDecorator.ts#services`)                             |
+| `@injectable()`                     | `nodefony`           | Rend une classe résoluble par le conteneur (`injectable()`, `kernelDecorator.ts#injectable`)               |
+| `@Inject("nom")`                    | `nodefony`           | Injecte un service à une position de constructeur (`kernelDecorator.ts#Inject`)                            |
+| `@RealtimeAction("méthode")`        | `@nodefony/realtime` | Expose une action JSON-RPC sur socket (`RealtimeAction()`, `realtimeDecorators.ts#RealtimeAction`)         |
+| `@RealtimeChannel("canal", policy)` | `@nodefony/realtime` | Déclare un canal temps réel et sa politique (`RealtimeChannel()`, `realtimeDecorators.ts#RealtimeChannel`) |
+| `@RealtimeInbound("méthode")`       | `@nodefony/realtime` | Traite un message entrant typé (`RealtimeInbound()`, `realtimeDecorators.ts#RealtimeInbound`)              |
 
 Injection et portées → [injection-portees](../../../../../docs/architecture/injection-portees.md) ·
 socket → [realtime](../../realtime/docs/index.md).
@@ -588,7 +637,7 @@ socket → [realtime](../../realtime/docs/index.md).
 ## 🔌 HTTP et WebSocket — les mêmes décorateurs
 
 Un contrôleur ne change pas de forme selon le transport : ce sont les `requirements.methods` qui
-déclarent le canal, `WEBSOCKET` étant une pseudo-méthode du type `HTTPMethod` (`Context.ts:104`).
+déclarent le canal, `WEBSOCKET` étant une pseudo-méthode du type `HTTPMethod` (`Context.ts#HTTPMethod`).
 
 ```typescript
 @controller("/ws/chat")
@@ -620,11 +669,11 @@ Trois faits à retenir :
   `@route`, ou via `@All("/x", { requirements: { methods: ["WEBSOCKET"] } })` si tu préfères la forme
   courte. Les fabriques `@Get`/`@Post`… **fusionnent** les méthodes déclarées avec la leur :
   `@Get("/x", { requirements: { methods: ["WEBSOCKET"] } })` sert GET **et** WebSocket
-  (`routerDecorators.ts:535`).
+  (`routerDecorators.ts#Get`).
 - **Les décorateurs de paramètre fonctionnent pareil.** Pour une invocation par socket, le corps de
   la mutation voyage dans l'ALS et **prime** sur le corps HTTP (vide dans ce cas) — c'est traité dans
-  `resolveParamArg()` (`routerDecorators.ts:1326`), et `@Query` lit la query du chemin **invoqué**,
-  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts:929`).
+  `resolveParamArg()` (`routerDecorators.ts#resolveParamArg`), et `@Query` lit la query du chemin **invoqué**,
+  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts#Resolver._buildParamArgs`).
 - **Les gardes s'appliquent identiquement.** `@IsGranted` protège une action joignable par socket
   exactement comme une action HTTP : la décision est prise avant l'instanciation, quel que soit le
   transport.
@@ -640,16 +689,16 @@ pas toutes identiques — c'est la source d'erreur n°1.
 <!-- prettier-ignore -->
 | Sujet | Règle | Ancre |
 | --- | --- | --- |
-| `@Domain` | option `host` de la route > méthode > classe | `controller()` (`routerDecorators.ts:189`) |
-| `@BypassFirewall` | **cumulatif** : `true` de la route, de la méthode ou de la classe suffit | `routerDecorators.ts:750` |
-| `@UseSession` | méthode > classe (fusion des champs) | `resolveSessionIntent()` (`routerDecorators.ts:858`) |
-| `@Idempotent` | méthode > classe | `computeIdempotent()` (`routerDecorators.ts:1606`) |
-| `@IsGranted` / `@RequireScope` | **cumul en ET** : classe **plus** méthode | `computeSecurityRequirement()` (`routerDecorators.ts:1544`) |
-| `@Anonymous` | méthode → annule tout ce que la classe a posé | `routerDecorators.ts:953` |
-| `@Csp` | fusion **additive** classe + méthode (sources concaténées) | `mergeCspDirectives()` (`routerDecorators.ts:1043`) |
-| `@CsrfProtect` / `@CsrfExempt` | OU logique : classe **ou** méthode suffit | `computeActionMeta()` (`routerDecorators.ts:1632`) |
-| `@Header` | s'empile (plusieurs en-têtes) ; même clé → dernier écrit gagne | `Header()` (`routerDecorators.ts:603`) |
-| `@HttpCode` | un seul par action (le dernier posé écrase) | `HttpCode()` (`routerDecorators.ts:582`) |
+| `@Domain` | option `host` de la route > méthode > classe | `controller()` (`routerDecorators.ts#controller`) |
+| `@BypassFirewall` | **cumulatif** : `true` de la route, de la méthode ou de la classe suffit | `routerDecorators.ts#BypassFirewall` |
+| `@UseSession` | méthode > classe (fusion des champs) | `resolveSessionIntent()` (`routerDecorators.ts#resolveSessionIntent`) |
+| `@Idempotent` | méthode > classe | `computeIdempotent()` (`routerDecorators.ts#computeIdempotent`) |
+| `@IsGranted` / `@RequireScope` | **cumul en ET** : classe **plus** méthode | `computeSecurityRequirement()` (`routerDecorators.ts#computeSecurityRequirement`) |
+| `@Anonymous` | méthode → annule tout ce que la classe a posé | `routerDecorators.ts#Anonymous` |
+| `@Csp` | fusion **additive** classe + méthode (sources concaténées) | `mergeCspDirectives()` (`routerDecorators.ts#mergeCspDirectives`) |
+| `@CsrfProtect` / `@CsrfExempt` | OU logique : classe **ou** méthode suffit | `computeActionMeta()` (`routerDecorators.ts#computeActionMeta`) |
+| `@Header` | s'empile (plusieurs en-têtes) ; même clé → dernier écrit gagne | `Header()` (`routerDecorators.ts#Header`) |
+| `@HttpCode` | un seul par action (le dernier posé écrase) | `HttpCode()` (`routerDecorators.ts#HttpCode`) |
 
 ### Où placer les décorateurs de classe
 
@@ -692,7 +741,7 @@ sequenceDiagram
   RS->>RS: requêtes suivantes : lecture O(1), 0 Reflect
 ```
 
-Le snapshot `RouteActionMeta` (`routerDecorators.ts:1436`) regroupe **tout** ce que les décorateurs
+Le snapshot `RouteActionMeta` (`routerDecorators.ts#RouteActionMeta`) regroupe **tout** ce que les décorateurs
 ont dit de l'action :
 
 <!-- prettier-ignore -->
@@ -710,12 +759,12 @@ ont dit de l'action :
 
 Le `Resolver` consomme ce snapshot dans un ordre qui a du sens sécurité :
 **garde d'abord, instanciation ensuite**. `security !== null` déclenche
-`_enforceSecurity()` (`Resolver.ts:853`) **avant** `newController()` — un `403` n'instancie pas le
+`_enforceSecurity()` (`Resolver.ts#Resolver._enforceSecurity`) **avant** `newController()` — un `403` n'instancie pas le
 contrôleur et n'exécute pas son `initialize()`. Puis viennent les arguments
-(`_buildParamArgs()`, `Resolver.ts:929`), les métadonnées de réponse
-(`_applyResponseMeta()`, `Resolver.ts:955`), l'action, et enfin la redirection éventuelle.
+(`_buildParamArgs()`, `Resolver.ts#Resolver._buildParamArgs`), les métadonnées de réponse
+(`_applyResponseMeta()`, `Resolver.ts#Resolver._applyResponseMeta`), l'action, et enfin la redirection éventuelle.
 
-Un usage cold path mérite d'être connu : `extractActionScopes()` (`routerDecorators.ts:1520`) parcourt
+Un usage cold path mérite d'être connu : `extractActionScopes()` (`routerDecorators.ts#extractActionScopes`) parcourt
 les routes au démarrage pour bâtir le **catalogue des scopes déclarés** — le formulaire de création
 de clés API dans Studio propose les scopes réellement utilisés par le code, jamais une liste
 maintenue à part.
@@ -724,26 +773,26 @@ maintenue à part.
 
 Un décorateur non employé doit coûter **zéro**. C'est tenu par trois mécanismes vérifiables :
 
-- **Lecture unique.** `resolveActionMeta()` (`routerDecorators.ts:1669`) mémorise le snapshot sur la
+- **Lecture unique.** `resolveActionMeta()` (`routerDecorators.ts#resolveActionMeta`) mémorise le snapshot sur la
   route au premier passage — ensuite, plus aucun appel `Reflect.getMetadata` ni `Object.entries` par
   requête. Le même schéma vaut pour la détection du flux brut
-  (`routeExpectsBodyStream()`, `routerDecorators.ts:1408`).
+  (`routeExpectsBodyStream()`, `routerDecorators.ts#routeExpectsBodyStream`).
 - **`null` plutôt que structure vide.** Une action sans garde a `security: null` : le `Resolver` teste
-  un `null` et passe — ni résolution de service, ni `await`, ni allocation (`Resolver.ts:486`). Idem
+  un `null` et passe — ni résolution de service, ni `await`, ni allocation (`Resolver.ts#Resolver._enforceActionSecurity`). Idem
   pour `idempotent`, `cspDirectives`, `paramsMeta`.
 - **Objets gelés et partagés.** Les exigences de sécurité et d'idempotence sont créées **une fois** et
-  `Object.freeze`-ées (`routerDecorators.ts:1496`, `:1340`) : une seule instance pour la durée de vie
+  `Object.freeze`-ées (`routerDecorators.ts#computeSecurityRequirement`, `routerDecorators.ts#computeCspDirectives`) : une seule instance pour la durée de vie
   du processus, quelle que soit la charge. Corollaire : ne les mute jamais.
 
 Coût résiduel côté montage seulement : la reconstruction de la pile d'appels dans `route()`
-(`stackTrace`, `routerDecorators.ts:304`) pour retrouver le fichier source. Elle a lieu **à l'import**, une fois par
+(`stackTrace`, `routerDecorators.ts#route`) pour retrouver le fichier source. Elle a lieu **à l'import**, une fois par
 route, jamais pendant une requête.
 
 ## 🧩 Extension — écrire son propre décorateur
 
 Le module montre le patron à suivre : un décorateur maison **ne fait qu'écrire une métadonnée**, et
 un point du pipeline la relit. Pour un simple drapeau dual (classe + méthode), le framework fournit
-déjà la fabrique `booleanMarkerDecorator()` (`routerDecorators.ts:1108`), dont `@CsrfProtect` et
+déjà la fabrique `booleanMarkerDecorator()` (`routerDecorators.ts#booleanMarkerDecorator`), dont `@CsrfProtect` et
 `@CsrfExempt` sont les deux usages.
 
 Le squelette d'un drapeau maison, en dehors du framework :
@@ -773,7 +822,7 @@ export function Audited() {
 Deux invariants à respecter, tirés du code du module :
 
 1. **Classe → constructeur, méthode → prototype keyé par nom.** C'est la convention de toutes les
-   métadonnées du fichier (`routerDecorators.ts:903` pour `@IsGranted`) ; s'en écarter rend la
+   métadonnées du fichier (`routerDecorators.ts#IsGranted` pour `@IsGranted`) ; s'en écarter rend la
    fusion classe/méthode impossible.
 2. **Aucune I/O, aucun service, aucun import lourd dans le décorateur.** Il s'exécute à l'import, hors
    de tout kernel : y résoudre un service planterait le simple fait de charger le fichier.
@@ -796,7 +845,7 @@ L'écran **Routes** (`/nodefony/routes`) et le point d'API `/nodefony/framework/
 | Symptôme | Cause (dans le code) | Correction |
 | --- | --- | --- |
 | `404` sur une route pourtant décorée | Contrôleur jamais importé, ou absent de `@controllers([…])` | L'ajouter au tableau `@controllers` du module |
-| `Action « remove » … : ce nom est RÉSERVÉ` au démarrage — ou `TS2416` au build | L'action reprend le nom d'un membre de `Controller` : la classe étend `Service`, qui expose déjà `remove(name): boolean` ([`Service.ts:608`](../../../../nodefony/src/Service.ts)), `set`, `get`, `clean`… Le décorateur refuse le nom avant que le conflit n'atteigne le compilateur. | Renommer l'action (`destroy`, `deleteOne`…). Le nom d'une action est libre : c'est le chemin du décorateur qui fait l'URL. |
+| `Action « remove » … : ce nom est RÉSERVÉ` au démarrage — ou `TS2416` au build | L'action reprend le nom d'un membre de `Controller` : la classe étend `Service`, qui expose déjà `remove(name): boolean` ([`Service.ts#Service.remove`](../../../../nodefony/src/Service.ts)), `set`, `get`, `clean`… Le décorateur refuse le nom avant que le conflit n'atteigne le compilateur. | Renommer l'action (`destroy`, `deleteOne`…). Le nom d'une action est libre : c'est le chemin du décorateur qui fait l'URL. |
 | `404` après avoir déplacé `@controller` sous `@Domain` | `@controller` monte les routes ; les décorateurs lus au montage doivent être **sous** | Remettre `@controller` en **premier** (le plus haut) |
 | Le vhost de `@Domain` classe est ignoré | `@Domain` placé **au-dessus** de `@controller` → posé trop tard | Placer `@Domain` sous `@controller` |
 | `@BypassFirewall` n'ouvre rien | Écrit **avec** parenthèses — c'est un drapeau, pas une fabrique | `@BypassFirewall` (sans `()`) |