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

package/docs/routing.md

@@ -49,13 +49,13 @@ Trois faits à retenir avant tout le reste :
 
 1. **L'ordre de déclaration EST la priorité.** Une route paramétrée déclarée avant une route
    littérale gagne sur le chemin littéral — c'est figé par le banc de non-régression
-   (`routing-nonregression.test.ts:83`).
+   (`routing-nonregression.test.ts`).
 2. **Le routeur ne lève jamais de 404.** Aucun match = `resolver.resolve === false`, sans exception ;
    le 404 est décidé plus loin, après le repli sur les fichiers statiques
-   (`HttpError("Not Found", 404)`, `http-kernel.ts:907`).
+   (`HttpError("Not Found", 404)`, `http-kernel.ts#HttpKernel.prepareFrontController`).
 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:393`).
+   `Route.ts#Route.match`).
 
 ## 📖 Lexique
 
@@ -95,30 +95,30 @@ tranchent différemment :
 **L'arbitrage est explicite, pas calculé.** Beaucoup de routeurs trient les routes par « spécificité »
 (le motif le plus précis gagne) — pratique jusqu'au jour où l'on ne comprend plus pourquoi telle route
 passe devant telle autre. Nodefony garde l'**ordre de déclaration** : la table est parcourue de haut en
-bas, le premier motif satisfait l'emporte (`Router.resolve()`, `router.ts:313`). Le compromis assumé :
+bas, le premier motif satisfait l'emporte (`Router.resolve()`, `router.ts#Router.resolve`). Le compromis assumé :
 c'est à toi de déclarer le littéral avant le paramétré. En échange, tu peux **lire** l'ordre dans ton
 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:130`). À la
+O(1) ; les chemins **dynamiques** restent un scan regex (`buildRouteIndex()`, `router.ts#buildRouteIndex`). À 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:313`). C'est cette équivalence que fige le
+toute façon pas correspondre (`Router.resolve()`, `router.ts#Router.resolve`). C'est cette équivalence que fige le
 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:816`). C'est le différenciateur du framework — le même contrôleur, le même contexte, les
+`Route.ts#Route.matchRequirements`). 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
 jamais le `stat` du serveur de fichiers : le repli statique n'est tenté que si la résolution a échoué
-(`serverStatic.handle()`, `http-kernel.ts:839`).
+(`serverStatic.handle()`, `http-kernel.ts#HttpKernel.handle`).
 
 > [!NOTE]
 > **Le routage n'a aucune option de configuration.** Le schéma Zod du module n'expose qu'un sac
-> d'options de Service pour le `Router` (`config.ts:36`) — tout se déclare par **décorateurs**, dans le
+> d'options de Service pour le `Router` (`config.ts#serviceOptionsSchema`) — tout se déclare par **décorateurs**, dans le
 > contrôleur, à côté du code qu'ils servent. Pas de `routes.yaml`, pas de table centrale à maintenir.
 
 ## 🚀 Démarrage rapide
@@ -172,7 +172,7 @@ class CatalogController extends Controller {
     path: "/files/*",
     requirements: { methods: ["GET"] },
   })
-  async files(rest: string) {
+  async download(rest: string) {
     return this.renderJson({ rest });
   }
 
@@ -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:494`).
+  posent `requirements: { methods }` (`httpMethodDecorator()`, `routerDecorators.ts#httpMethodDecorator`).
 - `@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:548`).
+  donc jamais produire un 405 sur la méthode (`All()`, `routerDecorators.ts#All`).
 - `@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:189`).
+sur le constructeur (clé `routes:definitions`, `routerDecorators.ts`) ; c'est `@controller(prefix)`
+qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `routerDecorators.ts#controller`).
 
 > [!WARNING]
 > **`@route`/`@Get` doivent être SOUS `@controller`** — les décorateurs de classe s'évaluent après ceux
@@ -281,8 +281,8 @@ 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:514`). La grammaire tient en cinq
-briques (`REG_ROUTE`, `Route.ts:17`) :
+ancrée et **insensible à la casse** (`Route.compile()`, `Route.ts#Route.compile`). La grammaire tient en cinq
+briques (`REG_ROUTE`, `Route.ts#REG_ROUTE`) :
 
 | Écriture           | Motif compilé | Capture           | Exemple                                               |
 | ------------------ | ------------- | ----------------- | ----------------------------------------------------- |
