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

package/docs/controller.md

@@ -49,8 +49,8 @@ Trois idées à retenir :
 1. **Tu hérites de `Service`** — `Controller` étend `Service` (`Controller.ts:146`). Tu récupères
    donc gratuitement le container (`this.get()`), les logs (`this.log()`) et les événements.
 2. **Tu ne construis rien toi-même** — le `Resolver` instancie ta classe via l'injecteur
-   (`Resolver.newController()`, `Resolver.ts:315`), jamais un `new` direct.
-3. **Ton `return` EST la réponse** — `Resolver.returnController()` (`Resolver.ts:1034`) traduit la
+   (`Resolver.newController()`, `Resolver.ts:319`), jamais un `new` direct.
+3. **Ton `return` EST la réponse** — `Resolver.returnController()` (`Resolver.ts:1039`) traduit la
    valeur retournée : objet → JSON, string → corps brut, `void` → « j'ai répondu moi-même ».
 
 ## 📖 Lexique
@@ -198,16 +198,16 @@ Le tableau ci-dessous donne la séquence exacte, avec l'ancre qui la prouve :
 
 | #   | Étape                                   | Où                                                  |
 | --- | --------------------------------------- | --------------------------------------------------- |
-| 1   | Appariement de la route                 | `router.resolve()` (`http-kernel.ts:807`)           |
-| 2   | En-têtes de sécurité applicatifs        | `applySecurityHeaders()` (`http-kernel.ts:1624`)    |
-| 3   | Parse du corps (sauf `@Body({stream})`) | `http-kernel.ts:1606`                               |
-| 4   | Armement de la route (sans instance)    | `prepareFrontController()` (`http-kernel.ts:811`)   |
-| 5   | CSRF                                    | `firewall.enforceCsrf()` (`http-kernel.ts:1747`)    |
-| 6   | Session (reprise ou ouverture)          | `HttpKernel.startSession()` (`http-kernel.ts:1246`) |
-| 7   | Firewall — **authentification**         | `firewall.handleSecurity()` (`http-kernel.ts:1772`) |
-| 8   | Autorisation `@IsGranted`               | `Resolver.executeAction()` (`Resolver.ts:446`)      |
-| 9   | **Instanciation DI + `initialize()`**   | `Resolver.executeAction()` (`Resolver.ts:446`)      |
-| 10  | **Ton action**                          | `controller[methodKey]()` (`Resolver.ts:382`)       |
+| 1   | Appariement de la route                 | `router.resolve()` (`http-kernel.ts:1717`)          |
+| 2   | En-têtes de sécurité applicatifs        | `applySecurityHeaders()` (`http-kernel.ts:1727`)    |
+| 3   | Parse du corps (sauf `@Body({stream})`) | `http-kernel.ts:1709`                               |
+| 4   | Armement de la route (sans instance)    | `prepareFrontController()` (`http-kernel.ts:876`)   |
+| 5   | CSRF                                    | `firewall.enforceCsrf()` (`http-kernel.ts:1850`)    |
+| 6   | Session (reprise ou ouverture)          | `HttpKernel.startSession()` (`http-kernel.ts:1330`) |
+| 7   | Firewall — **authentification**         | `firewall.handleSecurity()` (`http-kernel.ts:1865`) |
+| 8   | Autorisation `@IsGranted`               | `Resolver.executeAction()` (`Resolver.ts:450`)      |
+| 9   | **Instanciation DI + `initialize()`**   | `Resolver.executeAction()` (`Resolver.ts:450`)      |
+| 10  | **Ton action**                          | `controller[methodKey]()` (`Resolver.ts:386`)       |
 
 > [!IMPORTANT]
 > **Rien de ton contrôleur ne s'exécute pour une requête qui sera refusée.** L'appariement de route
@@ -222,8 +222,8 @@ Le tableau ci-dessous donne la séquence exacte, avec l'ancre qui la prouve :
 C'est **sa raison d'être** : un `constructor` ne peut pas être `async`, et la résolution DI est
 synchrone. Tout ce qui demande un `await` à la mise en place de l'instance n'a pas d'autre endroit
 où aller. Le hook est **optionnel** — le Resolver ne l'appelle que s'il existe
