@nodefony/framework 10.0.0-alpha.7 → 10.0.0-alpha.9

package/docs/idempotence.md

@@ -67,21 +67,21 @@ reste du pipeline ne fait que traduire son verdict.
 
 ## 📖 Lexique
 
-| Terme             | Sens (dans ce module)                                                                              |
-| ----------------- | -------------------------------------------------------------------------------------------------- |
-| Mutation          | Méthode non sûre : `POST`/`PUT`/`PATCH`/`DELETE` (RFC 9110 §9.2.1). GET/HEAD/OPTIONS = no-op.      |
-| `Idempotency-Key` | En-tête client : un identifiant par **intention** d'écriture (convention Stripe, draft IETF).      |
-| Empreinte         | SHA-256 de `route + params + corps` — détecte une clé réutilisée pour autre chose.                 |
-| Bail (_lease_)    | Durée pendant laquelle une réservation _in-flight_ tient sans `complete`/`abort` (60 s).           |
-| Rétention (TTL)   | Durée pendant laquelle une réponse mémorisée reste rejouable (10 min).                             |
-| in-flight         | Réservation posée, pas encore complétée ni abandonnée.                                             |
-| Verdict           | Décision neutre du helper : `execute` / `guarded` / `replay` / `reject`.                           |
-| Scope de clé      | La clé réellement stockée = `[identité, clé client]` → anti-IDOR.                                  |
-| IDOR              | _Insecure Direct Object Reference_ : lire la donnée d'autrui en devinant son identifiant.          |
-| Store             | Backend qui porte les clés (`memory`, `redis`, `drizzle`) derrière le contrat `IIdempotencyStore`. |
-| GC                | _Garbage Collection_ : purge périodique des clés expirées — nécessaire seulement sans TTL natif.   |
-| Fail-soft         | Le store indisponible n'échoue pas la mutation : elle s'exécute **sans** dédup.                    |
-| Fail-loud         | Un store distribué demandé mais non câblé fait échouer le boot plutôt que dédupliquer en silence.  |
+| Terme             | Sens (dans ce module)                                                                                          |
+| ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| Mutation          | Méthode non sûre : `POST`/`PUT`/`PATCH`/`DELETE` (RFC 9110 §9.2.1). GET/HEAD/OPTIONS = no-op.                  |
+| `Idempotency-Key` | En-tête client : un identifiant par **intention** d'écriture (convention Stripe, draft IETF).                  |
+| Empreinte         | SHA-256 de `route + params + corps` — détecte une clé réutilisée pour autre chose.                             |
+| Bail (_lease_)    | Durée pendant laquelle une réservation _in-flight_ tient sans `complete`/`abort` (60 s).                       |
+| Rétention (TTL)   | Durée pendant laquelle une réponse mémorisée reste rejouable (10 min).                                         |
+| in-flight         | Réservation posée, pas encore complétée ni abandonnée.                                                         |
+| Verdict           | Décision neutre du helper : `execute` / `guarded` / `replay` / `reject`.                                       |
+| Scope de clé      | La clé réellement stockée = `[identité, clé client]` → anti-IDOR.                                              |
+| IDOR              | _Insecure Direct Object Reference_ : lire la donnée d'autrui en devinant son identifiant.                      |
+| Store             | Backend qui porte les clés (`memory`, `redis`, `drizzle`, `mongoose`) derrière le contrat `IIdempotencyStore`. |
+| GC                | _Garbage Collection_ : purge périodique des clés expirées — nécessaire seulement sans TTL natif.               |
+| Fail-soft         | Le store indisponible n'échoue pas la mutation : elle s'exécute **sans** dédup.                                |
+| Fail-loud         | Un store distribué demandé mais non câblé fait échouer le boot plutôt que dédupliquer en silence.              |
 
 ## Qu'est-ce que c'est ?
 
@@ -104,7 +104,7 @@ Sans ce ticket, trois choses cassent :
 3. **DoS du cache** — une clé arbitrairement longue, ou un flot de clés uniques, remplirait la
    mémoire. Une clé > 255 octets est traitée comme **absente** plutôt que stockée
    (`IDEMPOTENCY_KEY_MAX`, `idempotency.ts:36`) et le cache mémoire est **borné** (`DEFAULT_CAP`,
-   `IdempotencyStore.ts:18`).
+   `IdempotencyStore.ts:25`).
 
 > [!IMPORTANT]
 > L'idempotence n'est pas qu'une commodité de résilience : c'est une brique de **sécurité**. Une
