@nodefony/framework 10.0.0-alpha.1

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

@@ -0,0 +1,98 @@
+import type { IAdminEndpoint } from "nodefony";
+/**
+ * Endpoints « Playground » du data plane framework — la source de données de la
+ * console vivante des controllers dans Studio (`/nodefony/playground`).
+ *
+ * Sérialise ce que le Router et les décorateurs savent déjà (routes, transports,
+ * paramètres décorés, gardes) : tout est en Reflect/mémoire, il n'y a qu'à
+ * l'exposer en JSON. La page Studio générique construit ses formulaires depuis
+ * ces métadonnées — AUCUN code généré dans l'app du user, rétroactif sur tout
+ * controller (même écrit à la main).
+ *
+ * **Dev-only par montage** : `createFrameworkAdminApi` n'inclut ces endpoints
+ * que si l'app tourne en développement (le playground EXÉCUTE des mutations
+ * depuis le navigateur). Hors dev le endpoint n'existe pas (404) — la page
+ * Studio affiche « dev uniquement » (fail-loud, pas de dégradation silencieuse).
+ *
+ * Cold path (introspection à la demande) : le coût de sérialisation par appel
+ * est assumé, aucune structure n'est retenue entre les appels.
+ */
+/** Un paramètre décoré d'une action (`@Param`/`@Body`/`@Query`…), JSON-safe. */
+export interface PlaygroundParam {
+    /** Source d'injection (`param`, `body`, `query`, `headers`, `cookie`, `user`…). */
+    source: string;
+    /** Clé ciblée (`@Query("q")` → `"q"`) — `null` = l'objet complet. */
+    key: string | null;
+    /** Position dans la signature de l'action. */
+    index: number;
+    /** `@Body({ stream: true })` — flux brut, non rejouable par formulaire. */
+    stream: boolean;
+}
+/** Les gardes déclaratives d'une action, prêtes à afficher (badges Studio). */
+export interface PlaygroundGuards {
+    /** Clauses `@IsGranted`/`@RequireScope` fusionnées (AND) — `null` = non gardée. */
+    security: {
+        clauses: {
+            anyOf: string[];
+            subjectParam: string | null;
+        }[];
+    } | null;
+    /** Scopes `api:action` déclarés (`@RequireScope`), dédupliqués. */
+    scopes: string[];
+    /** `@Idempotent` — `required:true` = clé obligatoire sur mutation. */
+    idempotent: {
+        required: boolean;
+    } | null;
+    csrfProtect: boolean;
+    csrfExempt: boolean;
+    /** Intent `@UseSession`/`@Session` — `null` si la route n'en déclare pas. */
+    session: unknown;
+    /** Route hors firewall (mécanisme d'auth lui-même). */
+    bypassFirewall: boolean;
+}
+/** Une action invocable depuis le playground (1 route du Router). */
+export interface PlaygroundAction {
+    /** Nom de route (unique) — clé de deep-link et de rejeu. */
+    route: string;
+    path: string | null;
+    /** Transports déclarés (`["POST","WEBSOCKET"]`…) — majuscules. */
+    methods: string[];
+    /** Vrai si l'action déclare AUSSI le transport WEBSOCKET (pont `api.request`). */
+    duplex: boolean;
+    /** Nom de la méthode de classe (action). */
+    action: string | null;
+    /** Variables de path (`{id}` → `["id"]`), ordre de capture. */
+    variables: string[];
+    /** Défauts de variables (hors clé interne `controller`). */
+    defaults: Record<string, unknown>;
+    params: PlaygroundParam[];
+    guards: PlaygroundGuards;
+}
+/** Un controller et ses actions, groupés pour la navigation Studio. */
+export interface PlaygroundController {
+    /** Nom de classe du controller. */
+    name: string;
+    /** Module propriétaire (`null` si non rattaché). */
+    module: string | null;
+    actions: PlaygroundAction[];
+}
+/**
+ * Construit le snapshot playground : toutes les routes à controller, groupées
+ * par classe de controller, triées (module puis nom, actions par path).
+ *
+ * Exclut les routes du **pont admin** (`AdminApiController.dispatch`) : le data
+ * plane a déjà son catalogue (`GET /nodefony/framework/api/admin`) et ses ~50
+ * routes techniques noieraient les controllers applicatifs.
+ *
+ * @returns la liste des controllers jouables, prête pour la page Studio.
+ */
+export declare function buildPlaygroundSnapshot(): {
+    controllers: PlaygroundController[];
+};
+/**
+ * Endpoints playground à greffer au producteur `framework` (dev uniquement —
+ * cf gating dans `createFrameworkAdminApi`).
+ *
+ * @returns `GET /nodefony/framework/api/playground/routes`.
+ */
+export declare function createPlaygroundEndpoints(): IAdminEndpoint[];

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