-(`Resolver._createController()`, `Resolver.ts:330`). Son contrat est décrit par
-`ControllerWithInitialize` (`Resolver.ts:72`) : aucun argument, retour `Promise<this>`.
+(`Resolver._createController()`, `Resolver.ts:334`). Son contrat est décrit par
+`ControllerWithInitialize` (`Resolver.ts:76`) : aucun argument, retour `Promise<this>`.
 
 > [!IMPORTANT]
 > **Sur un contrôleur singleton — le défaut —, `initialize()` tourne UNE fois**, à la création, dans
@@ -259,7 +259,7 @@ Si ton `initialize()` lève, l'exception remonte le pipeline et sort en réponse
 (`LifecycleController.initialize()`, `LifecycleController.ts:21`, exercée par
 `lifecycle-init-crash.test.ts`). Aucune requête pendue, aucun timeout muet. Pour un singleton,
 une création en échec ne reste pas en cache : la requête suivante recrée l'instance
-(`Router.getSingletonController()`, `router.ts:197`) — une base pas encore prête au premier appel ne
+(`Router.getSingletonController()`, `router.ts:232`) — une base pas encore prête au premier appel ne
 tue pas le contrôleur jusqu'au redémarrage.
 
 ### Les phases mesurées
@@ -267,7 +267,7 @@ tue pas le contrôleur jusqu'au redémarrage.
 Chaque étape est chronométrée sous le nom d'une **phase**, lisible dans la debug bar et le profileur :
 `resolve` · `initialize` (DI + ton hook) · `parse` · `firewall` · `action` · `render` · `send`.
 La phase `initialize` existe précisément pour que le temps passé dans ton hook et dans la résolution
-DI **soit imputé à quelqu'un** au lieu de disparaître dans le bloc `action` (`Resolver.ts:112`).
+DI **soit imputé à quelqu'un** au lieu de disparaître dans le bloc `action` (`Resolver.ts:116`).
 
 ## 🔌 HTTP et WebSocket — le même contrôleur
 