@@ -119,9 +119,9 @@ connaît **aucun transport**. Il rend un verdict neutre (`IdempotencyVerdict`, `
 que **deux** appelants traduisent dans leur monde :
 
 - le **data plane admin** — `AdminApiController.idempotencyGate()`
-  (`AdminApiController.ts:158`) → réponse `{status, headers, body}` ;
+  (`AdminApiController.ts:131`) → réponse `{status, headers, body}` ;
 - les **controllers userland** décorés `@Idempotent` — seam `Resolver._callWithIdempotency()`
-  (`Resolver.ts:460`) → `nodefonyError` typée, ou réponse rejouée.
+  (`Resolver.ts:499`) → `nodefonyError` typée, ou réponse rejouée.
 
 Conséquence pratique : il est **impossible** que l'idempotence HTTP et l'idempotence WebSocket
 divergent — elles partagent la même fonction. C'est le différenciateur du framework (HTTP + WS
@@ -187,7 +187,7 @@ use("@nodefony/framework", {
     // un nom distribué non câblé fait ÉCHOUER le boot en production (fail-loud)
     // plutôt que dédupliquer per-pod en silence.
     store: "redis",
-    // Purge des clés expirées — utile UNIQUEMENT pour un store SQL (drizzle).
+    // Purge des clés expirées — utile pour les stores SANS TTL natif (drizzle, mongoose).
     gcIntervalS: 600,
   },
 });
@@ -238,7 +238,7 @@ une route que d'anciens clients appellent déjà sans clé, le temps de la migra
 async subscribe(@Body() body: SubscribeInput) { /* … */ }
 ```
 
-Précédence **méthode > classe** (`computeIdempotent()`, `routerDecorators.ts:1561`), comme
+Précédence **méthode > classe** (`computeIdempotent()`, `routerDecorators.ts:1576`), comme
 `@UseSession`. Poser `@Idempotent()` sur la **classe** couvre toutes les mutations du controller ;
 une méthode peut resserrer ou relâcher le mode. Les méthodes sûres (GET…) restent des no-op même
 sous une classe décorée.
@@ -264,9 +264,9 @@ Deux mécanismes rendent ça possible côté socket :
 - **La méthode logique voyage par `methodOverride`** — sur une socket, `context.method` vaut
   `WEBSOCKET`, qui n'est **pas** une mutation. Sans override, la porte serait sautée et un rejeu de
   frame `socket.mutate` créerait un doublon. Le Resolver teste donc
-  `isMutationMethod(this.methodOverride ?? context.method)` (`Resolver.ts:473`).
+  `isMutationMethod(this.methodOverride ?? context.method)` (`Resolver.ts:126`).
 
-Le pont utilise `executeActionGuarded()` (`Resolver.ts:425`) : porte d'idempotence **sans** rendu HTTP
+Le pont utilise `executeActionGuarded()` (`Resolver.ts:464`) : porte d'idempotence **sans** rendu HTTP
 — la valeur nue est enveloppée par le peer WS, jamais écrite sur un transport HTTP.
 
 ## 🏗️ Architecture interne
@@ -299,7 +299,7 @@ sequenceDiagram
 
 ### Le parcours d'une mutation, étape par étape
 
-1. **Court-circuit hot path.** `callController()` (`Resolver.ts:396`) lit `meta.idempotent` sur les
+1. **Court-circuit hot path.** `callController()` (`Resolver.ts:435`) lit `meta.idempotent` sur les
    métadonnées d'action **figées par route**. `null` sur la quasi-totalité des routes → une
    comparaison, flux normal, **zéro** lookup de store et zéro allocation.
 2. **No-op sur méthode sûre.** Une action `GET` sous une classe `@Idempotent` repart directement en
@@ -327,20 +327,20 @@ sequenceDiagram
 
 | Appelant                     | Point d'entrée                                                       | Traduction du verdict              |
 | ---------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
-| Controller userland HTTP     | `callController()` (`Resolver.ts:396`)                               | `nodefonyError` + rendu normal     |
-| Controller userland via WS   | `executeActionGuarded()` (`Resolver.ts:425`)                         | valeur nue, enveloppée par le peer |
-| Data plane admin `/nodefony` | `AdminApiController.idempotencyGate()` (`AdminApiController.ts:158`) | `{status, headers, body}`          |
+| Controller userland HTTP     | `callController()` (`Resolver.ts:435`)                               | `nodefonyError` + rendu normal     |
+| Controller userland via WS   | `executeActionGuarded()` (`Resolver.ts:464`)                         | valeur nue, enveloppée par le peer |
+| Data plane admin `/nodefony` | `AdminApiController.idempotencyGate()` (`AdminApiController.ts:131`) | `{status, headers, body}`          |
 
 ## ⚙️ Configuration
 
 Source unique = schéma Zod `idempotencySchema`
 (`src/packages/@nodefony/framework/nodefony/config/config.ts:42`).
 
-| Option        | Type      | Défaut   | Effet                                                                                                                       |
-| ------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `store`       | `string`  | `"auto"` | Backing du cache. `auto` suit l'infra déclarée ; `memory` / `redis` / `drizzle` sont explicites (`config.ts:43`).           |
-| `gcIntervalS` | `int ≥ 0` | `600`    | Intervalle de purge des clés expirées, **hors** hot-path. Sans effet pour `redis` (TTL natif) et `memory` (`config.ts:57`). |
-| `gcJitter`    | `bool`    | `true`   | Étale le départ du GC par process — anti _thundering-herd_ sur un store SQL partagé (`config.ts:68`).                       |
+| Option        | Type      | Défaut   | Effet                                                                                                                          |
+| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `store`       | `string`  | `"auto"` | Backing du cache. `auto` suit l'infra déclarée ; `memory` / `redis` / `drizzle` / `mongoose` sont explicites (`config.ts:43`). |
+| `gcIntervalS` | `int ≥ 0` | `600`    | Intervalle de purge des clés expirées, **hors** hot-path. Sans effet pour `redis` (TTL natif) et `memory` (`config.ts:57`).    |
+| `gcJitter`    | `bool`    | `true`   | Étale le départ du GC par process — anti _thundering-herd_ sur un store SQL partagé (`config.ts:68`).                          |
 
 ### Comment `store: "auto"` se résout VRAIMENT
 
@@ -351,7 +351,7 @@ réel est le suivant :
 
 | Ordre | Condition                                                                | Résolution                             | Ancre          |
 | ----- | ------------------------------------------------------------------------ | -------------------------------------- | -------------- |
-| 1     | `NF_STORE=<x>` et `<x>` enregistré pour cette brique                     | `<x>` (override global)                | `infra.ts:251` |
+| 1     | `NF_STORE=<x>` et `<x>` enregistré pour cette brique                     | `<x>` (override global)                | `infra.ts:343` |
 | 2     | Infra **cache** déclarée (`NF_REDIS_URL`) et `redis` enregistré          | `redis`                                | `infra.ts:258` |
 | 3     | Infra **database** déclarée (`NF_DATABASE_URL`) et le backend enregistré | `drizzle` (SQL) / `mongoose` (Mongo)   | `infra.ts:261` |
 | 4     | Une préférence existait mais son backend n'est pas enregistré            | `fallback` = `memory`, raison ANNONCÉE | `infra.ts:274` |
@@ -364,11 +364,11 @@ réel est le suivant :
 > que les données survivent au redémarrage. La résolution effective est toujours **journalisée au
 > boot** (`index.ts:207`) : lis cette ligne plutôt que de la déduire.
 
-MongoDB mérite une mention : `mongoose` n'implémente **pas encore** de store d'idempotence. Déclarer
-`NF_DATABASE_URL=mongodb://…` fait donc tomber la résolution en étape **4** → repli `memory` avec la
-raison annoncée — et un repli `memory` en cluster ne déduplique plus rien entre pods : le rejeu que
-cette brique promet d'empêcher passe sur un autre pod. En attendant le store Mongo (objectif « full
-NoSQL », `MIGRATION_STATUS.md` P7.11), la dédup cross-pod passe par `redis`.
+MongoDB mérite une mention : `mongoose` porte lui aussi un store d'idempotence. Déclarer
+`NF_DATABASE_URL=mongodb://…` résout donc en étape **3** → `mongoose`, et la dédup cross-pod tient
+sans qu'il faille ajouter Redis à l'infrastructure. Sa réservation atomique repose sur la
+contrainte d'unicité de `_id` — un `findOneAndUpdate` filtré sur l'entrée morte, en `upsert`, dont
+le perdant reçoit un `E11000` : l'équivalent Mongo du `SET … NX PX` de Redis.
 
 ### Le contrat de dégradation : fail-loud, jamais silencieux
 