@@ -295,10 +295,10 @@ 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:355`). Corollaire : `/files/*` ne matche pas `/files/`, qui a été
+  (`Route.cleanPathname()`, `Route.ts#Route.cleanPathname`). 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`).
+  (`decode()`, `Route.ts#decode`).
 - **La query string n'entre jamais dans le matching** — seul le `pathname` est comparé. Les paramètres
   de query se lisent avec `@Query` (voir [decorateurs](./decorateurs.md)).
 
@@ -306,8 +306,8 @@ 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:622`).
+par défaut est réinjectée quand la capture est vide (`checkDefaultParameters()`, `Route.ts#checkDefaultParameters` ·
+`Route.hydrateDefaultParameters()`, `Route.ts#Route.hydrateDefaultParameters`).
 
 ```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:224`), lu par le contexte pour
+nom → valeur par requête (`Resolver.getMatchedParams()`, `Resolver.ts#Resolver.getMatchedParams`), lu par le contexte pour
 les métadonnées et par les décorateurs `@Param`.
 
 > [!IMPORTANT]
@@ -354,20 +354,34 @@ correspondent à `/books/new` : `{id}` capturerait `"new"` comme un identifiant.
 ```
 
 Aucune spécificité n'est calculée : la première route déclarée qui correspond gagne
-(`routing-nonregression.test.ts:83`). La même règle vaut pour le catch-all `*`, qui absorbe tout ce qui
+(`routing-nonregression.test.ts`). La même règle vaut pour le catch-all `*`, qui absorbe tout ce qui
 le suit — un `@All("*")` déclaré tôt masque le reste du contrôleur.
 
 > [!TIP]
 > Une exception utile : dans un contrôleur, une route dont le chemin vaut **exactement** `"*"` est
 > repoussée **en dernier** au moment du montage — la capture-tout d'un contrôleur ne masque donc jamais
-> ses propres routes, quel que soit l'ordre d'écriture (`hasMagic`, `routerDecorators.ts:253`). Ça ne
+> ses propres routes, quel que soit l'ordre d'écriture (`hasMagic`, `routerDecorators.ts#controller`). Ça ne
 > vaut **que** pour `"*"` seul : `/files/*` reste ordonné comme les autres.
 
+Pour un repli qui doit céder **entre modules** — la page d'une application monopage, servie sur
+`/app/{page}` ou `/app/*` —, l'option `fallback: true` range la route après toutes les autres, dans
+leur ordre relatif, au moment de construire l'index (`Route.ts#RouteOptions.fallback`) : une route
+littérale ou dynamique de même forme, déclarée par un module chargé après, garde la main. Aucun coût
+par requête. Sans ce drapeau, un repli déclaré tôt capture en silence les routes des modules
+suivants.
+
+```ts ignore
+@Get("/app/{page}", { fallback: true })
+renderSpa(): unknown {
+  return this.renderApp();
+}
+```
+
 ### Situation 2 — le même chemin, deux méthodes
 
 Deux routes peuvent partager un chemin et se distinguer par la méthode. La passe 1 essaie la première,
 qui **lève** un 405 sur la méthode ; l'exception est mémorisée et le scan **continue** jusqu'à la route
-qui accepte la méthode (`Router.resolve()`, `router.ts:313`).
+qui accepte la méthode (`Router.resolve()`, `router.ts#Router.resolve`).
 
 ```ts ignore
 @Get("/book/{id}")    show() {}
@@ -376,12 +390,12 @@ qui accepte la méthode (`Router.resolve()`, `router.ts:313`).
 
 Si **aucune** route n'accepte la méthode, la **passe 2** entre en scène : elle reparcourt la table,
 collecte toutes les méthodes servies par ce chemin **sur ce vhost**, et lève un 405 dont l'en-tête
-`Allow` est l'**agrégat** (`collectSupportedMethods()`, `router.ts:37`, qui lit le `methodsSet`
+`Allow` est l'**agrégat** (`collectSupportedMethods()`, `router.ts#collectSupportedMethods`, qui lit le `methodsSet`
 compilé de chaque route — la MÊME source que le match). C'est la conformité RFC 9110 §15.5.6 :
 `Allow` liste tout ce que la ressource accepte, pas seulement ce que la dernière route scannée
 acceptait — `HEAD` compris dès qu'une route sert `GET`.
 
-**`HEAD` est implicite sur `GET`** (`Route.compileRequirements`, `Route.ts:568`) : RFC 9110 §9.1
+**`HEAD` est implicite sur `GET`** (`Route.compileRequirements`, `Route.ts#Route.compileRequirements`) : RFC 9110 §9.1
 impose à tout serveur généraliste de servir `GET` et `HEAD`, et `HEAD` rend la réponse de `GET`
 sans corps (§9.3.2) — le serveur Node écarte le corps lui-même, en HTTP/1.1 comme en HTTP/2.
 L'ajout se fait à la compilation de la route : aucun coût par requête.
@@ -395,11 +409,11 @@ L'ajout se fait à la compilation de la route : aucun coût par requête.
 ### 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:754`). Le point de sécurité est
+au lieu de participer au match (`Route.matchHostname()`, `Route.ts#Route.matchHostname`). 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:393`). La passe 2 applique la même règle : les routes d'un autre vhost sont
-exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts:432`).
+(`Route.match()`, `Route.ts#Route.match`). La passe 2 applique la même règle : les routes d'un autre vhost sont
+exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts#Router.resolve`).
 
 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.
@@ -420,45 +434,45 @@ async chat(room: string, message: string | Buffer | null) { /* … */ }
 Ce qui change par rapport au HTTP :
 
 - **La route est résolue AVANT l'acceptation du handshake.** Le contexte WS passe par le même
