@nodefony/framework 10.0.0-alpha.8 → 10.0.0-beta.1

package/docs/controller.md

@@ -17,24 +17,25 @@ coverageFiles: Controller.ts,Resolver.ts
 # Controller — le code de ta route
 
 > Une fois la route trouvée, quelqu'un doit **faire le travail** : c'est le contrôleur. Nodefony
-> l'instancie par requête (DI compris), appelle ton action, puis traduit ce que tu **retournes** en
+> l'instancie (DI compris) — une fois par défaut, à chaque requête sous `@Scope("request")` —, appelle ton action, puis traduit ce que tu **retournes** en
 > réponse HTTP ou en frame WebSocket. Cette page décrit ce qui se passe **dans** le contrôleur : de
 > quoi il hérite, son cycle de vie réel (dont `initialize()`), d'où viennent `request`/`response`/
 > `session`, comment répondre, comment échouer proprement. Tout est ancré sur le code.
 
 📍 [Documentation](../../../../../docs/index.md) › [Framework](index.md) › **Controller**
 
-## 🧠 Le modèle mental — un objet jetable entre deux mondes
+## 🧠 Le modèle mental — du code partagé entre deux mondes
 
-Un contrôleur n'est **pas** un serveur ni un service partagé : par défaut c'est un **objet jetable**,
-construit pour UNE requête et abandonné à la fin. Il vit entre deux mondes qu'il ne connaît pas :
+Par défaut, un contrôleur est un **singleton** : construit à sa première requête, puis partagé par
+toutes les suivantes, concurrentes comprises. Il ne porte que du **code** ; l'état d'une requête
+lui arrive par les arguments décorés et les helpers, qui retrouvent la requête EN COURS. Il vit entre deux mondes qu'il ne connaît pas :
 le **transport** (le contexte HTTP ou WebSocket, fourni par `@nodefony/http`) et le **container**
 (tes services, fournis par le DI).
 
 ```mermaid
 flowchart LR
   RT["Router<br/>route trouvée"] --> RS["Resolver<br/>par requête"]
-  RS -->|"instantiate + DI"| CT["TON Controller<br/>extends Controller"]
+  RS -->|"instantiate + DI<br/>(une fois si singleton)"| CT["TON Controller<br/>extends Controller"]
   CT -->|"initialize()"| CT
   RS -->|"action(...args)"| CT
   CT -->|"return valeur"| RC["returnController<br/>traduit le retour"]
@@ -45,11 +46,11 @@ flowchart LR
 
 Trois idées à retenir :
 
-1. **Tu hérites de `Service`** — `Controller` étend `Service` (`Controller.ts:112`). Tu récupères
+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:236`), jamais un `new` direct.
-3. **Ton `return` EST la réponse** — `Resolver.returnController()` (`Resolver.ts:697`) traduit la
+   (`Resolver.newController()`, `Resolver.ts:282`), jamais un `new` direct.
+3. **Ton `return` EST la réponse** — `Resolver.returnController()` (`Resolver.ts:857`) traduit la
    valeur retournée : objet → JSON, string → corps brut, `void` → « j'ai répondu moi-même ».
 
 ## 📖 Lexique
@@ -65,7 +66,7 @@ Trois idées à retenir :
 | Auto-JSON          | Le fait qu'un objet retourné par l'action devienne une réponse `application/json` sans le demander. |
 | Handshake          | La poignée de main d'ouverture d'une connexion WebSocket (avant tout message).                      |
 | Frame              | Un message WebSocket individuel, une fois la connexion ouverte.                                     |
-| Scope (contrôleur) | `"request"` (une instance par requête, défaut) ou `"singleton"` (une instance partagée).            |
+| Scope (contrôleur) | `"singleton"` (une instance partagée, défaut) ou `"request"` (une instance par requête).            |
 | `waitAsync`        | Drapeau posé quand le framework conclut « l'action enverra la réponse elle-même, plus tard ».       |
 
 ## 🚀 Démarrage rapide