@@ -392,28 +392,29 @@ Tous respectent le même contrat `IIdempotencyStore`
 
 ### Choisir en 5 secondes
 
-| Store     | Atomicité de `begin`                            | Expiration         | `gc()` | Multi-pod | Pour…                                    |
-| --------- | ----------------------------------------------- | ------------------ | :----: | :-------: | ---------------------------------------- |
-| `memory`  | mono-thread JS                                  | passive + cap FIFO |   ❌   |    ❌     | dev, tests, mono-pod                     |
-| `redis`   | `SET … NX PX`                                   | TTL natif (`PX`)   |   ❌   |    ✅     | cluster — le choix par défaut recommandé |
-| `drizzle` | `INSERT … ON CONFLICT DO UPDATE … WHERE expiré` | applicative        |   ✅   |    ✅     | cluster qui a déjà du SQL, pas de Redis  |
+| Store      | Atomicité de `begin`                            | Expiration         | `gc()` | Multi-pod | Pour…                                    |
+| ---------- | ----------------------------------------------- | ------------------ | :----: | :-------: | ---------------------------------------- |
+| `memory`   | mono-thread JS                                  | passive + cap FIFO |   ❌   |    ❌     | dev, tests, mono-pod                     |
+| `redis`    | `SET … NX PX`                                   | TTL natif (`PX`)   |   ❌   |    ✅     | cluster — le choix par défaut recommandé |
+| `drizzle`  | `INSERT … ON CONFLICT DO UPDATE … WHERE expiré` | applicative        |   ✅   |    ✅     | cluster qui a déjà du SQL, pas de Redis  |
+| `mongoose` | `findOneAndUpdate(expiré) upsert` → `E11000`    | applicative        |   ✅   |    ✅     | cluster qui a déjà Mongo, pas de Redis   |
 
 ### `memory` — le défaut per-pod, gratuit
 
 `MemoryIdempotencyStore` (`IdempotencyStore.ts:44`) est enregistré d'office comme service DI
 `idempotencyStore` par le manifeste `@services` du module framework — zéro configuration.
 
-- **Atomicité par le mono-thread JS** : `begin()` (`IdempotencyStore.ts:107`) lit et écrit la `Map`
+- **Atomicité par le mono-thread JS** : `begin()` (`IdempotencyStore.ts:115`) lit et écrit la `Map`
   sans point de suspension → deux `begin` concurrents ne peuvent pas se croiser.
-- **Constantes** : rétention `DEFAULT_TTL_MS` = 600 s (`IdempotencyStore.ts:14`), bail
-  `DEFAULT_LEASE_MS` = 60 s (`IdempotencyStore.ts:16`), plafond `DEFAULT_CAP` = 1000 entrées
-  (`IdempotencyStore.ts:18`). Elles ne sont **pas** configurables.
-- **Lazy** : la `Map` n'est allouée qu'au **1ᵉʳ** `begin` (`IdempotencyStore.ts:46`) ; aucun timer,
+- **Constantes** : rétention `DEFAULT_TTL_MS` = 600 s (`IdempotencyStore.ts:21`), bail
+  `DEFAULT_LEASE_MS` = 60 s (`IdempotencyStore.ts:23`), plafond `DEFAULT_CAP` = 1000 entrées
+  (`IdempotencyStore.ts:25`). Elles ne sont **pas** configurables.
+- **Lazy** : la `Map` n'est allouée qu'au **1ᵉʳ** `begin` (`IdempotencyStore.ts:115`) ; aucun timer,
   aucun listener.
 - **Purge passive** : les entrées expirées ne sont retirées qu'à l'écriture, dans `evictIfNeeded()`
-  (`IdempotencyStore.ts:164`), qui purge d'abord les mortes puis évince en **FIFO** jusqu'à repasser
+  (`IdempotencyStore.ts:172`), qui purge d'abord les mortes puis évince en **FIFO** jusqu'à repasser
   sous le cap. Coût nul tant qu'on n'écrit pas.
-- **Garde anti-résurrection** : `complete()` (`IdempotencyStore.ts:134`) n'écrit **que** si la clé est
+- **Garde anti-résurrection** : `complete()` (`IdempotencyStore.ts:142`) n'écrit **que** si la clé est
   encore _notre_ in-flight — jamais de résurrection d'une clé déjà `abort`-ée ou évincée.
 
 ⚠️ Limite structurelle : la dédup est **affine au pod**. Un rejeu routé vers un autre pod n'est pas
@@ -452,7 +453,7 @@ déjà Postgres mais pas Redis obtient la dédup cross-pod **sans nouvelle infra
 
 - **Réservation atomique en UNE instruction** — un `INSERT` avec
   `onConflictDoUpdate` (`DrizzleIdempotencyStore.ts:234`) dont la garde `setWhere` ne réécrit que si
-  l'entrée est morte (`DrizzleIdempotencyStore.ts:244`). Le `returning` ne rend une ligne que si
+  l'entrée est morte (`DrizzleIdempotencyStore.ts:264`). Le `returning` ne rend une ligne que si
   l'INSERT a passé (clé neuve) ou si le `DO UPDATE` a **volé** une entrée expirée → `fresh`. Zéro
   ligne = contention → on lit l'état réel.
 - **Invariant capital** : le store ne renvoie **jamais** `fresh` hors réservation atomique gagnée.
@@ -460,14 +461,14 @@ déjà Postgres mais pas Redis obtient la dédup cross-pod **sans nouvelle infra
   (`DrizzleIdempotencyStore.ts:264`), jamais `fresh`.
 - **MySQL/MariaDB** : ni `RETURNING`, ni `WHERE` sur l'`ON DUPLICATE KEY UPDATE`, et un `affectedRows`
   ambigu → la réservation passe par `reserveIdempotencyKeyMysql()`
-  (`DrizzleIdempotencyStore.ts:213`), qui la reconstruit en deux instructions chacune atomique.
+  (`DrizzleIdempotencyStore.ts:233`), qui la reconstruit en deux instructions chacune atomique.
 - **Pas de TTL natif** → `gc()` (`DrizzleIdempotencyStore.ts:318`) = `DELETE WHERE expiresAt <= now`.
   C'est le **seul** store qui expose `gc`, donc le seul que le framework planifie (voir plus bas).