-  `handleFrontController()`, puis seulement `context.connect()` (`http-kernel.ts:1568`). Un chemin
+  `handleFrontController()`, puis seulement `context.connect()` (`http-kernel.ts#HttpKernel.handleHttp`). Un chemin
   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:911`).
+  (`acceptedProtocol`, `Route.ts#Route.matchRequirements`).
 - **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:313`).
+  l'exception d'origine est préservée (`Router.resolve()`, `router.ts#Router.resolve`).
 - **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:297` · boucle message,
-  `callController`, `WebsocketContext.ts:59`).
+  (`WebsocketContext.handle()`, `WebsocketContext.ts#WebsocketContext.handle` · boucle message,
+  `callController`, `WebsocketContext.ts#callAsPromise`).
   L'action est donc invoquée une fois au handshake (`message` vaut `null`), puis une fois par frame.
 
 ### Duplex — le même chemin en HTTP et en WS
 
 Déclarer `methods: ["GET", "WEBSOCKET"]` rend une action joignable par les deux transports. C'est ce
 que fait le data plane d'administration pour toutes ses lectures (`AdminBroker.mountAll()` →
-`Router.createRoute()`, `AdminBroker.ts:125`). Deux conséquences :
+`Router.createRoute()`, `AdminBroker.ts#AdminBroker.mountAll`). Deux conséquences :
 
 - **La pseudo-méthode `WEBSOCKET` n'apparaît jamais dans `Allow`** : ce n'est pas une méthode HTTP
   (RFC 9110 §10.2.1), elle est retirée de l'agrégat. Un chemin qui n'existe qu'en WebSocket, appelé
   en HTTP, répond `426 Upgrade Required` avec `Upgrade: websocket` plutôt qu'un 405
-  (`routing-nonregression.test.ts:164`).
+  (`routing-nonregression.test.ts`).
 - **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:156`) que la
+  chemin. Le pont transporte donc une **méthode logique** (`methodOverride`, `Resolver.ts#Resolver.methodOverride`) 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:852`).
+  **injoignable** par socket (zéro contournement, `Route.ts#Route.matchRequirements`).
 
 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
-jamais muté (`Router.resolve()`, `router.ts:313`). Détails côté socket :
+jamais muté (`Router.resolve()`, `router.ts#Router.resolve`). Détails côté socket :
 [socket Nodefony](../../../../../docs/architecture/realtime-socket-nodefony.md).
 
 ## Vhosts — une route par domaine
 
 `@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:740`).