@@ -306,13 +306,13 @@ class ChatController extends Controller {
 | Nombre d'appels d'action | 1 | 1 au handshake (`WebsocketContext.handle()`, `WebsocketContext.ts:297`) + 1 par frame (`handleMessage()`, `WebsocketContext.ts:507`) |
 | Argument de l'action | Variables de route (ou paramètres décorés) | Idem + **le message** en dernier argument (`WebsocketContext.ts:508`) |
 | Rendu d'un `return` | Corps de la réponse | Frame envoyée sur la socket |
-| Échec | Statut HTTP + corps d'erreur | **Code de fermeture** RFC 6455 (401/403 → 1008, 5xx → 1011, autre → 4004) |
+| Échec | Statut HTTP + corps d'erreur | **Code de fermeture** RFC 6455 (401/403 → 1008, 5xx → 1011, autre → 4004) ; chemin sans route WebSocket → **404 HTTP avant l'ouverture** |
 | `initialize()` | Singleton : **une fois**, à la création · `@Scope("request")` : à chaque requête | Singleton : une fois, à la création · `@Scope("request")` : **une fois par connexion**, au handshake |
 
 La réutilisation de l'instance vient du cache posé sur le container du contexte
-(`Resolver.newController()`, `Resolver.ts:315`) : le contexte WS étant partagé par la connexion, le
+(`Resolver.newController()`, `Resolver.ts:319`) : le contexte WS étant partagé par la connexion, le
 contrôleur l'est aussi. Un garde-fou vérifie que l'instance cachée est bien de la classe de la route
-courante et la reconstruit sinon (`Resolver.ts:344-347`) — sans quoi un message invoquant une autre
+courante et la reconstruit sinon (`Resolver.ts:348-351`) — sans quoi un message invoquant une autre
 action se tromperait d'objet.
 
 > [!WARNING]
@@ -321,10 +321,10 @@ action se tromperait d'objet.
 > `@Scope("request")`, chaque requête HTTP repart d'une instance neuve ; un singleton, lui, refuse
 > tout état de requête sur `this`.
 
-Côté WebSocket, l'ordre est encore plus marqué : `HttpKernel.onConnect()` (`http-kernel.ts:2008`)
+Côté WebSocket, l'ordre est encore plus marqué : `HttpKernel.onConnect()` (`http-kernel.ts:2098`)
 appelle `handleFrontController()` (donc `initialize()`) **avant** `startSession()`
-(`http-kernel.ts:1246`), avant l'acceptation de la socket, et avant le firewall
-(`http-kernel.ts:1457`).
+(`http-kernel.ts:1330`), avant l'acceptation de la socket, et avant le firewall
+(`http-kernel.ts:1488`).
 
 ## 🧠 D'où viennent `request`, `response`, `session`
 
@@ -334,14 +334,14 @@ sont des accesseurs qui dérivent du contexte **vivant**, selon le motif `champ
 | Raccourci        | Ce que tu obtiens                                  | Ancre               |
 | ---------------- | -------------------------------------------------- | ------------------- |
 | `this.context`   | Le contexte transport de la requête courante       | `Controller.ts:238` |
-| `this.route`     | La route matchée                                   | `Controller.ts:202` |
+| `this.route`     | La route matchée                                   | `Controller.ts:256` |
 | `this.request`   | La requête (HTTP, HTTP/2 ou WS)                    | `Controller.ts:269` |
 | `this.response`  | La réponse du transport                            | `Controller.ts:277` |
 | `this.method`    | La méthode HTTP (ou `WEBSOCKET`)                   | `Controller.ts:212` |
-| `this.queryGet`  | Les paramètres de la query string                  | `Controller.ts:302` |
-| `this.queryPost` | Le corps parsé                                     | `Controller.ts:351` |
-| `this.body`      | Le corps parsé — alias de `queryPost`              | `Controller.ts:351` |
-| `this.queryFile` | Les fichiers uploadés                              | `Controller.ts:341` |
+| `this.queryGet`  | Les paramètres de la query string                  | `Controller.ts:315` |
+| `this.queryPost` | Le corps parsé                                     | `Controller.ts:364` |
+| `this.body`      | Le corps parsé — alias de `queryPost`              | `Controller.ts:364` |
+| `this.queryFile` | Les fichiers uploadés                              | `Controller.ts:354` |
 | `this.session`   | La session **ou `null`** si elle n'est pas activée | `Controller.ts:384` |
 
 Pourquoi des accesseurs plutôt que des champs recopiés au constructeur : **la fraîcheur et le coût**.
@@ -351,7 +351,7 @@ gratuitement.
 
 ### La session est **lazy** — elle n'existe que si tu la demandes
 
-`this.session` est un simple getter sur `context.session` (`Controller.ts:384`). Il n'y a **pas** de
+`this.session` est un simple getter sur `context.session` (`Controller.ts:397`). Il n'y a **pas** de
 `startSession()` à appeler depuis un contrôleur : l'activation se déclare sur la route, avec
 `@UseSession()` (ou un paramètre `@Session()`, qui vaut déclaration implicite), et le pipeline
 l'exécute à son point unique. Sans déclaration et sans cookie de session entrant, **aucune session
@@ -360,16 +360,16 @@ n'est créée** — donc aucun coût de stockage.
 Deux corollaires :
 
 - Dans `initialize()`, `this.session` vaut `null` (l'activation vient plus tard — étape 6 du cycle).
-- `this.getSession()` (`Controller.ts:657`) ne « démarre » rien : il retourne la session existante,
+- `this.getSession()` (`Controller.ts:704`) ne « démarre » rien : il retourne la session existante,
   ou `undefined`.
 
-Les messages flash s'appuient dessus : sans session active, `getFlashBag()` (`Controller.ts:677`)
-journalise une **erreur** et retourne `null`, et `setFlashBag()`/`addFlash()` (`Controller.ts:693`)
+Les messages flash s'appuient dessus : sans session active, `getFlashBag()` (`Controller.ts:724`)
+journalise une **erreur** et retourne `null`, et `setFlashBag()`/`addFlash()` (`Controller.ts:740`)
 retournent `null` sans rien journaliser — pas de crash, mais rien n'est mémorisé.
 
 ### Contrôleur singleton — le défaut : `this` n'est pas à toi
 
-Par défaut, `Controller.scope` vaut `"singleton"` (`Controller.ts:182`) : UNE instance par classe,
+Par défaut, `Controller.scope` vaut `"singleton"` (`Controller.ts:412`) : UNE instance par classe,
 construite à sa première requête puis partagée par toutes les suivantes, concurrentes comprises.
 
 - **une seule instance** pour tout le process, liée au container du **kernel**, pas à celui de la
@@ -404,26 +404,26 @@ class MeController extends Controller {
 
 ## 🧰 Répondre — ce que ton `return` déclenche
 
-Le traducteur unique est `Resolver.returnController()` (`Resolver.ts:1034`). Il regarde le **type**
+Le traducteur unique est `Resolver.returnController()` (`Resolver.ts:1039`). Il regarde le **type**
 de ce que tu as retourné :
 
 <!-- prettier-ignore -->
 | Tu retournes… | Ce qui se passe | Ancre |
 | --- | --- | --- |
-| Une `Promise` / un thenable | Déballée puis re-traitée (récursif) | `Resolver.ts:830-840` |
-| Une `string` | Envoyée telle quelle en corps | `Resolver.ts:711` |
-| Un objet simple ou un tableau | **Auto-JSON** : `application/json` + sérialisation | `Resolver.ts:1081` |
-| Un `number` / un `boolean` | Auto-JSON scalaire (RFC 8259 §2 : `42`, `true` sont des documents valides) | `Resolver.ts:734` |
-| Un `Buffer` | Envoyé brut | `Resolver.ts:1074` |
-| Une `Response` (via un `render*`) | Retournée telle quelle — l'envoi a déjà eu lieu | `Resolver.ts:581` |
-| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `NO_BODY_STATUS` (`Resolver.ts:1168`) |
-| `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts:1147` |
-| Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts:1108-1117` |
+| Une `Promise` / un thenable | Déballée puis re-traitée (récursif) | `Resolver.ts:848-858` |
+| Une `string` | Envoyée telle quelle en corps | `Resolver.ts:716` |
+| Un objet simple ou un tableau | **Auto-JSON** : `application/json` + sérialisation | `Resolver.ts:1086` |
+| Un `number` / un `boolean` | Auto-JSON scalaire (RFC 8259 §2 : `42`, `true` sont des documents valides) | `Resolver.ts:739` |
+| Un `Buffer` | Envoyé brut | `Resolver.ts:1079` |
+| Une `Response` (via un `render*`) | Retournée telle quelle — l'envoi a déjà eu lieu | `Resolver.ts:599` |
+| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `NO_BODY_STATUS` (`Resolver.ts:1229`) |
+| `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts:1165` |
+| Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts:1113-1122` |
 
 > [!WARNING]
 > **Le piège n° 1 : `return null` sur un statut à corps.** Le framework l'interprète comme « je
 > répondrai moi-même » et attend — jusqu'au timeout. La distinction se fait sur le **statut** :
-> `NO_BODY_STATUS` (`Resolver.ts:1168`) contient 204, 205 et 304. Donc un `@Delete` qui fait
+> `NO_BODY_STATUS` (`Resolver.ts:1229`) contient 204, 205 et 304. Donc un `@Delete` qui fait
 > `@HttpCode(204)` puis `return null` répond bien 204 vide ; le même `return null` sans `@HttpCode`
 > laisse la requête pendue.
 
@@ -436,25 +436,25 @@ Quand tu veux piloter l'envoi plutôt que retourner une valeur :
 
 | Helper                                       | Pour…                                                    | Ancre               |
 | -------------------------------------------- | -------------------------------------------------------- | ------------------- |
-| `renderJson(obj, status?, headers?)`         | JSON explicite avec statut/en-têtes                      | `Controller.ts:629` |
-| `render(data, encoding?, status?, headers?)` | Envoyer un corps quelconque via le contexte              | `Controller.ts:485` |
-| `renderView(path, params, status?)`          | Rendre un template **Eta** (avec les helpers frontend)   | `Controller.ts:544` |
-| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:523` |
-| `redirect(url, status?, headers?)`           | Rediriger                                                | `Controller.ts:663` |
-| `forward("module:controller:action")`        | Déléguer à une autre action **sans** aller-retour réseau | `Controller.ts:697` |
-| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:430` |
+| `renderJson(obj, status?, headers?)`         | JSON explicite avec statut/en-têtes                      | `Controller.ts:631` |
+| `render(data, encoding?, status?, headers?)` | Envoyer un corps quelconque via le contexte              | `Controller.ts:499` |
+| `renderView(path, params, status?)`          | Rendre un template **Eta** (avec les helpers frontend)   | `Controller.ts:556` |
+| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:535` |
+| `redirect(url, status?, headers?)`           | Rediriger                                                | `Controller.ts:710` |
+| `forward("module:controller:action")`        | Déléguer à une autre action **sans** aller-retour réseau | `Controller.ts:744` |
+| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:443` |
 
 `renderView()` mesure sa propre phase `render` et injecte automatiquement les aides frontend
 (`frontendTags`, `frontendDocument`, `asset`) dans les variables du template
-(`withFrontendLocals()`, `Controller.ts:562`) — tes propres valeurs restent prioritaires.
+(`withFrontendLocals()`, `Controller.ts:594`) — tes propres valeurs restent prioritaires.
 
 `forward()` re-résout un contrôleur sur le **même** contexte et rappelle son action
-(`Controller.ts:697`) : c'est une délégation interne, la requête cliente reste unique.
+(`Controller.ts:744`) : c'est une délégation interne, la requête cliente reste unique.
 
 > [!TIP]
 > **Redirection : le code par défaut est 302** (Found), pas 301. Un statut absent ou hors de la liste
 > RFC 9110 §15.4 (301, 302, 303, 307, 308) retombe sur 302 avec un log d'avertissement
-> (`Response.redirect()`, `Response.ts:735`). Un 301 par défaut piégeait : les navigateurs le mettent
+> (`Response.redirect()`, `Response.ts:755`). Un 301 par défaut piégeait : les navigateurs le mettent
 > en cache de façon quasi irréversible.
 
 ## 📁 Servir un fichier — téléchargement et flux média
@@ -463,15 +463,15 @@ Deux besoins distincts, deux helpers.
 
 ### Téléchargement — `renderFileDownload()`
 
-`renderFileDownload(file, options?, headers?)` (`Controller.ts:788`) pose
+`renderFileDownload(file, options?, headers?)` (`Controller.ts:825`) pose
 `Content-Disposition: attachment`, `Content-Length`, le type MIME du fichier, puis délègue au moteur
-de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts:749`) ;
+de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts:786`) ;
 la variante synchrone `getFile()` existe encore mais est marquée obsolète — elle appelle `lstatSync`
 et gèle le process le temps du stat.
 
 ### Lecture en continu — `renderMediaStream()`
 
-`renderMediaStream(file, headers?, options?)` (`Controller.ts:952`) implémente les **requêtes par
+`renderMediaStream(file, headers?, options?)` (`Controller.ts:999`) implémente les **requêtes par
 plage** (RFC 9110 §14), ce qui permet à un lecteur vidéo de sauter dans le flux :
 
 | Le client envoie…                             | Réponse                                                         |
@@ -487,11 +487,11 @@ donc testable sans serveur.
 
 ### Ce que `streamFile()` garantit
 
-`streamFile()` (`Controller.ts:828`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
+`streamFile()` (`Controller.ts:865`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
 **nettoyage** : le flux est ouvert avec `autoClose: false`, et un client qui raccroche en plein
 téléchargement laisserait sinon un descripteur de fichier ouvert et une promesse pendue à jamais. Un
 écouteur `close` sur la réponse détruit le flux, ce qui déclenche la fermeture du descripteur et
-résout la promesse (`Controller.ts:762-804`), puis se retire lui-même (`Controller.ts:746`). Un
+résout la promesse (`Controller.ts:931-969`), puis se retire lui-même (`Controller.ts:961`). Un
 téléchargement interrompu ne coûte donc **rien** en ressource retenue.
 
 ## ⚠️ Erreurs — lever, rendre, observer
@@ -506,7 +506,7 @@ throw new nodefonyError("Article introuvable", 404); // statut porté par l'erre
 throw new HttpError("Not Found", 404, this.context); // variante enrichie du contexte
 ```
 