-- **Mutations conditionnelles** : `complete()` (`DrizzleIdempotencyStore.ts:276`) et `abort()`
-  (`DrizzleIdempotencyStore.ts:294`) portent `WHERE state = 'if'` — jamais d'écrasement d'une réponse
+- **Mutations conditionnelles** : `complete()` (`DrizzleIdempotencyStore.ts:296`) et `abort()`
+  (`DrizzleIdempotencyStore.ts:314`) portent `WHERE state = 'if'` — jamais d'écrasement d'une réponse
   déjà mémorisée, jamais de résurrection d'une clé libérée. `complete` ne touche pas `fingerprint`.
 - **Résolution lazy + dégradation gracieuse** : le handle Drizzle est résolu à **chaque** appel
-  (`DrizzleIdempotencyStore.from()`, `DrizzleIdempotencyStore.ts:172`). ORM non connecté → `begin`
+  (`DrizzleIdempotencyStore.from()`, `DrizzleIdempotencyStore.ts:191`). ORM non connecté → `begin`
   renvoie `fresh` (sans dédup), le reste est no-op.
 
 Le câblage est **automatique** : charger `@nodefony/drizzle` enregistre l'entité **et** la fabrique
@@ -522,10 +523,14 @@ Deux détails qui expliquent des surprises réelles :
 | `drizzle` (SQL) | SQLite                   | idem, mais mono-machine → **test**              |    ❌     |      ✅       |
 | `memory`        | RAM du pod               | mono-thread JS ; cap FIFO 1000 ; TTL 10 min     |    ❌     |      n/a      |
 
-> [!CAUTION]
-> **MongoDB (`@nodefony/mongoose`) n'implémente PAS de store d'idempotence.** Sélectionner
-> `store: "mongoose"` échoue à la résolution (fail-loud) ; laisser `auto` avec une infra Mongo replie
-> sur `memory` avec une raison annoncée. En cluster Mongo, la dédup passe par `redis`.
+> [!NOTE]
+> **MongoDB (`@nodefony/mongoose`) porte un store d'idempotence.** `store: "mongoose"` est
+> sélectionnable dès que le module est chargé, et `auto` avec une infra Mongo y résout tout seul.
+> En cluster Mongo, la dédup cross-pod n'exige donc pas d'ajouter Redis.
+>
+> Comme la variante SQL, il n'a **pas de TTL natif** : le framework arme un `GcScheduler` parce
+> que le store expose `gc()`. L'échéance d'une entrée bascule du bail à la rétention, ce qu'un
+> index TTL ne saurait pas suivre.
 
 ## 🧰 API publique
 
@@ -533,8 +538,8 @@ Signatures complètes : `.ai/symbols.json`. Ce qui compte à l'usage :
 
 ### Le décorateur
 
-`@Idempotent(options?)` (`routerDecorators.ts:1103`) — dual **classe + méthode**. N'écrit que des
-métadonnées (`IdempotentMeta`, `routerDecorators.ts:443`), zéro import de `@nodefony/security`, zéro
+`@Idempotent(options?)` (`routerDecorators.ts:1142`) — dual **classe + méthode**. N'écrit que des
+métadonnées (`IdempotentMeta`, `routerDecorators.ts:457`), zéro import de `@nodefony/security`, zéro
 cycle. La porte est appliquée par le Resolver.
 
 ### Le contrat de store
@@ -576,7 +581,7 @@ Le mode **curseur** de Redis mérite une explication, parce qu'il piège : `SCAN
 plafond** mais un indice d'effort — Redis peut rendre plus de clés que demandé. Sans précaution, la
 page dépasserait `limit` et violerait le contrat `IPage` (`src/nodefony/src/types/IPage.ts:108`). D'où
 le **curseur composite** `"<consommé>:<curseurRedis>"` (`encodeCursor()`,
-`RedisIdempotencyStore.ts:57`) : on ne rend que `limit` éléments et on mémorise combien de clés du
+`RedisIdempotencyStore.ts:63`) : on ne rend que `limit` éléments et on mémorise combien de clés du
 lot ont été consommées ; la page suivante rejoue le **même** `SCAN` et reprend là.
 
 > [!IMPORTANT]
@@ -641,13 +646,13 @@ pour l'affichage Studio, `idempotencyStoreRegistry.ts:81`).
 
 Le coût est **nul hors mutations décorées**. Sans `@Idempotent`, `RouteActionMeta.idempotent` vaut
 `null` (`routerDecorators.ts:1103`) : `callController()` fait **une comparaison** et repart en flux
-normal — zéro lookup de container, zéro `await` supplémentaire, zéro allocation (`Resolver.ts:396`).
+normal — zéro lookup de container, zéro `await` supplémentaire, zéro allocation (`Resolver.ts:435`).
 La métadonnée est **figée par route** et mémoïsée : aucune lecture `Reflect` par requête.
 
 Sur le chemin décoré :
 
 - Le store mémoire n'alloue sa `Map` qu'au 1ᵉʳ `begin`, ne pose **aucun timer ni listener**, et purge
-  en passif (`IdempotencyStore.ts:164`).
+  en passif (`IdempotencyStore.ts:115`).
 - L'empreinte est un hash SHA-256 court → comparaison O(1), et le payload n'est jamais conservé en
   clair.
 - Le GC est **hors hot-path** et armé pour un seul store (SQL) ; le jitter évite que N pods purgent
@@ -669,7 +674,7 @@ Trois surfaces existent aujourd'hui :
   façon la plus rapide de voir un rejeu, un `409` ou un `422` en vrai.
 - **Stores** — la brique `idempotency` y apparaît avec sa nature **éphémère**, le backend configuré,
   le backend résolu, la liste des backends disponibles et la raison de la résolution — brique
-  `idempotency` (`stores/storesModel.ts:150`). C'est là qu'on vérifie qu'`auto` a choisi ce qu'on
+  `idempotency` (`stores/storesModel.ts:145`). C'est là qu'on vérifie qu'`auto` a choisi ce qu'on
   croyait.
 - **ERD** — la table `idempotency_key` est regroupée sous `@nodefony/framework`
   (`idempotencyEntity.ts:133`), pas sous l'ORM qui l'héberge.
@@ -684,7 +689,7 @@ Trois surfaces existent aujourd'hui :
 
 | Symptôme                                               | Cause (dans le code)                                                                 | Correction                                                                   |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| Rejeu qui renvoie un corps **vide**                    | L'action a retourné `this.renderJson(...)` au lieu du payload (`Resolver.ts:549`)    | Retourner la **valeur brute** ; un WARNING le signale déjà dans les logs     |