@@ -95,7 +96,8 @@ interface CatalogService {
 
 @controller("/api/catalog")
 class CatalogController extends Controller {
-  // Champ per-requête : sûr ici, car le scope par défaut est UNE instance par requête.
+  // Posé UNE fois dans `initialize()` : le contrôleur est un singleton par défaut,
+  // partagé par toutes les requêtes — ce champ ne doit plus changer ensuite.
   private catalog: CatalogService | null = null;
 
   // Le contexte de la requête est le SEUL argument obligatoire ; le nom passé à
@@ -104,8 +106,9 @@ class CatalogController extends Controller {
     super("catalog", context);
   }
 
-  // Hook optionnel, appelé à CHAQUE requête juste après l'instanciation.
-  // Voir « Le cycle de vie » : ici, ni session ni utilisateur ne sont encore résolus.
+  // Hook optionnel, appelé UNE fois, à la création du singleton (à chaque requête
+  // sous `@Scope("request")`). Voir « Le cycle de vie » : ni session ni
+  // utilisateur n'y sont résolus.
   async initialize(): Promise<this> {
     this.catalog = this.get<CatalogService>("catalog");
     return this;
@@ -195,15 +198,15 @@ 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:1324`)          |
-| 2   | En-têtes de sécurité applicatifs        | `applySecurityHeaders()` (`http-kernel.ts:1334`)    |
-| 3   | Parse du corps (sauf `@Body({stream})`) | `http-kernel.ts:1316`                               |
-| 4   | Armement de la route (sans instance)    | `prepareFrontController()` (`http-kernel.ts:767`)   |
-| 5   | CSRF                                    | `firewall.enforceCsrf()` (`http-kernel.ts:1290`)    |
-| 6   | Session (reprise ou ouverture)          | `HttpKernel.startSession()` (`http-kernel.ts:1131`) |
-| 7   | Firewall — **authentification**         | `firewall.handleSecurity()` (`http-kernel.ts:1301`) |
-| 8   | Autorisation `@IsGranted`               | `Resolver.executeAction()` (`Resolver.ts:334`)      |
-| 9   | **Instanciation DI + `initialize()`**   | `Resolver.executeAction()` (`Resolver.ts:313`)      |
+| 1   | Appariement de la route                 | `router.resolve()` (`http-kernel.ts:807`)           |
+| 2   | En-têtes de sécurité applicatifs        | `applySecurityHeaders()` (`http-kernel.ts:1418`)    |
+| 3   | Parse du corps (sauf `@Body({stream})`) | `http-kernel.ts:1449`                               |
+| 4   | Armement de la route (sans instance)    | `prepareFrontController()` (`http-kernel.ts:789`)   |
+| 5   | CSRF                                    | `firewall.enforceCsrf()` (`http-kernel.ts:1524`)    |
+| 6   | Session (reprise ou ouverture)          | `HttpKernel.startSession()` (`http-kernel.ts:1168`) |
+| 7   | Firewall — **authentification**         | `firewall.handleSecurity()` (`http-kernel.ts:1535`) |
+| 8   | Autorisation `@IsGranted`               | `Resolver.executeAction()` (`Resolver.ts:372`)      |
+| 9   | **Instanciation DI + `initialize()`**   | `Resolver.executeAction()` (`Resolver.ts:372`)      |
 | 10  | **Ton action**                          | `controller[methodKey]()` (`Resolver.ts:382`)       |
 
 > [!IMPORTANT]
@@ -219,25 +222,29 @@ 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:269`). Son contrat est décrit par
+(`Resolver._createController()`, `Resolver.ts:330`). Son contrat est décrit par
 `ControllerWithInitialize` (`Resolver.ts:72`) : aucun argument, retour `Promise<this>`.
 
+> [!IMPORTANT]
+> **Sur un contrôleur singleton — le défaut —, `initialize()` tourne UNE fois**, à la création, dans
+> le contexte de la requête qui l'a déclenchée ; l'instance sert ensuite toutes les autres. Tout ce
+> qui dépend de LA requête (identité, cookie, mode de rendu) y serait figé pour tout le monde : sa
+> place est dans l'action. Sous `@Scope("request")`, le hook retrouve sa sémantique par requête.
+
 ```typescript
 async initialize(): Promise<this> {
-  this.setContextJson();                                   // forme de la réponse
-  const user = RequestContext.getUser();                   // identité déjà résolue
-  this.prefs = await this.get<Prefs>("prefs").load(user.identifier);
+  this.catalog = this.get<CatalogService>("catalog");      // service résolu une fois
+  this.defaults = await this.get<Prefs>("prefs").loadDefaults(); // préchauffage partagé
   return this;                                             // toujours rendre `this`
 }
 ```
 
-| Dans `initialize()`, tu peux…                                                            | Ce qui n'a rien à y faire                                                                                  |
-| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Un `await` de mise en place : charger des préférences, ouvrir une ressource, précalculer | Une **décision d'autorisation** — c'est `@IsGranted`, évalué avant, et un 403 n'arrive jamais jusqu'ici    |
-| Résoudre des services (`this.get("catalog")`)                                            | Un travail qu'**une seule action sur cinq** utilise : il serait payé par toutes → fais-le dans l'action    |
-| Lire l'identité (`RequestContext.getUser()`) — le firewall est passé                     | Un effet de bord **par requête** qu'un rechargement ferait deux fois (compteur, envoi) sans idempotence    |
-| Poser un cookie ou un en-tête (`this.context?.setCookie()`) — rien n'est encore écrit    | Une écriture longue qui bloque : la phase `initialize` est chronométrée, elle apparaîtra dans la debug bar |
-| Choisir un mode de rendu (`this.setContextHtml()`)                                       | Lire `this.session` sans l'avoir demandée : elle reste **lazy** (`@UseSession`, cf plus bas)               |
+| Dans `initialize()` d'un singleton, tu peux…                                                       | Ce qui n'a rien à y faire                                                                                                  |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Un `await` de mise en place : ouvrir une ressource, précalculer, préchauffer                       | Une **décision d'autorisation** — c'est `@IsGranted`, évalué avant, et un 403 n'arrive jamais jusqu'ici                    |
+| Résoudre des services (`this.get("catalog")`)                                                      | Lire l'identité, poser un cookie, choisir un mode de rendu : c'est l'état d'UNE requête → l'action, ou `@Scope("request")` |
+| Poser des champs de démarrage sur `this` — le filet de développement ne les garde qu'APRÈS le hook | Écrire sur `this` ensuite : en développement, l'écriture lève (l'état fuirait vers la requête suivante)                    |
+| —                                                                                                  | Une écriture longue qui bloque : la phase `initialize` est chronométrée, elle apparaîtra dans la debug bar                 |
 
 > [!NOTE]
 > **La session ne s'ouvre pas ici.** Nodefony a un point d'activation **unique**
@@ -250,14 +257,17 @@ async initialize(): Promise<this> {
 Si ton `initialize()` lève, l'exception remonte le pipeline et sort en réponse d'erreur cohérente :
 **500 JSON**, serveur toujours sain. C'est prouvé par une sonde dédiée du dépôt
 (`LifecycleController.initialize()`, `LifecycleController.ts:21`, exercée par
-`lifecycle-init-crash.test.ts`). Aucune requête pendue, aucun timeout muet.
+`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
+tue pas le contrôleur jusqu'au redémarrage.
 
 ### Les phases mesurées
 
 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:281`).
+DI **soit imputé à quelqu'un** au lieu de disparaître dans le bloc `action` (`Resolver.ts:112`).
 
 ## 🔌 HTTP et WebSocket — le même contrôleur
 
@@ -292,27 +302,28 @@ class ChatController extends Controller {
 | Aspect | HTTP | WebSocket |
 | --- | --- | --- |
 | Durée de vie du contexte | Une requête | **Toute la connexion** |
-| Instance du contrôleur | Une par requête | **Une par connexion**, réutilisée à chaque frame |
-| Nombre d'appels d'action | 1 | 1 au handshake (`WebsocketContext.handle()`, `WebsocketContext.ts:265`) + 1 par frame (`handleMessage()`, `WebsocketContext.ts:479`) |
+| Instance du contrôleur | Singleton (défaut) : **la même** pour toutes les requêtes · `@Scope("request")` : une par requête | Singleton : **la même** pour toutes les connexions · `@Scope("request")` : **une par connexion**, réutilisée à chaque frame |
+| Nombre d'appels d'action | 1 | 1 au handshake (`WebsocketContext.handle()`, `WebsocketContext.ts:271`) + 1 par frame (`handleMessage()`, `WebsocketContext.ts:479`) |
 | 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) |
-| `initialize()` | À chaque requête | **Une seule fois**, au handshake |
+| `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:232`) : le contexte WS étant partagé par la connexion, le
+(`Resolver.newController()`, `Resolver.ts:282`) : 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
 action se tromperait d'objet.
 
 > [!WARNING]
 > **Sur une connexion WS, `this` survit aux frames.** Un champ écrit à la frame 1 est encore là à la
-> frame 2 — pratique pour un état de conversation, piège si tu comptais sur une instance neuve. En
-> HTTP, l'inverse : chaque requête repart d'une instance vierge.
+> frame 2 — pratique pour un état de conversation, piège si tu comptais sur une instance neuve. Sous
+> `@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:1702`)
+Côté WebSocket, l'ordre est encore plus marqué : `HttpKernel.onConnect()` (`http-kernel.ts:1779`)
 appelle `handleFrontController()` (donc `initialize()`) **avant** `startSession()`
-(`http-kernel.ts:1131`), avant l'acceptation de la socket, et avant le firewall
+(`http-kernel.ts:1168`), avant l'acceptation de la socket, et avant le firewall
 (`http-kernel.ts:1457`).
 
 ## 🧠 D'où viennent `request`, `response`, `session`
@@ -322,16 +333,16 @@ 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:146` |
-| `this.route`     | La route matchée                                   | `Controller.ts:158` |
-| `this.request`   | La requête (HTTP, HTTP/2 ou WS)                    | `Controller.ts:162` |
-| `this.response`  | La réponse du transport                            | `Controller.ts:169` |
+| `this.context`   | Le contexte transport de la requête courante       | `Controller.ts:238` |
+| `this.route`     | La route matchée                                   | `Controller.ts:202` |
+| `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:221` |
-| `this.queryPost` | Le corps parsé                                     | `Controller.ts:248` |
-| `this.body`      | Le corps parsé — alias de `queryPost`              | `Controller.ts:248` |
-| `this.queryFile` | Les fichiers uploadés                              | `Controller.ts:239` |
-| `this.session`   | La session **ou `null`** si elle n'est pas activée | `Controller.ts:229` |
+| `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.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**.
 Une valeur recopiée vieillit dès que le pipeline modifie le contexte, et recopier quatre structures
@@ -340,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:229`). Il n'y a **pas** de
+`this.session` est un simple getter sur `context.session` (`Controller.ts:384`). 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
@@ -349,64 +360,70 @@ 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:496`) ne « démarre » rien : il retourne la session existante,
+- `this.getSession()` (`Controller.ts:630`) ne « démarre » rien : il retourne la session existante,
   ou `undefined`.
 