-L'exception remonte jusqu'à `HttpKernel.onError()` (`http-kernel.ts:918`), qui délègue la mise en
+L'exception remonte jusqu'à `HttpKernel.onError()` (`http-kernel.ts:994`), qui délègue la mise en
 forme au rendeur d'erreurs. Ce qui en sort :
 
 - **statut normalisé** — un code absent (ou l'ancien quirk `200`) devient **500**
@@ -515,16 +515,18 @@ forme au rendeur d'erreurs. Ce qui en sort :
   `nodefony` portant l'environnement, l'URL et l'**identifiant de requête** — de quoi retrouver la
   trace complète dans les logs ;
 - **course gérée** : si le client est déjà parti (contexte terminé ou réponse envoyée), le framework
-  ne tente pas de rendre — il journalise et s'arrête (`http-kernel.ts:770-775`).
+  ne tente pas de rendre — il journalise et s'arrête (`http-kernel.ts:782-787`).
 
 En **WebSocket**, il n'y a pas de statut : l'erreur devient un **code de fermeture** RFC 6455
 (`renderWebsocket()`, `error-renderer.ts:518`) — 401/403 → 1008 (violation de politique),
 5xx → 1011 (erreur interne), le reste → 4004 (plage privée). Si la socket n'est pas encore acceptée,
-c'est un **rejet** de handshake.
+c'est un **rejet** de handshake. Un chemin qu'aucune route WebSocket ne sert n'atteint jamais ton
+contrôleur : il reçoit un **404 HTTP** avant l'ouverture (RFC 6455 §4.2.2), le client ne voit donc
+jamais d'`open`.
 
 > [!NOTE]
 > Les erreurs de ton action remontent **seules** : le Resolver n'enveloppe pas l'appel dans un
-> `try/catch` inutile (`Resolver.ts:625-626`). Inutile d'attraper pour re-lever — sauf si tu veux
+> `try/catch` inutile (`Resolver.ts:630-631`). Inutile d'attraper pour re-lever — sauf si tu veux
 > vraiment traduire l'erreur en un autre statut.
 
 ## 🧩 Services injectés — trois façons
@@ -585,9 +587,9 @@ code du framework applique — et attend de toi — les règles suivantes :
   (`Controller.ts:574`).
 - **Métadonnées d'action figées** : `@HttpCode`, `@Header`, les paramètres décorés et l'intention de
   session sont calculés **une fois** par route puis mémorisés, au lieu d'être relus par `Reflect` à
-  chaque requête (`resolveActionMeta()` appelé en `Resolver.ts:458`).
+  chaque requête (`resolveActionMeta()` appelé en `Resolver.ts:462`).
 - **Gardes payées seulement si présentes** : sans `@IsGranted`, la vérification d'autorisation est
-  un test de nullité (`Resolver.ts:890`) — 0 lookup, 0 `await`, 0 allocation.
+  un test de nullité (`Resolver.ts:895`) — 0 lookup, 0 `await`, 0 allocation.
 - **Ta part du contrat** : pas de structure allouée « au cas où » dans le constructeur ni dans
   `initialize()`. Une valeur utile à 5 % des requêtes s'alloue à la demande.
 
@@ -595,12 +597,12 @@ code du framework applique — et attend de toi — les règles suivantes :
 
 | Domaine                          | Norme                    | Comment le code s'y conforme                                    |
 | -------------------------------- | ------------------------ | --------------------------------------------------------------- |
-| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts:1168`)                           |
+| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts:1229`)                           |
 | Requêtes par plage               | RFC 9110 §14.1.2, §14.2  | `parseByteRange()` (`Controller.ts:107`)                        |
-| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts:523`)               |
+| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts:535`)               |
 | Redirections                     | RFC 9110 §15.4           | Liste blanche + repli 302 (`Response.ts:666`)                   |
-| Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts:1081`), vérifié par le banc `auto-json` |
-| Scalaire JSON de premier niveau  | RFC 8259 §2              | `number`/`boolean` rendus (`Resolver.ts:734`)                   |
+| Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts:1086`), vérifié par le banc `auto-json` |
+| Scalaire JSON de premier niveau  | RFC 8259 §2              | `number`/`boolean` rendus (`Resolver.ts:739`)                   |
 | Codes de fermeture WebSocket     | RFC 6455 §7.4            | `renderWebsocket()` (`error-renderer.ts:518`)                   |
 
 ## 📡 Observabilité — Studio
@@ -618,17 +620,17 @@ code du framework applique — et attend de toi — les règles suivantes :
 <!-- prettier-ignore -->
 | Symptôme | Cause (dans le code) | Correction |
 | --- | --- | --- |
-| La requête pend puis expire, alors que l'action a bien tourné | `return null`/`undefined` avec un statut à corps → `waitAsync` (`Resolver.ts:1147`) | Retourner une valeur, ou poser `@HttpCode(204)` |
-| Réponse vide alors qu'on retourne une entité ORM | Instance de classe **non** sérialisée → `waitAsync` (`Resolver.ts:1117`) | Retourner un objet simple, ou `renderJson(entity.toJSON())` |
+| La requête pend puis expire, alors que l'action a bien tourné | `return null`/`undefined` avec un statut à corps → `waitAsync` (`Resolver.ts:1165`) | Retourner une valeur, ou poser `@HttpCode(204)` |
+| Réponse vide alors qu'on retourne une entité ORM | Instance de classe **non** sérialisée → `waitAsync` (`Resolver.ts:1122`) | Retourner un objet simple, ou `renderJson(entity.toJSON())` |
 | `Route Action not found` | L'action porte un nom déjà utilisé par un membre de `Controller` | Renommer : `session`, `request`, `response`, `context`, `route`, `method`, `query*`, `get`, `set`, `render*`, `redirect`, `forward` sont réservés |