+| Rejeu qui renvoie un corps **vide**                    | L'action a retourné `this.renderJson(...)` au lieu du payload (`Resolver.ts:581`)    | Retourner la **valeur brute** ; un WARNING le signale déjà dans les logs     |
 | `409` en boucle sur un endpoint                        | Action qui lève avant `complete`/`abort` → in-flight bloqué jusqu'au bail (60 s)     | Le seam le gère ; en usage manuel du store, `try/finally` obligatoire        |
 | `422 Idempotency-Key is already used`                  | Même clé, **payload différent** (empreinte ≠, `idempotency.ts:189`)                  | Une clé = une intention ; nouvelle clé par requête distincte                 |
 | Rien n'est dédupliqué **malgré** la clé                | Pas d'identité fiable → verdict `execute` (`idempotency.ts:176`)                     | S'assurer que le firewall a résolu l'utilisateur **avant** la mutation       |

package/docs/routing.md

@@ -55,7 +55,7 @@ Trois faits à retenir avant tout le reste :
    (`HttpError("Not Found", 404)`, `http-kernel.ts:798`).
 3. **Le chemin est vérifié avant la méthode, et le domaine entre les deux** — c'est ce qui produit un
    `403` plutôt qu'un `405` bavard quand la route appartient à un autre vhost (`Route.match()`,
-   `Route.ts:212`).
+   `Route.ts:327`).
 
 ## 📖 Lexique
 
@@ -101,7 +101,7 @@ contrôleur.
 
 **La performance ne change pas la sémantique.** Sous le capot, la table est partitionnée : les chemins
 **littéraux** (aucun `{var}`, aucun métacaractère) vivent dans une `Map path → candidates` en lookup
-O(1) ; les chemins **dynamiques** restent un scan regex (`buildRouteIndex()`, `router.ts:92`). À la
+O(1) ; les chemins **dynamiques** restent un scan regex (`buildRouteIndex()`, `router.ts:130`). À la
 résolution, les deux flux sont fusionnés **par position d'insertion** — la séquence de candidats est
 exactement celle du scan linéaire complet, moins les littérales d'un autre chemin, qui ne pouvaient de
 toute façon pas correspondre (`Router.resolve()`, `router.ts:221`). C'est cette équivalence que fige le
@@ -109,7 +109,7 @@ banc de non-régression : un refacto du routeur doit le repasser à l'identique.
 
 **Une seule table pour HTTP et WebSocket.** Il n'y a pas de « routeur WS » séparé : une action WS est
 une route dont les méthodes déclarées contiennent `WEBSOCKET` (`Route.matchRequirements()`,
-`Route.ts:649`). C'est le différenciateur du framework — le même contrôleur, le même contexte, les
+`Route.ts:700`). C'est le différenciateur du framework — le même contrôleur, le même contexte, les
 mêmes décorateurs.
 
 **Le routeur passe avant les fichiers statiques.** Une requête qui correspond à une route ne paie
@@ -263,15 +263,15 @@ que chaque forme **produit dans la table**.
 | `@route(nom, options)`                    | **le tien** (stable, réutilisable) | `requirements.methods` (libre)   | WebSocket, multi-méthodes, contraintes fines |
 
 - Les décorateurs de méthode HTTP délèguent tous à `@route` avec un nom auto `Classe::methode`, et
-  posent `requirements: { methods }` (`httpMethodDecorator()`, `routerDecorators.ts:340`).
+  posent `requirements: { methods }` (`httpMethodDecorator()`, `routerDecorators.ts:469`).
 - `@All` n'émet **aucun** requirement de méthode : la route sert alors GET, POST, DELETE… et ne peut
-  donc jamais produire un 405 sur la méthode (`All()`, `routerDecorators.ts:374`).
+  donc jamais produire un 405 sur la méthode (`All()`, `routerDecorators.ts:528`).
 - `@route` est la forme complète : elle seule permet `protocol` (sous-protocole WS), un nom lisible, et
   des requirements par variable.
 
 **Comment une déclaration devient une route.** Les décorateurs de méthode **accumulent** des métadonnées
 sur le constructeur (clé `routes:definitions`, `routerDecorators.ts:16`) ; c'est `@controller(prefix)`
-qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `routerDecorators.ts:129`).
+qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `routerDecorators.ts:189`).
 
 > [!WARNING]
 > **`@route`/`@Get` doivent être SOUS `@controller`** — les décorateurs de classe s'évaluent après ceux