+au boot en expressions ancrées (`Route.compileHost()`, `Route.ts#Route.compileHost`).
 
 ```ts ignore
 @controller("/")
@@ -470,14 +484,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:189`). Une route sans domaine est servie sur **tous** les
+la classe (`controller()`, `routerDecorators.ts#controller`). 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:754`).
+`Route.ts#Route.matchHostname`).
 
 > [!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:2140`) via la liste `trustedHosts` de `@nodefony/http`.
+> `http-kernel.ts#HttpKernel.checkValidDomain`) via la liste `trustedHosts` de `@nodefony/http`.
 
 ## Préfixes — contrôleur, module, data plane
 
@@ -485,14 +499,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:715`). Un chemin vide (`@Get("")`) désigne donc le préfixe
+   retiré (`Route.setPattern()`, `Route.ts#Route.setPattern`). 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:542`). Un module tiers et ton app peuvent porter deux
-   contrôleurs homonymes sans collision : la clé du registre est `module:Classe` (`router.ts:203`).
+   logs (`Router.setController()`, `router.ts#Router.setController`). Un module tiers et ton app peuvent porter deux
+   contrôleurs homonymes sans collision : la clé du registre est `module:Classe` (`router.ts#Router.constructor`).
 3. **Le data plane d'administration** — réservé, non négociable : `/nodefony/<namespace>/api/<endpoint>`
-   (`AdminBroker.resolvePath()`, `AdminBroker.ts:99`). Trois segments minimum, pour ne jamais entrer en
+   (`AdminBroker.resolvePath()`, `AdminBroker.ts#AdminBroker.resolvePath`). Trois segments minimum, pour ne jamais entrer en
    collision avec les routes de l'application ni avec la SPA de Studio.
 
 > [!TIP]
@@ -503,46 +517,46 @@ Trois niveaux de préfixe coexistent, et un seul est à ta main.
 ## Nommer une route, la retrouver, l'appeler
 
 Chaque route porte un **nom unique** dans le processus : celui que tu donnes à `@route`, ou l'auto-nom
-`Classe::methode` des décorateurs de méthode (`routerDecorators.ts:348`). Le nom est le handle stable
+`Classe::methode` des décorateurs de méthode (`routerDecorators.ts#extractControllerFilePath`). Le nom est le handle stable
 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:495`)              |
-| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts:484`) |
-| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts:744`)          |
-| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts:504`)                       |
+| Besoin                                   | Comment                                                                                  |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Retrouver une route par son nom          | `router.getRoutes("ma-route")` → l'objet `Route` (`router.ts#IndexedRoute.route`)        |
+| Lister toutes les routes                 | `router.getRoutes("")` → la table complète (`router.ts#Router.getRoutes`)                |
+| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts#Router.matchRoutes`) |
+| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts#Controller.forward`)          |
+| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts#Router.removeRoutes`)                      |
 
 **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
 `{var}` est faite là où on en a besoin — par exemple par la console Studio, qui remplace chaque
-variable par sa valeur encodée (`buildUrl()`, `PlaygroundModel.ts:88`). Pour un lien interne, écris le
+variable par sa valeur encodée (`buildUrl()`, `PlaygroundModel.ts#buildUrl`). Pour un lien interne, écris le
 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:251`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
+`Resolver.ts#Resolver.parsePathernController`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
 
 ## 🧰 API publique
 
 Le routage s'utilise **par décorateurs** ; l'API impérative sert l'outillage (introspection, tests,
 modules qui montent des routes dynamiquement). Signatures complètes : `.ai/symbols.json`.
 
-| Symbole                                    | Usage réel                                                              |
-| ------------------------------------------ | ----------------------------------------------------------------------- |
-| `Router.createRoute(nom, options)`         | Monter une route sans décorateur (data plane, module dynamique).        |
-| `Router.setController(classe, module)`     | Rattacher une classe à un module (fait par `@controllers`).             |
-| `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:664`). |
-| `Resolver#route` · `#variables`            | Ce que la requête courante a matché.                                    |
-| `Resolver#getMatchedParams()`              | Les variables en `nom → valeur` (`Resolver.ts:204`).                    |
+| Symbole                                    | Usage réel                                                                          |
+| ------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `Router.createRoute(nom, options)`         | Monter une route sans décorateur (data plane, module dynamique).                    |
+| `Router.setController(classe, module)`     | Rattacher une classe à un module (fait par `@controllers`).                         |
+| `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#Route.toLogLine`). |
+| `Resolver#route` · `#variables`            | Ce que la requête courante a matché.                                                |
+| `Resolver#getMatchedParams()`              | Les variables en `nom → valeur` (`Resolver.ts#Resolver.match`).                     |
 
 > [!CAUTION]
 > **La table de routes est un état de processus, pas d'instance** : `Router.routes` est une liste
-> module-level partagée par tout le processus (`router.ts:48`). `removeRoutes()` sans argument la
+> module-level partagée par tout le processus (`router.ts#routes`). `removeRoutes()` sans argument la
 > **vide pour tout le monde** — réservé aux bancs de test, qui sauvegardent et restaurent la table
 > autour de chaque cas.
 
@@ -553,50 +567,51 @@ 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:568`). Le matching ne fait plus que des lookups.
+  (`Route.compileRequirements()`, `Route.ts#Route.compileRequirements`). 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:355`).
+  chaîne seraient refaits pour **chaque** route de la table (`Route.cleanPathname()`, `Route.ts#Route.cleanPathname`).
 - **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