-| `this.session` est `null` dans `initialize()` | La session est activée **après** (`http-kernel.ts:1752`) | Lire la session dans l'action, pas dans le hook |
-| Effet de bord exécuté pour une requête finalement 401 | `initialize()` tourne avant `firewall.handleSecurity()` (`http-kernel.ts:1772`) | Déplacer l'effet de bord dans l'action |
+| `this.session` est `null` dans `initialize()` | La session est activée **après** (`http-kernel.ts:1783`) | Lire la session dans l'action, pas dans le hook |
+| Effet de bord exécuté pour une requête finalement 401 | `initialize()` tourne avant `firewall.handleSecurity()` (`http-kernel.ts:1865`) | Déplacer l'effet de bord dans l'action |
 | Redirection permanente non voulue | Un statut invalide retombe sur 302, un `301` explicite reste 301 | Passer le code voulu : `this.redirect(url, 302)` |
-| WS : l'état d'une frame « bave » sur la suivante | L'instance est partagée — par TOUTES les connexions en singleton (le défaut), par toute la connexion en `@Scope("request")` (`Resolver.ts:805`) | Porter l'état par message, ou sur le contexte de la connexion |
+| WS : l'état d'une frame « bave » sur la suivante | L'instance est partagée — par TOUTES les connexions en singleton (le défaut), par toute la connexion en `@Scope("request")` (`Resolver.ts:960`) | Porter l'état par message, ou sur le contexte de la connexion |
 | WS : l'action n'est jamais appelée | Route sans transport `WEBSOCKET` déclaré | `requirements: { methods: ["WEBSOCKET"] }` |
 | Contrôleur singleton : données d'un autre utilisateur | État muté que les filets ne voient pas (`#privé`, objet muté) sur l'instance partagée | Passer par les arguments décorés, ou déclarer `@Scope("request")` |
 | « Contrôleur … : écriture de « this.x » refusée » | Un état de requête écrit sur un singleton (le défaut) | Argument décoré, service `request`, ou `@Scope("request")` sur la classe |
-| Event loop figé sur une route de fichier | `getFile()` synchrone (`lstatSync`, `Controller.ts:709`) | Utiliser `getFileAsync()` (`Controller.ts:749`) |
+| Event loop figé sur une route de fichier | `getFile()` synchrone (`lstatSync`, `Controller.ts:746`) | Utiliser `getFileAsync()` (`Controller.ts:786`) |
 
 ## 🧪 Tests & couverture