@@ -281,7 +281,7 @@ qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `rou
 ## Motifs de chemin et paramètres
 
 Le chemin déclaré est compilé **une fois**, à la création de la route, en une expression régulière
-ancrée et **insensible à la casse** (`Route.compile()`, `Route.ts:395`). La grammaire tient en cinq
+ancrée et **insensible à la casse** (`Route.compile()`, `Route.ts:424`). La grammaire tient en cinq
 briques (`REG_ROUTE`, `Route.ts:17`) :
 
 | Écriture           | Motif compilé | Capture           | Exemple                                               |
@@ -295,7 +295,7 @@ briques (`REG_ROUTE`, `Route.ts:17`) :
 Et trois comportements qui surprennent la première fois :
 
 - **Le slash final est retiré avant le matching** — `/books/` et `/books` désignent la même route
-  (`Route.cleanPathname()`, `Route.ts:274`). Corollaire : `/files/*` ne matche pas `/files/`, qui a été
+  (`Route.cleanPathname()`, `Route.ts:303`). Corollaire : `/files/*` ne matche pas `/files/`, qui a été
   normalisé en `/files`.
 - **Les valeurs sont URL-décodées** — `%C3%A9t%C3%A9` arrive dans l'action comme `été`
   (`decode()`, `Route.ts:79`).
@@ -307,7 +307,7 @@ Et trois comportements qui surprennent la première fois :
 C'est le mécanisme le moins évident, et le plus utile. Déclarer un `defaults` pour une variable change
 le motif compilé : le segment devient facultatif (`[^/]*`) **et son slash aussi** (`/?`), puis la valeur
 par défaut est réinjectée quand la capture est vide (`checkDefaultParameters()`, `Route.ts:99` ·
-`Route.hydrateDefaultParameters()`, `Route.ts:469`).
+`Route.hydrateDefaultParameters()`, `Route.ts:513`).
 
 ```ts ignore
 @route("route-page", { path: "/page/{slug}", defaults: { slug: "home" } })
@@ -327,7 +327,7 @@ async page(slug: string) {
 Les captures sont passées **positionnellement**, dans l'ordre des variables du chemin — c'est pourquoi
 la signature `async method6(metier: string, format: string)` suit l'ordre de `/{metier}/{format}`. Un
 wildcard est exposé sous les clés `wildcard` et `*`. Le `Resolver` en fabrique aussi un instantané
-nom → valeur par requête (`Resolver.getMatchedParams()`, `Resolver.ts:170`), lu par le contexte pour
+nom → valeur par requête (`Resolver.getMatchedParams()`, `Resolver.ts:188`), lu par le contexte pour
 les métadonnées et par les décorateurs `@Param`.
 
 > [!IMPORTANT]
@@ -389,11 +389,11 @@ accepte, pas seulement ce que la dernière route scannée acceptait.
 ### Situation 3 — une route réservée à un domaine
 
 Une route restreinte par `@Domain` est **invisible** aux requêtes des autres vhosts : elle lève un 403
-au lieu de participer au match (`Route.matchHostname()`, `Route.ts:605`). Le point de sécurité est
+au lieu de participer au match (`Route.matchHostname()`, `Route.ts:641`). Le point de sécurité est
 l'**ordre des vérifications** : le domaine est vérifié **avant** la méthode. Sans cela, une route d'un
 autre vhost pourrait répondre 405 en révélant SES méthodes — une fuite d'information cross-domaine
-(`Route.match()`, `Route.ts:298`). La passe 2 applique la même règle : les routes d'un autre vhost sont
-exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts:270`).
+(`Route.match()`, `Route.ts:327`). La passe 2 applique la même règle : les routes d'un autre vhost sont
+exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts:341`).
 
 Si une autre route du même chemin sert **tous** les vhosts, le scan continue jusqu'à elle : le 403
 n'interrompt pas la recherche, il ne conclut que s'il ne reste aucune candidate.
@@ -418,12 +418,12 @@ Ce qui change par rapport au HTTP :
   inconnu ou un sous-protocole non conforme ferme la connexion **sans jamais l'ouvrir**.
 - **Le sous-protocole est un requirement de route.** Un `protocol` déclaré et non satisfait lève une
   erreur de code **1002** (Protocol Error, RFC 6455 §7.4) au lieu d'un statut HTTP
-  (`acceptedProtocol`, `Route.ts:722`).
+  (`acceptedProtocol`, `Route.ts:758`).
 - **Le 405 ne s'applique pas au WebSocket.** La passe 2 est réservée au HTTP : sur un contexte WS,
   l'exception d'origine est préservée (`Router.resolve()`, `router.ts:230`).
 - **Un `Resolver` par connexion, réutilisé à chaque frame.** Il est créé au handshake, puis chaque
   message rejoue `match()` sur la route déjà trouvée avant d'appeler l'action
-  (`WebsocketContext.handle()`, `WebsocketContext.ts:271` · boucle message,
+  (`WebsocketContext.handle()`, `WebsocketContext.ts:265` · boucle message,
   `callController`, `WebsocketContext.ts:508`).
   L'action est donc invoquée une fois au handshake (`message` vaut `null`), puis une fois par frame.
 
@@ -438,9 +438,9 @@ que fait le data plane d'administration pour toutes ses lectures (`AdminBroker.m
   (`routing-nonregression.test.ts:164`).
 - **Une invocation WS d'une mutation doit dire quelle méthode logique elle vise.** Sur une socket,
   `context.method` vaut toujours `WEBSOCKET` : insuffisant pour distinguer un GET d'un POST sur le même
-  chemin. Le pont transporte donc une **méthode logique** (`methodOverride`, `Resolver.ts:116`) que la
+  chemin. Le pont transporte donc une **méthode logique** (`methodOverride`, `Resolver.ts:126`) que la
   route doit déclarer **en plus** du transport — une route `POST` qui n'annonce pas `WEBSOCKET` reste
-  **injoignable** par socket (zéro contournement, `Route.ts:678`).
+  **injoignable** par socket (zéro contournement, `Route.ts:722`).
 
 Le routage par **message** (invoquer un chemin porté par une frame, sans toucher l'URL de la connexion)
 passe par le même `resolve()`, avec un chemin fourni en argument — l'état partagé de la socket n'est
@@ -451,7 +451,7 @@ jamais muté (`Router.resolve()`, `router.ts:230`). Détails côté socket :
 
 `@Domain` restreint une méthode (ou tout un contrôleur) à un ou plusieurs noms d'hôte. Les motifs
 acceptent l'exact (`"marseille.fr"`) et le joker d'un label (`"*.cdn.example.com"`), compilés une fois
-au boot en expressions ancrées (`Route.compileHost()`, `Route.ts:468`).
+au boot en expressions ancrées (`Route.compileHost()`, `Route.ts:627`).
 
 ```ts ignore
 @controller("/")
@@ -463,14 +463,14 @@ class MarseilleController extends Controller {
 ```
 
 Précédence, du plus fort au plus faible : `@route({ host })` › `@Domain` sur la méthode › `@Domain` sur
-la classe (`controller()`, `routerDecorators.ts:89`). Une route sans domaine est servie sur **tous** les
+la classe (`controller()`, `routerDecorators.ts:189`). Une route sans domaine est servie sur **tous** les
 vhosts, et ne coûte rien au matching (`hostRegexp` absent → aucun test, `Route.matchHostname()`,
-`Route.ts:605`).
+`Route.ts:641`).
 
 > [!WARNING]
 > `@Domain` déclare quels vhosts une route **sert** ; il ne remplace pas la barrière d'entrée. Un
 > `Host` inconnu du serveur est rejeté en amont (421 Misdirected Request, `checkValidDomain()`,
-> `http-kernel.ts:1697`) via la liste `trustedHosts` de `@nodefony/http`.
+> `http-kernel.ts:1749`) via la liste `trustedHosts` de `@nodefony/http`.
 
 ## Préfixes — contrôleur, module, data plane
 
@@ -478,14 +478,14 @@ Trois niveaux de préfixe coexistent, et un seul est à ta main.
 
 1. **Le préfixe de contrôleur** — `@controller("/api/catalog")` est concaténé devant le chemin de
    chaque route de la classe, puis le chemin est normalisé : les `//` sont réduits et le slash final
-   retiré (`Route.setPattern()`, `Route.ts:551`). Un chemin vide (`@Get("")`) désigne donc le préfixe
+   retiré (`Route.setPattern()`, `Route.ts:602`). Un chemin vide (`@Get("")`) désigne donc le préfixe
    lui-même.
 2. **Le module propriétaire** — il n'ajoute **aucun** préfixe d'URL. `@controllers([…])` enregistre la
    classe au boot et propage le nom du module sur les routes déjà créées, pour l'introspection et les
-   logs (`Router.setController()`, `router.ts:417`). Un module tiers et ton app peuvent porter deux
+   logs (`Router.setController()`, `router.ts:421`). Un module tiers et ton app peuvent porter deux
    contrôleurs homonymes sans collision : la clé du registre est `module:Classe` (`router.ts:164`).
 3. **Le data plane d'administration** — réservé, non négociable : `/nodefony/<namespace>/api/<endpoint>`
-   (`AdminBroker.resolvePath()`, `AdminBroker.ts:91`). Trois segments minimum, pour ne jamais entrer en
+   (`AdminBroker.resolvePath()`, `AdminBroker.ts:99`). Trois segments minimum, pour ne jamais entrer en
    collision avec les routes de l'application ni avec la SPA de Studio.
 
 > [!TIP]
@@ -502,10 +502,10 @@ d'une route — il survit à un changement de chemin.
 | Besoin                                   | Comment                                                                   |
 | ---------------------------------------- | ------------------------------------------------------------------------- |
 | Retrouver une route par son nom          | `router.getRoutes("ma-route")` → l'objet `Route` (`router.ts:326`)        |
-| Lister toutes les routes                 | `router.getRoutes("")` → la table complète (`router.ts:387`)              |
-| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts:376`) |
-| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts:445`)          |
-| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts:335`)                       |
+| Lister toutes les routes                 | `router.getRoutes("")` → la table complète (`router.ts:391`)              |
+| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts:380`) |
+| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts:534`)          |
+| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts:400`)                       |
 
 **Il n'existe pas de générateur d'URL inverse côté serveur** (pas de `path("ma-route", {id})` à la
 Symfony). Le chemin déclaré est lisible sur l'objet `Route` (`route.path`), et la substitution des
@@ -515,7 +515,7 @@ chemin ; pour un appel interne, utilise `forward()`.
 
 **`forward()` n'est pas une redirection** : il résout `module:Controller:action` et exécute l'action
 dans le **même** contexte de requête, sans repasser par le réseau (`Resolver.parsePathernController()`,
-`Resolver.ts:185`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
+`Resolver.ts:203`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
 
 ## 🧰 API publique
 
@@ -529,7 +529,7 @@ modules qui montent des routes dynamiquement). Signatures complètes : `.ai/symb
 | `router.resolve(context)`                  | Le cœur : rend un `Resolver` (`resolve === true` si trouvé).            |
 | `router.getRoutes(nom)` · `removeRoutes()` | Introspection et démontage.                                             |
 | `Route#path` · `#variables` · `#pattern`   | Ce que la route déclare, après compilation.                             |
-| `Route#toObject()` · `#toLogLine()`        | Sérialisation pour l'API admin · ligne de log lisible (`Route.ts:525`). |
+| `Route#toObject()` · `#toLogLine()`        | Sérialisation pour l'API admin · ligne de log lisible (`Route.ts:554`). |
 | `Resolver#route` · `#variables`            | Ce que la requête courante a matché.                                    |
 | `Resolver#getMatchedParams()`              | Les variables en `nom → valeur` (`Resolver.ts:170`).                    |
 
@@ -546,31 +546,31 @@ alloué par requête.
 
 - **Compilation unique au montage** : motif d'URL, motifs de domaine, `Set` de méthodes en majuscules,
   chaîne `Allow`, et regex des requirements par variable sont figés à la création de la route
-  (`Route.compileRequirements()`, `Route.ts:324`). Le matching ne fait plus que des lookups.
+  (`Route.compileRequirements()`, `Route.ts:476`). Le matching ne fait plus que des lookups.
 - **Un seul calcul de chemin par requête** : le `pathname` normalisé est calculé une fois puis passé à
   chaque route scannée — sinon le getter `URL.pathname`, la regex de normalisation et l'allocation de
-  chaîne seraient refaits pour **chaque** route de la table (`Route.cleanPathname()`, `Route.ts:204`).
+  chaîne seraient refaits pour **chaque** route de la table (`Route.cleanPathname()`, `Route.ts:303`).
 - **Lookup O(1) pour les chemins littéraux**, scan pour les seuls chemins à motif — sans changer la
   séquence de candidats (`buildRouteIndex()`, `router.ts:130`). L'index est invalidé par toute mutation
   de la table, avec un garde-fou sur une photo `longueur/première/dernière` qui rattrape même les
-  mutations directes de la liste (`routeIndex`, `router.ts:201`).
+  mutations directes de la liste (`routeIndex`, `router.ts:127`).
 - **Zéro journalisation en production** : le log « route trouvée » est promu au niveau NOTICE hors
   production seulement, et le test est résolu une fois puis mémoïsé — en production, aucune chaîne
   n'est même construite (`routeNoticePromoted`, `router.ts:299`).
 - **Métadonnées d'action mémoïsées par route** au premier passage (`@HttpCode`, `@Header`, `@Redirect`,
   paramètres, intention de session) : plus aucune lecture `Reflect` par requête
-  (`resolveActionMeta`, `Resolver.ts:142`).
+  (`resolveActionMeta`, `Resolver.ts:469`).
 
 ## 📜 Normes appliquées
 
 | Sujet                                    | Norme             | Où le code s'y conforme                                         |
 | ---------------------------------------- | ----------------- | --------------------------------------------------------------- |
 | 405 + en-tête `Allow` agrégé             | RFC 9110 §15.5.6  | passe 2 (`collectSupportedMethods()`, `router.ts:31`)           |
-| Cible identifiée par l'URI, hôte compris | RFC 9110 §7.2     | hôte vérifié avant la méthode (`Route.match()`, `Route.ts:298`) |
-| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:605`)                        |
+| Cible identifiée par l'URI, hôte compris | RFC 9110 §7.2     | hôte vérifié avant la méthode (`Route.match()`, `Route.ts:327`) |
+| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:641`)                        |
 | 404 quand rien ne correspond             | RFC 9110 §15.5.5  | après repli statique (`http-kernel.ts:688`)                     |
-| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1740`)                    |
-| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:649`)                    |
+| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1749`)                    |
+| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:700`)                    |
 | Décodage pourcent des segments           | RFC 3986 §2.1     | `decode()` (`Route.ts:79`)                                      |
 
 ## 📡 Observabilité — Studio
@@ -581,14 +581,14 @@ La table de routes est introspectable en ligne, sans lire le code :
   méthodes, contrôleur (`FrameworkAdminApi.ts:123`). Variante paginée/triée/filtrée côté serveur :
   `routes/page`.
 - **`GET /nodefony/framework/api/info`** — résumé : nombre de routes, méthodes servies, modules
-  propriétaires (`FrameworkAdminApi.ts:183`).
+  propriétaires (`FrameworkAdminApi.ts:335`).
 - **Écran Routes** de Studio (`/nodefony/routes`) — la même table, filtrable.
 - **Playground** (`/nodefony/playground`, développement uniquement) — un formulaire par action, généré depuis la table :
   transports (dont le duplex), paramètres décorés, gardes de sécurité. Il **exécute** de vraies actions,
   donc il n'est monté qu'en développement (`PlaygroundAdminApi.ts`).
 
 Au boot, avec le debug actif, chaque route est aussi journalisée en une ligne
-`[MÉTHODES] chemin → @module/Controller.action` (`Route.toLogLine()`, `Route.ts:402`).
+`[MÉTHODES] chemin → @module/Controller.action` (`Route.toLogLine()`, `Route.ts:554`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 

package/docs/templates.md

@@ -104,7 +104,7 @@ Le branchement est **délibérément minimal** :
 
 > [!NOTE]
 > Le rendu **d'erreurs** ne passe **pas** par les templates : une exception devient un corps **JSON
-> structuré** (`ErrorRenderer.renderHttp()`, `error-renderer.ts:348`), jamais une page Eta. Le moteur
+> structuré** (`ErrorRenderer.renderHttp()`, `error-renderer.ts:473`), jamais une page Eta. Le moteur
 > de vues ne sert que le HTML **que tu rends explicitement**.
 
 ## 🚀 Démarrage rapide
@@ -222,11 +222,11 @@ sequenceDiagram
 | 2   | Ouverture de la phase mesurée `render`       | `phaseStart("render")` (`Controller.ts:377`)                  |
 | 3   | Injection des aides frontend dans les locals | `withFrontendLocals()` (`Controller.ts:448`)                  |
 | 4   | Rendu de la source par le moteur             | `Eta.render()` → `renderStringAsync` (`Eta.ts:51`)            |
-| 5   | `Content-Type: text/html` puis envoi         | `setContextHtml()` + `renderResponse()` (`Controller.ts:331`) |
+| 5   | `Content-Type: text/html` puis envoi         | `setContextHtml()` + `renderResponse()` (`Controller.ts:392`) |
 
 Le point notable de l'étape 3 : `withFrontendLocals()` ajoute automatiquement `frontendTags`,
 `frontendDocument` et `asset` aux locals **si** le service `frontend` est présent — et **tes** valeurs
-priment (spread `param` en dernier, `Controller.ts:345`). Si le module frontend n'est pas chargé, la
+priment (spread `param` en dernier, `Controller.ts:412`). Si le module frontend n'est pas chargé, la
 fonction retourne les locals inchangés : zéro couplage dur.
 
 ## 🔐 Sécurité — échappement HTML et XSS
@@ -270,7 +270,7 @@ scaffold). Les deux sont **asynchrones** (I/O non bloquante).
 | ----------------------------------- | ------------------------------------------------------- | ------------------- |
 | `renderView(path, locals, status?)` | Rendre une vue `.eta` (lit le fichier + aides frontend) | `Controller.ts:308` |
 | `render(data, encoding?, status?)`  | Envoyer un corps quelconque (ex. HTML déjà prêt)        | `Controller.ts:377` |
-| `renderJson(obj, status?)`          | Réponse JSON explicite (pas un template)                | `Controller.ts:392` |
+| `renderJson(obj, status?)`          | Réponse JSON explicite (pas un template)                | `Controller.ts:481` |
 
 Les signatures exactes vivent dans le graphe symbolique `.ai/symbols.json` — jamais recopiées ici.
 
@@ -285,7 +285,7 @@ Le moteur est configuré **en dur**, pas via un bloc Zod exposé à `use()`. Tro
 | `cache`      | `true` en prod, `false` sinon | compile-once des templates en production ; recompile à chaud en dev | `Template.ts:20` |
 
 Le cache n'est **pas** un booléen figé : `Template` le dérive de l'environnement du kernel
-(`environment === "prod"`, `Template.ts:20`) puis `Eta` l'applique au moteur (`Eta.ts:41`). En
+(`environment === "prod"`, `Template.ts:20`) puis `Eta` l'applique au moteur (`Eta.ts:34`). En
 développement, un template modifié est donc pris en compte sans redémarrer.
 
 ## 🔌 HTTP et WebSocket — le même rendu
@@ -309,7 +309,7 @@ c'est le différenciateur Nodefony : une classe, deux transports, le même moteu
 | Domaine            | Norme / référence       | Comment le code s'y conforme                                          |
 | ------------------ | ----------------------- | --------------------------------------------------------------------- |
 | Neutralisation XSS | OWASP — Output Encoding | échappement HTML par défaut (`autoEscape`, `Eta.ts:16`)               |
-| Type de média HTML | `text/html`             | posé par `setContextHtml()` dans `renderView()` (`Controller.ts:331`) |
+| Type de média HTML | `text/html`             | posé par `setContextHtml()` dans `renderView()` (`Controller.ts:410`) |
 | I/O non bloquante  | Node.js async fs        | lecture async du fichier (`readFile`, `Eta.ts:71`)                    |
 
 ## ⚡ Performance et mémoire
@@ -323,7 +323,7 @@ template), et le framework l'isole pour ça :
 - **Cache en prod** : les templates sont compilés une fois (`cache` vrai en production,
   `Template.ts:20`) ; le coût de parsing n'est payé qu'au premier rendu.
 - **Lecture non bloquante** : le fichier est lu en async (`FileClass.readAsync()` côté `renderView`,
-  `readFile` côté `renderFile`, `Eta.ts:71`) — l'event loop n'est jamais gelé par un `readFileSync`.
+  `readFile` côté `renderFile`, `Eta.ts:66`) — l'event loop n'est jamais gelé par un `readFileSync`.
 - **Aides frontend paresseuses** : `withFrontendLocals()` (`Controller.ts:448`) ne construit les
   fonctions `frontendTags`/`asset` que si le service `frontend` répond — sinon il rend les locals tels
   quels, zéro allocation superflue.