+  séquence de candidats (`buildRouteIndex()`, `router.ts#buildRouteIndex`). 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: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:395`).
+  mutations directes de la liste (`routeIndex`, `router.ts#invalidateRouteIndex`).
+- **Zéro journalisation en production** : le log « route trouvée » est émis en DEBUG hors
+  production seulement — imprimé avec `-d`, toujours lu par le suivi de requête de Studio — et le
+  test est résolu une fois puis mémoïsé : en production, aucune chaîne n'est même construite
+  (`routeMatchLogged`, `router.ts#routeMatchLogged`).
 - **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:462`).
+  (`resolveActionMeta`, `Resolver.ts#Resolver.executeAction`).
 
 ## 📜 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:37`)           |
-| `HEAD` servi par toute route `GET`       | RFC 9110 §9.1     | `Route.compileRequirements` (`Route.ts:568`)                    |
-| 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:393`) |
-| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:754`)                        |
-| 404 quand rien ne correspond             | RFC 9110 §15.5.5  | après repli statique (`http-kernel.ts:700`)                     |
-| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:2140`)                    |
-| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:816`)                    |
-| Décodage pourcent des segments           | RFC 3986 §2.1     | `decode()` (`Route.ts:79`)                                      |
+| 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#collectSupportedMethods`)  |
+| `HEAD` servi par toute route `GET`       | RFC 9110 §9.1     | `Route.compileRequirements` (`Route.ts#Route.compileRequirements`)          |
+| 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#Route.match`)     |
+| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts#Route.matchHostname`)                    |
+| 404 quand rien ne correspond             | RFC 9110 §15.5.5  | après repli statique (`http-kernel.ts#HttpKernel.isWebsocketOriginAllowed`) |
+| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts#HttpKernel.checkValidDomain`)         |
+| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts#Route.matchRequirements`)            |
+| Décodage pourcent des segments           | RFC 3986 §2.1     | `decode()` (`Route.ts#decode`)                                              |
 
 ## 📡 Observabilité — Studio
 
 La table de routes est introspectable en ligne, sans lire le code :
 
 - **`GET /nodefony/framework/api/routes`** — dump de toutes les routes enregistrées : nom, chemin,
-  méthodes, contrôleur (`FrameworkAdminApi.ts:123`). Variante paginée/triée/filtrée côté serveur :
+  méthodes, contrôleur (`FrameworkAdminApi.ts#createFrameworkAdminApi`). 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:356`).
+  propriétaires (`FrameworkAdminApi.ts#createFrameworkAdminApi`).
 - **É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:664`).
+`[MÉTHODES] chemin → @module/Controller.action` (`Route.toLogLine()`, `Route.ts#Route.toLogLine`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -609,7 +624,7 @@ Au boot, avec le debug actif, chaque route est aussi journalisée en une ligne
 | Une route paramétrée avale un chemin littéral | Premier match dans l'ordre de déclaration, aucune spécificité | Déclarer le littéral **avant** le paramétré |
 | `/files/*` ne répond pas sur `/files` | Le slash final est retiré avant le matching ; le motif exige `/files/` | Déclarer une seconde route pour le chemin nu |
 | `{id}` ne capture pas `a/b` | Une variable vaut `[^/]+` — un seul segment, par construction | Utiliser un wildcard `*` si le `/` doit être capturé |
-| `500` au lieu d'un non-match sur une contrainte | Un requirement par variable non satisfait **lève** (chaîne brute, `Route.ts:286`) | Préférer la contrainte inline `{id}(\d+)`, qui ne matche pas |
+| `500` au lieu d'un non-match sur une contrainte | Un requirement par variable non satisfait **lève** (chaîne brute, `Route.ts#Route.methodsSet`) | Préférer la contrainte inline `{id}(\d+)`, qui ne matche pas |
 | `403` inattendu sur une route qui « existe » | La route est restreinte à un autre vhost (`@Domain`) | Retirer la restriction, ou servir ce vhost |
 | Action WebSocket jamais atteinte | Transport `WEBSOCKET` absent des méthodes déclarées | `requirements: { methods: ["WEBSOCKET"] }` |
 | Une action nommée `session`/`request`/`method` est refusée | Le décorateur refuse tout nom déjà porté par `Controller` — il masquerait l'action | Renommer l'action (réservés : tout membre de `Controller`/`Service` — `session`, `get`, `set`, `remove`, `request`, `response`, `method`…) |