-Les messages flash s'appuient dessus : `setFlashBag()`/`addFlash()` (`Controller.ts:530`) et
-`getFlashBag()` (`Controller.ts:514`) journalisent une **erreur** et retournent `null` si aucune
+Les messages flash s'appuient dessus : `setFlashBag()`/`addFlash()` (`Controller.ts:666`) et
+`getFlashBag()` (`Controller.ts:650`) journalisent une **erreur** et retournent `null` si aucune
 session n'est active — pas de crash, mais rien n'est mémorisé.
 
-### Contrôleur `singleton` — quand `this` n'est plus à toi
+### 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,
+construite à sa première requête puis partagée par toutes les suivantes, concurrentes comprises.
 
-Par défaut, `Controller.scope` vaut `"request"` (`Controller.ts:196`). Un contrôleur **sans état**
-peut passer en instance unique partagée :
+- **une seule instance** pour tout le process, liée au container du **kernel**, pas à celui de la
+  requête (`Controller.ts:399-411`) — capturer le container de requête serait fatal, il est nettoyé
+  à la fin de la requête ;
+- **`initialize()` n'est appelé qu'une fois**, à la création (sémantique « démarrage ») ;
+- le contexte n'est pas posé sur l'objet : `this.context` **lit l'ALS**
+  (`RequestContext.getContext()`, `Controller.ts:223`) et retrouve donc la requête réellement en
+  cours, jamais celle d'une requête concurrente — y compris la route et la query d'un appel du pont
+  `api.request` (`Controller.ts:269`).
+
+Deux filets rendent visible l'état de requête posé sur `this` : les accesseurs (`this.query = …`,
+`setRoute()`…) **lèvent** dans tous les environnements, et **en développement** toute écriture sur
+un champ lève aussi, en nommant le contrôleur, le champ et le remède.
+
+> [!WARNING]
+> Ce que les filets ne voient pas — un champ `#privé`, un objet muté (`this.cache.set(…)`) — reste
+> une **fuite de données entre utilisateurs** silencieuse. Et un callback qui s'exécute HORS de la
+> bulle de la requête (écouteur d'un émetteur, minuteur armé ailleurs) n'y retrouve pas
+> `this.context` : lire le contexte AVANT, dans une variable.
+
+Besoin d'une instance **par requête** — injecter un service de portée `request`, préparer chaque
+requête dans `initialize()`, garder un état sur `this` ? Déclarer la classe `@Scope("request")` :
 
 ```typescript
-@Scope("singleton")
-@controller("/api/health")
-class HealthController extends Controller {
+@Scope("request")
+@controller("/api/me")
+class MeController extends Controller {
   /* … */
 }
 ```
 
-Ce que ça change, concrètement :
-
-- **une seule instance** pour tout le process, bindée au container du **kernel**, pas à celui de la
-  requête (`Controller.ts:244-252`) — capturer le container de requête serait fatal, il est nettoyé
-  au teardown ;
-- **`initialize()` n'est appelé qu'une fois**, à la création (sémantique « boot ») ;
-- le contexte n'est plus posé sur l'objet : `this.context` **retombe sur l'ALS**
-  (`RequestContext.getContext()`, `Controller.ts:147`) et retrouve donc la requête réellement en
-  cours, jamais celle d'une requête concurrente.
-
-> [!WARNING]
-> Un champ mutable par requête sur un contrôleur `singleton` est une **fuite de données entre
-> utilisateurs** silencieuse (requête A lit ce qu'a écrit requête B). N'utilise `@Scope("singleton")`
-> que si toutes tes données passent par les arguments décorés et l'ALS. Le défaut per-requête reste
-> le choix sûr — le gain mesuré du singleton est dans le bruit de mesure.
-
 ## 🧰 Répondre — ce que ton `return` déclenche
 
-Le traducteur unique est `Resolver.returnController()` (`Resolver.ts:697`). Il regarde le **type**
+Le traducteur unique est `Resolver.returnController()` (`Resolver.ts:857`). 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:700-710` |
+| 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:760` |
+| Un objet simple ou un tableau | **Auto-JSON** : `application/json` + sérialisation | `Resolver.ts:936` |
 | 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:723` |
-| Une `Response` (via un `render*`) | Retournée telle quelle — l'envoi a déjà eu lieu | `Resolver.ts:716` |
-| `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:855`) |
-| `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts:801` |
-| Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts:770-777` |
+| Un `Buffer` | Envoyé brut | `Resolver.ts:900` |
+| 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:1002`) |
+| `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts:981` |
+| Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts:942-951` |
 
 > [!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:855`) contient 204, 205 et 304. Donc un `@Delete` qui fait
+> `NO_BODY_STATUS` (`Resolver.ts:1002`) 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.
 
@@ -419,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:379` |
-| `render(data, encoding?, status?, headers?)` | Envoyer un corps quelconque via le contexte              | `Controller.ts:377` |
-| `renderView(path, params, status?)`          | Rendre un template **Eta** (avec les helpers frontend)   | `Controller.ts:410` |
-| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:392` |
-| `redirect(url, status?, headers?)`           | Rediriger                                                | `Controller.ts:382` |
-| `forward("module:controller:action")`        | Déléguer à une autre action **sans** aller-retour réseau | `Controller.ts:432` |
-| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:319` |
+| `renderJson(obj, status?, headers?)`         | JSON explicite avec statut/en-têtes                      | `Controller.ts:602` |
+| `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:524` |
+| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:503` |
+| `redirect(url, status?, headers?)`           | Rediriger                                                | `Controller.ts:636` |
+| `forward("module:controller:action")`        | Déléguer à une autre action **sans** aller-retour réseau | `Controller.ts:670` |
+| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:430` |
 
 `renderView()` mesure sa propre phase `render` et injecte automatiquement les aides frontend
 (`frontendTags`, `frontendDocument`, `asset`) dans les variables du template
-(`withFrontendLocals()`, `Controller.ts:448`) — tes propres valeurs restent prioritaires.
+(`withFrontendLocals()`, `Controller.ts:562`) — tes propres valeurs restent prioritaires.
 
 `forward()` re-résout un contrôleur sur le **même** contexte et rappelle son action
-(`Controller.ts:534`) : c'est une délégation interne, la requête cliente reste unique.
+(`Controller.ts:670`) : 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:595`). Un 301 par défaut piégeait : les navigateurs le mettent
+> (`Response.redirect()`, `Response.ts:666`). 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
@@ -446,15 +463,15 @@ Deux besoins distincts, deux helpers.
 
 ### Téléchargement — `renderFileDownload()`
 
-`renderFileDownload(file, options?, headers?)` (`Controller.ts:473`) pose
+`renderFileDownload(file, options?, headers?)` (`Controller.ts:761`) 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:586`) ;
+de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts:722`) ;
 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:609`) implémente les **requêtes par
+`renderMediaStream(file, headers?, options?)` (`Controller.ts:928`) 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                                                         |
@@ -470,11 +487,11 @@ donc testable sans serveur.
 
 ### Ce que `streamFile()` garantit
 
-`streamFile()` (`Controller.ts:669`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
+`streamFile()` (`Controller.ts:801`) 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:553-558`), puis se retire lui-même (`Controller.ts:574`). Un
+résout la promesse (`Controller.ts:762-804`), puis se retire lui-même (`Controller.ts:746`). Un
 téléchargement interrompu ne coûte donc **rien** en ressource retenue.
 
 ## ⚠️ Erreurs — lever, rendre, observer
@@ -489,11 +506,11 @@ 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:874`), qui délègue la mise en
+L'exception remonte jusqu'à `HttpKernel.onError()` (`http-kernel.ts:896`), 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**
-  (`normalizeHttpStatus()`, `error-renderer.ts:355`) ;
+  (`normalizeHttpStatus()`, `error-renderer.ts:642`) ;
 - **corps structuré** : `{ code, message, result: null, error: {…}, nodefony: {…} }`, l'enveloppe
   `nodefony` portant l'environnement, l'URL et l'**identifiant de requête** — de quoi retrouver la
   trace complète dans les logs ;
@@ -501,13 +518,13 @@ forme au rendeur d'erreurs. Ce qui en sort :
   ne tente pas de rendre — il journalise et s'arrête (`http-kernel.ts:770-775`).
 
 En **WebSocket**, il n'y a pas de statut : l'erreur devient un **code de fermeture** RFC 6455
-(`renderWebsocket()`, `error-renderer.ts:393`) — 401/403 → 1008 (violation de politique),
+(`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.
 
 > [!NOTE]
 > Les erreurs de ton action remontent **seules** : le Resolver n'enveloppe pas l'appel dans un
-> `try/catch` inutile (`Resolver.ts:405-406`). Inutile d'attraper pour re-lever — sauf si tu veux
+> `try/catch` inutile (`Resolver.ts:493-494`). Inutile d'attraper pour re-lever — sauf si tu veux
 > vraiment traduire l'erreur en un autre statut.
 
 ## 🧩 Services injectés — trois façons
@@ -521,7 +538,7 @@ explicite :
 const catalog = this.get<CatalogService>("catalog"); // null si absent ou container nettoyé
 ```
 
-`Service.get()` (`Service.ts:472`) est une **façade sûre** : elle retourne `null` au lieu de lever si
+`Service.get()` (`Service.ts:525`) est une **façade sûre** : elle retourne `null` au lieu de lever si
 le container a déjà été détaché. C'est le style à privilégier dans `initialize()`.
 
 ### 2. Injection par le constructeur — `@inject`
@@ -541,7 +558,7 @@ class DemoController extends Controller {
 ```
 
 L'injecteur lit les noms déclarés par `@inject` et résout chaque dépendance dans le container avant
-de construire (`Injector._instantiateWithStack()`, `injector.ts:254`). Le **contexte n'est pas une
+de construire (`Injector._instantiateWithStack()`, `injector.ts:549`). Le **contexte n'est pas une
 dépendance** : il est passé en argument par le Resolver, et les paramètres non annotés le reçoivent
 dans l'ordre (`injector.ts:309`). Les **dépendances circulaires sont détectées** et signalées avec le
 chemin complet (`injector.ts:262-266`), jamais silencieusement.
@@ -568,9 +585,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:402`).
+  chaque requête (`resolveActionMeta()` appelé en `Resolver.ts:491`).
 - **Gardes payées seulement si présentes** : sans `@IsGranted`, la vérification d'autorisation est
-  un test de nullité (`Resolver.ts:334`) — 0 lookup, 0 `await`, 0 allocation.
+  un test de nullité (`Resolver.ts:406`) — 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.
 
@@ -578,13 +595,13 @@ 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:855`)                           |
+| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts:1002`)                          |
 | 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:392`)              |
-| Redirections                     | RFC 9110 §15.4           | Liste blanche + repli 302 (`Response.ts:534`)                  |
-| Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts:760`), vérifié par le banc `auto-json` |
+| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts:503`)              |
+| Redirections                     | RFC 9110 §15.4           | Liste blanche + repli 302 (`Response.ts:666`)                  |
+| Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts:936`), vérifié par le banc `auto-json` |
 | Scalaire JSON de premier niveau  | RFC 8259 §2              | `number`/`boolean` rendus (`Resolver.ts:734`)                  |
