@nodefony/framework 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/types/nodefony/interfaces/IResolver.d.ts

@@ -1,25 +1,25 @@
-import type { ContextType, HttpError } from "@nodefony/http";
-import type { Injector } from "nodefony";
+import type { ContextType, HttpError, IRouteResolver } from "@nodefony/http";
+import type { Injector, MaybePromise } from "nodefony";
 import type { ControllerConstructor } from "../src/Route.js";
 import type { IRoute } from "./IRoute.js";
 import type { IController } from "./IController.js";
-export interface IResolver {
-    injector?: Injector | null;
+export interface IResolver extends IRouteResolver {
+    injector?: Injector | null | undefined;
     controller: ControllerConstructor | null;
-    actionName?: string;
-    action?: (...args: unknown[]) => unknown;
+    actionName?: string | undefined;
+    action?: ((...args: unknown[]) => unknown) | undefined;
     context: ContextType;
     readonly route: IRoute | null;
     resolve: boolean;
     variables: unknown[];
-    exception?: HttpError | Error | null;
+    exception?: HttpError | Error | null | undefined;
     acceptedProtocol: string | null;
     bypassFirewall: boolean;
     match(route: IRoute, context: ContextType, cleanPath?: string): unknown;
     getMatchedParams(): Record<string, unknown>;
     parsePathernController(name: string): void;
     getAction(name: string): ((...args: unknown[]) => unknown) | null;
-    newController(context?: ContextType): Promise<IController | object>;
-    callController(data?: unknown[], reload?: boolean): Promise<unknown>;
-    returnController(result: unknown): Promise<unknown>;
+    newController(context?: ContextType): MaybePromise<IController | object>;
+    callController(data?: unknown[], reload?: boolean): MaybePromise<unknown>;
+    returnController(result: unknown): MaybePromise<unknown>;
 }

package/dist/types/nodefony/interfaces/IRoute.d.ts

@@ -1,22 +1,22 @@
-import type { HTTPMethod, SchemeType, ContextType } from "@nodefony/http";
+import type { HTTPMethod, SchemeType, ContextType, IResolvedRoute } from "@nodefony/http";
 import type { ControllerConstructor, RouteRequirements } from "../src/Route.js";
-export interface IRoute {
+export interface IRoute extends IResolvedRoute {
     name: string;
-    path?: string;
-    controller?: ControllerConstructor;
-    classMethod?: string;
-    prefix?: string;
-    method?: HTTPMethod;
-    schemes?: SchemeType;
-    pattern?: RegExp;
+    path?: string | undefined;
+    controller?: ControllerConstructor | undefined;
+    classMethod?: string | undefined;
+    prefix?: string | undefined;
+    method?: HTTPMethod | undefined;
+    schemes?: SchemeType | undefined;
+    pattern?: RegExp | undefined;
     variables: unknown[];
     defaults: Partial<Record<string, unknown>>;
     requirements: Partial<RouteRequirements>;
-    hash?: string;
-    host?: string | string[];
-    hostRegexp?: RegExp[];
+    hash?: string | undefined;
+    host?: string | string[] | undefined;
+    hostRegexp?: RegExp[] | undefined;
     bypassFirewall: boolean;
-    filePath?: string;
+    filePath?: string | undefined;
     match(context: ContextType, cleanPath?: string): unknown[] | null | undefined;
     compile(): RegExp;
     toString(): string;

package/dist/types/nodefony/service/AdminBroker.d.ts

@@ -15,11 +15,11 @@ declare class AdminBroker extends Service implements IAdminBroker {
     readonly apiSegment = "api";
     readonly defaultRole = "ROLE_NODEFONY_ADMIN";
     /** Producteurs enregistrés, indexés par namespace. */
-    private producers;
+    private readonly producers;
     /** Routes résolues, indexées par nom de route (dispatch O(1)). */
-    private byRouteName;
+    private readonly byRouteName;
     /** Module framework propriétaire — requis pour `Router.setController`. */
-    private frameworkModule;
+    private readonly frameworkModule;
     /** Vrai une fois `mountAll()` exécuté (idempotence + verrou de register). */
     private mounted;
     constructor(module: Module);

package/dist/types/nodefony/service/router.d.ts

@@ -1,26 +1,35 @@
 import { Service, Module } from "nodefony";
+import type { MaybePromise } from "nodefony";
 import Route, { RouteOptions } from "../src/Route.js";
 import { ContextType } from "@nodefony/http";
+import type { IRequestRouter } from "@nodefony/http";
 import Resolver from "../src/Resolver.js";
 import Controller from "../src/Controller.js";
 export type TypeController<T> = new (...args: any[]) => T;
-declare class Router extends Service {
+declare class Router extends Service implements IRequestRouter {
     static routes: Route[];
     routes: Route[];
     private singletonControllers;
     constructor(module: Module);
     /**
      * Retourne l'instance singleton d'une classe controller `@Scope("singleton")`,
-     * en la créant au premier appel via `create`. On cache la **promesse** (pas
-     * l'instance) : N requêtes concurrentes pendant la création (`initialize()`
-     * async) attendent le MÊME travail — jamais deux instances (race de création
-     * éliminée structurellement).
+     * en la créant au premier appel via `create`.
+     *
+     * Tant que la création est en cours (`initialize()` async), c'est la
+     * **promesse** qui est en cache : N requêtes concurrentes attendent le MÊME
+     * travail — jamais deux instances (race de création éliminée
+     * structurellement). Dès que l'instance est prête, elle REMPLACE la promesse :
+     * les requêtes suivantes la reçoivent directement, au lieu d'attendre à
+     * chaque fois une promesse déjà tenue (#505).
      *
      * @param ctor - la classe controller (clé du cache).
      * @param create - fabrique exécutée une seule fois (instantiate + initialize).
-     * @returns la promesse de l'instance partagée.
+     * @returns l'instance partagée quand elle existe — ou que `create` la rend
+     *   sans rien attendre —, sinon la promesse de sa création.
+     * @throws ce que `create` lève de façon synchrone ; rien n'est alors mis en
+     *   cache, la requête suivante recrée.
      */
-    getSingletonController(ctor: TypeController<Controller>, create: () => Promise<Controller>): Promise<Controller>;
+    getSingletonController<T extends object>(ctor: new (...args: never[]) => T, create: () => MaybePromise<T>): MaybePromise<T>;
     /**
      * Résout une route pour un contexte donné.
      *
@@ -42,6 +51,23 @@ declare class Router extends Service {
     setRoute(): void;
     removeRoutes(name: string): void;
     static createRoute(name: string, obj: RouteOptions): Route;
+    /**
+     * Enregistre une classe contrôleur pour un module — l'entonnoir UNIQUE : le
+     * décorateur `@controllers` y passe, comme les contrôleurs internes que le
+     * framework enregistre directement (plan d'administration, OAuth,
+     * WebAuthn…).
+     *
+     * C'est donc ICI que se refusent, au démarrage, les fautes de déclaration
+     * qu'un contrôleur ne révélerait qu'à sa première requête : une dépendance
+     * captive (un singleton qui détient un service de portée `request`), et une
+     * portée que sa classe de base n'admet pas (`Controller.assertScope`).
+     *
+     * @param myconstructor - la classe contrôleur.
+     * @param module - le module qui la porte.
+     * @returns la classe, rangée sous `module:Classe`.
+     * @throws BootConfigurationError sur une dépendance captive ou une portée
+     *   refusée — fatale dans tous les environnements.
+     */
     static setController(myconstructor: TypeController<Controller>, module: Module): TypeController<Controller>;
     /**
      * Retourne les routes enregistrées pour un controller donné — utilisé par

package/dist/types/nodefony/src/Controller.d.ts

@@ -1,4 +1,5 @@
 import { Service, Module, FileClass } from "nodefony";
+import type { MaybePromise } from "nodefony";
 import type { IController } from "../interfaces/index.js";
 import Route from "./Route.js";
 import { contextRequest, HTTPMethod, HttpResponse, Session, ContextType, Http2Response, WebsocketResponse } from "@nodefony/http";
@@ -32,40 +33,61 @@ export declare function parseByteRange(range: string, length: number): {
     end: number;
 } | "unsatisfiable" | null;
 /**
- * Scope d'instanciation d'un controller (V4.3).
+ * Portée d'instanciation d'un contrôleur.
  *
- * - `"request"` (défaut) : une instance par requête — l'état per-request peut
- *   vivre sur `this` (legacy sûr, zéro breaking).
- * - `"singleton"` (opt-in via `@Scope`) : UNE instance partagée par toutes les
- *   requêtes — réservé aux controllers **stateless** (état uniquement via
- *   arguments décorés + ALS). Un champ mutable par requête sur `this` y serait
- *   une data race silencieuse entre requêtes concurrentes.
+ * - `"singleton"` (le défaut) : UNE instance par classe, construite à la
+ *   première requête et partagée par toutes les suivantes, concurrentes
+ *   comprises. Le contrôleur ne porte que du CODE : l'état de la requête
+ *   arrive par les arguments décorés (`@Param`, `@Query`, `@Body`…) et par les
+ *   helpers, qui retrouvent la requête courante dans l'ALS. Écrire un état de
+ *   requête sur `this` le ferait fuir vers la requête suivante — les
+ *   accesseurs d'état le refusent, et le développement refuse toute écriture
+ *   sur un champ (cf `singletonGuard.ts`).
+ * - `"request"` (option explicite, `@Scope("request")`) : une instance par
+ *   requête — par CONNEXION en WebSocket. Pour un contrôleur qui injecte un
+ *   service de portée `request` à son constructeur, prépare chaque requête
+ *   dans `initialize()`, ou garde un état sur `this`.
  */
 export type ControllerScope = "request" | "singleton";
 declare class Controller extends Service implements IController {
     #private;
     static prefix: string;
     /**
-     * Scope d'instanciation de la classe — `"request"` par défaut, `"singleton"`
-     * posé par le décorateur `@Scope` (statique hérité, lu via `new.target` au
-     * constructor et par le Resolver : 0 Reflect). Cf {@link ControllerScope}.
+     * Portée d'instanciation de la classe — `"singleton"` par défaut,
+     * `"request"` posé par le décorateur `@Scope` (statique hérité, lu via
+     * `new.target` au constructeur et par le Resolver : 0 Reflect).
+     * Cf {@link ControllerScope}.
      */
     static scope: ControllerScope;
-    module?: Module;
-    template?: Eta | null;
     /**
-     * Contexte transport courant. Per-request : champ posé par `setContext`
-     * (constructor) — coût d'accès inchangé. Singleton stateless (V4.3) : champ
-     * jamais posé → lecture de l'ALS `RequestContext` (le `HttpKernel` y place
-     * le contexte à l'entrée du scope, V4.1) — chaque appel de helper retrouve
-     * LA requête en cours, jamais celle d'une requête concurrente.
+     * Vérifie que la portée de la classe est admise par sa lignée. Appelée à
+     * l'enregistrement du contrôleur (`Router.setController`), donc au
+     * démarrage.
+     *
+     * N'impose rien par défaut. Une classe de base qui n'admet qu'une portée la
+     * fait respecter ici — `RealtimeController`, lié à SA connexion par
+     * construction, refuse le singleton.
+     *
+     * @throws BootConfigurationError quand la portée déclarée est refusée.
+     */
+    static assertScope(): void;
+    module?: Module | undefined;
+    template?: Eta | null | undefined;
+    /**
+     * Contexte transport courant. Par requête : champ posé par `setContext`
+     * (constructeur). Singleton : champ jamais posé → lecture de l'ALS
+     * `RequestContext`, où le `HttpKernel` place le contexte à l'entrée de la
+     * requête — chaque helper retrouve LA requête en cours, jamais une requête
+     * concurrente.
      */
     get context(): ContextType | undefined;
     set context(context: ContextType | undefined);
     /**
-     * Route matchée. Per-request : posée par le Resolver via `setRoute`.
-     * Sans champ (singleton) : dérive du Resolver de la requête courante
-     * (`context.resolver`), donc toujours la route de CETTE requête.
+     * Route de l'appel en cours. Par requête : posée par le Resolver
+     * (`setRoute`). Singleton : celle du résolveur de l'APPEL quand le pont
+     * `api.request` en a posé un dans l'ALS (clé `resolver` — un résolveur par
+     * appel, jamais rangé sur le contexte de la connexion), sinon celle du
+     * contexte.
      */
     get route(): Route | null;
     get request(): contextRequest;
@@ -74,8 +96,14 @@ declare class Controller extends Service implements IController {
     set response(response: HttpResponse | Http2Response | WebsocketResponse | null);
     get method(): HTTPMethod | undefined;
     set method(method: HTTPMethod | undefined);
+    /**
+     * Query string de l'appel en cours — pour un singleton invoqué par le pont
+     * `api.request`, celle du chemin INVOQUÉ (résolveur d'appel dans l'ALS), pas
+     * celle du handshake de la connexion. Une seule lecture de l'ALS.
+     */
     get queryGet(): Record<string, unknown>;
     set queryGet(value: Record<string, unknown>);
+    /** Comme {@link queryGet}, pour la query fusionnée (`query`). */
     get query(): Record<string, unknown>;
     set query(value: Record<string, unknown>);
     get queryFile(): unknown[];
@@ -101,11 +129,38 @@ declare class Controller extends Service implements IController {
      */
     get session(): Session | null;
     constructor(name: string, context: ContextType);
+    /**
+     * Lie l'instance au contexte de SA requête — contrôleur par requête
+     * seulement : tout l'état de la requête (`request`, `response`, `method`,
+     * `query*`) en dérive ensuite, toujours frais.
+     *
+     * @param context - le contexte de la requête servie par cette instance.
+     * @throws TypeError sur un singleton, qui sert toutes les requêtes.
+     */
     setContext(context: ContextType): void;
     setContextJson(encoding?: BufferEncoding): void | undefined;
     setContextHtml(encoding?: BufferEncoding): void | undefined;
-    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): Promise<Http2Response | HttpResponse>;
-    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): Promise<Http2Response | HttpResponse> | Promise<WebsocketResponse>;
+    /**
+     * Rend une donnée sur la réponse de la requête courante (JSON, HTML ou
+     * texte selon son type).
+     *
+     * Synchrone quand l'envoi l'est — réponse unique, sans session à sauver ni
+     * hook d'envoi (#505). Un `await` reste valable dans tous les cas ; un
+     * `.then` chaîné ne l'est plus : la valeur n'est une promesse que quand
+     * l'envoi attend.
+     *
+     * @returns la réponse, ou sa promesse.
+     */
+    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): MaybePromise<Http2Response | HttpResponse>;
+    /**
+     * Envoie une donnée déjà sérialisée sur le transport de la requête (HTTP ou
+     * WebSocket), après statut et en-têtes éventuels.
+     *
+     * Synchrone quand l'envoi l'est (#505) — cf {@link render}.
+     *
+     * @returns la réponse, ou sa promesse.
+     */
+    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<Http2Response | HttpResponse | WebsocketResponse>;
     renderView(path: string | FileClass, param?: Record<string, unknown>, status?: string | number, headers?: Record<string, string | number>): Promise<Http2Response | HttpResponse | WebsocketResponse>;
     /**
      * Injecte les helpers frontend (`frontendTags`/`frontendDocument`) dans les
@@ -114,14 +169,32 @@ declare class Controller extends Service implements IController {
      * valeurs fournies par l'action priment (spread `param` en dernier).
      */
     private withFrontendLocals;
-    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): Promise<Http2Response | HttpResponse | WebsocketResponse>;
+    /**
+     * Sérialise en JSON puis envoie ({@link renderResponse}). Synchrone quand
+     * l'envoi l'est (#505).
+     *
+     * @returns la réponse, ou sa promesse.
+     * @throws de façon SYNCHRONE ce que lève `JSON.stringify` (cycle, BigInt).
+     */
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<Http2Response | HttpResponse | WebsocketResponse>;
+    /**
+     * Pose la route de la requête courante sur l'instance (per-request).
+     *
+     * `null` est accepté : un re-routage sans route matchée (forward interne)
+     * efface la précédente au lieu de la laisser traîner.
+     *
+     * @param route - route matchée, ou `null`.
+     * @returns la route posée.
+     * @throws TypeError sur un singleton : sa route se lit dans l'appel en cours.
+     */
     setRoute(route: Route): Route;
+    setRoute(route: Route | null): Route | null;
     getSession(): Session | undefined | null;
     redirect(url: string, status?: string | number, headers?: Record<string, string | number>): void;
     getFlashBag(key: string): unknown;
     setFlashBag(key: string, value: unknown): unknown;
     addFlash(key: string, value: unknown): unknown;
-    forward(name: string, param?: unknown[]): Promise<unknown>;
+    forward(name: string, param?: unknown[]): unknown;
     /**
      * @deprecated Bloque l'event-loop (`fs.lstatSync` via `new FileClass`).
      *   Utiliser {@link getFileAsync} dans tout pipeline. Conservé pour compat.

package/dist/types/nodefony/src/Resolver.d.ts

@@ -1,13 +1,15 @@
 import { Injector } from "nodefony";
+import type { MaybePromise } from "nodefony";
 import type { IResolver } from "../interfaces/index.js";
 import { HttpError, ContextType } from "@nodefony/http";
 import Route, { ControllerConstructor } from "./Route.js";
 import Controller from "./Controller.js";
 import { type RouteActionMeta, type RedirectMeta } from "../decorators/routerDecorators.js";
 /**
- * Interface-marqueur du hook **per-request** d'un {@link Controller} : `initialize`
- * est appelé par le {@link Resolver} à CHAQUE requête, avant l'action (hot path —
- * jamais gardé/borné, contrairement au boot des services). Distinct du hook de boot
+ * Interface-marqueur du hook d'initialisation d'un {@link Controller} : `initialize`
+ * est appelé par le {@link Resolver} à la création de l'instance, avant l'action —
+ * UNE fois pour un singleton (défaut), à CHAQUE requête sous `@Scope("request")`
+ * (jamais gardé/borné, contrairement au boot des services). Distinct du hook de boot
  * `ServiceWithInit` (singleton, 1× au démarrage).
  *
  * @remarks Signature alignée sur l'appel réel `controller.initialize()` (sans arg) ;
@@ -16,16 +18,25 @@ import { type RouteActionMeta, type RedirectMeta } from "../decorators/routerDec
 export interface ControllerWithInitialize {
     initialize(): Promise<this>;
 }
+/**
+ * Ce qu'une action a rendu, AVANT rendu sur le transport : sa valeur brute
+ * (éventuellement une promesse, que le rendu démêle) et la redirection
+ * déclarée par `@Redirect`.
+ */
+type ActionOutcome = {
+    result: unknown;
+    redirectMeta: RedirectMeta | undefined;
+};
 declare class Resolver implements IResolver {
-    injector?: Injector | null;
+    injector?: Injector | null | undefined;
     controller: ControllerConstructor | null;
-    actionName?: string;
-    action?: (...args: unknown[]) => unknown;
+    actionName?: string | undefined;
+    action?: ((...args: unknown[]) => unknown) | undefined;
     context: ContextType;
     route: Route | null;
     resolve: boolean;
     variables: unknown[];
-    exception?: HttpError | Error | null;
+    exception?: HttpError | Error | null | undefined;
     acceptedProtocol: string | null;
     bypassFirewall: boolean;
     /**
@@ -60,7 +71,7 @@ declare class Resolver implements IResolver {
      */
     messageInvocation: boolean;
     constructor(context: ContextType);
-    match(route: Route, context: ContextType, cleanPath?: string): ((string | null)[] & Record<string, unknown>) | null | undefined;
+    match(route: Route, context: ContextType, cleanPath?: string, literal?: boolean): ((string | null)[] & Record<string, unknown>) | null | undefined;
     /**
      * Snapshot per-requête des variables de route matchées (`{name}` → valeur,
      * + wildcard `*` éventuel). Construit depuis les valeurs de CETTE requête
@@ -71,17 +82,66 @@ declare class Resolver implements IResolver {
      * `Context.setMetaData()` pour exposer `msg.nodefony.route.variablesMap`.
      */
     getMatchedParams(): Record<string, unknown>;
+    /**
+     * Associe chaque nom de variable de la route à la valeur capturée au match.
+     *
+     * @returns la table nom → valeur (vide sans route)
+     */
+    private _zipRouteParams;
     parsePathernController(name: string): void;
     getAction(name: string): ((...args: unknown[]) => unknown) | null;
-    newController(context?: ContextType): Promise<Controller>;
+    /**
+     * L'instance du controller de la route, posée sur le container du contexte.
+     *
+     * Singleton (le défaut) : l'instance partagée du cache du Router — rendue
+     * DIRECTEMENT une fois créée, sans promesse à attendre (#505). Portée
+     * `request` : une instance neuve, synchrone tant que son `initialize()` ne
+     * rend pas de promesse.
+     *
+     * @param context - le contexte à injecter (celui du résolveur par défaut).
+     * @returns l'instance, ou la promesse de l'instance quand sa création attend
+     *   (`initialize()` asynchrone).
+     * @throws de façon SYNCHRONE si la route n'a pas de controller, ou si sa
+     *   construction lève ; un `initialize()` qui échoue rompt la promesse rendue.
+     */
+    newController(context?: ContextType): MaybePromise<Controller>;
+    /**
+     * Pose le pointeur `"controller"` sur le container du contexte : un message
+     * WS suivant ou un forward (`reload`) retrouve l'instance par ce chemin.
+     *
+     * SAUF pour une invocation par message (pont `api.request`) : le container
+     * est alors celui de la CONNEXION, et son pointeur désigne le contrôleur qui
+     * la sert (le hub). L'écraser par la cible de l'appel faisait échouer le test
+     * `instanceof` au message suivant — le hub était RÉINSTANCIÉ (DI +
+     * `initialize()`) à chaque frame qui suivait un `api.request`.
+     *
+     * @returns le controller reçu, pour enchaîner.
+     */
+    private _pinController;
     /**
      * Instancie la classe controller résolue (DI) + hooks de création : `module`
      * (constante de classe, shadow d'instance posé 1× ici — plus de write par
      * requête dans `executeAction`) puis `initialize()`. Pour un singleton,
      * `initialize()` n'est donc appelé qu'UNE fois, à la création (sémantique
      * boot) — le per-request y lit l'ALS s'il a besoin de la requête.
+     *
+     * @returns le controller prêt ; sa promesse seulement quand `initialize()`
+     *   en rend une.
+     * @throws de façon SYNCHRONE ce que lèvent la DI, le constructeur ou un
+     *   `initialize()` synchrone ; un `initialize()` asynchrone qui échoue rompt
+     *   la promesse rendue.
      */
     private _createController;
+    /**
+     * Filet de DÉVELOPPEMENT : un singleton sert toutes les requêtes, donc une
+     * écriture sur l'un de ses champs, à partir d'ici, fuirait vers la suivante.
+     * Posé APRÈS `initialize()`, qui prépare légitimement un état de démarrage.
+     * Jamais hors développement : les champs y deviennent des accesseurs, un coût
+     * que la production ne paie pas.
+     *
+     * @returns le controller reçu, pour enchaîner.
+     */
+    private _guardSingleton;
     /**
      * Exécute l'action résolue et retourne sa **valeur brute**, SANS la rendre sur
      * le transport (pas de `returnController`/`send`). Découple « exécuter → valeur »
@@ -90,15 +150,69 @@ declare class Resolver implements IResolver {
      * (`{ id, result }`, champ GraphQL…). Le pipeline HTTP/WS normal passe par
      * {@link callController} (= `executeAction` + rendu).
      *
+     * Synchrone tant que rien n'est à attendre (#505) : la garde d'autorisation
+     * n'est attendue que sur une route gardée, l'instance que si elle est à
+     * créer. La valeur de l'action est rendue BRUTE — une promesse si l'action
+     * est asynchrone ; c'est le rendu qui la démêle.
+     *
      * @param data - args supplémentaires (message WS brut legacy) concaténés aux variables de route.
      * @param reload - force `newController()` (le container peut déjà porter un AUTRE controller).
-     * @returns la valeur retournée par l'action + son `RedirectMeta` éventuel.
+     * @returns la valeur retournée par l'action + son `RedirectMeta` éventuel —
+     *   ou la promesse de ce couple quand la garde ou la création attendent.
+     * @throws de façon SYNCHRONE ce que lève une action synchrone (ou l'absence
+     *   d'action) ; un refus d'autorisation rompt la promesse rendue.
      */
-    executeAction(data?: unknown[], reload?: boolean, metaArg?: RouteActionMeta): Promise<{
-        result: unknown;
-        redirectMeta: RedirectMeta | undefined;
-    }>;
-    callController(data?: unknown[], reload?: boolean): Promise<unknown>;
+    executeAction(data?: unknown[], reload?: boolean, metaArg?: RouteActionMeta): MaybePromise<ActionOutcome>;
+    /**
+     * Les gardes d'autorisation d'une action : `@IsGranted`/`@RequireScope`, puis
+     * le filet de la ZONE quand aucune garde n'a décidé du RÔLE.
+     *
+     * ⚠️ Vrai du trajet HTTP SEULEMENT. Le kernel y arme la route sans instancier
+     * (`http-kernel.ts` `prepareFrontController`), donc ce court-circuit est celui
+     * de bout en bout. En **WebSocket**, le controller est instancié au HANDSHAKE
+     * — avant qu'une frame ne soit gardée : sur ce transport, un refus n'évite
+     * ni la DI ni `initialize()`, qui ont déjà tourné.
+     *
+     * @returns `undefined` quand la route n'est pas gardée (le cas nominal : ni
+     *   lookup, ni attente) ; sinon la promesse du verdict, rompue par un refus.
+     */
+    private _enforceActionSecurity;
+    /**
+     * Filet de la ZONE : une route dont personne n'a décidé le RÔLE hérite de
+     * celui de sa zone du firewall, au lieu d'être ouverte à tout compte
+     * authentifié.
+     *
+     * @returns `undefined` sur l'immense majorité des routes (aucune zone, ou
+     *   zone sans rôle) ; sinon la promesse du verdict.
+     */
+    private _enforceAreaSecurity;
+    /**
+     * L'instance qui sert l'action — celle déjà posée sur le container quand
+     * c'est la bonne classe, sinon une création —, puis l'action elle-même.
+     * N'attend que la création, et seulement quand elle attend.
+     */
+    private _acquireAndInvoke;
+    /**
+     * Appelle l'action sur l'instance : état de requête (portée `request`
+     * seulement), arguments, méta de réponse (`@HttpCode`, `@Header`), puis
+     * l'appel — synchrone, sa valeur rendue brute.
+     *
+     * @throws de façon SYNCHRONE ce que lève l'action, ou l'absence d'action.
+     */
+    private _invokeAction;
+    /**
+     * Exécute l'action PUIS rend sa valeur sur le transport.
+     *
+     * Synchrone de bout en bout quand rien n'attend — route non gardée,
+     * controller déjà créé, action synchrone, rendu synchrone (#505).
+     *
+     * @param data - args supplémentaires (message WS brut legacy).
+     * @param reload - force une nouvelle instance (forward).
+     * @returns le résultat du rendu, ou sa promesse dès qu'une étape attend.
+     * @throws de façon SYNCHRONE ce que lève une étape synchrone (action,
+     *   construction) ; les échecs asynchrones rompent la promesse rendue.
+     */
+    callController(data?: unknown[], reload?: boolean): MaybePromise<unknown>;
     /**
      * Exécute l'action AVEC la porte d'idempotence mais SANS rendu
      * (`returnController`) — le chemin du **pont `api.request`** (WS) : la valeur
@@ -196,8 +310,33 @@ declare class Resolver implements IResolver {
      * partagée ne porte aucune response).
      */
     private _applyResponseMeta;
+    /**
+     * Applique `@Redirect` à la valeur de l'action, puis la rend.
+     *
+     * Sans `@Redirect` (le cas nominal), rend directement. Avec, la valeur est
+     * attendue seulement si c'est une promesse — une action synchrone qui rend
+     * `undefined` redirige sans suspension.
+     *
+     * @returns le résultat du rendu, ou sa promesse.
+     */
     private _handleRedirect;
-    returnController(result: unknown): Promise<unknown>;
+    /** Suite de {@link _handleRedirect}, la valeur de l'action connue. */
+    private _redirectOrReturn;
+    /**
+     * Rend la valeur d'une action sur le transport, selon sa nature : promesse
+     * (démêlée puis re-rendue), texte, Buffer, réponse déjà construite, scalaire
+     * ou objet (auto-JSON), rien (l'action envoie elle-même).
+     *
+     * Pas `async` : l'envelopper dans une promesse de plus ne changeait rien au
+     * rendu, et coûtait une suspension à chaque requête (#505). La valeur n'est
+     * attendue que si c'en est une.
+     *
+     * @param result - la valeur rendue par l'action.
+     * @returns ce que rend l'envoi (souvent sa promesse), ou `undefined` quand il
+     *   n'y a rien à envoyer.
+     * @throws de façon SYNCHRONE ce que lève un envoi synchrone.
+     */
+    returnController(result: unknown): MaybePromise<unknown>;
     /** Statut courant de la réponse (0 si le transport n'en porte pas). */
     private getResponseStatus;
 }

package/dist/types/nodefony/src/ResourceController.d.ts

@@ -1,7 +1,7 @@
 import Controller from "./Controller.js";
 import type { ControllerScope } from "./Controller.js";
 import type { ContextType } from "@nodefony/http";
-import type { IPage, IPageQuery } from "nodefony";
+import type { IPage, IPageQuery, PartialInput } from "nodefony";
 /**
  * Contrat structurel du service de ressource consommé par un
  * {@link ResourceController} — aligné sur `AbstractCrudService`
@@ -31,7 +31,7 @@ export interface IResourceReadOptions {
      * par la caster, et le tri se perd en silence — la pagination devient alors
      * fausse par intermittence, ce qui est pire qu'absente.
      */
-    order?: Array<[string, "ASC" | "DESC"]>;
+    order?: Array<[string, "ASC" | "DESC"]> | undefined;
     /** Associations à charger avec l'enregistrement. */
     relations?: string[];
 }
@@ -62,8 +62,8 @@ export interface IResourceService<T = unknown> {
      * de `find`.
      */
     findPage?(page: IResourcePageQuery): Promise<IPage<T>> | IPage<T>;
-    create?(data: Partial<T>): Promise<T> | T;
-    updateOne?(criteria: Record<string, unknown>, data: Partial<T>): Promise<T | null> | T | null;
+    create?(data: PartialInput<T>): Promise<T> | T;
+    updateOne?(criteria: Record<string, unknown>, data: PartialInput<T>): Promise<T | null> | T | null;
     delete?(criteria: Record<string, unknown>): Promise<number> | number;
 }
 /**
@@ -162,9 +162,9 @@ declare class ResourceController<T = unknown> extends Controller {
      */
     protected getResource(id: string, options?: IResourceReadOptions): Promise<T | null>;
     /** Crée une entité — 501 si la ressource est read-only. */
-    protected createResource(data: Partial<T>): Promise<T>;
+    protected createResource(data: PartialInput<T>): Promise<T>;
     /** Met à jour une entité ciblée par critères — 501 si non supporté. */
-    protected updateResource(criteria: Record<string, unknown>, data: Partial<T>): Promise<T | null>;
+    protected updateResource(criteria: Record<string, unknown>, data: PartialInput<T>): Promise<T | null>;
     /** Supprime par critères (nombre d'entités touchées) — 501 si non supporté. */
     protected removeResource(criteria: Record<string, unknown>): Promise<number>;
 }