@@ -0,0 +1,104 @@
+import type { IIdempotencyKeyEntry, IIdempotencyListQuery, IIdempotencyStore, IdempotencyOutcome, IdempotentResponse, IPage } from "nodefony";
+/**
+ * Sous-ensemble structural du client `redis` v6 utilisé par le store — permet de
+ * tester contre un double déterministe sans serveur (le vrai `RedisClientType`
+ * satisfait cette forme par ses méthodes camelCase v6). `set` renvoie `"OK"` si
+ * la valeur est posée, `null` si `NX` l'a empêchée (clé déjà présente).
+ *
+ * Le store reste **structurel** (pas d'import de `@nodefony/redis`) : la fabrique
+ * (`framework/index.ts`) résout le service `redis` par NOM dans le container et
+ * passe son client `main` — exactement comme `RedisBackplane` (`@nodefony/realtime`)
+ * consomme `getClient("publish"/"subscribe")` sans dépendance directe.
+ */
+export interface RedisIdempotencyClientLike {
+    set(key: string, value: string, options?: {
+        NX?: boolean;
+        PX?: number;
+    }): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    del(key: string): Promise<number>;
+    /** Parcours incrémental du keyspace (introspection admin — jamais `KEYS`). */
+    scan(cursor: string, options?: {
+        MATCH?: string;
+        COUNT?: number;
+    }): Promise<{
+        cursor: string | number;
+        keys: string[];
+    }>;
+    /** TTL résiduel en millisecondes (`-1` = sans expiration, `-2` = absente). */
+    pTTL(key: string): Promise<number>;
+}
+/**
+ * Store d'idempotence **Redis** (node-redis v6) — implémentation distribuée
+ * d'{@link IIdempotencyStore} pour le cluster (dédup des mutations rejouées
+ * PARTAGÉE cross-pod, là où l'impl mémoire par défaut reste affine à un pod).
+ *
+ * **Pourquoi Redis est le bon backing** (modèle Stripe `Idempotency-Key`) :
+ *  - `SET key … NX PX` = **réservation atomique côté serveur** → le `409`
+ *    in-flight marche VRAIMENT entre pods (deux requêtes concurrentes sur deux
+ *    pods : un seul `SET NX` gagne, l'autre voit l'entrée → conflit) ;
+ *  - **TTL natif** (`PX`) sur le bail in-flight ET la réponse mémorisée → `gc()`
+ *    superflu (zéro balayage applicatif, ≠ Drizzle).
+ *
+ * **Placement** : vit dans `@nodefony/framework` (le consommateur du contrat),
+ * PAS dans `@nodefony/redis` — calqué sur `RedisBackplane` (`@nodefony/realtime`)
+ * qui possède son adaptateur Redis et résout le service `redis` par nom (couplage
+ * structurel, 0 dépendance directe → 0 cycle). Le contrat `IIdempotencyStore`
+ * vit au CORE (`nodefony`), consommé en `import type`.
+ *
+ * **Modèle de clés** (préfixe `nf:idem`, cloisonné par application) : `<prefix>:<key>` = string JSON de
+ * l'{@link Entry}. La `<key>` est DÉJÀ scopée à l'identité par l'appelant
+ * (`evaluateIdempotency` compose `[identity, clientKey]`) → anti-IDOR garanti en
+ * amont ; le store reste agnostique au scope.
+ *
+ * **Empreinte préservée à la complétion** : `complete()` ne reçoit pas le
+ * fingerprint → il **relit** l'entrée *in-flight* pour reporter son `f` dans
+ * l'entrée *done*. Sans ça, un rejeu de la clé avec un AUTRE payload après
+ * complétion ne serait pas détecté (`mismatch` 422 perdu, draft §2.7).
+ *
+ * **Dégradation gracieuse** : si la connexion `main` n'est pas (ou plus) ouverte
+ * (boot/shutdown), `begin` renvoie `fresh` (la mutation s'exécute, **sans**
+ * dédup) et `complete`/`abort` sont des no-op — l'idempotence est temporairement
+ * inactive plutôt que de bloquer la mutation (fail-soft sur la dispo, comme le
+ * session/token store Redis). Trade-off assumé : un rejeu pendant une coupure
+ * Redis peut ré-exécuter (le client rejoue alors sa clé au rétablissement).
+ */
+export declare class RedisIdempotencyStore implements IIdempotencyStore {
+    #private;
+    /**
+     * @param resolveClient - résolveur **lazy** du client Redis (l'ordre de boot
+     *   n'est pas garanti à la construction ; `null` = connexion indisponible).
+     * @param leaseMs - bail d'une entrée *in-flight* (ms).
+     * @param ttlMs - rétention d'une réponse mémorisée (ms).
+     */
+    constructor(resolveClient: () => RedisIdempotencyClientLike | null, leaseMs?: number, ttlMs?: number, resolvePrefix?: () => string);
+    /**
+     * Approximation **per-pod, best-effort** : compteur local des réservations
+     * faites par CE pod, non décrémenté si le bail expire sans `complete`/`abort`,
+     * et désaligné cross-pod (un `begin` sur un pod, un `complete` sur un autre).
+     * La vérité cluster passe par `redis-cli` (`SCAN nf:idem:*`/`DBSIZE`), jamais
+     * ce getter (un `SCAN` à chaque lecture serait cher). Borné à ≥ 0.
+     */
+    get size(): number;
+    /**
+     * {@inheritDoc IIdempotencyStore.listPage}
+     *
+     * **Curseur SCAN** : au plus UN passage par appel (cold-path admin). Capacité
+     * réduite ASSUMÉE — pas de `total` (compter exigerait un SCAN complet du
+     * keyspace, précisément ce qu'on refuse), pas d'ordre global, et la page peut
+     * compter moins que `limit` (le filtre s'applique au batch scanné). Le client
+     * boucle tant que `hasNext` en repassant `nextCursor`.
+     *
+     * ⚠️ **`COUNT` n'est PAS un plafond** mais un indice d'effort : Redis peut
+     * rendre plus de clés que demandé (petit keyspace en listpack → tout arrive
+     * d'un coup). Sans précaution la page dépasserait `limit` et violerait
+     * `IPage`. D'où le **curseur composite** `"<consommé>:<curseurRedis>"` : on ne
+     * rend que `limit` éléments et on mémorise combien de clés du batch ont été
+     * consommées ; la page suivante rejoue le MÊME `SCAN` et reprend là. Bug
+     * réel, invisible contre un double — trouvé sur serveur Redis réel.
+     */
+    listPage(query: IIdempotencyListQuery): Promise<IPage<IIdempotencyKeyEntry>>;
+    begin(key: string, fingerprint: string): Promise<IdempotencyOutcome>;
+    complete(key: string, response: IdempotentResponse): Promise<void>;
+    abort(key: string): Promise<void>;
+}

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