-| Codes de fermeture WebSocket     | RFC 6455 §7.4            | `renderWebsocket()` (`error-renderer.ts:393`)                  |
+| Codes de fermeture WebSocket     | RFC 6455 §7.4            | `renderWebsocket()` (`error-renderer.ts:518`)                  |
 
 ## 📡 Observabilité — Studio
 
@@ -601,16 +618,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:801`) | 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:775`) | 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:981`) | 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:951`) | 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:1142`) | 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:1294`) | 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:1210`) | 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:1715`) | 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 toute la connexion (`Resolver.ts:262`) | Réinitialiser l'état en tête d'action, ou le porter par message |
+| 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'action n'est jamais appelée | Route sans transport `WEBSOCKET` déclaré | `requirements: { methods: ["WEBSOCKET"] }` |
-| Contrôleur `singleton` : données d'un autre utilisateur | Champ mutable per-requête sur une instance partagée | Retirer `@Scope("singleton")`, ou passer par les arguments décorés |
-| Event loop figé sur une route de fichier | `getFile()` synchrone (`lstatSync`, `Controller.ts:546`) | Utiliser `getFileAsync()` (`Controller.ts:586`) |
+| 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:682`) | Utiliser `getFileAsync()` (`Controller.ts:722`) |
 
 ## 🧪 Tests & couverture