@@ -0,0 +1,165 @@
+import { Injector } 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
+ * `ServiceWithInit` (singleton, 1× au démarrage).
+ *
+ * @remarks Signature alignée sur l'appel réel `controller.initialize()` (sans arg) ;
+ *   retour `Promise<this>` — le controller renvoie son instance.
+ */
+export interface ControllerWithInitialize {
+    initialize(): Promise<this>;
+}
+/**
+ * Résout une route vers son couple controller/action et exécute l'action —
+ * UN Resolver est alloué par requête HTTP (et par connexion WS, réutilisé
+ * par message). **POJO volontaire** (V3.1) : n'étend PAS `Service` — le
+ * plumbing Service (Map de listeners trackés, spread d'options, lookups
+ * kernel/syslog) coûtait par requête sans aucun consommateur (jamais écouté,
+ * jamais loggé, jamais dans le container). Le DI per-request passe par
+ * `context.container` (le cache `"controller"` y survit au Resolver : un
+ * forward ou un 2ᵉ Resolver WS sur la MÊME connexion retrouve l'instance).
+ */
+declare class Resolver implements IResolver {
+    injector?: Injector | null;
+    controller: ControllerConstructor | null;
+    actionName?: string;
+    action?: (...args: unknown[]) => unknown;
+    context: ContextType;
+    route: Route | null;
+    resolve: boolean;
+    variables: unknown[];
+    exception?: HttpError | Error | null;
+    acceptedProtocol: string | null;
+    bypassFirewall: boolean;
+    /**
+     * Query d'une invocation **par message** (pont WS-RPC `api.request`) — pendant
+     * de `cleanPathOverride` pour le `?…` du path invoqué. Le contexte WS étant
+     * PARTAGÉ par la connexion (sa `queryGet` = celle du handshake), la query
+     * per-invocation vit ici (le Resolver est per-invocation → zéro bleed entre
+     * requêtes concurrentes d'une même socket). `null` (hot path HTTP) = ignoré.
+     * Consommé par `@Query` (`_buildParamArgs`) et copié sur le controller
+     * per-request (`executeAction`).
+     */
+    queryOverride: Record<string, unknown> | null;
+    /**
+     * Méthode HTTP **logique** d'une invocation par le pont WS-RPC `api.request`
+     * quand c'est une MUTATION (POST/PUT/PATCH/DELETE). Posée par
+     * `Router.resolve(ctx, cleanPath, methodOverride)` → consommée par `match()`
+     * pour désambiguïser, sur le transport WEBSOCKET unique, la route logique
+     * visée (cf `Route.matchRequirements`). `null` (GET/HTTP) = match historique
+     * sur `context.method`.
+     */
+    methodOverride: string | null;
+    constructor(context: ContextType);
+    match(route: Route, context: ContextType, cleanPath?: string): ((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
+     * (`this.variables`, posées par `match()`) zippées avec les noms de
+     * `route.variables`. Remplace l'ancien `Route.variablesMap` qui vivait sur
+     * l'instance `Route` partagée (statique) → écrasé par toute requête/connexion
+     * concurrente sur la même route (bleed inter-requêtes). Lu par
+     * `Context.setMetaData()` pour exposer `msg.nodefony.route.variablesMap`.
+     */
+    getMatchedParams(): Record<string, unknown>;
+    parsePathernController(name: string): void;
+    getAction(name: string): ((...args: unknown[]) => unknown) | null;
+    newController(context?: ContextType): Promise<Controller>;
+    /**
+     * 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.
+     */
+    private _createController;
+    /**
+     * 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 »
+     * de « rendre la valeur » : un appelant multi-transport (WS-RPC `invoke`, futur
+     * GraphQL) réutilise la MÊME action puis emballe le résultat à sa façon
+     * (`{ id, result }`, champ GraphQL…). Le pipeline HTTP/WS normal passe par
+     * {@link callController} (= `executeAction` + rendu).
+     *
+     * @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.
+     */
+    executeAction(data?: unknown[], reload?: boolean, metaArg?: RouteActionMeta): Promise<{
+        result: unknown;
+        redirectMeta: RedirectMeta | undefined;
+    }>;
+    callController(data?: unknown[], reload?: boolean): Promise<unknown>;
+    /**
+     * Exécute l'action AVEC la porte d'idempotence mais SANS rendu
+     * (`returnController`) — le chemin du **pont `api.request`** (WS) : la valeur
+     * nue est enveloppée `{id, result}` par le peer, jamais rendue sur le
+     * transport. La méthode HTTP logique d'une mutation du pont voyage dans
+     * {@link methodOverride} ; sans porte ici, un rejeu `socket.mutate` (socket
+     * qui reconnecte) ré-exécuterait la mutation (doublon — vécu au banc duplex).
+     *
+     * @returns `{ result }` — la valeur retournée par l'action (ou la réponse
+     *   mémorisée rejouée pour une clé d'idempotence déjà servie).
+     */
+    executeActionGuarded(data?: unknown[], reload?: boolean): Promise<{
+        result: unknown;
+    }>;
+    /**
+     * Applique la porte d'idempotence d'une action `@Idempotent` (mutations), via le
+     * helper partagé `idempotency.ts` (la MÊME sémantique que le data plane admin) et
+     * le service `idempotencyStore`. Conforme `draft-ietf-httpapi-idempotency-key-header`.
+     *
+     * Cycle (anti double-effet) : `evaluateIdempotency` rend un verdict neutre →
+     *  - `reject` → `nodefonyError` (400 clé requise / 409 concurrent / 422 mismatch) ;
+     *  - `replay` → réponse mémorisée rejouée SANS ré-exécuter l'action ;
+     *  - `execute` → exécution directe (mode souple sans clé / store absent) ;
+     *  - `guarded` → exécuter, puis `complete()` (succès, réponse rejouable) ou
+     *    `abort()` (échec/403 — la clé reste réessayable, un échec ne se mémorise pas).
+     *
+     * No-op sur les méthodes sûres (GET…). La réponse mémorisée est
+     * le **résultat retourné** par l'action (`return data`) + son statut : une action
+     * qui pilote la response manuellement (`this.render`/stream) n'est pas rejouée
+     * fidèlement (le double-effet reste évité, mais le corps rejoué est vide).
+     *
+     * Retourne la forme BRUTE `{ result, redirectMeta }` (comme `executeAction`) :
+     * le rendu appartient à l'appelant — `callController` rend (`_handleRedirect`),
+     * le pont (`executeActionGuarded`) enveloppe la valeur nue.
+     */
+    private _callWithIdempotency;
+    /**
+     * Évalue l'exigence d'autorisation (`@IsGranted`) d'une action via le service
+     * `authorization` (par nom, 0 import security). Clauses en **AND**, attributs
+     * d'une clause en **OR**. Refus (ou moteur/identité absents) → 403 (Zero Trust,
+     * fail-closed). Cold path : n'est appelé que sur une route gardée.
+     *
+     * @throws nodefonyError 403 si l'accès est refusé.
+     */
+    private _enforceSecurity;
+    /**
+     * Résout un paramètre de route NOMMÉ (`@IsGranted(..., { subject: "id" })`) vers
+     * sa valeur, depuis `route.variables` (noms) + `this.variables` (valeurs déjà
+     * parsées). 0 alloc (indexOf + accès tableau).
+     */
+    private _resolveSubject;
+    private _buildParamArgs;
+    /**
+     * Applique `@HttpCode` + `@Header` depuis le snapshot figé de la route
+     * (P5) — plus aucune lecture `Reflect` ni `Object.entries` par requête.
+     * V4.3 : cible la response du CONTEXT (per-request : identique à
+     * `controller.response` ; singleton : la seule source correcte — l'instance
+     * partagée ne porte aucune response).
+     */
+    private _applyResponseMeta;
+    private _handleRedirect;
+    returnController(result: unknown): Promise<unknown>;
+    /** Statut courant de la réponse (0 si le transport n'en porte pas). */
+    private getResponseStatus;
+}
+export default Resolver;

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

@@ -0,0 +1,171 @@
+import Controller from "./Controller.js";
+import type { ControllerScope } from "./Controller.js";
+import type { ContextType } from "@nodefony/http";
+import type { IPage, IPageQuery } from "nodefony";
+/**
+ * Contrat structurel du service de ressource consommé par un
+ * {@link ResourceController} — aligné sur `AbstractCrudService`
+ * (`@nodefony/orm-core`) SANS en dépendre : le framework ne connaît pas
+ * l'ORM, n'importe quel objet de cette forme convient (service DI, objet
+ * en mémoire, façade distante…). `create`/`updateOne`/`delete` sont
+ * optionnels : une ressource read-only n'expose que la lecture.
+ */
+/**
+ * Options de lecture d'une liste — **pagination avant tout**.
+ *
+ * Elles font partie du contrat parce qu'une ressource sans borne est une fuite qui
+ * attend son heure : le jour où la table grossit, `find()` charge tout en mémoire.
+ * Miroir structurel de `RepositoryReadOptions` (`@nodefony/orm-core`), sans dépendre
+ * de l'ORM.
+ */
+export interface IResourceReadOptions {
+    /** Nombre maximum d'enregistrements rendus. */
+    limit?: number;
+    /** Enregistrements sautés (⚠️ se dégrade sur les grandes tables — curseur à venir). */
+    offset?: number;
+    /**
+     * Tri, sous la forme `[[champ, sens], …]` — même écriture que `IPageQuery.order`
+     * (core) et que `RepositoryReadOptions` (orm-core).
+     *
+     * Typé plutôt que libre : une porte qui doit deviner la forme attendue finit
+     * 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"]>;
+    /** Associations à charger avec l'enregistrement. */
+    relations?: string[];
+}
+/**
+ * Requête de page telle qu'une porte la passe au service — `IPageQuery` du core,
+ * plus les critères que la sous-classe a EXPLICITEMENT décidé d'exposer.
+ *
+ * Miroir structurel de `PageQuery<T>` (orm-core) sans dépendre de l'ORM : le
+ * framework ne connaît pas `Criteria<T>`.
+ */
+export interface IResourcePageQuery extends IPageQuery {
+    /** Critères de filtrage — jamais dérivés de la query string automatiquement. */
+    criteria?: Record<string, unknown>;
+}
+export interface IResourceService<T = unknown> {
+    find(criteria?: Record<string, unknown>, options?: IResourceReadOptions): Promise<T[]> | T[];
+    /**
+     * Lit par identifiant. `options.relations` charge les associations en une fois
+     * (`AbstractCrudService` le transmet au repository, qui sait les résoudre).
+     */
+    findById(id: string, options?: IResourceReadOptions): Promise<T | null> | T | null;
+    /**
+     * Rend une PAGE plutôt qu'un tableau nu — `AbstractCrudService` l'hérite déjà
+     * (`findPage` → `paginate`).
+     *
+     * Optionnel : une ressource read-only ou une façade en mémoire n'a pas à
+     * l'implémenter, `listPageResource` sait alors reconstituer la page à partir
+     * 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;
+    delete?(criteria: Record<string, unknown>): Promise<number> | number;
+}
+/**
+ * Controller de ressource **souverain** (V4.2 — POC API souveraine, Phase 2) :
+ * la logique métier est écrite UNE fois dans le service de ressource, les
+ * actions de la sous-classe ne sont que des portes (REST, WS-RPC `invoke`,
+ * GraphQL à venir) qui retournent la **valeur brute** — `returnController`
+ * l'auto-JSON en REST, le pont WS l'enveloppe (`{id,result}`), sans réécrire
+ * l'action par transport.
+ *
+ * **Stateless par construction** :
+ * - `static scope = "singleton"` : UNE instance partagée (cache Router, V4.3).
+ *   L'état per-request n'existe PAS sur `this` — il arrive par les arguments
+ *   décorés (`@Param`/`@Body`/`@Query`) et par les helpers hérités qui
+ *   retrouvent la requête courante via l'ALS (V4.1).
+ * - le seul champ est `resource`, posé 1× au constructor (état de BOOT,
+ *   immuable ensuite — sûr en concurrence).
+ * - règle absolue pour les sous-classes : **jamais `this.x = …` par requête**
+ *   (data race silencieuse). Une sous-classe qui a besoin d'état per-request
+ *   sur `this` doit rétrograder : `static scope = "request"`.
+ *
+ * Sécurité : aucun critère de requête n'est passé AUTOMATIQUEMENT au service
+ * (pas de `find(this.queryGet)` implicite) — exposer un filtrage est une
+ * décision EXPLICITE de la sous-classe (deny-by-default ; le scope de
+ * sécurité des données se branche au niveau service/criteria, P6).
+ *
+ * @example
+ * ```ts
+ * \@controller("/api/books")
+ * class BookController extends ResourceController<Book> {
+ *   constructor(context: Context) {
+ *     super("BookController", context, bookService);
+ *   }
+ *   \@route("books-list", { path: "", requirements: { methods: ["GET", "WEBSOCKET"] } })
+ *   list() {
+ *     return this.listResource();
+ *   }
+ *   \@route("books-get", { path: "/{id}", requirements: { methods: ["GET", "WEBSOCKET"] } })
+ *   detail(\@Param("id") id: string) {
+ *     return this.getResource(id);
+ *   }
+ * }
+ * ```
+ */
+declare class ResourceController<T = unknown> extends Controller {
+    /**
+     * Singleton PAR DÉFAUT : la classe est conçue stateless — premier client
+     * du scope V4.3. Une sous-classe peut rétrograder (`static scope =
+     * "request"`) si elle doit porter de l'état per-request sur `this`.
+     */
+    static scope: ControllerScope;
+    /**
+     * Service de ressource — état de BOOT (posé 1× ici, jamais réassigné).
+     * `protected` : les actions de la sous-classe y accèdent, les portes non.
+     */
+    protected resource: IResourceService<T> | null;
+    constructor(name: string, context: ContextType, resource?: IResourceService<T>);
+    /**
+     * Service de ressource garanti — 500 explicite si la sous-classe ne l'a
+     * pas fourni (erreur de câblage, pas une erreur client).
+     */
+    protected requireResource(): IResourceService<T>;
+    /**
+     * Liste la ressource. `criteria` est EXPLICITE (jamais dérivé de la query
+     * string automatiquement — deny-by-default).
+     */
+    protected listResource(criteria?: Record<string, unknown>, options?: IResourceReadOptions): Promise<T[]>;
+    /**
+     * Liste la ressource en rendant une **page** (`{ items, hasNext, total? }`)
+     * plutôt qu'un tableau nu.
+     *
+     * Pourquoi une page et pas un tableau : un tableau ne dit pas s'il en reste.
+     * Le client qui reçoit 25 lignes ne peut pas distinguer « c'est tout » de
+     * « demande la suite » — il redemande indéfiniment, ou s'arrête trop tôt.
+     *
+     * **Mode offset imposé** (`assertPageQuery`) : un client qui enverrait un
+     * `cursor` recevrait sinon la page 1 à chaque appel, en boucle et sans erreur.
+     *
+     * Si le service n'expose pas `findPage`, la page est reconstituée à partir de
+     * `find` en chargeant `limit + 1` lignes (même technique que `paginate`) : le
+     * `hasNext` reste exact, seul `total` manque — et son absence est lisible dans
+     * la réponse, le contrat `IPage` le donnant pour optionnel.
+     *
+     * @param page - bornes, tri et critères de la page demandée.
+     * @returns la page (`items` borné à `limit`).
+     * @throws PaginationModeError si la requête mélange offset et curseur.
+     */
+    protected listPageResource(page: IResourcePageQuery): Promise<IPage<T>>;
+    /**
+     * Lit une entité par id — `null` si absente (la porte décide du 404).
+     *
+     * `options.relations` charge les associations dans la foulée. La porte doit
+     * n'y laisser passer que des relations qu'elle a DÉCLARÉES : un `include`
+     * libre laisse le client nommer n'importe quelle association, donc lire des
+     * données qu'aucune route ne lui ouvre.
+     */
+    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>;
+    /** 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>;
+    /** Supprime par critères (nombre d'entités touchées) — 501 si non supporté. */
+    protected removeResource(criteria: Record<string, unknown>): Promise<number>;
+}
+export default ResourceController;